# `nanobox`

[![crates.io](https://img.shields.io/crates/v/nanobox.svg)](https://crates.io/crates/nanobox)


`NanoBox` optimization: store small item on stack and fallback to heap for large item.

## Documentation

# Usage

First, add the following to your `Cargo.toml`:

```toml
[dependencies]
nanobox = "0.1"
```

# Unsized Type

There are two ways to have an unsized `NanoBox`: Using `nanobox!()` macro (or `nb!()` if you are lazy) or coercing from a sized `NanoBox` instance(requires nightly compiler).

Once the feature `coerce` is enabled, sized `NanoBox<T>` will be automatically coerced into `NanoBox<T: ?Sized>` if necessary.

# Example

Eliminate heap alloction for small items by `NanoBox`:

```rust
use nanobox::NanoBox;

let small: NanoBox<_> = NanoBox::new([0; 2]);
let large: NanoBox<_> = NanoBox::new([0; 32]);

assert_eq!(small.len(), 2);
assert_eq!(large.len(), 32);

assert_eq!(*small, [0; 2]);
assert_eq!(*large, [0; 32]);

assert!(small.is_heap() == false);
assert!(large.is_heap() == true);
```

## Unsized type

Construct with `nanobox!()` macro:

```rust
use nanobox::NanoBox;
use nanobox::nb;

let array: NanoBox<[usize]> = nb!([0usize, 1]);

assert_eq!(array.len(), 2);
assert_eq!(*array, [0, 1]);
```

coerce

```rust
use nanobox::NanoBox;
 
let array: NanoBox<[usize]> = NanoBox::new([0usize, 1]);

assert_eq!(array.len(), 2);
assert_eq!(*array, [0, 1]);
```

`Any` downcasting:

```rust
use std::any::Any;
use nanobox::NanoBox;
use nanobox::nb;

let num: NanoBox<dyn Any> = nb!(1234u32);

if let Some(num) = num.downcast_ref::<u32>() {
    assert_eq!(*num, 1234);
} else {
    unreachable!();
}
```


# Capacity

`NanoBox` has a capacity of 3*`usize` by default. You can change the capacity by specifying the capacity type parameter.

```text
nanobox_small_item_small_space
                        time:   [494.41 ps 497.13 ps 500.13 ps]
nanobox_small_item_large_space
                        time:   [5.4159 ns 5.4886 ns 5.5663 ns]
box_small_item          
                        time:   [8.8157 ns 8.8830 ns 8.9659 ns]
```

497.13 ps vs 8.8830 ns for small item in small space. 5.5 ns vs 8.9 ns for small item in large space. `NanoBox` is faster than `Box` for small items in small space and large items in large space.


```text
nanobox_large_item_small_space
                        time:   [23.428 ns 23.478 ns 23.523 ns]

nanobox_large_item_large_space
                        time:   [18.288 ns 18.461 ns 18.605 ns]

box_large_item          time:   [16.378 ns 16.438 ns 16.497 ns]
```

for large items, `NanoBox` is slower than `Box` in every cases.
you don't want to run into stack overflow, so you should use `Box` for large items.


# License

Licensed under either of

 * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
 * MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)

at your option.

# Thanks

thanks to @andylokandy for writting [smallbox](https://github.com/andylokandy/smallbox)