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.
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.
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.
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)
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:
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 undefinedspecifically to indicate a missing bound is slightly unwieldy, allowing undefinedornull looks a lot better, I think:
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);