Tracking Issue for `#![feature(pointer_try_cast_aligned)]`

[mathisbot]

Feature gate: #![feature(pointer_try_cast_aligned)]

This is a tracking issue for adding the convenience method try_cast_aligned to *const T, *mut T and NonNull<T>.

impl<T: ?Sized> *const T {
    pub fn try_cast_aligned<U: Sized>(self) -> Option<*const U>;
}

impl<T: ?Sized> *mut T {
    pub fn try_cast_aligned<U: Sized>(self) -> Option<*mut U>;
}

impl<T: ?Sized> NonNull<T> {
    pub fn try_cast_aligned<U: Sized>(self) -> Option<NonNull<U>>;
}

Steps / History

• API change proposal (ACP): ACP: ptr::is_aligned_for::<U> libs-team#588
• Implementation: Implement ptr::try_cast_aligned and NonNull::try_cast_aligned. #141222
• Fix doctest: try_cast_aligned: avoid bare int-to-ptr casts #141381
• Final comment period (FCP)
• Stabilization PR: Stabilize ptr::try_cast_aligned #154170

Unresolved Questions

None yet.

[mathisbot]

Stabilization report: ptr::try_cast_aligned

Summary

This report proposes the stabilization of try_cast_aligned on pointers, which attempts to cast a pointer to a target type while checking alignment requirements.

impl<T: ?Sized> *const T {
    pub fn try_cast_aligned<U: Sized>(self) -> Option<*const U>;
}

impl<T: ?Sized> *mut T {
    pub fn try_cast_aligned<U: Sized>(self) -> Option<*mut U>;
}

impl<T: ?Sized> NonNull<T> {
    pub fn try_cast_aligned<U: Sized>(self) -> Option<NonNull<U>>;
}

The method returns Some if the pointer is properly aligned for U, and None otherwise.
It also ensures the checked alignment and the resulting pointer type are consistent.

Motivation

Working with raw pointers often requires ensuring proper alignment before performing casts or de-referencing. Currently, users must write patterns such as:

assert!(ptr.cast::<U>().is_aligned());
let ptr = ptr.cast::<U>();

This approach has several drawbacks:

• it requires casting before checking alignment,
• it is still flagged by clippy::cast_ptr_alignment,
• it obscures the intent of the code.

Alternatives

The original ACP proposed ptr::is_aligned_for::<U>() -> bool as the primary API.

This approach is closely related to the existing unstable API in #96284 (is_aligned_to), which provides alignment checks independently of casting.

During the ACP discussion, the combined approach (try_cast_aligned) was preferred.

Experience

The feature has been available on nightly for an extended period (almost one year), with no reported issues or API concerns.

While real-world usage appears to be relatively limited, no negative feedback has been raised during this period.

Its implementation is straightforward and does not introduce new unsafe behavior beyond existing primitives.

Conclusion

I believe this feature is ready for stabilization.

cc @rust-lang/libs-api

[mathisbot]

Stabilization PR: #154170

[mathisbot]

cc @tgross35