| # normalize-range |
| |
| Utility for normalizing a numeric range, with a wrapping function useful for polar coordinates. |
| |
| [](https://travis-ci.org/jamestalmage/normalize-range) |
| [](https://coveralls.io/github/jamestalmage/normalize-range?branch=master) |
| [](https://codeclimate.com/github/jamestalmage/normalize-range) |
| [](https://david-dm.org/jamestalmage/normalize-range) |
| [](https://david-dm.org/jamestalmage/normalize-range#info=devDependencies) |
| |
| [](https://nodei.co/npm/normalize-range/) |
| |
| ## Usage |
| |
| ```js |
| var nr = require('normalize-range'); |
| |
| nr.wrap(0, 360, 400); |
| //=> 40 |
| |
| nr.wrap(0, 360, -90); |
| //=> 270 |
| |
| nr.limit(0, 100, 500); |
| //=> 100 |
| |
| nr.limit(0, 100, -20); |
| //=> 0 |
| |
| // There is a convenient currying function |
| var wrapAngle = nr.curry(0, 360).wrap; |
| var limitTo10 = nr.curry(0, 10).limit; |
| |
| wrapAngle(-30); |
| //=> 330 |
| ``` |
| ## API |
| |
| ### wrap(min, max, value) |
| |
| Normalizes a values that "wraps around". For example, in a polar coordinate system, 270˚ can also be |
| represented as -90˚. |
| For wrapping purposes we assume `max` is functionally equivalent to `min`, and that `wrap(max + 1) === wrap(min + 1)`. |
| Wrap always assumes that `min` is *inclusive*, and `max` is *exclusive*. |
| In other words, if `value === max` the function will wrap it, and return `min`, but `min` will not be wrapped. |
| |
| ```js |
| nr.wrap(0, 360, 0) === 0; |
| nr.wrap(0, 360, 360) === 0; |
| nr.wrap(0, 360, 361) === 1; |
| nr.wrap(0, 360, -1) === 359; |
| ``` |
| |
| You are not restricted to whole numbers, and ranges can be negative. |
| |
| ```js |
| var π = Math.PI; |
| var radianRange = nr.curry(-π, π); |
| |
| redianRange.wrap(0) === 0; |
| nr.wrap(π) === -π; |
| nr.wrap(4 * π / 3) === -2 * π / 3; |
| ``` |
| |
| ### limit(min, max, value) |
| |
| Normalize the value by bringing it within the range. |
| If `value` is greater than `max`, `max` will be returned. |
| If `value` is less than `min`, `min` will be returned. |
| Otherwise, `value` is returned unaltered. |
| Both ends of this range are *inclusive*. |
| |
| ### test(min, max, value, [minExclusive], [maxExclusive]) |
| |
| Returns `true` if `value` is within the range, `false` otherwise. |
| It defaults to `inclusive` on both ends of the range, but that can be |
| changed by setting `minExclusive` and/or `maxExclusive` to a truthy value. |
| |
| ### validate(min, max, value, [minExclusive], [maxExclusive]) |
| |
| Returns `value` or throws an error if `value` is outside the specified range. |
| |
| ### name(min, max, value, [minExclusive], [maxExclusive]) |
| |
| Returns a string representing this range in |
| [range notation](https://en.wikipedia.org/wiki/Interval_(mathematics)#Classification_of_intervals). |
| |
| ### curry(min, max, [minExclusive], [maxExclusive]) |
| |
| Convenience method for currying all method arguments except `value`. |
| |
| ```js |
| var angle = require('normalize-range').curry(-180, 180, false, true); |
| |
| angle.wrap(270) |
| //=> -90 |
| |
| angle.limit(200) |
| //=> 180 |
| |
| angle.test(0) |
| //=> true |
| |
| angle.validate(300) |
| //=> throws an Error |
| |
| angle.toString() // or angle.name() |
| //=> "[-180,180)" |
| ``` |
| |
| #### min |
| |
| *Required* |
| Type: `number` |
| |
| The minimum value (inclusive) of the range. |
| |
| #### max |
| |
| *Required* |
| Type: `number` |
| |
| The maximum value (exclusive) of the range. |
| |
| #### value |
| |
| *Required* |
| Type: `number` |
| |
| The value to be normalized. |
| |
| #### returns |
| |
| Type: `number` |
| |
| The normalized value. |
| |
| ## Building and Releasing |
| |
| - `npm test`: tests, linting, coverage and style checks. |
| - `npm run watch`: autotest mode for active development. |
| - `npm run debug`: run tests without coverage (istanbul can obscure line #'s) |
| |
| Release via `cut-release` tool. |
| |
| ## License |
| |
| MIT © [James Talmage](http://github.com/jamestalmage) |
