Trait BoxExt 

pub trait BoxExt {
    type Inner;

    // Required methods
    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;
}

Extensions to the Box type

Required Associated Types

type Inner

Type contained inside the Box.

Required Methods

fn new_with<F: FnOnce() -> Self::Inner>(f: F) -> Self

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());
}

fn new_zeroed() -> Self

where Self: Sized, Self::Inner: Zero,

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.

fn try_new(x: Self::Inner) -> Option<Self>

where Self: Sized,

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);
}

fn try_new_with<F: FnOnce() -> Self::Inner>(f: F) -> Option<Self>

where Self: Sized,

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());
}

fn try_new_zeroed() -> Option<Self>

where Self: Sized, Self::Inner: Zero,

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.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl<T> BoxExt for Box<T>

Available on crate feature std only.

type Inner = T

fn new_with<F: FnOnce() -> T>(f: F) -> Box<T>

fn new_zeroed() -> Box<T>

where T: Zero,

fn try_new(x: T) -> Option<Self>

fn try_new_with<F: FnOnce() -> Self::Inner>(f: F) -> Option<Self>

fn try_new_zeroed() -> Option<Self>

where Self::Inner: Zero,

Implementors