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

[IntegralPilot]

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: ACP: Add clamp_magnitude method to float and signed integer primitives libs-team#686
• Implementation: PR to be made soon
• Final comment period (FCP)¹
• Stabilization PR

Unresolved Questions

• None yet.

Footnotes

1. https://std-dev-guide.rust-lang.org/feature-lifecycle/stabilization.html ↩

[IntegralPilot]

@rustbot claim

[interactive-toast]

If/when this is stabilized, should a style lint be added to clippy to suggest this method instead of val.clamp(-limit, limit)?

Apologies if this isn't the right place for clippy discussion.