SmallBox

https://docs.rs/smallbox/0.8.8/smallbox/
Admin
SmallBox is a space-efficient alternative to Box that stores small values on the stack and...
Tokens:6,370
Snippets:89
Trust Score:9.1
Update:3 months ago
Show doc for...
Tokens:
Raw
### Using the smallbox Macro

Source: https://docs.rs/smallbox/0.8.8/smallbox/macro.smallbox.html?search=u32+-%3E+bool

Demonstrates creating SmallBox instances that automatically allocate on the stack or heap based on the size of the input.

```rust
#[macro_use]
extern crate smallbox;

use smallbox::SmallBox;
use smallbox::space::*;

let small: SmallBox<[usize], S4> = smallbox!([0usize; 2]);
let large: SmallBox<[usize], S4> = smallbox!([1usize; 8]);

assert_eq!(small.len(), 2);
assert_eq!(large[7], 1);

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

--------------------------------

### No-std Configuration

Source: https://docs.rs/smallbox/0.8.8/smallbox/index.html?search=u32+-%3E+bool

Configure SmallBox for environments without the standard library.

```toml
[dependencies]
smallbox = { version = "0.8", default-features = false }
```

--------------------------------

### Add SmallBox Dependency

Source: https://docs.rs/smallbox/0.8.8/smallbox/index.html?search=u32+-%3E+bool

Add the crate to your Cargo.toml file.

```toml
[dependencies]
smallbox = "0.8"
```

--------------------------------

### Basic SmallBox usage

Source: https://docs.rs/smallbox/0.8.8/smallbox/index.html

Demonstrates stack allocation for small values and automatic heap fallback for larger ones.

```rust
use smallbox::SmallBox;
use smallbox::space::S4;

// Small values are stored on the stack
let small: SmallBox<[u32; 2], S4> = SmallBox::new([1, 2]);
assert!(!small.is_heap());

// Large values automatically use heap allocation
let large: SmallBox<[u32; 32], S4> = SmallBox::new([0; 32]);
assert!(large.is_heap());

// Use like a regular Box
println!("Values: {:?} and length {}", *small, large.len());
```

--------------------------------

### Convert from Box

Source: https://docs.rs/smallbox/0.8.8/smallbox/struct.SmallBox.html?search=u32+-%3E+bool

Create a SmallBox from a standard Box, keeping the data on the heap.

```rust
use smallbox::SmallBox;
use smallbox::space::S4;

let boxed = Box::new([1, 2, 3, 4]);
let small_box: SmallBox<_, S4> = SmallBox::from_box(boxed);

assert!(small_box.is_heap());
assert_eq!(*small_box, [1, 2, 3, 4]);
```

--------------------------------

### Configure Cargo dependencies

Source: https://docs.rs/smallbox/0.8.8/smallbox/index.html

Add the crate to your project dependencies.

```toml
[dependencies]
smallbox = "0.8"
```

```toml
[dependencies]
smallbox = { version = "0.8", default-features = false }
```

--------------------------------

### SmallBox::new

Source: https://docs.rs/smallbox/0.8.8/smallbox/struct.SmallBox.html?search=u32+-%3E+bool

Creates a new SmallBox, storing the value on the stack if it fits within the specified space, or on the heap otherwise.

```APIDOC
## pub fn new(val: T) -> SmallBox<T, Space>

### Description
Boxes a value on the stack or on the heap depending on its size.

### Signature
`pub fn new(val: T) -> SmallBox<T, Space> where T: Sized`
```

--------------------------------

### Create a SmallBox

Source: https://docs.rs/smallbox/0.8.8/smallbox/struct.SmallBox.html?search=u32+-%3E+bool

Initialize a new SmallBox, which automatically determines whether to store the value on the stack or heap.

```rust
use smallbox::SmallBox;
use smallbox::space::*;

let small: SmallBox<_, S4> = SmallBox::new([0usize; 2]);
let large: SmallBox<_, S4> = SmallBox::new([1usize; 8]);

assert_eq!(small.len(), 2);
assert_eq!(large[7], 1);

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

--------------------------------

### SmallBox::from_box

Source: https://docs.rs/smallbox/0.8.8/smallbox/struct.SmallBox.html?search=u32+-%3E+bool

Creates a SmallBox from a standard Box, transferring ownership without copying.

```APIDOC
## pub fn from_box(boxed: Box<T>) -> Self

### Description
Creates a `SmallBox` from a standard `Box`. The data will always be stored on the heap since it’s already allocated there.
```

--------------------------------

### Define custom space types

Source: https://docs.rs/smallbox/0.8.8/smallbox/index.html

Create custom capacity configurations for specific memory requirements.

```rust
use smallbox::SmallBox;

// Custom 128-byte capacity
type MySpace = [u8; 128];
type MySmallBox<T> = SmallBox<T, MySpace>;

let value: MySmallBox<[u8; 100]> = SmallBox::new([0; 100]);
assert!(!value.is_heap()); // Fits in custom space
```

--------------------------------

### Interoperate with Box

Source: https://docs.rs/smallbox/0.8.8/smallbox/index.html

Convert between SmallBox and standard Box types.

```rust
use smallbox::SmallBox;
use smallbox::space::S4;

// Box -> SmallBox (data stays on heap)
let boxed = Box::new([1, 2, 3, 4]);
let small_box: SmallBox<_, S4> = SmallBox::from_box(boxed);
assert!(small_box.is_heap());

// SmallBox -> Box (data moves to heap if needed)
let back_to_box: Box<[i32; 4]> = SmallBox::into_box(small_box);
```

--------------------------------

### Convert to Box

Source: https://docs.rs/smallbox/0.8.8/smallbox/struct.SmallBox.html?search=u32+-%3E+bool

Convert a SmallBox into a standard Box, moving data to the heap if it was on the stack.

```rust
use smallbox::SmallBox;
use smallbox::space::S4;

let small_box: SmallBox<_, S4> = SmallBox::new([1, 2, 3, 4]);
let boxed: Box<[i32; 4]> = SmallBox::into_box(small_box);

assert_eq!(*boxed, [1, 2, 3, 4]);
```

--------------------------------

### SmallBox::into_box

Source: https://docs.rs/smallbox/0.8.8/smallbox/struct.SmallBox.html?search=u32+-%3E+bool

Converts a SmallBox into a standard Box, moving data to the heap if necessary.

```APIDOC
## pub fn into_box(boxed: SmallBox<T, Space>) -> Box<T>

### Description
Converts a `SmallBox` into a standard `Box`. If the data is stored on the stack, it will be moved to the heap.
```

--------------------------------

### Working with Unsized Types via Macro

Source: https://docs.rs/smallbox/0.8.8/smallbox/index.html?search=u32+-%3E+bool

Use the smallbox! macro to create trait objects and slices on stable Rust.

```rust
#[macro_use]
extern crate smallbox;

use std::any::Any;

use smallbox::SmallBox;
use smallbox::space::S4;

// Create trait objects
let values: Vec<SmallBox<dyn Any, S4>> = vec![
    smallbox!(42u32),
    smallbox!("hello world"),
    smallbox!(vec![1, 2, 3]),
];

// Create slices
let slice: SmallBox<[i32], S4> = smallbox!([1, 2, 3, 4]);
assert_eq!(slice.len(), 4);
```

--------------------------------

### Convert Box to SmallBox

Source: https://docs.rs/smallbox/0.8.8/smallbox/struct.SmallBox.html?search=

Transfer ownership from a standard Box to a SmallBox, ensuring the data remains on the heap.

```rust

use smallbox::SmallBox;
use smallbox::space::S4;

let boxed = Box::new([1, 2, 3, 4]);
let small_box: SmallBox<_, S4> = SmallBox::from_box(boxed);

assert!(small_box.is_heap());
assert_eq!(*small_box, [1, 2, 3, 4]);
```

--------------------------------

### smallbox! Macro

Source: https://docs.rs/smallbox/0.8.8/smallbox/macro.smallbox.html

The smallbox! macro is used to create a new SmallBox instance. It checks coercion rules at compile-time and allows for storing values on the stack or heap.

```APIDOC
## smallbox!

### Description
Creates a new `SmallBox` instance. This macro relaxes the `T: Sized` constraint and performs compile-time checks for valid type coercion.

### Signature
`smallbox!(val: U) -> SmallBox<T, Space>`

### Example
```rust
#[macro_use]
extern crate smallbox;

use smallbox::SmallBox;
use smallbox::space::*;

let small: SmallBox<[usize], S4> = smallbox!([0usize; 2]);
let large: SmallBox<[usize], S4> = smallbox!([1usize; 8]);

assert_eq!(small.len(), 2);
assert_eq!(large[7], 1);
assert!(large.is_heap() == true);
```
```

--------------------------------

### smallbox!(val)

Source: https://docs.rs/smallbox/0.8.8/smallbox/macro.smallbox.html?search=std%3A%3Avec

Creates a new SmallBox instance. This macro checks coercion rules at compile-time and allows for unsized types.

```APIDOC
## smallbox!(val)

### Description
Creates a new `SmallBox` instance. It is similar to `SmallBox::new` but relaxes the `T: Sized` constraint, allowing the macro to check coercion rules from the input type to the target type at compile-time.

### Signature
`smallbox!<U: Sized, T: ?Sized>(val: U) -> SmallBox<T, Space>`

### Example
```rust
#[macro_use]
extern crate smallbox;

use smallbox::SmallBox;
use smallbox::space::*;

// Creates a SmallBox on the stack
let small: SmallBox<[usize], S4> = smallbox!([0usize; 2]);

// Creates a SmallBox on the heap due to size
let large: SmallBox<[usize], S4> = smallbox!([1usize; 8]);

assert_eq!(small.len(), 2);
assert_eq!(large[7], 1);
assert!(large.is_heap() == true);
```
```

--------------------------------

### smallbox!(expr)

Source: https://docs.rs/smallbox/0.8.8/smallbox/macro.smallbox.html?search=

Creates a new SmallBox instance from an expression. This macro checks coercion rules at compile-time and supports types that are not necessarily Sized.

```APIDOC
## smallbox!(expr)

### Description
Creates a new `SmallBox` instance. It is similar to `SmallBox::new` but relaxes the `T: Sized` constraint, allowing for flexible storage allocation on the stack or heap.

### Signature
`smallbox!<U: Sized, T: ?Sized>(val: U) -> SmallBox<T, Space>`

### Example
```rust
#[macro_use]
extern crate smallbox;

use smallbox::SmallBox;
use smallbox::space::*;

let small: SmallBox<[usize], S4> = smallbox!([0usize; 2]);
let large: SmallBox<[usize], S4> = smallbox!([1usize; 8]);

assert_eq!(small.len(), 2);
assert_eq!(large[7], 1);
assert!(large.is_heap() == true);
```
```

--------------------------------

### smallbox!

Source: https://docs.rs/smallbox/0.8.8/smallbox/macro.smallbox.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

The smallbox! macro creates a new SmallBox instance. It checks coercion rules from the input type to the target type at compile-time, allowing for the creation of SmallBox instances where the inner type T does not need to be Sized.

```APIDOC
## smallbox!

### Description
Creates a new `SmallBox` instance. This macro is similar to `SmallBox::new` but relaxes the `T: Sized` constraint by validating type coercion at compile-time.

### Signature
`smallbox!<U: Sized, T: ?Sized>(val: U) -> SmallBox<T, Space>`

### Usage Example
```rust
#[macro_use]
extern crate smallbox;

use smallbox::SmallBox;
use smallbox::space::*;

// Create a SmallBox on the stack
let small: SmallBox<[usize], S4> = smallbox!([0usize; 2]);

// Create a SmallBox on the heap
let large: SmallBox<[usize], S4> = smallbox!([1usize; 8]);
```
```

--------------------------------

### SmallBox::resize

Source: https://docs.rs/smallbox/0.8.8/smallbox/struct.SmallBox.html?search=u32+-%3E+bool

Changes the capacity of the SmallBox, potentially moving stack-allocated data to the heap.

```APIDOC
## pub fn resize<ToSpace>(self) -> SmallBox<T, ToSpace>

### Description
Change the capacity of `SmallBox`. This method may move stack-allocated data from stack to heap when inline space is not sufficient. Once the data is moved to heap, it will never be moved back to stack.
```

--------------------------------

### Define SmallBox struct

Source: https://docs.rs/smallbox/0.8.8/smallbox/struct.SmallBox.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

The basic structure definition for SmallBox.

```rust
pub struct SmallBox<T: ?Sized, Space> { /* private fields */ }
```

--------------------------------

### smallbox Macro Definition

Source: https://docs.rs/smallbox/0.8.8/smallbox/macro.smallbox.html?search=u32+-%3E+bool

The internal structure of the smallbox macro.

```rust
macro_rules! smallbox {
    ( $e: expr ) => { ... };
}
```

--------------------------------

### Check heap allocation

Source: https://docs.rs/smallbox/0.8.8/smallbox/struct.SmallBox.html?search=u32+-%3E+bool

Determine if the data inside the SmallBox is currently stored on the heap.

```rust
use smallbox::SmallBox;
use smallbox::space::S1;

let stacked: SmallBox<usize, S1> = SmallBox::new(0usize);
assert!(!stacked.is_heap());

let heaped: SmallBox<(usize, usize), S1> = SmallBox::new((0usize, 1usize));
assert!(heaped.is_heap());
```

--------------------------------

### SmallBox::is_heap

Source: https://docs.rs/smallbox/0.8.8/smallbox/struct.SmallBox.html?search=u32+-%3E+bool

Checks if the data is currently allocated on the heap.

```APIDOC
## pub fn is_heap(&self) -> bool

### Description
Returns true if data is allocated on heap.
```

--------------------------------

### SmallBox::into_inner

Source: https://docs.rs/smallbox/0.8.8/smallbox/struct.SmallBox.html?search=u32+-%3E+bool

Consumes the SmallBox and returns ownership of the boxed value.

```APIDOC
## pub fn into_inner(self) -> T

### Description
Consumes the SmallBox and returns ownership of the boxed value where T: Sized.
```

--------------------------------

### Resize SmallBox capacity

Source: https://docs.rs/smallbox/0.8.8/smallbox/struct.SmallBox.html?search=u32+-%3E+bool

Change the capacity of a SmallBox, potentially moving stack-allocated data to the heap if the new space is insufficient.

```rust
use smallbox::SmallBox;
use smallbox::space::S2;
use smallbox::space::S4;

let s: SmallBox<_, S4> = SmallBox::new([0usize; 4]);
let m: SmallBox<_, S2> = s.resize();
```

--------------------------------

### Work with unsized types

Source: https://docs.rs/smallbox/0.8.8/smallbox/index.html

Handle trait objects and slices using the macro or nightly coercion features.

```rust
#[macro_use]
extern crate smallbox;

use std::any::Any;

use smallbox::SmallBox;
use smallbox::space::S4;

// Create trait objects
let values: Vec<SmallBox<dyn Any, S4>> = vec![
    smallbox!(42u32),
    smallbox!("hello world"),
    smallbox!(vec![1, 2, 3]),
];

// Create slices
let slice: SmallBox<[i32], S4> = smallbox!([1, 2, 3, 4]);
assert_eq!(slice.len(), 4);
```

```rust
use std::any::Any;

use smallbox::SmallBox;
use smallbox::space::S4;

// Automatic coercion to trait objects
let num: SmallBox<dyn Any, S4> = SmallBox::new(42u32);
let text: SmallBox<dyn Any, S4> = SmallBox::new("hello");

// Automatic coercion to slices
let slice: SmallBox<[i32], S4> = SmallBox::new([1, 2, 3, 4]);
```

--------------------------------

### Consume SmallBox

Source: https://docs.rs/smallbox/0.8.8/smallbox/struct.SmallBox.html?search=u32+-%3E+bool

Retrieve the inner value from a SmallBox, consuming the box in the process.

```rust
use smallbox::SmallBox;
use smallbox::space::S1;

let stacked: SmallBox<_, S1> = SmallBox::new([21usize]);
let val = stacked.into_inner();
assert_eq!(val[0], 21);

let boxed: SmallBox<_, S1> = SmallBox::new(vec![21, 56, 420]);
let val = boxed.into_inner();
assert_eq!(val[1], 56);
```

--------------------------------

### S64 Struct Definition

Source: https://docs.rs/smallbox/0.8.8/smallbox/space/struct.S64.html?search=

The definition of the S64 struct, which contains private fields.

```rust
pub struct S64 { /* private fields */ }
```

--------------------------------

### S32 Struct Definition

Source: https://docs.rs/smallbox/0.8.8/smallbox/space/struct.S32.html?search=

The definition of the S32 struct, which contains private fields.

```rust
pub struct S32 { /* private fields */ }
```

--------------------------------

### S16 Struct Definition

Source: https://docs.rs/smallbox/0.8.8/smallbox/space/struct.S16.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

The definition of the S16 struct, which contains private fields.

```rust
pub struct S16 { /* private fields */ }
```

--------------------------------

### S1 Struct Definition

Source: https://docs.rs/smallbox/0.8.8/smallbox/space/struct.S1.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

The definition of the S1 struct, which contains private fields.

```rust
pub struct S1 { /* private fields */ }
```

--------------------------------

### S8 Struct Definition

Source: https://docs.rs/smallbox/0.8.8/smallbox/space/struct.S8.html

The definition of the S8 struct, which contains private fields.

```rust
pub struct S8 { /* private fields */ }
```

--------------------------------

### Define S2 struct

Source: https://docs.rs/smallbox/0.8.8/smallbox/space/struct.S2.html?search=

The definition of the S2 struct representing 2 * usize space.

```rust
pub struct S2 { /* private fields */ }
```

--------------------------------

### Downcast types

Source: https://docs.rs/smallbox/0.8.8/smallbox/index.html

Attempt to downcast a SmallBox containing a trait object back to its concrete type.

```rust
#[macro_use]
extern crate smallbox;

use std::any::Any;

use smallbox::SmallBox;
use smallbox::space::S2;

let value: SmallBox<dyn Any, S2> = smallbox!(42u32);

match value.downcast::<u32>() {
    Ok(num) => println!("Got number: {}", *num),
    Err(original) => println!("Not a u32, got: {:?}", original.type_id()),
}
```

--------------------------------

### Automatic Coercion for Unsized Types

Source: https://docs.rs/smallbox/0.8.8/smallbox/index.html?search=u32+-%3E+bool

Use automatic coercion to trait objects and slices (requires nightly and coerce feature).

```rust
use std::any::Any;

use smallbox::SmallBox;
use smallbox::space::S4;

// Automatic coercion to trait objects
let num: SmallBox<dyn Any, S4> = SmallBox::new(42u32);
let text: SmallBox<dyn Any, S4> = SmallBox::new("hello");

// Automatic coercion to slices
let slice: SmallBox<[i32], S4> = SmallBox::new([1, 2, 3, 4]);
```

--------------------------------

### S4 Struct Definition

Source: https://docs.rs/smallbox/0.8.8/smallbox/space/struct.S4.html?search=

The definition of the S4 struct, which contains private fields.

```rust
pub struct S4 { /* private fields */ }
```
Tokens:
Raw