proposal: math: add Clamp function

[gucio321]

somethimes, I need to get a number clamped in a range. I think math package would be appropiate to add such a Clamp function.

Also, for some percentage calculation, Clamp01 method is useful as well.

(see #58144)

[seankhliao]

What are the proposed function signatures?
Can you demonstrate why it should be in the standard library other than "it is sometimes useful"? ref https://go.dev/doc/faq#x_in_std

[gucio321]

Can you demonstrate why it should be in the standard library other than "it is sometimes useful"?

Both of these functions, are parts of so called "standard libraries" in most of programming languages I know (C#, C++, rust).
ref: https://learn.microsoft.com/en-us/dotnet/api/system.math.clamp?view=net-7.0, https://en.cppreference.com/w/cpp/algorithm/clamp, https://docs.rs/num/0.2.1/num/fn.clamp.html

[earthboundkid]

Clamp seems like a good idea, although I don't think math.Clamp01(v) is more clear than just math.Clamp(v, 0, 1). One question is whether this should wait for some kind of math/v2 with a generic Min, Max, etc.

Hmm, thinking out loud 🤔 :

• Deprecate all the functions in math.
• Add math/float and copy the existing math functions there. If it's practical to make them generic over float32/64 do it, but otherwise, just have them work with float64.
• Add math/compare and put generic Min, Max, Clamp, and Compare(a, b) → -1,0,1 in it.

[gucio321]

I don't think math.Clamp01(v) is more clear than just math.Clamp(v, 0, 1).

It is quit useful if you do e.g. percentage operations or something like that. And Clamp01 VS Clamp(value, 0, 1) means less writing and if someone sees Clamp01 he already knows exactly the purpose of the statement. However I don't insist, I can limit this proposal to Clamp method only, if you think it would be better to leave Clamp01 for now.

One question is whether this should wait for some kind of math/v2 with a generic Min, Max, etc.

Personally, I don't think so. If current math api bases on float64s, we should leave it this way and any extensions should match this api for now. The other thing is that I find generics support in math library extremely useful, since making these conversions from float32 to 64 and back and again and so... makes using math annoying tbh.

Deprecate all the functions in math.
Add math/float and copy the existing math functions there. If it's practical to make them generic over float32/64 do it, but otherwise, just have them work with float64.

In my opinion deprecating current math is not really necessary.
If making it generic without breaking compatibility promise really IS NOT possible (it should be discussed tbh)
A subpackage (e.g. math/generic) should be created

[codenoid]

Rust has it

and, It's better to be math.Clamp only (wihout 01)

[gophun]

@codenoid "Language X has it" is usually not a viable argument, otherwise Go would have to become a superset of all other languages.

[earthboundkid]

I dunno, "language X has feature Y" isn't a definitive argument, but it is slight evidence for the usefulness of feature Y. A little bit of counter-evidence is that JavaScript has Math.max and Math.min, but not Math.clamp. I still lean towards math.Clamp being a good idea, but it should be part of a larger generic reorg, like #58559 (comment).

[rsc]

This proposal has been added to the active column of the proposals project
and will now be reviewed at the weekly proposal review meetings.
— rsc for the proposal review group

[rsc]

math.Clamp(x, min, max float64) float64 seems okay although perhaps not above the bar.
Our current rule for the math package is that the bar is "what's in the C <math.h> library".
A generic math.Clamp that works on ints (or strings?)
would have to wait for a math/v2 or some other answer to generics in std.

math.Clamp01 seems too special-purpose either way.