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

# Struct std::heap::Layout [−] [src]

    pub struct Layout { /* fields omitted */ }

🔬 This is a nightly-only experimental API. (`allocator_api` #32838)

the precise API and guarantees it provides may be tweaked slightly, especially to possibly take into account the types being stored to make room for a future tracing garbage collector

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 requeusts 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]

#### `fn from_size_align(size: usize, align: usize) -> Option<Layout>`

🔬 This is a nightly-only experimental API. (`allocator_api` #32838)

the precise API and guarantees it provides may be tweaked slightly, especially to possibly take into account the types being stored to make room for a future tracing garbage collector

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

- `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`).

#### `unsafe fn from_size_align_unchecked(size: usize, align: usize) -> Layout`

🔬 This is a nightly-only experimental API. (`allocator_api` #32838)

the precise API and guarantees it provides may be tweaked slightly, especially to possibly take into account the types being stored to make room for a future tracing garbage collector

Creates a layout, bypassing all checks.

# Unsafety

This function is unsafe as it does not verify that `align` is a power of two nor that `size` aligned to `align` fits within the address space.

#### `fn size(&self) -> usize`

🔬 This is a nightly-only experimental API. (`allocator_api` #32838)

the precise API and guarantees it provides may be tweaked slightly, especially to possibly take into account the types being stored to make room for a future tracing garbage collector

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

#### `fn align(&self) -> usize`

🔬 This is a nightly-only experimental API. (`allocator_api` #32838)

the precise API and guarantees it provides may be tweaked slightly, especially to possibly take into account the types being stored to make room for a future tracing garbage collector

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

#### `fn new<T>() -> Layout`

🔬 This is a nightly-only experimental API. (`allocator_api` #32838)

the precise API and guarantees it provides may be tweaked slightly, especially to possibly take into account the types being stored to make room for a future tracing garbage collector

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

#### `fn for_value<T>(t: &T) -> Layout where
T: ?Sized,`

🔬 This is a nightly-only experimental API. (`allocator_api` #32838)

the precise API and guarantees it provides may be tweaked slightly, especially to possibly take into account the types being stored to make room for a future tracing garbage collector

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).

#### `fn align_to(&self, align: usize) -> Layout`

🔬 This is a nightly-only experimental API. (`allocator_api` #32838)

the precise API and guarantees it provides may be tweaked slightly, especially to possibly take into account the types being stored to make room for a future tracing garbage collector

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.

# Panics

Panics if the combination of `self.size` and the given `align` violates the conditions listed in `from_size_align`.

#### `fn padding_needed_for(&self, align: usize) -> usize`

🔬 This is a nightly-only experimental API. (`allocator_api` #32838)

the precise API and guarantees it provides may be tweaked slightly, especially to possibly take into account the types being stored to make room for a future tracing garbage collector

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`.

#### `fn repeat(&self, n: usize) -> Option<(Layout, usize)>`

🔬 This is a nightly-only experimental API. (`allocator_api` #32838)

the precise API and guarantees it provides may be tweaked slightly, especially to possibly take into account the types being stored to make room for a future tracing garbage collector

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 `None`.

#### `fn extend(&self, next: Layout) -> Option<(Layout, usize)>`

🔬 This is a nightly-only experimental API. (`allocator_api` #32838)

the precise API and guarantees it provides may be tweaked slightly, especially to possibly take into account the types being stored to make room for a future tracing garbage collector

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`.

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 witnin the concatenated record (assuming that the record itself starts at offset 0).

On arithmetic overflow, returns `None`.

#### `fn repeat_packed(&self, n: usize) -> Option<Layout>`

🔬 This is a nightly-only experimental API. (`allocator_api` #32838)

the precise API and guarantees it provides may be tweaked slightly, especially to possibly take into account the types being stored to make room for a future tracing garbage collector

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 `None`.

#### `fn extend_packed(&self, next: Layout) -> Option<(Layout, usize)>`

🔬 This is a nightly-only experimental API. (`allocator_api` #32838)

the precise API and guarantees it provides may be tweaked slightly, especially to possibly take into account the types being stored to make room for a future tracing garbage collector

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 incoporated at all into the resulting layout.

Returns `(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 witnin the concatenated record (assuming that the record itself starts at offset 0).

(The `offset` is always the same as `self.size()`; we use this signature out of convenience in matching the signature of `extend`.)

On arithmetic overflow, returns `None`.

#### `fn array<T>(n: usize) -> Option<Layout>`

🔬 This is a nightly-only experimental API. (`allocator_api` #32838)

the precise API and guarantees it provides may be tweaked slightly, especially to possibly take into account the types being stored to make room for a future tracing garbage collector

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

On arithmetic overflow, returns `None`.

## Trait Implementations

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

#### `fn fmt(&self, __arg_0: &mut Formatter) -> Result<(), Error>`

Formats the value using the given formatter.

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

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

#### `fn clone(&self) -> Layout`

Returns a copy of the value. Read more

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

Performs copy-assignment from `source`. Read more

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

#### `fn eq(&self, __arg_0: &Layout) -> bool`

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

#### `fn ne(&self, __arg_0: &Layout) -> bool`

This method tests for `!=`.

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result
+
  Collapse/expand 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`)