@@ -591,7 +591,7 @@ impl<T: ?Sized> *const T {
591
591
/// Behavior:
592
592
///
593
593
/// * Both the starting and resulting pointer must be either in bounds or one
594
- /// byte past the end of an allocated object.
594
+ /// byte past the end of *the same* allocated object.
595
595
///
596
596
/// * The computed offset, **in bytes**, cannot overflow an `isize`.
597
597
///
@@ -643,9 +643,15 @@ impl<T: ?Sized> *const T {
643
643
///
644
644
/// The resulting pointer does not need to be in bounds, but it is
645
645
/// potentially hazardous to dereference (which requires `unsafe`).
646
+ /// In particular, the resulting pointer may *not* be used to access a
647
+ /// different allocated object than the one `self` points to. In other
648
+ /// words, `x.wrapping_offset(y.wrapping_offset_from(x))` is
649
+ /// *not* the same as `y`, and dereferencing it is undefined behavior
650
+ /// unless `x` and `y` point into the same allocated object.
646
651
///
647
652
/// Always use `.offset(count)` instead when possible, because `offset`
648
- /// allows the compiler to optimize better.
653
+ /// allows the compiler to optimize better. If you need to cross object
654
+ /// boundaries, cast the pointer to an integer and do the arithmetic there.
649
655
///
650
656
/// # Examples
651
657
///
@@ -1340,7 +1346,7 @@ impl<T: ?Sized> *mut T {
1340
1346
/// Behavior:
1341
1347
///
1342
1348
/// * Both the starting and resulting pointer must be either in bounds or one
1343
- /// byte past the end of an allocated object.
1349
+ /// byte past the end of *the same* allocated object.
1344
1350
///
1345
1351
/// * The computed offset, **in bytes**, cannot overflow an `isize`.
1346
1352
///
@@ -1391,9 +1397,15 @@ impl<T: ?Sized> *mut T {
1391
1397
///
1392
1398
/// The resulting pointer does not need to be in bounds, but it is
1393
1399
/// potentially hazardous to dereference (which requires `unsafe`).
1400
+ /// In particular, the resulting pointer may *not* be used to access a
1401
+ /// different allocated object than the one `self` points to. In other
1402
+ /// words, `x.wrapping_offset(y.wrapping_offset_from(x))` is
1403
+ /// *not* the same as `y`, and dereferencing it is undefined behavior
1404
+ /// unless `x` and `y` point into the same allocated object.
1394
1405
///
1395
1406
/// Always use `.offset(count)` instead when possible, because `offset`
1396
- /// allows the compiler to optimize better.
1407
+ /// allows the compiler to optimize better. If you need to cross object
1408
+ /// boundaries, cast the pointer to an integer and do the arithmetic there.
1397
1409
///
1398
1410
/// # Examples
1399
1411
///
0 commit comments