Struct VariableElements

#[repr(C)]
pub struct VariableElements<Element, const RECOMMENDED_ALLOCATION: u32 = 0>
where
    Element: TrivialType,
{ /* private fields */ }

Container for storing variable number of elements.

RECOMMENDED_ALLOCATION is what is being used when a host needs to allocate memory for call into guest, but guest may receive an allocation with more or less memory in practice depending on other circumstances, like when called from another contract with specific allocation specified.

Implementations

impl<Element, const RECOMMENDED_ALLOCATION: u32> VariableElements<Element, RECOMMENDED_ALLOCATION>

where Element: TrivialType,

pub const fn from_buffer<'a>( buffer: &'a [<Self as IoType>::PointerType], size: &'a u32, ) -> impl Deref<Target = Self> + 'a

Create a new shared instance from provided memory buffer.

NOTE: size is specified in bytes, not elements.

Panics

Panics if buffer.len * Element::SIZE() != size

pub fn from_buffer_mut<'a>( buffer: &'a mut [<Self as IoType>::PointerType], size: &'a mut u32, ) -> impl DerefMut<Target = Self> + 'a

Create a new exclusive instance from provided memory buffer.

Panics

Panics if buffer.len() * Element::SIZE != size

pub fn from_uninit<'a, const CAPACITY: usize>( uninit: &'a mut [MaybeUninit<<Self as IoType>::PointerType>; CAPACITY], size: &'a mut u32, ) -> impl DerefMut<Target = Self> + 'a

Create a new shared instance from provided memory buffer.

NOTE: size is specified in bytes, not elements.

Panics

Panics if size > CAPACITY or size % Element::SIZE != 0

pub const fn size(&self) -> u32

pub fn capacity(&self) -> u32

Capacity in bytes

pub const fn count(&self) -> u32

Number of elements

pub const fn get_initialized(&self) -> &[Element]

Try to get access to initialized elements

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

Try to get exclusive access to initialized Data, returns None if not initialized

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

Append some elements by using more of allocated, but currently unused elements.

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

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

Truncate internal initialized bytes to this size.

Returns true on success or false if new_size is larger than Self::size() or not a multiple of Element::SIZE.

pub fn copy_from(&mut self, src: &Self) -> bool

Copy contents from another instance.

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

pub fn as_mut_ptr(&mut self) -> &mut NonNull<Element>

Get exclusive access to the underlying pointer with no checks.

Can be used for initialization with Self::assume_init() called afterward to confirm how many bytes are in use right now.

pub fn cast_ref<const DIFFERENT_RECOMMENDED_ALLOCATION: u32>( &self, ) -> &VariableElements<Element, DIFFERENT_RECOMMENDED_ALLOCATION>

Cast a shared reference to this instance into a reference to an instance of a different recommended allocation

pub fn cast_mut<const DIFFERENT_RECOMMENDED_ALLOCATION: u32>( &mut self, ) -> &mut VariableElements<Element, DIFFERENT_RECOMMENDED_ALLOCATION>

Cast an exclusive reference to this instance into a reference to an instance of a different recommended allocation

pub unsafe fn assume_init(&mut self, size: u32) -> Option<&mut [Element]>

Assume that the first size are initialized and can be read.

Returns Some(initialized_elements) on success or None if size is larger than its capacity or not a multiple of Element::SIZE.

Safety

Caller must ensure size is actually initialized

Trait Implementations

impl<Element, const RECOMMENDED_ALLOCATION: u32> Debug for VariableElements<Element, RECOMMENDED_ALLOCATION>

where Element: TrivialType + Debug,

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

Formats the value using the given formatter.

impl<Element, const RECOMMENDED_ALLOCATION: u32> IoType for VariableElements<Element, RECOMMENDED_ALLOCATION>

where Element: TrivialType,

const METADATA: &[u8]

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

type PointerType = Element

Pointer with trivial type that this IoType represents

fn size(&self) -> u32

Number of bytes that are currently used to store data

unsafe fn size_ptr(&self) -> impl Deref<Target = NonNull<u32>>

Pointer to the number of bytes that are currently used to store data.

unsafe fn size_mut_ptr(&mut self) -> impl DerefMut<Target = *mut u32>

An exclusive pointer to the number of bytes that are currently used to store data.

fn capacity(&self) -> u32

Number of bytes are allocated right now

unsafe fn capacity_ptr(&self) -> impl Deref<Target = NonNull<u32>>

Number of bytes are allocated right now

unsafe fn set_size(&mut self, size: u32)

Set the number of used bytes

unsafe fn from_ptr<'a>( ptr: &'a NonNull<Self::PointerType>, size: &'a u32, capacity: u32, ) -> impl Deref<Target = Self> + 'a

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

unsafe fn from_mut_ptr<'a>( ptr: &'a mut NonNull<Self::PointerType>, size: &'a mut *mut u32, capacity: u32, ) -> impl DerefMut<Target = Self> + 'a

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

unsafe fn as_ptr(&self) -> impl Deref<Target = NonNull<Self::PointerType>>

Get a raw pointer to the underlying data with no checks.

unsafe fn as_mut_ptr( &mut self, ) -> impl DerefMut<Target = NonNull<Self::PointerType>>

Get an exclusive raw pointer to the underlying data with no checks.

impl<Element, const RECOMMENDED_ALLOCATION: u32> IoTypeOptional for VariableElements<Element, RECOMMENDED_ALLOCATION>

where Element: TrivialType,