Struct Box

pub struct Box<T: ?Sized, A: Allocator = Global> { /* private fields */ }

A pointer type that uniquely owns a heap allocation of type T.

Implementations

impl<T> Box<T, Global>

pub fn try_new(value: T) -> 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 rune::alloc::Box;

let five = Box::try_new(5)?;

pub fn try_pin(x: T) -> Result<Pin<Box<T>>, AllocError>

Constructs a new Pin<Box<T>>. If T does not implement Unpin, then x will be pinned in memory and unable to be moved.

Constructing and pinning of the Box can also be done in two steps: Box::try?pin(x) does the same as Box::into_pin([Box::try?new](x)). Consider using into_pin if you already have a Box<T>, or if you want to construct a (pinned) Box in a different way than with Box::try_new.

impl<T: ?Sized> Box<T>

pub fn from_std(b: Box<T>) -> Result<Self, Error>

Convert from a std Box.

This causes the underlying allocation to be accounted for by the Global allocator.

A caveat of this method is that the allocation is already in use, but this might still be necessary because we want access to certain methods in std Box such as the ability to coerce to unsized values.

Examples

use rune::alloc::{Box, Vec};
use rune::alloc::limit;
use std::boxed::Box as StdBox;

assert_eq!(limit::get(), usize::MAX);

let b: StdBox<dyn Iterator<Item = u32>> = StdBox::new(1..3);
let mut b = Box::from_std(b)?;
assert_eq!(b.next(), Some(1));
assert_eq!(b.next(), Some(2));
assert_eq!(b.next(), None);

assert!(limit::get() < usize::MAX);
drop(b);

assert_eq!(limit::get(), usize::MAX);

impl<T, A: Allocator> Box<T, A>

pub fn try_new_in(x: T, alloc: A) -> Result<Self, AllocError>

Allocates memory in the given allocator then places x into it, returning an error if the allocation fails

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

Examples

use rune::alloc::Box;
use rune::alloc::alloc::Global;

let five = Box::try_new_in(5, Global)?;

pub fn try_new_uninit_in(alloc: A) -> Result<Box<MaybeUninit<T>, A>, AllocError>

where A: Allocator,

Constructs a new box with uninitialized contents in the provided allocator, returning an error if the allocation fails

Examples

use rune::alloc::Box;
use rune::alloc::alloc::Global;

let mut five = Box::<u32>::try_new_uninit_in(Global)?;

let five: Box<u32> = unsafe {
    // Deferred initialization:
    five.as_mut_ptr().write(5);

    five.assume_init()
};

assert_eq!(*five, 5);

pub fn into_inner(boxed: Self) -> T

Consumes the Box, returning the wrapped value.

impl<T: ?Sized, A: Allocator> Box<T, A>

pub fn leak<'a>(b: Self) -> &'a mut T

where A: 'a,

Consumes and leaks the Box, returning a mutable reference, &'a mut T. Note that the type T must outlive the chosen lifetime 'a. If the type has only static references, or none at all, then this may be chosen to be 'static.

This function is mainly useful for data that lives for the remainder of the program’s life. Dropping the returned reference will cause a memory leak. If this is not acceptable, the reference should first be wrapped with the Box::from_raw_in function producing a Box. This Box can then be dropped which will properly destroy T and release the allocated memory.

Note: this is an associated function, which means that you have to call it as Box::leak(b) instead of b.leak(). This is so that there is no conflict with a method on the inner type.

Examples

Simple usage:

use rune::alloc::Box;

let x = Box::try_new(41)?;
let static_ref: &'static mut usize = Box::leak(x);
*static_ref += 1;
assert_eq!(*static_ref, 42);

Unsized data:

use rune::alloc::{try_vec, Box};

let x = try_vec![1, 2, 3].try_into_boxed_slice()?;
let static_ref = Box::leak(x);
static_ref[0] = 4;
assert_eq!(*static_ref, [4, 2, 3]);

pub fn into_pin(boxed: Self) -> Pin<Self>

where A: 'static,

Converts a Box<T> into a Pin<Box<T>>. If T does not implement Unpin, then *boxed will be pinned in memory and unable to be moved.

This conversion does not allocate on the heap and happens in place.

This is also available via From.

Constructing and pinning a Box with Box::into_pin([Box::try?new](x)) can also be written more concisely using [Box::try?pin](x). This into_pin method is useful if you already have a Box<T>, or you are constructing a (pinned) Box in a different way than with Box::try_new.

Notes

It’s not recommended that crates add an impl like From<Box<T>> for Pin<T>, as it’ll introduce an ambiguity when calling Pin::from. A demonstration of such a poor impl is shown below.

use rune::alloc::Box;

struct Foo; // A type defined in this crate.
impl From<Box<()>> for Pin<Foo> {
    fn from(_: Box<()>) -> Pin<Foo> {
        Pin::new(Foo)
    }
}

let foo = Box::try_new(())?;
let bar = Pin::from(foo);

pub unsafe fn from_raw_in(raw: *mut T, alloc: A) -> Self

Constructs a box from a raw pointer in the given allocator.

After calling this function, the raw pointer is owned by the resulting Box. Specifically, the Box destructor will call the destructor of T and free the allocated memory. For this to be safe, the memory must have been allocated in accordance with the memory layout used by Box .

Safety

This function is unsafe because improper use may lead to memory problems. For example, a double-free may occur if the function is called twice on the same raw pointer.

Examples

Recreate a Box which was previously converted to a raw pointer using Box::into_raw_with_allocator:

use rune::alloc::Box;
use rune::alloc::alloc::Global;

let x = Box::try_new_in(5, Global)?;
let (ptr, alloc) = Box::into_raw_with_allocator(x);
let x = unsafe { Box::from_raw_in(ptr, alloc) };

Manually create a Box from scratch by using the system allocator:

use core::alloc::Layout;

use rune::alloc::Box;
use rune::alloc::alloc::{Allocator, Global};

unsafe {
    let ptr = Global.allocate(Layout::new::<i32>())?.as_ptr() as *mut i32;
    // In general .write is required to avoid attempting to destruct
    // the (uninitialized) previous contents of `ptr`, though for this
    // simple example `*ptr = 5` would have worked as well.
    ptr.write(5);
    let x = Box::from_raw_in(ptr, Global);
}

pub fn into_raw_with_allocator(b: Self) -> (*mut T, A)

Consumes the Box, returning a wrapped raw pointer and the allocator.

The pointer will be properly aligned and non-null.

After calling this function, the caller is responsible for the memory previously managed by the Box. In particular, the caller should properly destroy T and release the memory, taking into account the memory layout used by Box. The easiest way to do this is to convert the raw pointer back into a Box with the Box::from_raw_in function, allowing the Box destructor to perform the cleanup.

Note: this is an associated function, which means that you have to call it as Box::into_raw_with_allocator(b) instead of b.into_raw_with_allocator(). This is so that there is no conflict with a method on the inner type.

Examples

Converting the raw pointer back into a Box with Box::from_raw_in for automatic cleanup:

use rune::alloc::{Box, String};
use rune::alloc::alloc::Global;

let x = Box::try_new_in(String::try_from("Hello")?, Global)?;
let (ptr, alloc) = Box::into_raw_with_allocator(x);
let x = unsafe { Box::from_raw_in(ptr, alloc) };

Manual cleanup by explicitly running the destructor and deallocating the memory:

use core::alloc::Layout;
use core::ptr::{self, NonNull};

use rune::alloc::{Box, String};
use rune::alloc::alloc::{Allocator, Global};

let x = Box::try_new_in(String::try_from("Hello")?, Global)?;

let (ptr, alloc) = Box::into_raw_with_allocator(x);

unsafe {
    ptr::drop_in_place(ptr);
    let non_null = NonNull::new_unchecked(ptr);
    alloc.deallocate(non_null.cast(), Layout::new::<String>());
}

impl<T, A: Allocator> Box<MaybeUninit<T>, A>

pub unsafe fn assume_init(self) -> Box<T, A>

Converts to Box<T, A>.

Safety

As with MaybeUninit::assume_init, it is up to the caller to guarantee that the value really is in an initialized state. Calling this when the content is not yet fully initialized causes immediate undefined behavior.

Examples

use rune::alloc::Box;
use rune::alloc::alloc::Global;

let mut five = Box::<u32>::try_new_uninit_in(Global)?;

let five: Box<u32> = unsafe {
    // Deferred initialization:
    five.as_mut_ptr().write(5);

    five.assume_init()
};

assert_eq!(*five, 5);

impl<T, A: Allocator> Box<[T], A>

pub fn try_new_uninit_slice_in( len: usize, alloc: A, ) -> Result<Box<[MaybeUninit<T>], A>, Error>

Constructs a new boxed slice with uninitialized contents. Returns an error if the allocation fails

Examples

use rune::alloc::Box;
use rune::alloc::alloc::Global;

let mut values = Box::<[u32]>::try_new_uninit_slice_in(3, Global)?;

let values = unsafe {
    // Deferred initialization:
    values[0].as_mut_ptr().write(1);
    values[1].as_mut_ptr().write(2);
    values[2].as_mut_ptr().write(3);
    values.assume_init()
};

assert_eq!(*values, [1, 2, 3]);

impl<T, A: Allocator> Box<[MaybeUninit<T>], A>

pub unsafe fn assume_init(self) -> Box<[T], A>

Converts to Box<[T], A>.

Safety

As with MaybeUninit::assume_init, it is up to the caller to guarantee that the values really are in an initialized state. Calling this when the content is not yet fully initialized causes immediate undefined behavior.

Examples

use rune::alloc::Box;
use rune::alloc::alloc::Global;

let mut values = Box::<[u32]>::try_new_uninit_slice_in(3, Global)?;

let values = unsafe {
    // Deferred initialization:
    values[0].as_mut_ptr().write(1);
    values[1].as_mut_ptr().write(2);
    values[2].as_mut_ptr().write(3);
    values.assume_init()
};

assert_eq!(*values, [1, 2, 3]);

Trait Implementations

impl<T: ?Sized, A: Allocator> AsMut<T> for Box<T, A>

fn as_mut(&mut self) -> &mut T

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

impl<T: ?Sized, A: Allocator> AsRef<T> for Box<T, A>

fn as_ref(&self) -> &T

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

impl<T: ?Sized, A: Allocator> Borrow<T> for Box<T, A>

fn borrow(&self) -> &T

Immutably borrows from an owned value.

impl<T: ?Sized, A: Allocator> BorrowMut<T> for Box<T, A>

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value.

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

where T: Debug + ?Sized,

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

Formats the value using the given formatter.

impl<T> Default for Box<[T], Global>

fn default() -> Self

Returns the “default value” for a type.

impl Default for Box<str, Global>

fn default() -> Self

Returns the “default value” for a type.

impl<T: ?Sized, A: Allocator> Deref for Box<T, A>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<T: ?Sized, A: Allocator> DerefMut for Box<T, A>

fn deref_mut(&mut self) -> &mut T

Mutably dereferences the value.

impl<'de, T> Deserialize<'de> for Box<[T]>

where T: Deserialize<'de>,

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<'de, T: Deserialize<'de>> Deserialize<'de> for Box<T>

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<'de> Deserialize<'de> for Box<str>

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

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

where T: Display + ?Sized,

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

Formats the value using the given formatter.

impl<T: ?Sized, A: Allocator> Drop for Box<T, A>

fn drop(&mut self)

Executes the destructor for this type.

impl<T, A: Allocator> From<Box<[T], A>> for Vec<T, A>

fn from(s: Box<[T], A>) -> Self

Convert a boxed slice into a vector by transferring ownership of the existing heap allocation.

Examples

use rune::alloc::{Box, Vec};
use rune::alloc::try_vec;

let s: Box<[i32]> = Box::try_from([10, 40, 30])?;
let x: Vec<i32> = Vec::from(s);

assert_eq!(x, [10, 40, 30]);

let s: Box<[i32]> = try_vec![10, 40, 30].try_into_boxed_slice()?;
let x: Vec<i32> = Vec::from(s);

assert_eq!(x, [10, 40, 30]);

impl<T: ?Sized, A> From<Box<T, A>> for Pin<Box<T, A>>

where A: 'static + Allocator,

fn from(boxed: Box<T, A>) -> Self

Converts a Box<T> into a Pin<Box<T>>. If T does not implement Unpin, then *boxed will be pinned in memory and unable to be moved.

This conversion does not allocate on the heap and happens in place.

This is also available via Box::into_pin.

Constructing and pinning a Box with <Pin<Box<T>>>::from([Box::try?new](x)) can also be written more concisely using [Box::try?pin](x). This From implementation is useful if you already have a Box<T>, or you are constructing a (pinned) Box in a different way than with Box::try_new.

impl<A: Allocator> From<Box<str, A>> for Box<[u8], A>

fn from(value: Box<str, A>) -> Self

Converts to this type from the input type.

impl<A: Allocator> From<Box<str, A>> for String<A>

fn from(s: Box<str, A>) -> String<A>

Converts the given boxed str slice to a String. It is notable that the str slice is owned.

Examples

Basic usage:

use rune::alloc::{Box, String};

let s1: String = String::try_from("hello world")?;
let s2: Box<str> = s1.try_into_boxed_str()?;
let s3: String = String::from(s2);

assert_eq!("hello world", s3);

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

where T: Hash + ?Sized,

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: Allocator> Ord for Box<T, A>

where T: Ord + ?Sized,

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.

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

where T: PartialEq + ?Sized,

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

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

where T: PartialOrd + ?Sized,

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: &Rhs) -> bool

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

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

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

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

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

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

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

impl<T> Serialize for Box<T>

where T: Serialize + ?Sized,

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl<T, A: Allocator + Clone> TryClone for Box<[T], A>

where T: TryClone,

fn try_clone(&self) -> Result<Self, Error>

Try to clone the current value, raising an allocation error if it’s unsuccessful.

fn try_clone_from(&mut self, source: &Self) -> Result<(), Error>

Performs copy-assignment from source.

impl<A: Allocator + Clone> TryClone for Box<Path, A>

fn try_clone(&self) -> Result<Self, Error>

Try to clone the current value, raising an allocation error if it’s unsuccessful.

fn try_clone_from(&mut self, source: &Self) -> Result<(), Error>

Performs copy-assignment from source.

impl<T, A: Allocator + Clone> TryClone for Box<T, A>

where T: TryClone,

fn try_clone(&self) -> Result<Self, Error>

Try to clone the current value, raising an allocation error if it’s unsuccessful.

fn try_clone_from(&mut self, source: &Self) -> Result<(), Error>

Performs copy-assignment from source.

impl<A: Allocator + Clone> TryClone for Box<str, A>

fn try_clone(&self) -> Result<Self, Error>

Try to clone the current value, raising an allocation error if it’s unsuccessful.

fn try_clone_from(&mut self, source: &Self) -> Result<(), Error>

Performs copy-assignment from source.

impl TryFrom<&[u8]> for Box<[u8]>

fn try_from(values: &[u8]) -> Result<Self, Error>

Converts a &[u8] into a Box<[u8]>.

Examples

use rune::alloc::Box;

let s: Box<[u8]> = Box::try_from(&b"Hello World"[..])?;
assert_eq!(s.as_ref(), b"Hello World");

type Error = Error

The type returned in the event of a conversion error.

impl TryFrom<&Path> for Box<Path>

fn try_from(path: &Path) -> Result<Self, Error>

Converts a &[u8] into a Box<[u8]>.

Examples

use std::path::Path;
use rune::alloc::Box;

let path = Path::new("foo/bar");

let s: Box<Path> = Box::try_from(path)?;
assert_eq!(s.as_ref(), Path::new("foo/bar"));

type Error = Error

The type returned in the event of a conversion error.

impl TryFrom<&str> for Box<str>

fn try_from(values: &str) -> Result<Self, Error>

Converts a &str into a Box<str>.

Examples

use rune::alloc::Box;

let s: Box<str> = Box::try_from("Hello World")?;
assert_eq!(s.as_ref(), "Hello World");

type Error = Error

The type returned in the event of a conversion error.

impl<T, const N: usize> TryFrom<[T; N]> for Box<[T]>

type Error = Error

The type returned in the event of a conversion error.

fn try_from(values: [T; N]) -> Result<Self, Error>

Performs the conversion.

impl<T> TryFrom<Box<[T]>> for Box<[T]>

type Error = Error

The type returned in the event of a conversion error.

fn try_from(values: Box<[T]>) -> Result<Self, Error>

Performs the conversion.

impl<T, const N: usize> TryFrom<Box<[T]>> for Box<[T; N]>

fn try_from(boxed_slice: Box<[T]>) -> Result<Self, Self::Error>

Attempts to convert a Box<[T]> into a Box<[T; N]>.

The conversion occurs in-place and does not require a new memory allocation.

Errors

Returns the old Box<[T]> in the Err variant if boxed_slice.len() does not equal N.

type Error = Box<[T]>

The type returned in the event of a conversion error.

impl TryFrom<Cow<'_, str>> for Box<str>

fn try_from(s: Cow<'_, str>) -> Result<Self, Error>

Converts the given String to a boxed str slice that is owned.

Examples

use rune::alloc::Box;
use rune::alloc::borrow::Cow;

let s2: Box<str> = Box::try_from(Cow::Borrowed("Hello World"))?;

assert_eq!("Hello World", s2.as_ref());

type Error = Error

The type returned in the event of a conversion error.

impl<A: Allocator> TryFrom<String<A>> for Box<str, A>

fn try_from(s: String<A>) -> Result<Self, Error>

Converts the given String to a boxed str slice that is owned.

Examples

use rune::alloc::{String, Box};

let s1: String = String::try_from("Hello World")?;
let s2: Box<str> = Box::try_from("Hello World")?;

assert_eq!("Hello World", s2.as_ref());

type Error = Error

The type returned in the event of a conversion error.

impl TryFrom<String> for Box<str>

fn try_from(string: String) -> Result<Self, Error>

Converts a std String into a Box<str>.

Examples

use rune::alloc::Box;

let s = String::from("Hello World");
let s: Box<str> = Box::try_from(s)?;
assert_eq!(s.as_ref(), "Hello World");

type Error = Error

The type returned in the event of a conversion error.

impl<T, A: Allocator> TryFrom<Vec<T, A>> for Box<[T], A>

type Error = Error

The type returned in the event of a conversion error.

fn try_from(vec: Vec<T, A>) -> Result<Self, Error>

Performs the conversion.

impl<T, A: Allocator> TryFromIteratorIn<T, A> for Box<[T], A>

fn try_from_iter_in<I>(iter: I, alloc: A) -> Result<Self, Error>

where I: IntoIterator<Item = T>,

Creates a value from an iterator within an allocator.

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

where T: Eq + ?Sized,

impl<T: ?Sized, A> Unpin for Box<T, A>

where A: 'static + Allocator,