DEV Community: Timothée Boucher

Using modulo to shift a value and keep it inside a range

Timothée Boucher — Sun, 27 Feb 2022 21:27:48 +0000

The modulo operator is fairly simple, but often underused. In particular, I find it useful when changing a value and keeping it inside a pre-determined range.

E.g., index in an array, hours in a day, degrees on a compass.

First of all, a quick definition: the modulo operator gives the remainder of a division of one number by another. In JavaScript the modulo operator is %.

The number after the operator is called modulus.

Importantly, in JavaScript the return value is signed. What does this mean? 14 % 4 is 2, and -14 % 4 is -2. Some languages keep the result in [0, modulus - 1]. This adds some complexity to the formula below.

(if you're reading this and use a different language than JavaScript, check Wikipedia for the details on your language of choice)

Ultimate formula

The context is this: you have a starting value in a given range, you need to increase or decrease the value by a certain amount, and you need the final value to loop back and stay in that range.

This is the ultimate formula that works for all these cases:

(startingValue - minimumValue + (offset % modulus) + modulus) % modulus + minimalValue

startingValue is the value you start with. It's assumed to be in your desired range already.
minimumValue is the lowest value of your desired range. Doing startingValue - minimumValue shifts the modulo operation to a range starting at 0. We add it back at the end to shift the value back to the desired range. NB: minimumValue can be negative too!
offset is the amount you want to shift your starting value by. It can be negative, positive, and as small or large as you want. We use offset % modulus to make sure we shift by the smallest amount necessary. Since this can be negative (because the modulo operation is signed), we add modulus to that to make sure the result stays in range. (see below)
modulus is the length of your desired range.

Adding the modulus doesn't affect the result, and guarantees that adding offset % modulus will keep the number positive in the case where offset is negative.

E.g., if you're looking at 24 hours and your offset is -50, offset % modulus is -2. Removing two hours is equivalent to adding -2 + 24 hours which is 22. In other words, this ensures that we're always adding to the value. When we subtract, we sometimes can get a negative value, which leads us to the same problem and solution.

Let's put this in practice with concrete use cases!

Cycling through an array

It's very common to need to cycle through an array and loop back on the other end. E.g., you change the selected item of a dropdown and need to go back at the top once you reach the bottom.

I have seen code like this to achieve this:

const options = ['alpha', 'beta', 'gamma', 'delta']
let selectedIndex = 0

function goDown () {
  selectedIndex = selectedIndex + 1
  if (selectedIndex === options.length) {
    selectedIndex = 0
  }
}
function goUp () {
  selectedIndex = selectedIndex - 1
  if (selectedIndex === -1) {
    selectedIndex = options.length - 1
  }
}

It works! However, using the formula above, you can combine the two functions:

function go (offset) {
  selectedIndex = (selectedIndex + offset + options.length) % options.length
}
const goDown = () => go(1)
const goUp = () => go(-1)

minimumValue here is 0 because an array's index is between 0 and options.length - 1, so we don't need it.
We also know that direction is either 1 or -1 so we don't need (offset % modulus), and offset is enough.

Time-related modulo

Most time units loop back: there are 12 months in a year, 24 hours in a day, 60 minutes in an hour, etc.

Because time is finicky, you may want to use dedicated time functions for this. Sometimes you can just put a modulo and be on your way!

One use-case is starting from a month index, adding or subtracting a certain number of months, and wanting to know which month you end up on.

Your desired range is [1, 12], so minimumValue is 1.
modulus is 12 because there are 12 months

function shiftMonth (startingMonth, offset) {
  return (startingMonth - 1 + (offset % 12) + 12) % 12 + 1
}

Once again, the - 1 sets your initial value back into [0, 11], then you can do your regular operation, and you add 1 again at the end to shift back the range to [1, 12].

Angles and non-integer values

And this works with non-integer values!

For example, say you have to keep track of a direction in radians, but want to keep the value between -π and π.

minimumValue is -Math.PI
modulus is the length of the range: 2 * Math.PI

You can then have the following function:

function shiftAngles (startingAngle, offset) {
  return (startingAngle + Math.PI + (offset % (2 * Math.PI)) + 2 * Math.PI) % (2 * Math.PI) - Math.PI
}

For contrast, this function keeps the angle between 0 and 2π:

function shiftAnglesPositive (startingAngle, offset) {
  return (startingAngle + (offset % (2 * Math.PI)) + 2 * Math.PI) % (2 * Math.PI)
}

In action:

> shiftAngles(Math.PI / 3, -5 * Math.PI) / Math.PI
-0.6666666666666667
> shiftAnglesPositive(Math.PI / 3, -5 * Math.PI) / Math.PI
1.3333333333333333

I'll be honest, it's a bit of a mouthful of a formula, and it can look too clever for its own good. But it has the benefit of just working without missing edge cases, especially when the offset is unknown. If you don't use it, you end up with a bunch of ifs and it's quite easy to slip up.

Photo by Joel Fulgencio on Unsplash

Quick and easy value clamping in JavaScript

Timothée Boucher — Mon, 14 Feb 2022 20:49:45 +0000

Ever needed to make sure a value stays within a certain range?

I've often written code like this:

function clamp (value, min, max) {
  if (value > maximum) return maximum
  if (value < minimum) return minimum
  return value
}

let lower = clamp(9, 10, 25) // 10
let higher = clamp(30, 10, 25) // 25
let middle = clamp(22, 10, 25) // 22

Every time I see code like this, I know there's a way to do it with Math.max and Math.min but I'm always getting my wires crossed thinking about it.

So here it is:

function clamp (value, min, max) {
  return Math.max(min, Math.min(max, value))
}

Next time, I just need to remember "max-min-min-max-value".

How Wordle kept your streak alive when it migrated to the NYT's website

Timothée Boucher — Mon, 14 Feb 2022 17:53:17 +0000

If you've been online even just one day in the past few weeks, you've probably heard of Wordle, a word-game that caught the world, and Twitter in particular, by surprise with cryptic grids of colored square emoji.

It got so popular that after a few weeks, the New York Times bought the game to add it to their suite of daily word games.

Josh Wardle, Wordle's creator, had announced that he "was working with [the NYT] to make sure wins and streaks will be preserved".

Last week, the game migrated to the NYTimes' domain and I was curious how they migrated the statistics. It turns out that it's pretty simple. :)

The original game lived at https://www.powerlanguage.co.uk/wordle/

If you curl that URL today, you get this:

$ curl -D /dev/stdout https://www.powerlanguage.co.uk/wordle/
HTTP/2 200
date: Mon, 14 Feb 2022 16:57:50 GMT
content-type: text/html
last-modified: Sun, 13 Feb 2022 22:37:30 GMT
[...skip...]
<!DOCTYPE html>
<html lang="en">
  <head>
    <title>Wordle - The New York Times</title>
    <meta http-equiv="cache-control" content="no-cache" />
    <meta name="description" content="Guess the hidden word in 6 tries. A new puzzle is available each day" />
  </head>
  <body>
    <script type="text/javascript">
      const ls = window.localStorage;
      // Ensure we're always sending something
      let stringifiedData = '{}';
      // Default to production
      let url = 'https://www.nytimes.com/games/wordle'

      // Don't attempt unless our user has local storage enabled
      if (ls) {
        const errors = [];
        const localData = {
          time: new Date().getTime(),
          statistics: null,
          darkTheme: null,
          colorBlindTheme: null
        };

        // Attempt to pull and parse the stats and themes
        try {
          localData.statistics = JSON.parse(ls.getItem('statistics'));
          localData.darkTheme = JSON.parse(ls.getItem('darkTheme'));
          localData.colorBlindTheme = JSON.parse(ls.getItem('colorBlindTheme'));
        } catch (e) {
          // Anything that's not valid JSON will not be sent
          errors.push(e);
        }

        try {
          stringifiedData = JSON.stringify(localData);
        } catch (e) {
          errors.push(e);
        }
      }

      // Everyone will redirect, regardless of local storage
      window.location.assign(`${url}?data=${stringifiedData}`)
    </script>
  </body>
</html>

It serves a simple HTML document with an inline script that grabs all the statistics of the original game from localStorage, put all the important data in the URL, and forwards the browser to the nytimes.com URL.

Once that page loads (there's a 301 permanent redirect to index.html but that doesn't do much), that data is parsed and saved locally again with this code:

function os() {
    if (localStorage) {
        try {
            var e = new Proxy(new URLSearchParams(window.location.search),{
                get: function(e, a) {
                    return e.get(a)
                }
            });
            if (e.data)
                !function(e) {
                    if (!e.statistics)
                        throw new Error("User local data does not contain statistics. Aborting transfer.");
                    if (ns(e.statistics, e.force)) {
                        localStorage.setItem('nyt-wordle-statistics', JSON.stringify(e.statistics));
                        var a = e.darkTheme;
                        window.themeManager.setDarkTheme(a);
                        var s = !!e.colorBlindTheme;
                        window.themeManager.setColorBlindTheme(s)
                    }
                }(JSON.parse(e.data))
        } catch (e) {}
        window.history.replaceState({}, document.title, new URL(location.pathname,location.href).href)
    }
}

You can see in the call to the ns function that you can force an override of the data. By default, ns short-circuits the data transfer when it finds local data.

And if you do force it by passing "force": true, ns looks at the given statistics, and makes sure you played at least one game but also more games on the original game than the new site.

Finally, note the call to window.history.replaceState. This strips all the data passed in the URL. Using replaceState makes sure that clicking "Back" in your browser won't bring back all the transfer data in the URL. That makes it less likely that someone will share that URL with somebody and erase their statistics by accident.

And that's it!

There IS one part that I haven't quite figured out while looking at this.

I play Wordle on my phone and the old URL was saved in my history so I would just type po and the rest would show up. After the transfer, it stopped populating completely as if I had never been to https://www.powerlanguage.co.uk/wordle/.

But looking at the steps above I don't know why it would just disappear from my local history. There's a 301 in the process, but it's from https://www.nytimes.com/games/wordle?data=... to /games/wordle/index.html?data=....

I'd love to hear if you have ideas about that.

P.S.: I'm aware that the transfer had some bugs for some people, but I believe it was all fixed up.