core::alloc::Layout - Rust
Description: API documentation for the Rust `Layout` struct in crate `core`.
Keywords: rust, rustlang, rust-lang, Layout

# 1.28.0[−][src]Struct core::alloc::Layout

    #[lang = "alloc_layout"]pub struct Layout { /* fields omitted */ }

Layout of a block of memory.

An instance of `Layout` describes a particular layout of memory. You build a `Layout` up as an input to give to an allocator.

All layouts have an associated size and a power-of-two alignment.

(Note that layouts are not required to have non-zero size, even though `GlobalAlloc` requires that all memory requests be non-zero in size. A caller must either ensure that conditions like this are met, use specific allocators with looser requirements, or use the more lenient `Allocator` interface.)

## Implementations

### `impl Layout`[src]

#### `pub const fn from_size_align(
size: usize,
align: usize
) -> Result<Self, LayoutError>`1.28.0 (const: 1.50.0)[src]

Constructs a `Layout` from a given `size` and `align`, or returns `LayoutError` if any of the following conditions are not met:

- `align` must not be zero,

- `align` must be a power of two,

- `size`, when rounded up to the nearest multiple of `align`, must not overflow (i.e., the rounded value must be less than or equal to `usize::MAX`).

#### `pub const unsafe fn from_size_align_unchecked(size: usize, align: usize) -> Self`1.28.0 (const: 1.28.0)[src]

Creates a layout, bypassing all checks.

# Safety

This function is unsafe as it does not verify the preconditions from `Layout::from_size_align`.

#### `pub const fn size(&self) -> usize`1.28.0 (const: 1.50.0)[src]

The minimum size in bytes for a memory block of this layout.

#### `pub const fn align(&self) -> usize`1.28.0 (const: 1.50.0)[src]

The minimum byte alignment for a memory block of this layout.

#### `pub const fn new<T>() -> Self`1.28.0 (const: 1.42.0)[src]

Constructs a `Layout` suitable for holding a value of type `T`.

#### `pub fn for_value<T: ?Sized>(t: &T) -> Self`[src]

Produces layout describing a record that could be used to allocate backing structure for `T` (which could be a trait or other unsized type like a slice).

#### `pub unsafe fn for_value_raw<T: ?Sized>(t: *const T) -> Self`[src]

🔬 This is a nightly-only experimental API. (`layout_for_ptr` #69835)

Produces layout describing a record that could be used to allocate backing structure for `T` (which could be a trait or other unsized type like a slice).

# Safety

This function is only safe to call if the following conditions hold:

- If `T` is `Sized`, this function is always safe to call.
- If the unsized tail of `T` is:
  - a slice, then the length of the slice tail must be an intialized integer, and the size of the entire value (dynamic tail length + statically sized prefix) must fit in `isize`.
  - a trait object, then the vtable part of the pointer must point to a valid vtable for the type `T` acquired by an unsizing coersion, and the size of the entire value (dynamic tail length + statically sized prefix) must fit in `isize`.
  - an (unstable) extern type, then this function is always safe to call, but may panic or otherwise return the wrong value, as the extern type's layout is not known. This is the same behavior as `Layout::for_value` on a reference to an extern type tail.
  - otherwise, it is conservatively not allowed to call this function.

#### `pub fn dangling(&self) -> NonNull<u8>`[src]

🔬 This is a nightly-only experimental API. (`alloc_layout_extra` #55724)

Creates a `NonNull` that is dangling, but well-aligned for this Layout.

Note that the pointer value may potentially represent a valid pointer, which means this must not be used as a "not yet initialized" sentinel value. Types that lazily allocate must track initialization by some other means.

#### `pub fn align_to(&self, align: usize) -> Result<Self, LayoutError>`1.44.0[src]

Creates a layout describing the record that can hold a value of the same layout as `self`, but that also is aligned to alignment `align` (measured in bytes).

If `self` already meets the prescribed alignment, then returns `self`.

Note that this method does not add any padding to the overall size, regardless of whether the returned layout has a different alignment. In other words, if `K` has size 16, `K.align_to(32)` will still have size 16.

Returns an error if the combination of `self.size()` and the given `align` violates the conditions listed in `Layout::from_size_align`.

#### `pub fn padding_needed_for(&self, align: usize) -> usize`[src]

🔬 This is a nightly-only experimental API. (`alloc_layout_extra` #55724)

Returns the amount of padding we must insert after `self` to ensure that the following address will satisfy `align` (measured in bytes).

e.g., if `self.size()` is 9, then `self.padding_needed_for(4)` returns 3, because that is the minimum number of bytes of padding required to get a 4-aligned address (assuming that the corresponding memory block starts at a 4-aligned address).

The return value of this function has no meaning if `align` is not a power-of-two.

Note that the utility of the returned value requires `align` to be less than or equal to the alignment of the starting address for the whole allocated block of memory. One way to satisfy this constraint is to ensure `align <= self.align()`.

#### `pub fn pad_to_align(&self) -> Layout`1.44.0[src]

Creates a layout by rounding the size of this layout up to a multiple of the layout's alignment.

This is equivalent to adding the result of `padding_needed_for` to the layout's current size.

#### `pub fn repeat(&self, n: usize) -> Result<(Self, usize), LayoutError>`[src]

🔬 This is a nightly-only experimental API. (`alloc_layout_extra` #55724)

Creates a layout describing the record for `n` instances of `self`, with a suitable amount of padding between each to ensure that each instance is given its requested size and alignment. On success, returns `(k, offs)` where `k` is the layout of the array and `offs` is the distance between the start of each element in the array.

On arithmetic overflow, returns `LayoutError`.

#### `pub fn extend(&self, next: Self) -> Result<(Self, usize), LayoutError>`1.44.0[src]

Creates a layout describing the record for `self` followed by `next`, including any necessary padding to ensure that `next` will be properly aligned, but no trailing padding.

In order to match C representation layout `repr(C)`, you should call `pad_to_align` after extending the layout with all fields. (There is no way to match the default Rust representation layout `repr(Rust)`, as it is unspecified.)

Note that the alignment of the resulting layout will be the maximum of those of `self` and `next`, in order to ensure alignment of both parts.

Returns `Ok((k, offset))`, where `k` is layout of the concatenated record and `offset` is the relative location, in bytes, of the start of the `next` embedded within the concatenated record (assuming that the record itself starts at offset 0).

On arithmetic overflow, returns `LayoutError`.

# Examples

To calculate the layout of a `#[repr(C)]` structure and the offsets of the fields from its fields' layouts:

    pub fn repr_c(fields: &[Layout]) -> Result<(Layout, Vec<usize>), LayoutError> {
        let mut offsets = Vec::new();
        let mut layout = Layout::from_size_align(0, 1)?;
        for &field in fields {
            let (new_layout, offset) = layout.extend(field)?;
            layout = new_layout;
            offsets.push(offset);
        }
        // Remember to finalize with `pad_to_align`!
        Ok((layout.pad_to_align(), offsets))
    }

Run

#### `pub fn repeat_packed(&self, n: usize) -> Result<Self, LayoutError>`[src]

🔬 This is a nightly-only experimental API. (`alloc_layout_extra` #55724)

Creates a layout describing the record for `n` instances of `self`, with no padding between each instance.

Note that, unlike `repeat`, `repeat_packed` does not guarantee that the repeated instances of `self` will be properly aligned, even if a given instance of `self` is properly aligned. In other words, if the layout returned by `repeat_packed` is used to allocate an array, it is not guaranteed that all elements in the array will be properly aligned.

On arithmetic overflow, returns `LayoutError`.

#### `pub fn extend_packed(&self, next: Self) -> Result<Self, LayoutError>`[src]

🔬 This is a nightly-only experimental API. (`alloc_layout_extra` #55724)

Creates a layout describing the record for `self` followed by `next` with no additional padding between the two. Since no padding is inserted, the alignment of `next` is irrelevant, and is not incorporated at all into the resulting layout.

On arithmetic overflow, returns `LayoutError`.

#### `pub fn array<T>(n: usize) -> Result<Self, LayoutError>`1.44.0[src]

Creates a layout describing the record for a `[T; n]`.

On arithmetic overflow, returns `LayoutError`.

## Trait Implementations

### `impl Clone for Layout`[src]

#### `fn clone(&self) -> Layout`[src]

Returns a copy of the value. Read more

#### `fn clone_from(&mut self, source: &Self)`1.0.0[src]

Performs copy-assignment from `source`. Read more

### `impl Copy for Layout`[src]

### `impl Debug for Layout`[src]

#### `fn fmt(&self, f: &mut Formatter<'_>) -> Result`[src]

Formats the value using the given formatter. Read more

### `impl Eq for Layout`[src]

### `impl PartialEq<Layout> for Layout`[src]

#### `fn eq(&self, other: &Layout) -> bool`[src]

This method tests for `self` and `other` values to be equal, and is used by `==`. Read more

#### `fn ne(&self, other: &Layout) -> bool`[src]

This method tests for `!=`.

### `impl StructuralEq for Layout`[src]

### `impl StructuralPartialEq for Layout`[src]

## Auto Trait Implementations

### `impl Send for Layout`[src]

### `impl Sync for Layout`[src]

### `impl Unpin for Layout`[src]

## Blanket Implementations

### `impl<T> Any for T where
T: 'static + ?Sized,` [src]

#### `pub fn type_id(&Self) -> TypeId`[src]

Gets the `TypeId` of `self`. Read more

### `impl<T> Borrow<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow(&Self) -> &T`[src]

Immutably borrows from an owned value. Read more

### `impl<T> BorrowMut<T> for T where
T: ?Sized,` [src]

#### `pub fn borrow_mut(&mut Self) -> &mut T`[src]

Mutably borrows from an owned value. Read more

### `impl<T> From<T> for T`[src]

#### `pub fn from(T) -> T`[src]

Performs the conversion.

### `impl<T, U> Into<U> for T where
U: From<T>,` [src]

#### `pub fn into(Self) -> U`[src]

Performs the conversion.

### `impl<T, U> TryFrom<U> for T where
U: Into<T>,` [src]

#### `type Error = Infallible`

The type returned in the event of a conversion error.

#### `pub fn try_from(U) -> Result<T, <T as TryFrom<U>>::Error>`[src]

Performs the conversion.

### `impl<T, U> TryInto<U> for T where
U: TryFrom<T>,` [src]

#### `type Error = <U as TryFrom<T>>::Error`

The type returned in the event of a conversion error.

#### `pub fn try_into(Self) -> Result<U, <U as TryFrom<T>>::Error>`[src]

Performs the conversion.