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

cda3e83
Opened by Jonathan Chan Kwan Yin at 2024-10-28 21:58:44
<!-- Thank you for creating a tracking issue! Tracking issues are for tracking a feature from implementation to stabilization. Make sure to include the relevant RFC for the feature if it has one. If the new feature is small, it may be fine to skip the RFC process. In that case, you can use use `issue = "none"` in your initial implementation PR. The reviewer will ask you to open a tracking issue if they agree your feature can be added without an RFC. -->

Feature gate: #![feature(nonzero_from_mut)]

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

<!-- Include a short description of the feature. -->

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

<!-- For most library features, it'd be useful to include a summarized version of the public API. (E.g. just the public function signatures without their doc comments or implementation.) --> 
// 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) -> &mut $NonZeroInt;
    pub unsafe fn from_mut_unchecked(n: &mut int) -> &mut $NonZeroInt;
}

Steps / History

<!-- For larger features, more steps might be involved. If the feature is changed later, please add those PRs here as well. -->
  • [ ] Implementation: #103730
  • [ ] Final comment period (FCP)^1
  • [ ] Stabilization PR
<!-- Once the feature has gone through a few release cycles and there are no unresolved questions left, the feature might be ready for stabilization. If this feature didn't go through the RFC process, a final comment period (FCP) is always needed before stabilization. This works as follows: A library API team member can kick off the stabilization process, at which point the rfcbot will ask all the team members to verify they agree with stabilization. Once enough members agree and there are no concerns, the final comment period begins: this issue will be marked as such and will be listed in the next This Week in Rust newsletter. If no blocking concerns are raised in that period of 10 days, a stabilzation PR can be opened by anyone. -->

Unresolved Questions

<!-- Include any open questions that need to be answered before the feature can be stabilised. If multiple (unrelated) big questions come up, it can be a good idea to open a separate issue for each, to make it easier to keep track of the discussions. It's useful to link any relevant discussions and conclusions (whether on GitHub, Zulip, or the internals forum) here. -->
  • None yet.
  1. <!-- Thank you for creating a tracking issue! Tracking issues are for tracking a feature from implementation to stabilization. Make sure to include the relevant RFC for the feature if it has one. If the new feature is small, it may be fine to skip the RFC process. In that case, you can use use `issue = "none"` in your initial implementation PR. The reviewer will ask you to open a tracking issue if they agree your feature can be added without an RFC. -->

    Feature gate: #![feature(nonzero_from_mut)]

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

    <!-- Include a short description of the feature. -->

    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

    <!-- For most library features, it'd be useful to include a summarized version of the public API. (E.g. just the public function signatures without their doc comments or implementation.) --> 
    // 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

    <!-- For larger features, more steps might be involved. If the feature is changed later, please add those PRs here as well. -->
    • [x] ACP: rust-lang/libs-team#129
    • [x] Implementation: #103730
    • [ ] Final comment period (FCP)^1
    • [ ] Stabilization PR
    <!-- Once the feature has gone through a few release cycles and there are no unresolved questions left, the feature might be ready for stabilization. If this feature didn't go through the RFC process, a final comment period (FCP) is always needed before stabilization. This works as follows: A library API team member can kick off the stabilization process, at which point the rfcbot will ask all the team members to verify they agree with stabilization. Once enough members agree and there are no concerns, the final comment period begins: this issue will be marked as such and will be listed in the next This Week in Rust newsletter. If no blocking concerns are raised in that period of 10 days, a stabilzation PR can be opened by anyone. -->

    Unresolved Questions

    <!-- Include any open questions that need to be answered before the feature can be stabilised. If multiple (unrelated) big questions come up, it can be a good idea to open a separate issue for each, to make it easier to keep track of the discussions. It's useful to link any relevant discussions and conclusions (whether on GitHub, Zulip, or the internals forum) here. -->
    • None yet.

    Jonathan Chan Kwan Yin at 2022-12-30 15:00:33

  2. This tracking issue has a different signature for from_mut than the implementation PR.

    asquared31415 at 2022-12-30 15:48:07

  3. fixed

    Jonathan Chan Kwan Yin at 2022-12-30 15:51:53

  4. NonZero::from_mut could return &mut Option<Self> instead of Option<&mut Self>, due to the layout guarantee that 0 is None::<NonZero<_>>[^1]. 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.

    [^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.

    zachs18 at 2024-10-28 21:58:44