Repository files navigation

A TC39 proposal to addMath.clamp: a function that constrains a value between an upper and lower bound.

Stage: 2
Champion: Oliver Medhurst (@canadahonk)
Authors: Oliver Medhurst (@canadahonk), Richie Bendall (@richienb)
Last Presented:108th meeting

Aclamping function constrains a value between an upper and lower bound.

Our primary motivation is its usefulness andpopularity in existing projects where it is often defined for the sake of readability. A common use is for animations and interactive content. For example, it helps to keep objects in-bounds during user-controlled movement by restricting the coordinates that it can move to (see thep5.js demo for itsconstrain function). Projects tend to define a function that looks likeclamp(number, min, max), either through:

• Chaining mathematical operators with if statements or ternary operators

functionclamp(number,minimum,maximum){if(number<minimum){returnminimum;}if(number>maximum){returnmaximum;}returnnumber;}

• NestingMath.min andMath.max calls

functionclamp(number,minimum,maximum){returnMath.min(Math.max(number,minimum),maximum);}

Each of those examples require unnecessary boilerplate and are error-prone. For example, a developer only has to mistype a single operator or mix up a single variable name for the function to break. They also disregard the potential undefined behaviour that can occur when minimum is larger than maximum, or when onlymin ormax is specified.

We name it the functionclamp, like how it is in other programming languages...

• clamp in CSS
• Math.Clamp in C#
• std::clamp in the C++ standard library
• clamp forf32 andf64 in Rust
• coerceIn in Kotlin
• clamp in Dart
• clamp in Ruby
• clamp in Elm

...and userland implementations:

• clamp
• math-clamp
• lodash
• three.js
• p5.js
• ramda
• sugar
• phaser

Another motivation is to bring parity with theCSS function of the same name, although it will have a different parameter order because of the slightly different use cases in each context (see alsothe previous discussion on the order of options for CSSclamp.

The original proposal intended to have themin andmax arguments optional and allowingnull orundefined as values to mean no upper/lower bound; but followingrecent TC39 requirements, it was agreed among some delegates that it would be best to not do this, especially sinceMath.min/Math.max remains available for uses with a single bound.

The proposed API allows a developer to clamp numbers like:

Math.clamp(5,0,10)// 5Math.clamp(-5,0,10)// 0Math.clamp(15,0,10)// 10

It supports-Infinity/Infinity to specify when there is no upper or lower bound, althoughMath.min/Math.max are also already available to use:

Math.clamp(5,0,Infinity)===Math.max(5,0)// 5Math.clamp(-5,-Infinity,10)===Math.min(-5,10)// -5

If the minimum bound is larger than the maximum bound, it throws aRangeError to avoid possible developer confusion:

Math.clamp(10,5,0)// RangeError

It also correctly respects-0 if given:

Math.clamp(-2,-0,10)// -0Math.clamp(-0,-0,10)// -0Math.clamp(0,-0,10)// 0

• Ecmarkup source
• HTML version

Past work:

• Math Extensions Proposal