[Animated] Implement modulo operator method

[rt2zz]

This is an initial take on how to allow for value wrapping in Animated (currently .timing only). It adds a wrap config options which is an array specifying a range of values to be wrapped around. Anytime the delta of toValue and fromValue > wrapDistance / 2 instead of animating the long way it will animate towards the range extremity and then after breaching the range it will readjust to animated to the true toValue.

Example Usage:

Animated.timing(
  this.state.animatedDegrees, 
  {toValue: Math.random()*360, wrap: [0, 360]}
).start()

This is presumably very valuable in rotation based animations, but could also be useful in other applications like wrapping the edges of the viewport.

Questions & Todo:

• Is wrap as a config key semantically meaningful and accurate?
• Is there a way to expose this as a config option on .interpolate rather than timing
• Generalize to all animated API's (spring, decay), and will this work with ValueXY out of the box?
• Add tests

[facebook-github-bot]

By analyzing the blame information on this pull request, we identified @sahrens, @lelandrichardson and @ide to be potential reviewers.

[lelandrichardson]

I was just thinking about ways to do this the other day.
What if we did something like:

var newAnimatedValue = Animated.modulo(animatedValue, num);

Similar to Animated.multiply and Animated.add

[rt2zz]

@lelandrichardson I like that api a lot better, but I could not figure out how to make it work since the underlying Animation (spring/timing/decay) has already chosen the direction to go.

I suppose it could work as an Animated.modulo method which as a consumer you would pair with some wrapping logic like follows:

state = {
  rotation: Animated.value(0)
}

// ...

let degrees = Math.random()*360
if (lastDegreeValue - degrees > 180) degrees += 360
if (lastDegreeValue - degrees < -180) degrees -= 360
Animated.timing(this.state.rotation, {toValue: degrees}).start()

// ...

<Thingy style={{transform: [{rotate: Animated.modulo(this.state.rotation, 360)]}} />

[lelandrichardson]

@rt2zz right. I think this is also better since it doesn't depend on using the .timing(...) API. For example, if you want to have the dial of a clock move around, tracking the value of a pan or gesture. This is also more consistent with the existing add and multiply APIs.

[rt2zz]

I love the purity of the .modulo(value, modulus) but I think we need to figure out a way to support arbitrary ranges e.g. [-90, 90].

Because modulo in js is already messed up ( -1 % 2 = -1), imo we should adopt a more explicit array based api such as:
Animated.modulo(value, [start, end])
Animated.moduloRange(value, [start, end])

[lelandrichardson]

@rt2zz any modulo range could be expressed with a combination of modulo + interpolate though.

[rt2zz]

True but as a consumer you would then always have to map your raw input values to a (0, n) or (-n, n) range only to interpolate them back.

Maybe @sahrens or others can weigh in on api design - I am ok either way but prefer having an explicit range.

[lelandrichardson]

That's fair. A range would be very easy to do regardless....

(val) => val % mod;

versus

(val) => ((val - min) % (max - min)) + min;

[eslint-bot]

identifier array Could not resolve name

[rt2zz]

Note: I will be completely redoing this next week per @lelandrichardson suggestion

[facebook-github-bot]

@rt2zz updated the pull request.

[rt2zz]

Ok I updated the PR per leland's recommendation. This now adds a Animated.modulo method.

Note: ecmascript thinks -a % b should be a negative number which is annoying. I implemented the non-negative version of modulus via (a % modulus + modulus) % modulus. We can probably get some performance gains by only conditionally applying the adjustment for negative values of a.

[lelandrichardson]

@rt2zz is the -a % b thing just an order of operations? ie, would (-a) % b fix it?

Edit: nvm, that doesn't change anything.

[rt2zz]

@lelandrichardson ya I guess I should have been more explicit i.e. a % b < 0 for any a less than zero

[facebook-github-bot]

@rt2zz updated the pull request.

[rt2zz]

I just rebased master. The diff is pretty trivial and this functionality cannot be achieved through any other means.

[lelandrichardson]

@facebook-github-bot shipit

[facebook-github-bot]

Thanks for importing. If you are an FB employee go to Phabricator to review.

[mileung]

-a % b should be a negative number because that's how js behaves. In my case, I have a swipeX Animated Value and it can be + or -. When I use modulo on swipeX, I lose which direction swipeX is going in. Now I guess I need to have another swipeDirection variable which is either 1 or -1 and multiply it by the result of modulo to make it the value it should be if it behaved like js %.