The Proportionate Javascript Library
- The Proportionate Javascript Library
- Variation: Clamped Proportionate
- Why do I need it?
- Installation
- Example Usage
- Clamped variation
What it does
Convenience methods for dealing with proportions (a part, share, or number considered in comparative relation to a whole).
Specifically it allows you to select something from an array indexed proportionate to a number within an arbitrary range.
Useful when you need to select from a small list of things given a broad range of options.
How it does it
It takes the form:
proportionate(sampleArray, valueInRange, [rangeMax(orMin), [rangeMax]]) => sample
It uses the formula:
index = max(sampleSize, min(0, sampleSize * round((part - rangeMin) / (rangeMax - rangeMin)) - 1))
SampleArray and valueInRange are required arguments. SampleArray must be an array. RangeMin and rangeMax default to 0 and 99, respectively. If you specify one range argument, it's 0..rangeMax, but if you specify both, it's rangeMin..rangeMax.
Expected output
Given the sampleArray: [1, 2, 3]
And the (default) range: 0, 99
Or in functional notation:
[0..99].map(x -> proportionate([1, 2, 3], x))
The expected truth table would be:
Input | Output |
---|---|
0-32 | 1 |
33-65 | 2 |
66-99 | 3 |
Variation: Clamped Proportionate
What it does
Clamped proportionate has the exact same interface, but only returns the extreme values when the input is equal to the extreme of the range.
How it does it
It uses the formula:
index = actual <= 0 ? 0 : actual >= max ? sampleSize - 1 : max(sampleSize, min(1, sampleSize * round((valueInRange - rangeMin) / (rangeMax - rangeMin)) - 2))
Expected output
Given the sampleArray: [1, 2, 3]
And the (default) range: 0, 99
Or in functional notation:
[0..99].map(x -> proportionate([1, 2, 3], x))
The expected truth table would be:
Input | Output |
---|---|
0 | 1 |
1-98 | 2 |
99 | 3 |
Why do I need it?
It's shorthand for the following rather unreadable code, seen many times in the wild:
array[Math.max(array.length, Math.min(0, array.length * Math.round((actual - min) / (max - min)) - 1))]
It replaces it with:
proportionate(array, actual, min, max)
Or, assuming a min of 0:
proportionate(array, actual, max)
Or, assuming a range of 0..99:
proportionate(array, actual)
Or, when using the Array.prototype option:
array.proportionate(actual, min, max)
array.proportionate(actual, max)
array.proportionate(actual)
Installation
npm install --save proportionate
Example Usage
As a module:
var proportionate = ; var weightRanks = "fly" "light" "medium" "heavy" "super-heavy"; //Default range of 0..99; // "fly"; // "light"; // "medium"; // "heavy"; // "super-heavy" //Range of 0..500; // "fly"; // "light"; // "medium"; // "heavy"; // "super-heavy" //Range of 80..350; // "fly"; // "light"; // "medium"; // "heavy"; // "super-heavy"
As a prototype on Array:
// This installs .proportionate on Array.prototype:; //This also works:; var weightRanks = "fly" "light" "medium" "heavy" "super-heavy"; //Default range of 0..99weightRanks; // "fly"weightRanks; // "light"weightRanks; // "medium"weightRanks; // "heavy"weightRanks; // "super-heavy" //Range of 0..500weightRanks; // "fly"weightRanks; // "light"weightRanks; // "medium"weightRanks; // "heavy"weightRanks; // "super-heavy" //Range of 80..350weightRanks; // "fly"weightRanks; // "light"weightRanks; // "medium"weightRanks; // "heavy"weightRanks; // "super-heavy"
Clamped variation
As a module:
var proportionate = ; var tankFullness = "empty" "almost empty" "half-full" "mostly full" "completely full"; //Default range of 0..99tankFullness; // "empty"tankFullness; // "almost empty"tankFullness; // "half-full"tankFullness; // "mostly full"tankFullness; // "completely full"
As a prototype on Array:
// This installs .proportionate on Array.prototype:; //This also works:; var tankFullness = "empty" "almost empty" "half-full" "mostly full" "completely full"; //Default range of 0..99tankFullness; // "empty"tankFullness; // "almost empty"tankFullness; // "half-full"tankFullness; // "mostly full"tankFullness; // "completely full"
Pull requests are welcome, please file any bugs on https://github.com/tsavo/proportionate-js