Struct Box 

pub struct Box<T, A>
where
    A: Allocator,
{ /* private fields */ }

A Müsli-allocated pointer type that uniquely owns a heap allocation of type T.

This is a Box type capable of using the allocator provided through a Context. Therefore it can be safely used in no-std environments.

Thread safety

A box is Send or Sync only if the allocation it holds is. Boxes backed by the global allocator are thread safe as long as T is:

use musli::alloc::{Box, Global};

fn assert_send_sync<T: Send + Sync>(_: &T) {}

let boxed = Box::<u32, Global>::new_in(42, Global::new())?;
assert_send_sync(&boxed);

But a box allocated from a Slice refers to allocator state which is not synchronized, so it cannot be sent to another thread:

use musli::alloc::{ArrayBuffer, Box, Slice};

fn assert_send<T: Send>(_: &T) {}

let mut buf = ArrayBuffer::new();
let alloc = Slice::new(&mut buf);
let boxed = Box::new_in(42u32, &alloc)?;
assert_send(&boxed);

Nor can it be shared between threads:

use musli::alloc::{ArrayBuffer, Box, Slice};

fn assert_sync<T: Sync>(_: &T) {}

let mut buf = ArrayBuffer::new();
let alloc = Slice::new(&mut buf);
let boxed = Box::new_in(42u32, &alloc)?;
assert_sync(&boxed);

Implementations

impl<T, A> Box<T, A>

where A: Allocator,

pub fn new_in(value: T, alloc: A) -> Result<Self, AllocError>

Allocates memory on the heap and then places x into it.

This doesn’t actually allocate if T is zero-sized.

Examples

use musli::alloc::{AllocError, Box};

musli::alloc::default(|alloc| {
    let mut a = Box::new_in(10u32, alloc)?;
    assert_eq!(a.as_ref(), &10u32);
    Ok::<_, AllocError>(())
});

Zero-sized types:

use musli::alloc::{AllocError, Box};

musli::alloc::default(|alloc| {
    let mut a = Box::new_in((), alloc)?;
    assert_eq!(a.as_ref(), &());
    Ok::<_, AllocError>(())
});

Trait Implementations

impl<T, A> AsRef<T> for Box<T, A>

where A: Allocator,

fn as_ref(&self) -> &T

Converts this type into a shared reference of the (usually inferred) input type.

impl<T, A> Clone for Box<T, A>

where T: Clone, A: GlobalAllocator,

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T, A> Debug for Box<T, A>

where T: Debug, A: Allocator,

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

Formats the value using the given formatter.

impl<T, A> Deref for Box<T, A>

where A: Allocator,

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T, A> DerefMut for Box<T, A>

where A: Allocator,

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<T, A> Display for Box<T, A>

where T: Display, A: Allocator,

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

Formats the value using the given formatter.

impl<T, A> Drop for Box<T, A>

where A: Allocator,

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<T, A> Eq for Box<T, A>

where T: Eq, A: Allocator,

impl<T, A> Hash for Box<T, A>

where T: Hash, A: Allocator,

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T, A> Hasher for Box<T, A>

where T: Hasher, A: Allocator,

fn finish(&self) -> u64

Returns the hash value for the values written so far.

fn write(&mut self, bytes: &[u8])

Writes some data into this Hasher.

fn write_u8(&mut self, i: u8)

Writes a single u8 into this hasher.

fn write_u16(&mut self, i: u16)

Writes a single u16 into this hasher.

fn write_u32(&mut self, i: u32)

Writes a single u32 into this hasher.

fn write_u64(&mut self, i: u64)

Writes a single u64 into this hasher.

fn write_u128(&mut self, i: u128)

Writes a single u128 into this hasher.

fn write_usize(&mut self, i: usize)

Writes a single usize into this hasher.

fn write_i8(&mut self, i: i8)

Writes a single i8 into this hasher.

fn write_i16(&mut self, i: i16)

Writes a single i16 into this hasher.

fn write_i32(&mut self, i: i32)

Writes a single i32 into this hasher.

fn write_i64(&mut self, i: i64)

Writes a single i64 into this hasher.

fn write_i128(&mut self, i: i128)

Writes a single i128 into this hasher.

fn write_isize(&mut self, i: isize)

Writes a single isize into this hasher.

fn write_length_prefix(&mut self, len: usize)

🔬This is a nightly-only experimental API. (hasher_prefixfree_extras)

Writes a length prefix into this hasher, as part of being prefix-free.

fn write_str(&mut self, s: &str)

🔬This is a nightly-only experimental API. (hasher_prefixfree_extras)

Writes a single str into this hasher.

impl<T, A> Ord for Box<T, A>

where T: Ord, A: Allocator,

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

fn clamp_to<R>(self, range: R) -> Self

where Self: Sized, R: ClampBounds<Self>,

🔬This is a nightly-only experimental API. (clamp_to)

Restrict a value to a certain range.

impl<T, A> PartialEq for Box<T, A>

where T: PartialEq, A: Allocator,

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Self) -> bool

Inequality operator !=.

impl<T, A> PartialOrd for Box<T, A>

where T: PartialOrd, A: Allocator,

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Self) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Self) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn ge(&self, other: &Self) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

fn gt(&self, other: &Self) -> bool

Tests greater than (for self and other) and is used by the > operator.