update and clarify addr_of docs · rust-lang/rust@81af5b5 (original) (raw)

`@@ -1989,9 +1989,18 @@ impl<F: FnPtr> fmt::Debug for F {

1989

`/// as all other references. This macro can create a raw pointer without creating

1990

`/// a reference first.

1991

`///

1992

`` -

/// Note, however, that the expr in addr_of!(expr) is still subject to all

1993

`` -

/// the usual rules. In particular, addr_of!(*ptr::null()) is Undefined

1994

/// Behavior because it dereferences a null pointer.

1992

`` +

/// The expr in addr_of!(expr) is evaluated as a place expression, but never loads

1993

/// from the place or requires the place to be dereferenceable. This means that

1994

`` +

/// addr_of!(*ptr) is defined behavior even if ptr is dangling or misaligned.

1995

`` +

/// Note however that addr_of!((*ptr).field) still requires the projection to

1996

`` +

/// field to be in-bounds, using the same rules as [offset].

1997

///

1998

`` +

/// Note that Deref/Index coercions (and their mutable counterparts) are applied inside

1999

`` +

/// addr_of! like everywhere else, in which case a reference is created to call Deref::deref or

2000

`` +

/// Index::index, respectively. The statements above only apply when no such coercions are

2001

/// applied.

2002

///

2003

`` +

/// [offset]: pointer::offset

1995

2004

`///

1996

2005

`/// # Example

1997

2006

`///

`@@ -2029,9 +2038,18 @@ pub macro addr_of($place:expr) {

2029

2038

`/// as all other references. This macro can create a raw pointer without creating

2030

2039

`/// a reference first.

2031

2040

`///

2032

`` -

/// Note, however, that the expr in addr_of_mut!(expr) is still subject to all

2033

`` -

/// the usual rules. In particular, addr_of_mut!(*ptr::null_mut()) is Undefined

2034

/// Behavior because it dereferences a null pointer.

2041

`` +

/// The expr in addr_of_mut!(expr) is evaluated as a place expression, but never loads

2042

/// from the place or requires the place to be dereferenceable. This means that

2043

`` +

/// addr_of_mut!(*ptr) is defined behavior even if ptr is dangling or misaligned.

2044

`` +

/// Note however that addr_of_mut!((*ptr).field) still requires the projection to

2045

`` +

/// field to be in-bounds, using the same rules as [offset].

2046

///

2047

`` +

/// Note that Deref/Index coercions (and their mutable counterparts) are applied inside

2048

`` +

/// addr_of_mut! like everywhere else, in which case a reference is created to call Deref::deref

2049

`` +

/// or Index::index, respectively. The statements above only apply when no such coercions are

2050

/// applied.

2051

///

2052

`` +

/// [offset]: pointer::offset

2035

2053

`///

2036

2054

`/// # Examples

2037

2055

`///