[wrap)

[1ec5]

wrap() now excludes the maximum value, returning a value in the range [min, max). wrap(max, min, max) now returns the same thing as wrap(max * 2, min, max).

If (wrap] is desired, it is the responsibility of the caller to handle the case in which min is returned.

Backported from mapbox/mapbox-gl-native#1829. No expected changes in behavior.

/cc @mourner

[mourner]

But why?

[1ec5]

For consistency with mapbox/mapbox-gl-native#1829, which was necessary because functions that return wrapped values need predictable values. Currently, wrapping 360 to between 0 and 360 gives you 360, but wrapping 720 or -360 to the same range gives you 0. We could fix it so that any multiple of the maximum returns the maximum, but it's still counterintuitive because then negative multiples of the maximum don't behave the same way as their positive counterparts.

[mourner]

It just looks weird because you change a working util method in a way that introduces code duplication in lots of places. Leaflet solves this problem by having boolean includeMax argument.

[1ec5]

https://github.com/Leaflet/Leaflet/blob/45034155bdf8d958554b43ed8dbd7020df9ca6ab/src/core/Util.js#L83

[bhousel]

Can I merge this? The current wrap implementation makes no sense:

for(var i = -6; i < 6; i++) { console.log(i + ': ' + wrap(i,0,2)) }
 -6: 0
 -5: 1
 -4: 0
 -3: 1
 -2: 0
 -1: 1
 0: 0
 1: 1
 2: 2
 3: 1
 4: 0
 5: 1

AFAICT we use it only to wrap the bearing value. But I was also hoping to use it in a fix for #1483

[mourner]

@bhousel does it fix the issue?

[bhousel]

does it fix the issue?

Yes, Minh's wrap makes much more sense:

for(var i = -6; i < 6; i++) { console.log(i + ': ' + wrap(i,0,2)) }
-6: 0
-5: 1
-4: 0
-3: 1
-2: 0
-1: 1
 0: 0
 1: 1
 2: 0
 3: 1
 4: 0
 5: 1

[jfirebaugh]

The code duplication is unfortunate. Could we just switch to wrapping longitude and bearing to [-180, 180)? Or maybe longitude to [-180, 180) and bearing to [0, 360).

[jfirebaugh]

Also this needs to be rebased on master -- some tests have been added for wrap that need to be updated for this change.

[mourner]

@jfirebaugh sounds good to me.

[1ec5]

There are usually two reasons to use a wrap function:

• If the minimum is 0 and the maximum is positive, you typically want [minimum, maximum).
• If the minimum is negative and the maximum is positive, you typically want (minimum, maximum].

On the other hand, if the wrap function were to switch on the sign of the minimum value, I’d consider that to be surprising, hidden behavior. So how about two functions, wrapDown() and wrapUp(), that return values in the range [minimum, maximum) and (minimum, maximum], respectively?

[jfirebaugh]

How about supporting either (n, min, max) or (n, max, min) argument order and always wrapping inclusive on the first extremum and exclusive on the second?

[1ec5]

How about supporting either (n, min, max) or (n, max, min) argument order and always wrapping inclusive on the first extrema and exclusive on the second?

That’s an elegant approach. But at the risk of bike-shedding on this issue, I’m pretty sure that if I read wrap(n, -5, 5) and wrap(n, 5, -5), I wouldn’t know to look at the documentation to find out that there’s a difference between the two.

[1ec5]

OK, I wound up implementing the approach I outlined in #1363 (comment). The upshot is that, going forward, you’ll probably use wrapUp() when straddling 0 and wrapDown() when the minimum is 0. Think of this as being complementary to hypothetical roundUp() and roundDown() functions, rather than the existing clamp() function.

[mourner]

Looks good, but I'd rather have it as an optional wrap argument than two different functions.

[jfirebaugh]

Sorry for encouraging bikeshedding on this. I merged a minimal change -- just making the existing wrap behavior truly exclusive on min (so wrap(n, 0, 2) === 2 when n % 2 === 0).

[1ec5]

This means the bearing can never be 0°, which is a little strange. But functionally it’s all good.

[jfirebaugh]

It can be 0°; gl-js uses a range of (-180°, 180°].

[1ec5]

Got it; I was thrown off by the title of #1509. 😄 Thanks for taking care of this.