Skip to content

clarify requirements of byte_{offset,add,sub} for zero-sized referents #133576

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
+34 −22
Closed

clarify requirements of byte_{offset,add,sub} for zero-sized referents #133576

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 18 additions & 12 deletions library/core/src/ptr/const_ptr.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -444,9 +444,11 @@ impl<T: ?Sized> *const T {
///
/// `count` is in units of **bytes**.
///
/// This is purely a convenience for casting to a `u8` pointer and
/// using [offset][pointer::offset] on it. See that method for documentation
/// and safety requirements.
/// This is purely a convenience for casting to a `u8` pointer and using
/// [offset][pointer::offset] on it. See that method for documentation and
/// safety requirements. Note that the usual guidance on operations on
/// zero-sized referents does not apply here — the only valid `count` for
/// zero-sized referents is `0`.
Comment on lines +449 to +451
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The docs for pointer::offset don't even have any guidance about zero-sized references? In fact, neither operation involves any reference at all! Only raw pointers are involved.

I don't understand which problem you see with the current docs, and I think the new sentence is quite confusing.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So to be clear, please undo all these changes to the bytewise offset methods in your PR, and only keep the change in library/core/src/ptr/mod.rs.

///
/// For non-`Sized` pointees this operation changes only the data pointer,
/// leaving the metadata untouched.
Expand Down Expand Up @@ -526,9 +528,9 @@ impl<T: ?Sized> *const T {
///
/// `count` is in units of **bytes**.
///
/// This is purely a convenience for casting to a `u8` pointer and
/// using [wrapping_offset][pointer::wrapping_offset] on it. See that method
/// for documentation.
/// This is purely a convenience for casting to a `u8` pointer and using
/// [wrapping_offset][pointer::wrapping_offset] on it. See that method for
/// documentation.
///
/// For non-`Sized` pointees this operation changes only the data pointer,
/// leaving the metadata untouched.
Expand Down Expand Up @@ -955,9 +957,11 @@ impl<T: ?Sized> *const T {
///
/// `count` is in units of bytes.
///
/// This is purely a convenience for casting to a `u8` pointer and
/// using [add][pointer::add] on it. See that method for documentation
/// and safety requirements.
/// This is purely a convenience for casting to a `u8` pointer and using
/// [add][pointer::add] on it. See that method for documentation and safety
/// requirements. Note that the usual guidance on operations on zero-sized
/// referents does not apply here — the only valid `count`s for zero-sized
/// referents is `0`.
///
/// For non-`Sized` pointees this operation changes only the data pointer,
/// leaving the metadata untouched.
Expand Down Expand Up @@ -1068,9 +1072,11 @@ impl<T: ?Sized> *const T {
///
/// `count` is in units of bytes.
///
/// This is purely a convenience for casting to a `u8` pointer and
/// using [sub][pointer::sub] on it. See that method for documentation
/// and safety requirements.
/// This is purely a convenience for casting to a `u8` pointer and using
/// [sub][pointer::sub] on it. See that method for documentation and safety
/// requirements. Note that the usual guidance on operations on zero-sized
/// referents does not apply here — the only valid `count`s for zero-sized
/// referents is `0`.
///
/// For non-`Sized` pointees this operation changes only the data pointer,
/// leaving the metadata untouched.
Expand Down
2 changes: 1 addition & 1 deletion library/core/src/ptr/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
//! The precise rules for validity are not determined yet. The guarantees that are
//! provided at this point are very minimal:
//!
//! * For operations of [size zero][zst], *every* pointer is valid, including the [null] pointer.
//! * For operations of size zero, *every* pointer is valid, including the [null] pointer.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This leaves a dangling [zst] markdown link further down this file, please also remove that.

//! The following points are only concerned with non-zero-sized accesses.
//! * A [null] pointer is *never* valid.
//! * For a pointer to be valid, it is necessary, but not always sufficient, that the pointer be
Expand Down
24 changes: 15 additions & 9 deletions library/core/src/ptr/mut_ptr.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -442,9 +442,11 @@ impl<T: ?Sized> *mut T {
///
/// `count` is in units of **bytes**.
///
/// This is purely a convenience for casting to a `u8` pointer and
/// using [offset][pointer::offset] on it. See that method for documentation
/// and safety requirements.
/// This is purely a convenience for casting to a `u8` pointer and using
/// [offset][pointer::offset] on it. See that method for documentation and
/// safety requirements. Note that the usual guidance on operations on
/// zero-sized referents does not apply here — the only valid `count`s for
/// zero-sized referents is `0`.
///
/// For non-`Sized` pointees this operation changes only the data pointer,
/// leaving the metadata untouched.
Expand Down Expand Up @@ -1034,9 +1036,11 @@ impl<T: ?Sized> *mut T {
///
/// `count` is in units of bytes.
///
/// This is purely a convenience for casting to a `u8` pointer and
/// using [add][pointer::add] on it. See that method for documentation
/// and safety requirements.
/// This is purely a convenience for casting to a `u8` pointer and using
/// [add][pointer::add] on it. See that method for documentation and safety
/// requirements. Note that the usual guidance on operations on zero-sized
/// referents does not apply here — the only valid `count`s for zero-sized
/// referents is `0`.
///
/// For non-`Sized` pointees this operation changes only the data pointer,
/// leaving the metadata untouched.
Expand Down Expand Up @@ -1147,9 +1151,11 @@ impl<T: ?Sized> *mut T {
///
/// `count` is in units of bytes.
///
/// This is purely a convenience for casting to a `u8` pointer and
/// using [sub][pointer::sub] on it. See that method for documentation
/// and safety requirements.
/// This is purely a convenience for casting to a `u8` pointer and using
/// [sub][pointer::sub] on it. See that method for documentation and safety
/// requirements. Note that the usual guidance on operations on zero-sized
/// referents does not apply here — the only valid `count`s for zero-sized
/// referents is `0`.
///
/// For non-`Sized` pointees this operation changes only the data pointer,
/// leaving the metadata untouched.
Expand Down
Loading