Tracking Issue for `clamp_magnitude` method on float and signed integer primitives

Feature gate: #![feature(clamp_magnitude)]

This is a tracking issue for the clamp_magnitude method on primitive signed integer and floating-point types.

This method provides an ergonomic and intention-revealing way to clamp a numeric value to a symmetric range [-limit, limit]. This is a common operation in domains like graphics, physics, and signal processing, and is currently written as value.clamp(-limit, limit). The dedicated method improves clarity, reduces the chance of typos, and better conveys the developer's intent.

Public API

The proposed API adds the clamp_magnitude method to all primitive signed integer and floating-point types.

// For floating-point types
impl f16 {
    /// Clamps this number to a symmetric range centred around zero.
    ///
    /// The method clamps the number's magnitude (absolute value) to be at most `limit`.
    ///
    /// This is functionally equivalent to `self.clamp(-limit, limit)`, but is more
    /// explicit about the intent.
    ///
    /// # Panics
    ///
    /// Panics if `limit` is negative or NaN, as this indicates a logic error.
    #[must_use = "this returns the clamped value and does not modify the original"]
    pub fn clamp_magnitude(self, limit: f16) -> f16;
}
impl f32 {
    /// Same doc-comment as f16
    #[must_use = "this returns the clamped value and does not modify the original"]
    pub fn clamp_magnitude(self, limit: f32) -> f32;
}

impl f64 {
    /// Same doc-comment as f16
    #[must_use = "this returns the clamped value and does not modify the original"]
    pub fn clamp_magnitude(self, limit: f64) -> f64;
}

impl f128 {
    /// Same doc-comment as f16
    #[must_use = "this returns the clamped value and does not modify the original"]
    pub fn clamp_magnitude(self, limit: f128) -> f128;
}

// For signed integer types
impl i8 {
    /// Clamps this number to a symmetric range centred around zero.
    ///
    /// The method clamps the number's magnitude (absolute value) to be at most `limit`.
    ///
    /// This is functionally equivalent to `self.clamp(-limit, limit)`, but is more
    /// explicit about the intent.
    #[must_use = "this returns the clamped value and does not modify the original"]
    pub fn clamp_magnitude(self, limit: u8) -> i8;
}

impl i16 {
    /// Same doc-comment as i8
    #[must_use = "this returns the clamped value and does not modify the original"]
    pub fn clamp_magnitude(self, limit: u16) -> i16;
}

impl i32 {
    /// Same doc-comment as i8
    #[must_use = "this returns the clamped value and does not modify the original"]
    pub fn clamp_magnitude(self, limit: u32) -> i32;
}

impl i64 {
    /// Same doc-comment as i8
    #[must_use = "this returns the clamped value and does not modify the original"]
    pub fn clamp_magnitude(self, limit: u64) -> i64;
}

impl i128 {
    /// Same doc-comment as i8
    #[must_use = "this returns the clamped value and does not modify the original"]
    pub fn clamp_magnitude(self, limit: u128) -> i128;
}

impl isize {
    /// Same doc-comment as i8
    #[must_use = "this returns the clamped value and does not modify the original"]
    pub fn clamp_magnitude(self, limit: usize) -> isize;
}

Steps / History

(Remember to update the S-tracking-* label when checking boxes.)

• ACP: rust-lang/libs-team#686
• Implementation:
  • PR made: #148690
  • PR approved
  • PR landed in rollup merge - #149510
  • PR landed in nightly - just checked and works in latest nightly
• Community feedback
  • Post calls for testing
    • Discord
    • This week in rust (?)
    • Reddit
  • Collect feedback
• Final comment period (FCP)^1
• Stabilization PR

Unresolved Questions

• None yet.