| [6a3a178] | 1 | # normalize-range
|
|---|
| 2 |
|
|---|
| 3 | Utility for normalizing a numeric range, with a wrapping function useful for polar coordinates.
|
|---|
| 4 |
|
|---|
| 5 | [](https://travis-ci.org/jamestalmage/normalize-range)
|
|---|
| 6 | [](https://coveralls.io/github/jamestalmage/normalize-range?branch=master)
|
|---|
| 7 | [](https://codeclimate.com/github/jamestalmage/normalize-range)
|
|---|
| 8 | [](https://david-dm.org/jamestalmage/normalize-range)
|
|---|
| 9 | [](https://david-dm.org/jamestalmage/normalize-range#info=devDependencies)
|
|---|
| 10 |
|
|---|
| 11 | [](https://nodei.co/npm/normalize-range/)
|
|---|
| 12 |
|
|---|
| 13 | ## Usage
|
|---|
| 14 |
|
|---|
| 15 | ```js
|
|---|
| 16 | var nr = require('normalize-range');
|
|---|
| 17 |
|
|---|
| 18 | nr.wrap(0, 360, 400);
|
|---|
| 19 | //=> 40
|
|---|
| 20 |
|
|---|
| 21 | nr.wrap(0, 360, -90);
|
|---|
| 22 | //=> 270
|
|---|
| 23 |
|
|---|
| 24 | nr.limit(0, 100, 500);
|
|---|
| 25 | //=> 100
|
|---|
| 26 |
|
|---|
| 27 | nr.limit(0, 100, -20);
|
|---|
| 28 | //=> 0
|
|---|
| 29 |
|
|---|
| 30 | // There is a convenient currying function
|
|---|
| 31 | var wrapAngle = nr.curry(0, 360).wrap;
|
|---|
| 32 | var limitTo10 = nr.curry(0, 10).limit;
|
|---|
| 33 |
|
|---|
| 34 | wrapAngle(-30);
|
|---|
| 35 | //=> 330
|
|---|
| 36 | ```
|
|---|
| 37 | ## API
|
|---|
| 38 |
|
|---|
| 39 | ### wrap(min, max, value)
|
|---|
| 40 |
|
|---|
| 41 | Normalizes a values that "wraps around". For example, in a polar coordinate system, 270˚ can also be
|
|---|
| 42 | represented as -90˚.
|
|---|
| 43 | For wrapping purposes we assume `max` is functionally equivalent to `min`, and that `wrap(max + 1) === wrap(min + 1)`.
|
|---|
| 44 | Wrap always assumes that `min` is *inclusive*, and `max` is *exclusive*.
|
|---|
| 45 | In other words, if `value === max` the function will wrap it, and return `min`, but `min` will not be wrapped.
|
|---|
| 46 |
|
|---|
| 47 | ```js
|
|---|
| 48 | nr.wrap(0, 360, 0) === 0;
|
|---|
| 49 | nr.wrap(0, 360, 360) === 0;
|
|---|
| 50 | nr.wrap(0, 360, 361) === 1;
|
|---|
| 51 | nr.wrap(0, 360, -1) === 359;
|
|---|
| 52 | ```
|
|---|
| 53 |
|
|---|
| 54 | You are not restricted to whole numbers, and ranges can be negative.
|
|---|
| 55 |
|
|---|
| 56 | ```js
|
|---|
| 57 | var π = Math.PI;
|
|---|
| 58 | var radianRange = nr.curry(-π, π);
|
|---|
| 59 |
|
|---|
| 60 | redianRange.wrap(0) === 0;
|
|---|
| 61 | nr.wrap(π) === -π;
|
|---|
| 62 | nr.wrap(4 * π / 3) === -2 * π / 3;
|
|---|
| 63 | ```
|
|---|
| 64 |
|
|---|
| 65 | ### limit(min, max, value)
|
|---|
| 66 |
|
|---|
| 67 | Normalize the value by bringing it within the range.
|
|---|
| 68 | If `value` is greater than `max`, `max` will be returned.
|
|---|
| 69 | If `value` is less than `min`, `min` will be returned.
|
|---|
| 70 | Otherwise, `value` is returned unaltered.
|
|---|
| 71 | Both ends of this range are *inclusive*.
|
|---|
| 72 |
|
|---|
| 73 | ### test(min, max, value, [minExclusive], [maxExclusive])
|
|---|
| 74 |
|
|---|
| 75 | Returns `true` if `value` is within the range, `false` otherwise.
|
|---|
| 76 | It defaults to `inclusive` on both ends of the range, but that can be
|
|---|
| 77 | changed by setting `minExclusive` and/or `maxExclusive` to a truthy value.
|
|---|
| 78 |
|
|---|
| 79 | ### validate(min, max, value, [minExclusive], [maxExclusive])
|
|---|
| 80 |
|
|---|
| 81 | Returns `value` or throws an error if `value` is outside the specified range.
|
|---|
| 82 |
|
|---|
| 83 | ### name(min, max, value, [minExclusive], [maxExclusive])
|
|---|
| 84 |
|
|---|
| 85 | Returns a string representing this range in
|
|---|
| 86 | [range notation](https://en.wikipedia.org/wiki/Interval_(mathematics)#Classification_of_intervals).
|
|---|
| 87 |
|
|---|
| 88 | ### curry(min, max, [minExclusive], [maxExclusive])
|
|---|
| 89 |
|
|---|
| 90 | Convenience method for currying all method arguments except `value`.
|
|---|
| 91 |
|
|---|
| 92 | ```js
|
|---|
| 93 | var angle = require('normalize-range').curry(-180, 180, false, true);
|
|---|
| 94 |
|
|---|
| 95 | angle.wrap(270)
|
|---|
| 96 | //=> -90
|
|---|
| 97 |
|
|---|
| 98 | angle.limit(200)
|
|---|
| 99 | //=> 180
|
|---|
| 100 |
|
|---|
| 101 | angle.test(0)
|
|---|
| 102 | //=> true
|
|---|
| 103 |
|
|---|
| 104 | angle.validate(300)
|
|---|
| 105 | //=> throws an Error
|
|---|
| 106 |
|
|---|
| 107 | angle.toString() // or angle.name()
|
|---|
| 108 | //=> "[-180,180)"
|
|---|
| 109 | ```
|
|---|
| 110 |
|
|---|
| 111 | #### min
|
|---|
| 112 |
|
|---|
| 113 | *Required*
|
|---|
| 114 | Type: `number`
|
|---|
| 115 |
|
|---|
| 116 | The minimum value (inclusive) of the range.
|
|---|
| 117 |
|
|---|
| 118 | #### max
|
|---|
| 119 |
|
|---|
| 120 | *Required*
|
|---|
| 121 | Type: `number`
|
|---|
| 122 |
|
|---|
| 123 | The maximum value (exclusive) of the range.
|
|---|
| 124 |
|
|---|
| 125 | #### value
|
|---|
| 126 |
|
|---|
| 127 | *Required*
|
|---|
| 128 | Type: `number`
|
|---|
| 129 |
|
|---|
| 130 | The value to be normalized.
|
|---|
| 131 |
|
|---|
| 132 | #### returns
|
|---|
| 133 |
|
|---|
| 134 | Type: `number`
|
|---|
| 135 |
|
|---|
| 136 | The normalized value.
|
|---|
| 137 |
|
|---|
| 138 | ## Building and Releasing
|
|---|
| 139 |
|
|---|
| 140 | - `npm test`: tests, linting, coverage and style checks.
|
|---|
| 141 | - `npm run watch`: autotest mode for active development.
|
|---|
| 142 | - `npm run debug`: run tests without coverage (istanbul can obscure line #'s)
|
|---|
| 143 |
|
|---|
| 144 | Release via `cut-release` tool.
|
|---|
| 145 |
|
|---|
| 146 | ## License
|
|---|
| 147 |
|
|---|
| 148 | MIT © [James Talmage](http://github.com/jamestalmage)
|
|---|
