Add clamp to scala.math and numeric types

[exoego]

Clamping numbers between an upper and lower bound is a relatively-common task, specially in graphics domain.

• https://en.wikipedia.org/wiki/Clamping_(graphics)
• DotNet's math
• Android's MathUtils
• CSS math function

Currently, Java and Scala standard library does not offer such functionality, so users need to write something like max(LOWER_BOUND, min(VALUE, UPPER_BOUND)) which is error-prone.

I propose adding clamp function to math.
Adding clamp to numeric types (e.g. Int or Double) may be good to have, in analogus to max/min.

[NthPortal]

I propose the API def clamp(lower: Int, upper: Int)(value: Int): Int for the following reasons:

• two argument lists makes the order and meaning of the arguments unambiguous
• having the bounds first make it easier and cleaner to partially apply (e.g. val clamp = math.clamp(0, 10))

[Ichoran]

In my personal library, I have it only as an extension method, and I called it clip, with arguments clip(min, max). This lets you write things like

x clip (0, 1.5)

which is very clear. So I would recommend x clamp (0, 1.5).

If you want a static method equivalent, I think clamp(x)(0, 1.5) is a lot more natural. I don't think the ability to partially apply is as important as the flow.

[NthPortal]

I think it is also valuable to have it as an extension method (like min and max); however, I think having it in math should be the "core"

[NthPortal]

see also scala/scala#8510