Add clamp RFC

text/0000-clamp.md

@@ -0,0 +1,141 @@
+- Feature Name: clamp functions
+- Start Date: 2017-03-26
+- RFC PR: (leave this empty)
+- Rust Issue: (leave this empty)
+
+# Summary
+[summary]: #summary
+
+Add functions to the language which take a value and an inclusive range, and will "clamp" the input to the range.  I.E.
+
+```Rust
+if input > max {
+    return max;
+}
+else if input < min {
+    return min;
+} else {
+    return input;
+}
+```
+
+Likely locations would be in std::cmp::clamp implemented for all Ord types, and a special version implemented for f32 and f64.
+The f32 and f64 versions could live either in std::cmp or in the primitive types themselves.  There are good arguments for either
+location.
+
+# Motivation
+[motivation]: #motivation
+
+Clamp is a very common pattern in Rust libraries downstream.  Some observed implementations of this include:
+
+http://nalgebra.org/rustdoc/nalgebra/fn.clamp.html
+
+http://rust-num.github.io/num/num/fn.clamp.html
+
+Many libraries don't expose or consume a clamp function but will instead use patterns like this:
+```Rust
+if input > max {
+    max
+}
+else if input < min {
+    min
+} else {
+    input
+}
+```
+and
+```Rust
+input.max(min).min(max);
+```
+and even
+```Rust
+match input {
+    c if c >  max =>  max,
+    c if c < min => min,
+    c              =>  c,
+}
+```
+
+Typically these patterns exist where there is a need to interface with APIs that take normalized values or when sending 
+output to hardware that expects values to be in a certain range, such as audio samples or painting to pixels on a display.
+
+While this is pretty trivial to implement downstream there are quite a few ways to do it and just writing the clamp 
+inline usually results in rather a lot of control flow structure to describe a fairly simple and common concept.
+
+# Detailed design
+[design]: #detailed-design
+
+Add the following to std::cmp
+
+```Rust
+/// Returns max if input is greater than max, and min if input is less than min.  
+/// Otherwise this will return input.
+#[inline]
+pub fn clamp<T: Ord>(input: T, min: T, max: T) -> T {
+    if input < min {
+        min
+    }
+    else if input > max {
+        max
+    }
+    else {
+        input
+    }
+}
+```
+
+And the following to libstd/f32.rs, and a similar version for f64
+
+```Rust
+/// Returns max if self is greater than max, and min if self is less than min.
+/// Otherwise this returns self.
+///
+/// # Examples
+///
+/// ```
+/// assert!((-3.0f32).clamp(-2.0f32, 1.0f32) == -2.0f32);
+/// assert!((0.0f32).clamp(-2.0f32, 1.0f32) == 0.0f32);
+/// assert!((2.0f32).clamp(-2.0f32, 1.0f32) == 1.0f32);
+/// ```
+#[inline]
+pub fn clamp(self, min: f32, max: f32>) -> f32 {
+    if input < min {
+        min
+    }
+    else if input > max {
+        max
+    }
+    else {
+        input
+    }
+}
+```
+
+There are 3 special float values the clamp function will need to handle, and 3 positions into which they can go so I will represent
+the edge case behavior with a 3x3 chart.
+
+|  |INFINITY|NEG_INFINITY|NAN|
+|---|---|---|---|
+|self|return max;|return min;|return NAN;|
+|max|No max enforced|return NEG_INFINITY;|No max enforced|
+|min|return INFINITY;|No min enforced|No min enforced|
+
+# How We Teach This
+[how-we-teach-this]: #how-we-teach-this
+
+The proposed changes would not mandate modifications to any Rust educational material.
+
+# Drawbacks
+[drawbacks]: #drawbacks
+
+This is trivial to implement downstream, and several versions of it exist downstream.
+
+# Alternatives
+[alternatives]: #alternatives
+
+Alternatives were explored at https://internals.rust-lang.org/t/clamp-function-for-primitive-types/4999
+
+# Unresolved questions
+[unresolved]: #unresolved-questions
+
+Should the float version of the clamp function live in f32 and f64, or in std::cmp as that's where the Ord version would go?