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

# 1.28.0[−][src]Struct std::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<Layout, 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 unsafe fn from_size_align_unchecked(size: usize, align: usize) -> Layout`

[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>() -> Layout`

[src]

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

####

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

[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) -> Layout`

[src]

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

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 `Layout::from_size_align`.

####

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

[src]

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

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 repeat(&self, n: usize) -> Result<(Layout, usize), LayoutErr>`

[src]

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

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: Layout) -> Result<(Layout, usize), LayoutErr>`

[src]

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

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 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<Layout, LayoutErr>`

[src]

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

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: Layout) -> Result<(Layout, usize), LayoutErr>`

[src]

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

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.

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

####

`pub fn array<T>(n: usize) -> Result<Layout, LayoutErr>`

[src]

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

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

On arithmetic overflow, returns `LayoutErr`.

## Trait Implementations

###

`impl Debug for Layout`

[src]

####

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

[src]

Formats the value using the given formatter. Read more

###

`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 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 Copy for Layout`

[src]

## Auto Trait Implementations

###

`impl Send for Layout`

###

`impl Sync for Layout`

## Blanket Implementations

###

`impl<T> From for T`

[src]

####

`fn from(t: T) -> T`

[src]

Performs the conversion.

###

`impl<T, U> TryFrom for T where T: From<U>,`

[src]

#### `type Error = !`

🔬 This is a nightly-only experimental API. (`try_from` #33417)

The type returned in the event of a conversion error.

####

`fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>`

[src]

🔬 This is a nightly-only experimental API. (`try_from` #33417)

Performs the conversion.

###

`impl<T, U> TryInto for T where U: TryFrom<T>,`

[src]

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

🔬 This is a nightly-only experimental API. (`try_from` #33417)

The type returned in the event of a conversion error.

####

`fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>`

[src]

🔬 This is a nightly-only experimental API. (`try_from` #33417)

Performs the conversion.

###

`impl<T, U> Into for T where U: From<T>,`

[src]

####

`fn into(self) -> U`

[src]

Performs the conversion.

###

`impl<T> Borrow for T where T: ?Sized,`

[src]

####
ⓘImportant traits for &'a mut I

### Important traits for &'a mut I

`impl<'a, I> Iterator for &'a mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'a, R: Read + ?Sized> Read for &'a mut Rimpl<'a, W: Write + ?Sized> Write for &'a mut W`

`fn borrow(&self) -> &T`

[src]

Immutably borrows from an owned value. Read more

###

`impl<T> BorrowMut for T where T: ?Sized,`

[src]

####
ⓘImportant traits for &'a mut I

### Important traits for &'a mut I

`impl<'a, I> Iterator for &'a mut I where
I: Iterator + ?Sized, type Item = <I as Iterator>::Item;impl<'a, R: Read + ?Sized> Read for &'a mut Rimpl<'a, W: Write + ?Sized> Write for &'a mut W`

`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 get_type_id(&self) -> TypeId`

[src]

🔬 This is a nightly-only experimental API. (`get_type_id` #27745)

this method will likely be replaced by an associated static

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

###

`impl<T> ToOwned for T where T: Clone,`

[src]

#### `type Owned = T`

####

`fn to_owned(&self) -> T`

[src]

Creates owned data from borrowed data, usually by cloning. Read more

####

`fn clone_into(&self, target: &mut T)`

[src]

🔬 This is a nightly-only experimental API. (`toowned_clone_into` #41263)

recently added

Uses borrowed data to replace owned data, usually by cloning. 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`)