[sdlib] Add clamp to math module

[bgreni]

• Add clamp to the math module
• Replace private _clip function in List with clamp

[gabrieldemarmiesse]

I'm not in favor or against, just adding info here. In the Python stdlib, it's been discussed to add such a function in this mailing list the TLDR of the mailing list is that there are many different implementations of clamp in the wild and they slightly differ on the way NaN are handled. In the end it was not added to the stdlib due to the lack of concensus, mostly about NaN.

Maybe we should add information about how this new function handles NaN in the docstring? Adding a test with NaN would be good too as we should not change the way we handle them as time goes by.

[soraros]

We should also document how the max > min case is handled. There is another way out: define clamp as composition of min and max (both stablehlo and XLA took this approach), so it's not implementation detail anymore.

In other words, we can take the syntactic trait idea from #2924, and make clamp a generic function over types with HasMax and HasMin.

[bgreni]

Maybe we should add information about how this new function handles NaN in the docstring?

Since a clamp method already exists on SIMD, we'll have to just go with whatever behaviour it has?

We should also document how the max > min case is handled.

Out of curiosity I checked the std::clamp documentation and of course it's undefined behaviour...
Personally I wouldn't mind simply swapping lower and upper in that case?

[laszlokindrat]

Thanks for the patch! Is there a direct motivation for this change? As pointed out, Python's math module doesn't have a clamp method, so we don't need this for compatibility. There is also a SIMD.clamp method already, so I'm not sure we should bring this in yet.

[bgreni]

@laszlokindrat I noticed we had a private function for this in List and figured we might as well add it to the math module as a public function where it's properly tested and accounted for, and while it isn't included in Python, the C++ people might appreciate it's inclusion in this form as a free function like std::clamp.