Tracking Issue for NonZeroXxx::from_mut/from_mut_unchecked (nonzero_from_mut)

[SOF3]

Feature gate: #![feature(nonzero_from_mut)]

This is a tracking issue for the associated functions NonZeroXxx::from_mut and NonZeroXxx::from_mut_unchecked.

These associated functions allow converting a mutable reference to a primitive integer (&mut xxx) into the equivalent &mut NonZeroXxx, with or without validation. The safety is guaranteed by the mutable reference, but currently there is no way to perform this conversion without relying on an unsafe transparent cast.

Public API

// core::num

// $NonZeroInt is one of all signed and unsigned non-zero integer types in core::num,
// and $int is the corresponding primitive type.
impl $NonZeroInt {
    pub fn from_mut(n: &mut $int) -> Option<&mut $NonZeroInt>;
    pub unsafe fn from_mut_unchecked(n: &mut int) -> &mut $NonZeroInt;
}

Steps / History

• ACP: Add NonZeroXxx::from_mut libs-team#129
• Implementation: Added NonZeroXxx::from_mut(_unchecked)? #103730
• Final comment period (FCP)¹
• Stabilization PR

Unresolved Questions

• None yet.

Footnotes

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

[zachs18]

NonZero::from_mut could return &mut Option<Self> instead of Option<&mut Self>, due to the layout guarantee that 0 is None::<NonZero<_>>¹. This would be strictly more powerful (you could get a Option<&mut Self> with Option::as_mut after the cast; in fact, that is how from_mut is currently implemented).

Also, note that you can do this cast (checked, returning Option<NonZero<_>>) using bytemuck and zerocopy on stable.

Footnotes

1. This is true for all currently valid NonZero<_> types, but note that technically the layout-compatbility guarantee is currently only given on the specific NonZeroU32 (etc) aliases/instantiations, not the generic NonZero<T> type itself. ↩