Macro gstd::prelude::ptr::addr_of

pub macro addr_of($place:expr) {
    ...
}

Creates a const raw pointer to a place, without creating an intermediate reference.

Creating a reference with &/&mut is only allowed if the pointer is properly aligned and points to initialized data. For cases where those requirements do not hold, raw pointers should be used instead. However, &expr as *const _ creates a reference before casting it to a raw pointer, and that reference is subject to the same rules as all other references. This macro can create a raw pointer without creating a reference first.

See addr_of_mut for how to create a pointer to uninitialized data. Doing that with addr_of would not make much sense since one could only read the data, and that would be Undefined Behavior.

Safety

The expr in addr_of!(expr) is evaluated as a place expression, but never loads from the place or requires the place to be dereferenceable. This means that addr_of!((*ptr).field) still requires the projection to field to be in-bounds, using the same rules as offset. However, addr_of!(*ptr) is defined behavior even if ptr is null, dangling, or misaligned.

Note that Deref/Index coercions (and their mutable counterparts) are applied inside addr_of! like everywhere else, in which case a reference is created to call Deref::deref or Index::index, respectively. The statements above only apply when no such coercions are applied.

Example

Correct usage: Creating a pointer to unaligned data

use std::ptr;

#[repr(packed)]
struct Packed {
    f1: u8,
    f2: u16,
}

let packed = Packed { f1: 1, f2: 2 };
// `&packed.f2` would create an unaligned reference, and thus be Undefined Behavior!
let raw_f2 = ptr::addr_of!(packed.f2);
assert_eq!(unsafe { raw_f2.read_unaligned() }, 2);

Incorrect usage: Out-of-bounds fields projection

use std::ptr;

#[repr(C)]
struct MyStruct {
    field1: i32,
    field2: i32,
}

let ptr: *const MyStruct = ptr::null();
let fieldptr = unsafe { ptr::addr_of!((*ptr).field2) }; // Undefined Behavior ⚠️

The field projection .field2 would offset the pointer by 4 bytes, but the pointer is not in-bounds of an allocation for 4 bytes, so this offset is Undefined Behavior. See the offset docs for a full list of requirements for inbounds pointer arithmetic; the same requirements apply to field projections, even inside addr_of!. (In particular, it makes no difference whether the pointer is null or dangling.)