Rollup merge of #128306 - WiktorPrzetacznik:WiktorPrzetacznik-nonnull… · patricklam/verify-rust-std@9df61ad (original) (raw)

`@@ -1169,16 +1169,23 @@ impl<T: ?Sized> NonNull {

1169

`` /// align.

1170

`///

1171

`/// If it is not possible to align the pointer, the implementation returns

1172

`` -

/// usize::MAX. It is permissible for the implementation to always

1173

`` -

/// return usize::MAX. Only your algorithm's performance can depend

1174

/// on getting a usable offset here, not its correctness.

1172

`` +

/// usize::MAX.

1175

1173

`///

1176

1174

`` /// The offset is expressed in number of T elements, and not bytes.

1177

1175

`///

1178

1176

`/// There are no guarantees whatsoever that offsetting the pointer will not overflow or go

1179

1177

`/// beyond the allocation that the pointer points into. It is up to the caller to ensure that

1180

1178

`/// the returned offset is correct in all terms other than alignment.

1181

1179

`///

1180

/// When this is called during compile-time evaluation (which is unstable), the implementation

1181

`` +

/// may return usize::MAX in cases where that can never happen at runtime. This is because the

1182

/// actual alignment of pointers is not known yet during compile-time, so an offset with

1183

`` +

/// guaranteed alignment can sometimes not be computed. For example, a buffer declared as `[u8;

1184

`` +

/// N]` might be allocated at an odd or an even address, but at compile-time this is not yet

1185

/// known, so the execution has to be correct for either choice. It is therefore impossible to

1186

/// find an offset that is guaranteed to be 2-aligned. (This behavior is subject to change, as usual

1187

/// for unstable APIs.)

1188

///

1182

1189

`/// # Panics

1183

1190

`///

1184

1191

`` /// The function panics if align is not a power-of-two.