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.)

Unresolved Questions

None yet.

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

@rustbot

@rustbot claim

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.

Yes, that's a great idea. I mentioned it in the original ACP, I think it would be a good way to drive implementation of the new, more ergonomic method. :)

Rollup merge of rust-lang#148690 - IntegralPilot:clamp-mag, r=joboet

Unrolled build for #148690

@rustbot

@rustbot label +S-tracking-needs-to-bake -S-tracking-unimplemented

Will try and put some calls for testing out and see if there's any feedback or suggestions for changes for a few weeks before stabilising, S-tracking-needs-to-bake seemed the most appropriate S-tracking-* tag.

Rollup merge of #148690 - IntegralPilot:clamp-mag, r=joboet

Rollup merge of rust-lang#148690 - IntegralPilot:clamp-mag, r=joboet

It seems like you may have forgotten about this issue. That's a shame, since I think it would be nice if this was stabilized. I've noticed one problem with the method, and have two suggestions:

When you pass in NaN as limit in the float versions of clamp_magnitude, the error message is still the one used when limit is negative (limit must be non-negative) because the check for limit being non-negative is limit >= 0.0, which is false for NaN since it is unordered.
Since clamp is const, clamp_magnitude should also be const.
NonZero should also have clamp_magnitude.

I can implement some changes if you're very busy.

Oh yes, sorry this did slip my mind! Thank you for the suggestions, I think they sound good and agree with them! I am a bit busy (IBDP arghhh), so would really appreciate you implementing them if you have the time! :)

Rollup merge of rust-lang#163279 - Eleocraft:clamp-magnitude-unsigned…

Unrolled build for #163279 in rollup 163583

Rollup merge of #163279 - Eleocraft:clamp-magnitude-unsigned-limit, r…

When you pass in NaN as limit in the float versions of clamp_magnitude, the error message is still the one used when limit is negative (limit must be non-negative) because the check for limit being non-negative is limit >= 0.0, which is false for NaN since it is unordered.

Since clamp is const, clamp_magnitude should also be const.

NonZero should also have clamp_magnitude.

These issues should be closed with the merging of PR #163279. I think this feature is ready for the next steps.

Rollup merge of #163279 - Eleocraft:clamp-magnitude-unsigned-limit, r…

Navigation Menu

Repository navigation

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

Public API

Steps / History

Unresolved Questions

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Tracking Issue for clamp_magnitude method on float and signed integer primitives #148519

Description

Public API

Steps / History

Unresolved Questions

Footnotes

Activity

IntegralPilot commented on Nov 5, 2025

interactive-toast commented on Nov 6, 2025

IntegralPilot commented on Nov 7, 2025

IntegralPilot commented on Dec 2, 2025

IntegralPilot commented on Dec 2, 2025

joseph-b-baud commented on Jun 16, 2026

IntegralPilot commented on Jun 18, 2026

Eleocraft commented on Oct 2, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

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