Struct FixedCapacityElements 

pub struct FixedCapacityElements<Element, const CAPACITY: usize>
where
    Element: TrivialType,
{ /* private fields */ }

Container for storing a number of elements limited by the specified fixed capacity.

See also FixedCapacityBytes and FixedCapacityString.

In contrast to VariableElements, which can store arbitrary number of elements and can change the capacity, this container has fixed predefined capacity and occupies it regardless of how many elements are actually stored inside. This might seem limiting but allows implementing TrivialType trait, enabling its use for fields in data structures that derive TrivialType themselves, which isn’t the case with VariableElements.

The length (the number of stored elements) is a little-endian u32 in the first 4 bytes, followed by zero bytes up to TrivialType::ALIGNMENT of elements if it is larger than 4 bytes, and CAPACITY elements after that. As a result, the container has the same alignment as elements and no padding, regardless of the alignment of elements.

CAPACITY must not exceed u32::MAX, and the size of the container must be smaller than 2^32.

Parsing rejects a length above CAPACITY, but doesn’t check the rest of the length prefix, which is set to zero bytes whenever the length is set. The unsafe methods of TrivialType that skip parsing can create an instance with a larger length: methods don’t panic then, but such an instance has no accessible elements and nothing can be appended to it until a valid length is set with Self::truncate() or Self::copy_from().

Elements beyond the length are not part of the value. Default and Self::try_from_slice() fill them with default elements, while Self::truncate() and Self::copy_from() leave them as they are, so bytes of instances with the same elements can differ. Parsing checks all CAPACITY elements, they are values of Element too.

Implementations

impl<Element, const CAPACITY: usize> FixedCapacityElements<Element, CAPACITY>

where Element: TrivialType, [(); _]:,

pub fn try_from_slice(elements: &[Element]) -> Option<Self>

where Element: Default,

Try to create an instance from provided elements.

Unused capacity is filled with default elements.

Returns None if provided elements do not fit into the capacity.

pub fn get_elements(&self) -> &[Element]

Access to stored elements.

Returns no elements if the number of elements exceeds CAPACITY, which is only possible for an instance created from invalid bytes.

pub fn get_elements_mut(&mut self) -> &mut [Element]

Exclusive access to stored elements.

Returns no elements if the number of elements exceeds CAPACITY, which is only possible for an instance created from invalid bytes.

pub const fn len(&self) -> u32

Number of stored elements.

May exceed CAPACITY for an instance created from invalid bytes.

pub const fn is_empty(&self) -> bool

Returns true if there are no stored elements

pub fn append(&mut self, elements: &[Element]) -> bool

Append some elements.

true is returned on success, but if there isn’t enough capacity left, false is.

pub const fn truncate(&mut self, new_len: u32) -> bool

Truncate stored elements to this length.

Returns true on success or false if new_len is larger than Self::len().

pub fn copy_from(&mut self, src: &[Element]) -> bool

Copy from specified elements, replacing stored elements.

Returns false if capacity is not enough to copy contents of src

Trait Implementations

impl<Element, const CAPACITY: usize> Clone for FixedCapacityElements<Element, CAPACITY>

where Element: TrivialType + Clone,

fn clone(&self) -> FixedCapacityElements<Element, CAPACITY>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<Element, const CAPACITY: usize> Copy for FixedCapacityElements<Element, CAPACITY>

where Element: TrivialType + Copy,

impl<Element, const CAPACITY: usize> Debug for FixedCapacityElements<Element, CAPACITY>

where Element: TrivialType + Debug, [(); _]:,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<Element, const CAPACITY: usize> Default for FixedCapacityElements<Element, CAPACITY>

where Element: TrivialType + Default, [(); _]:,

fn default() -> Self

Returns the “default value” for a type.

impl<Element, const CAPACITY: usize> TrivialType for FixedCapacityElements<Element, CAPACITY>

where Element: TrivialType, [(); _]:,

const ALIGNMENT: Alignment = Element::ALIGNMENT

Alignment of the type in metadata.

const METADATA: &[u8]

Data structure metadata in binary form, describing shape and types of the contents, see IoTypeMetadataKind for encoding details.

fn try_from_bytes_unaligned(bytes: &[u8]) -> Option<(&Unaligned<Self>, &[u8])>

Parse the beginning of bytes, which don’t need to be aligned.

const SIZE: u32 = _

final fn try_from_bytes(bytes: &[u8]) -> Option<(&Self, &[u8])>

Parse the beginning of aligned bytes, returns the value and the remaining bytes.

final fn try_from_bytes_exact(bytes: &[u8]) -> Option<&Self>

Like Self::try_from_bytes(), but returns None if there are more bytes than the value

final fn try_from_bytes_mut(bytes: &mut [u8]) -> Option<(&mut Self, &mut [u8])>

Like Self::try_from_bytes(), but returns an exclusive reference.

final fn try_read_unaligned(bytes: &[u8]) -> Option<(Self, &[u8])>

Read a copy from the beginning of bytes, which don’t need to be aligned, returns the value and the remaining bytes

final fn try_read_unaligned_exact(bytes: &[u8]) -> Option<Self>

Like Self::try_read_unaligned(), but returns None if there are more bytes than the value

final unsafe fn read_unaligned(bytes: &[u8]) -> Option<Self>

Read unaligned value from memory.

final unsafe fn read_unaligned_unchecked(bytes: &[u8]) -> Self

Similar to Self::read_unaligned(), but doesn’t do any checks at all.

final unsafe fn from_bytes(bytes: &[u8]) -> Option<&Self>

Create a reference to a type, which is represented by provided memory.

final unsafe fn from_bytes_unchecked(bytes: &[u8]) -> &Self

Similar to Self::from_bytes(), but doesn’t do any checks at all.

final unsafe fn from_bytes_mut(bytes: &mut [u8]) -> Option<&mut Self>

Create a mutable reference to a type, which is represented by provided memory.

final unsafe fn from_bytes_mut_unchecked(bytes: &mut [u8]) -> &mut Self

Similar to Self::from_bytes_mut(), but doesn’t do any checks at all.

final fn as_bytes(&self) -> &[u8; _]

Access the underlying byte representation of a data structure

final unsafe fn as_bytes_mut(&mut self) -> &mut [u8; _]

Access the underlying mutable byte representation of a data structure.