Add Math.clamp

[DartBot]

This issue was originally filed by [email protected]

---

Please add a function to the Math class that clamps a value between a minimum and a maximum, like so:

a = Math.clamp( a, -1, 1 );

This would behave identically to:

a = Math.max( -1, Math.min( 1, a ) );

[DartBot]

This comment was originally written by [email protected]

---

Here's a patch with an implementation and tests.

---

Attachment:
clamp.diff (1.36 KB)

[DartBot]

This comment was originally written by [email protected]

---

What should happen if lower >= upper?

[DartBot]

This comment was originally written by [email protected]

---

Removed Type-Defect label.
Added Type-Enhancement label.

[DartBot]

This comment was originally written by [email protected]

---

It should probably throw an exception like the functions in Date do.

Side note: should the docs for Expect.throws() mention the () => foo() syntax? I at least had to poke around for a bit to figure it out.

---

Attachment:
clamp_v2.diff (1.51 KB)

[DartBot]

This comment was originally written by [email protected]

---

Added Area-Language, Triaged labels.

[DartBot]

This comment was originally written by [email protected]

---

It's probably worth noting here that this idea was received pretty warmly over on Reddit. http://www.reddit.com/r/programming/comments/l6uwv/dart_programming_language/c2q9sbc

[gbracha]

Removed Area-Language label.
Added Area-Library label.

[floitschG]

We are discussing the idea. Currently we are tending towards adding it to the num interface. Ex:
x.clamp(1, 3);
instead of
Math.clamp(x, 1, 3);

[DartBot]

This comment was originally written by [email protected]

---

I don't see if lower = upper as an issue. Just return lower or upper, which is almost certainly what the programmer would want. If lower > upper, than it would make sence to which lower and upper around. Although this is probably the best thing to do hear in terms of the programmers intentions, this would degrade performance(no more than throwing an exception would however).

[DartBot]

This comment was originally written by [email protected]

---

My vote agrees with Comment #­8. Sorry if this is considered a "Me too".. I'd like the ability to just Star a comment. :-\

[jmesserly]

Also would be good to get nearlyEquals from goog.math:

http://code.google.com/p/closure-library/source/browse/trunk/closure/goog/math/math.js

[sethladd]

cc @lrhn.
Added this to the Later milestone.

[DartBot]

This comment was originally written by [email protected]

---

@clamp_v2.diff

"if (lower >= upper) throw new IllegalArgumentException();"

That should be '>', not '>='. Using the same value for both is seemingly pointless, but it's not illegal. E.g. if you want that your 5 is at least 5 and at most 5, then, yes, you can have that totally five-y 5.

It really isn't as stupid as it sounds, seriously. Imagine there is a range slider which doesn't enforce a minimum distance between both values and you just take those values and throw them at this clamp function. Would be nice if it would work, wouldn't it?

Well, with "Math.max(Math.min(val, atLeast), atMost)" this works just fine. Naturally, it should work with a built-in clamp function, too.

[floitschG]

Set owner to @floitschG.
Added Started label.

[floitschG]

Fixed in lib_v2, r14576.

---

Added Fixed label.