diff options
Diffstat (limited to 'node_modules/normalize-range/readme.md')
| -rw-r--r-- | node_modules/normalize-range/readme.md | 148 |
1 files changed, 148 insertions, 0 deletions
diff --git a/node_modules/normalize-range/readme.md b/node_modules/normalize-range/readme.md new file mode 100644 index 0000000..29d84cd --- /dev/null +++ b/node_modules/normalize-range/readme.md @@ -0,0 +1,148 @@ +# 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) |