# 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)