Summary

Add functions to the language which take a value and an inclusive range, and will “clamp” the input to the range. I.E.

if input > max {
    return max;
}
else if input < min {
    return min;
} else {
    return input;
}

These would be on the Ord trait, and have a special version implemented for f32 and f64.

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:

if input > max {
    max
}
else if input < min {
    min
} else {
    input
}

and

input.max(min).min(max);

and even

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

Add the following to std::cmp::Ord

/// Returns max if self is greater than max, and min if self is less than min.  
/// Otherwise this will return self.  Panics if min > max.
#[inline]
pub fn clamp(self, min: Self, max: Self) -> Self {
    assert!(min <= max);
    if self < min {
        min
    }
    else if self > max {
        max
    } else {
        self
    }
}

And the following to libstd/f32.rs, and a similar version for f64

/// Returns max if self is greater than max, and min if self is less than min.
/// Otherwise this returns self.  Panics if min > max, min equals NaN, or max equals NaN.
///
/// # 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);
/// ```
pub fn clamp(self, min: f32, max: f32) -> f32 {
    assert!(min <= max);
    let mut x = self;
    if x < min { x = min; }
    if x > max { x = max; }
    x
}

This NaN handling behavior was chosen because a range with NaN on either side isn’t really a range at all and the function can’t be guaranteed to behave correctly if that is the case.

How We Teach This

The proposed changes would not mandate modifications to any Rust educational material.

Drawbacks

This is trivial to implement downstream, and several versions of it exist downstream.

Alternatives

Alternatives were explored at https://internals.rust-lang.org/t/clamp-function-for-primitive-types/4999

Additionally there is the option of placing clamp in std::cmp in order to avoid backwards compatibility problems. This is however semantically undesirable, as 1.clamp(2, 3); is more readable than clamp(1, 2, 3);

Unresolved questions

None