math

Math utilities.

ceil(val[, step]):Number

Round value up to full steps. Similar to Math.ceil() but can round value to an arbitrary radix.

ceil(7.2);   // 8
ceil(7.8);   // 8
ceil(7, 5);  // 10
ceil(11, 5); // 15
ceil(15, 5); // 15

Common use cases

Round values by increments of 5/10/1000/etc.

See: round(), floor(), countSteps()

clamp(val, min, max):Number

Clamps value inside range.

clamp() is extremely useful in cases where you need to limit a value inside a certain range. So instead of doing a complex if/else to filter/process the value you can restrict it to always be inside the desired range:

clamp(-5, 0, 10); // 0
clamp(7, 1, 10);  // 7
clamp(8, 1, 10);  // 8
clamp(10, 1, 10); // 10
clamp(11, 1, 10); // 10

If the value is smaller than min it returns the min, if val is higher than max it returns max.

Common use cases

Any situation where you need to limit a number inside a range like: slider position, image galleries (so user can't skip to an image that doesn't exist), drag and drop, scroll boundaries, etc.

See: loop()

countSteps(val, step[, overflow]):Number

Count number of full steps.

Arguments:

1. val (Number) : Value.
2. step (Number) : Step size.
3. [overflow] (Number) : Maximum number of steps, nSteps will loop if >= than overflow.

Count steps is very useful for cases where you need to know how many "full steps" the number completed. Think of it as a division that only returns integers and ignore remainders.

countSteps(3,  5);    // 0
countSteps(6,  5);    // 1
countSteps(12, 5);    // 2
countSteps(18, 5);    // 3
countSteps(21, 5);    // 4

You can also set an overflow which will reset the counter before reaching this number.

countSteps(3, 5, 3);  // 0
countSteps(6, 5, 3);  // 1
countSteps(12, 5, 3); // 2
countSteps(18, 5, 3); // 0
countSteps(21, 5, 3); // 1

Common use cases

How many items fit inside an area:

var containerWidth = 100;
var itemWidth = 8;
var howManyFit = countSteps(containerWidth, itemWidth); // 12

Split value into different scales or convert value from one scale to another

From mout/time/parseMs:

function parseMs(ms){
    return {
        milliseconds : countSteps(ms, 1, 1000),
        seconds      : countSteps(ms, 1000, 60),
        minutes      : countSteps(ms, 60000, 60),
        hours        : countSteps(ms, 3600000, 24),
        days         : countSteps(ms, 86400000)
    };
}

// {days:27, hours:4, minutes:26, seconds:5, milliseconds:454}
parseMs(2348765454);

floor(val[, step]):Number

Round value down to full steps. Similar to Math.floor() but can round value to an arbitrary radix. (formerly snap)

floor(7.2);   // 7
floor(7.8);   // 7
floor(7, 5);  // 5
floor(11, 5); // 10
floor(15, 5); // 15

Common use cases

Round values by increments of 5/10/1000/etc.

See: round(), ceil(), countSteps()

inRange(val, min, max[, threshold]):Boolean

Checks if value is inside the range.

inRange(-6, 1, 10);    // false
inRange( 5, 1, 10);    // true
inRange(12, 1, 10);    // false

The threshold can be useful when you want granular control of what should match and/or the precision could change at runtime or by some configuration option, avoids the clutter of adding/subtracting the threshold from mix and max.

inRange(12, 1, 10, 2); // true
inRange(13, 1, 10, 2); // false

Common use cases

Anything that needs to check if value is inside a range, be it collision detection, limiting interaction by mouse position, ignoring parts of the logic that shouldn't happen if value isn't valid, simplify if/else conditions, making code more readable, etc...

isNear(val, target, threshold):Boolean

Check if value is close to target.

Similar to inRange() but used to check if value is close to a certain value or match the desired value. Basically to simplify if/else conditions and to make code clearer.

isNear( 10.2, 10, 0.5); // true
isNear( 10.5, 10, 0.5); // true
isNear(10.51, 10, 0.5); // false

Common use cases

Games where a certain action should happen if an actor is close to a target, gravity fields, any numeric check that has some tolerance.

lerp(ratio, start, end):Number

Linear interpolation.

lerp(0.5, 0, 10);  // 5
lerp(0.75, 0, 10); // 7.5

Common use cases

Linear interpolation is commonly used to create animations of elements moving from one point to another, where you simply update the current ratio (which in this case represents time) and get back the position of the element at that "frame".

The core idea of lerp is that you are using a number that goes from 0 to 1 to specify a ratio inside that scale. This concept can be applied to convert numbers from different scales easily.

See: map(), norm()

loop(val, min, max):Number

Loops value inside range. Will return min if val > max and max if val < min, otherwise it returns val.

loop(-1, 0, 10); // 10
loop( 1, 0, 10); // 1
loop( 5, 0, 10); // 5
loop( 9, 0, 10); // 9
loop(10, 0, 10); // 10
loop(11, 0, 10); // 0

Similar to clamp() but loops the value inside the range when an overflow occurs.

Common use cases

Image galleries, infinite scroll, any kind of logic that requires that the first item should be displayed after the last one or the last one should be displayed after first if going on the opposite direction.

See: clamp()

map(val, min1, max1, min2, max2):Number

Maps a number from one scale to another.

map(3, 0, 4, -1, 1)   // 0.5
map(3, 0, 10, 0, 100) // 30

Common use cases

Very useful to convert values from/to multiple scales.

Let's suppose we have a slider that needs to go from 2000 to 5000 and that slider has 300px of width, here is how we would translate the knob position into the current value:

var knobX = 123;
var sliderWid = 300;
var minVal = 2000;
var maxVal = 5000;

var curVal = map(knobX, 0, sliderWid, minVal, maxVal); // 3230

See: lerp(), norm()

norm(val, min, max):Number

Gets normalized ratio of value inside range.

If val < min or val > max it will throw a RangeError since we can't normalize the value.

norm(50, 0, 100); // 0.5
norm(75, 0, 100); // 0.75
norm(100, 0, 100); // 1
norm(-50, 0, 100); // RangeError: value (-50) must be between 0 and 100

Common use cases

Convert values between scales, used by map() internally. Direct opposite of lerp().

See: lerp(), map()

overflow(val[, min], max):Number

Wraps number within [min, max). When no min is given, the value 0 is assumed. A number larger or equal max loops around and starts over at min. For positive numbers larger or equal max this method behaves identical to the modulo operator. Numbers smaller than min loop around and start over at max.

overflow(13, 5, 10); // 8
overflow(3, 5, 10); // 8
overflow(23, 5); // 3
overflow(-10, -7, -1); // -4

See: loop()

round(val[, step]):Number

Round value to full steps. Similar to Math.round() but allow setting an arbitrary radix.

// default
round(0.22);      // 0
round(0.49);      // 0
round(0.51);      // 1

// custom radix
round(0.22, 0.5); // 0
round(0.49, 0.5); // 0.5
round(0.51, 0.5); // 0.5
round(0.74, 0.5); // 0.5
round(0.75, 0.5); // 1
round(1.24, 0.5); // 1
round(1.25, 0.5); // 1.5
round(1.74, 0.5); // 1.5

Common use cases

Round values by increments of 0.5/5/10/1000/etc.

See: floor(), ceil(), countSteps()

---

For more usage more info check the specs and source code.