`Math.clamp` strawman

I believe the most important feature from the Math extensions proposal (last presented in 2016) is the Math.clamp function but the proposal as a whole has since gone quiet. Perhaps it was its amibition for features had eventually caused a roadblock in development.

But regardless, I wanted to take out only the Math.clamp function from the proposal and improve upon it in its own proposal. I'm not sure how the process of finding a champion, or for that matter, getting feedback in the first place goes, but I'll just put this out there.

Proposal: GitHub - Richienb/proposal-math-clamp: ECMAScript proposal and reference implementation for `Math.clamp`.

6 Likes

Could also support BigInt from the get go, if this other proposal advances.

You might want to reach out to @jschoi and see if they would be interested in championing this proposal. Seems like it would be easy to argue that it is motivated.

I am interested in championing (the explainer linked above looks pretty good), but I probably would not have the bandwidth to do so until after at least BigInt Math resolves.

2 Likes

FWIW, it is mathematically the same as a median function with 3 numbers (in any order), so this thread may be related: typedarray.p.[median() | lowerQuartile() | upperQuartile()].

1 Like

They are not the same. Median of 3 must do 3 comparisons, clamp only does 2. Clamp doesn't bother checking whether low <= high, you're supposed to "sort" the boundary arguments. When low > high, clamp returns low (or high, may depend on implementation), not the median.

1 Like

Well, that’s why I said they are mathematically the same. Personally I don’t think returning low or high when low > high is a good idea though.

I was just about to post a proposal for Math.clamp() as well. Not only is it a more human-friendly alternative to Math.min() or Math.max() for clamping operations, it also improves parity with CSS math functions, which already have clamp().

In fact, I find clamp() easier to use even when you only have a minimum or only a maximum, so we may want to handle undefined specially (though that would happen anyway with the current algorithm)

1 Like

An API that is used with undefined as one of the arguments seems a bit cumbersome, was thinking more like an options bag {min, max}.

Not a bad thought, but I'm discovering a complication in the project I'm working on right now: critical hot-path loops really need to be written in a zero-alloc style to avoid GC churn, and an options bag is an object. I'd need to preallocate the bag, and then usage becomes unwieldy:

const minmaxBag = {min: -Infinity, max: Infinity};
const minBag = {min: -Infinity};
const maxBag = {max: Infinity};

while (highPerformanceLoop) {
    minmaxBag.min = lowerBound;
    minmaxBag.max = upperBound;
    outputValue = Math.clamp(inputValue, minmaxBag);
}

I think I'd prefer a set of three functions:

Math.clamp(value, min, max)
Math.clampToMax(value, max)
Math.clampToMin(value, min)

the latter two are functionally equivalent to Math.min and Math.max (respectively! note the opposite max/min!) but they provide a clearer indication of intent. I know it always feels very weird to me to be writing a Math.min() call when what I'm trying to do is set a maximum for a value; I'd much rather call a function named Math.clampToMax() in that case.

I'm still not a fan of multiple function names here. I don't think the slight increase in clarity is worth the moderate decrease in ease-of-use when something might have a max or a min (or both) at runtime; you have to test and branch if you have multiple functions, versus just setting the min/max bound to null and calling the single function normally.

While using undefined specifically to indicate a missing bound is slightly unwieldy, allowing undefined or null looks a lot better, I think:

Math.clamp(val, min, max)
Math.clamp(val, null, max)
Math.clamp(val, min, null)

For example, assume you're pulling some JSON data which specifies the min and/or max for something. With multiple functions, you have to write:

var clampedVal = data.min == null && data.max == null ? val :
                 data.min == null ? Math.clampToMax(val, data.max) :
                 data.max == null ? Math.clampToMax(val, data.min) :
                 Math.clamp(val, data.min, data.max);

vs

var clampedVal = Math.clamp(val, data.min, data.max);
3 Likes

I like that version better than mine, that gets my vote :smile: the fact that null is representable in JSON makes it even better.

After accepting null/undefined in Math.clamp, I still want to consider keeping the other functions around for syntactic sugar. Specifically, their use case is to be a more explicit formulation of:

// Clamp to an upper bound of 10
Math.min(measurement, 10);

With only Math.clamp, it would be:

Math.clamp(measurement, Number.NEGATIVE_INFINITY, 10);

After:

Math.clampMax(measurement, 10);

I'm inspired by torch.clamp which, being a Python library, allows this sort of magic:

import torch

torch.clamp(x, 0, 10)
torch.clamp(x, min=0)
torch.clamp(x, max=10)