Trait boxext::BoxExt

source · 
pub trait BoxExt {
    type Inner;

    fn new_with<F: FnOnce() -> Self::Inner>(f: F) -> Self;
    fn new_zeroed() -> Self
    where
        Self: Sized,
        Self::Inner: Zero;
    fn try_new(x: Self::Inner) -> Option<Self>
    where
        Self: Sized;
    fn try_new_with<F: FnOnce() -> Self::Inner>(f: F) -> Option<Self>
    where
        Self: Sized;
    fn try_new_zeroed() -> Option<Self>
    where
        Self: Sized,
        Self::Inner: Zero;
}
Expand description

Extensions to the Box type

Required Associated Types

Type contained inside the Box.

Required Methods

Allocates memory on the heap and then places the result of f into it.

This doesn’t actually allocate if Self::Inner is zero-sized.

When building with optimization enabled, this is expected to avoid copies, contrary to Box::new.

Examples
extern crate boxext;
use boxext::BoxExt;

#[derive(Debug, PartialEq)]
struct Foo(usize, usize);

impl Foo {
    fn new(a: usize, b: usize) -> Self {
        Foo(a, b)
   }
}

impl Default for Foo {
    fn default() -> Self {
        Foo::new(0, 1)
    }
}

fn main() {
    // equivalent to `Box::new(Foo(1, 2))`
    let buf = Box::new_with(|| Foo(1, 2));
    assert_eq!(*buf, Foo(1, 2));

    // equivalent to `Box::new(Foo::new(2, 3))`
    let buf = Box::new_with(|| Foo::new(2, 3));
    assert_eq!(*buf, Foo(2, 3));

    // equivalent to `Box::new(Foo::default())`
    let buf = Box::new_with(Foo::default);
    assert_eq!(*buf, Foo::default());
}

Allocates zeroed memory on the heap.

This doesn’t actually allocate if Self::Inner is zero-sized.

This method will obtain zeroed memory directly from the underlying allocator, through the use of calloc, HeapAlloc(..., HEAP_ZERO_MEMORY, ...) or mallocx(..., MALLOCX_ZERO), whichever is used as a global allocator by the rust compiler.

Example
extern crate boxext;
use boxext::BoxExt;

fn main() {
    // equivalent to `Box::new([0usize; 32])`
    let buf: Box<[usize; 32]> = Box::new_zeroed();
    assert_eq!(*buf, [0usize; 32]);
}
Safety

This method is only assumed safe for Self::Inner types implementing the Zero trait, and not available otherwise. See the definition of that trait.

Fallible Box::new

This returns None if memory couldn’t be allocated.

Examples
extern crate boxext;
use boxext::BoxExt;

fn main() {
    let five = Box::try_new(5).unwrap();
    assert_eq!(*five, 5);
}

Fallible Box::new_with

This returns None if memory couldn’t be allocated.

Examples
extern crate boxext;
use boxext::BoxExt;

#[derive(Debug, PartialEq)]
struct Foo(usize, usize);

impl Foo {
    fn new(a: usize, b: usize) -> Self {
        Foo(a, b)
   }
}

impl Default for Foo {
    fn default() -> Self {
        Foo::new(0, 1)
    }
}

fn main() {
    // equivalent to `Box::try_new(Foo(1, 2))`
    let buf = Box::try_new_with(|| Foo(1, 2)).unwrap();
    assert_eq!(*buf, Foo(1, 2));

    // equivalent to `Box::try_new(Foo::new(2, 3))`
    let buf = Box::try_new_with(|| Foo::new(2, 3)).unwrap();
    assert_eq!(*buf, Foo(2, 3));

    // equivalent to `Box::try_new(Foo::default())`
    let buf = Box::try_new_with(Foo::default).unwrap();
    assert_eq!(*buf, Foo::default());
}

Fallible Box::new_zeroed

This returns None if memory couldn’t be allocated.

Example
extern crate boxext;
use boxext::BoxExt;

fn main() {
    // equivalent to `Box::try_new([0usize; 32])`
    let buf: Box<[usize; 32]> = Box::try_new_zeroed().unwrap();
    assert_eq!(*buf, [0usize; 32]);
}
Safety

This method is only assumed safe for Self::Inner types implementing the Zero trait, and not available otherwise. See the definition of that trait.

Implementations on Foreign Types

Implementors