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 non-negative size and a power-of-two alignment.

(Note however that layouts are not required to have positive size, even though many allocators require that all memory requests have positive size. A caller to the `Alloc::alloc` method must either ensure that conditions like this are met, or use specific allocators with looser requirements.)

## Methods

### `impl Layout`[src]

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

Constructs a `Layout` from a given `size` and `align`, or returns `LayoutErr` if either 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 `usize::MAX`).

#### `pub const unsafe fn from_size_align_unchecked(size: usize, align: usize) -> Self`[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 fn size(&self) -> usize`[src]

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

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

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

#### `pub fn new<T>() -> Self`[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 fn align_to(&self, align: usize) -> Result<Self, LayoutErr>`[src]

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

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) -> Result<Layout, LayoutErr>`[src]

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

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

Returns `Err` if the padded size would overflow.

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), LayoutErr>`[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 `LayoutErr`.

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

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

Creates a layout describing the record for `self` followed by `next`, including any necessary padding to ensure that `next` will be properly aligned. Note that the result layout will satisfy the alignment properties of both `self` and `next`.

The resulting layout will be the same as that of a C struct containing two fields with the layouts of `self` and `next`, in that order.

Returns `Some((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 `LayoutErr`.

#### `pub fn repeat_packed(&self, n: usize) -> Result<Self, LayoutErr>`[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 `LayoutErr`.

#### `pub fn extend_packed(&self, next: Self) -> Result<Self, LayoutErr>`[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 `LayoutErr`.

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

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

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

On arithmetic overflow, returns `LayoutErr`.

## Trait Implementations

### `impl Copy 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 Eq for Layout`[src]

### `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 Debug for Layout`[src]

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

Formats the value using the given formatter. Read more

## Auto Trait Implementations

### `impl Send for Layout`

### `impl Sync for Layout`

### `impl Unpin for Layout`

## Blanket Implementations

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

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

Performs the conversion.

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

#### `fn from(T) -> T`[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.

#### `fn try_into(Self) -> Result<U, <U as TryFrom<T>>::Error>`[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.

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

Performs the conversion.

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

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

Immutably borrows from an owned value. Read more

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

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

Mutably borrows from an owned value. Read more

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

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

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

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g., `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)