smallbox

Small Box optimization: store small item on the stack and fallback to heap for large item.

Documentation

# Usage

First, add the following to your Cargo.toml:

toml [dependencies] smallbox = "0.5"

Next, add this to your crate root:

rust extern crate smallbox;

If you want this crate to work with dynamic-sized type, you can request it via:

toml [dependencies] smallbox = { version = "0.5", features = ["unsize"] }

Currently smallbox by default links to the standard library, but if you would instead like to use this crate in a #![no_std] situation or crate, and want to opt out heap dependency and SmallBox<T> type, you can request this via:

toml [dependencies.smallbox] version = "0.5" features = ["unsize"] default-features = false

Enable heap feature for #![no_std] build to link to alloc crate and bring SmallBox<T> back.

toml [dependencies.smallbox] version = "0.5" features = ["unsize", "heap"] default-features = false

# Feature Flags

This crate has the following cargo feature flags:

• std

  • Optional, enabled by default
  • Use libstd

• heap

  • Optional, enabled by default
  • Support heap fallback by including SmallBox<T>
  • If std feature flag is opted out, this will link alloc crate, and it need nightly rust for that.

• unsize

  • Optional
  • Require nightly rust
  • Enable support for DST (dynamic-sized type).

  Stable Rust

  The only possible way to use this crate on stable rust is to use the default feature flag, which means you can't use it in no_std environment or use it with DST (dynamic-sized type).

  Unsized Type

  Once the feature unsize is enabled, the item type T of SmallBox and StackBox can and should be a unsized type, such as trait object or owned array slice.

  Overview

  This crate delivers two core type:

• SmallBox<T, Space>: Stores T on heap or stack depending on the size of T. It takes StackBox<T, Space> as an varience to store small item, and then fallback to heap allocated Box<T> when type T is larger then the capacity of Space.

• StackBox<T, Space>: Represents as a fixed-capacity allocation, and stores item on stack.

  Example

  Eliminate heap alloction for small items by SmallBox:

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

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

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

  match small { SmallBox::Stack(val) => assert_eq!(*val, [0; 2]), _ => unreachable!() }

  match large { SmallBox::Box(val) => assert_eq!(*val, [0; 32]), _ => unreachable!() } ```

  DST

  The following examples requires unsize feature flag enabled.

  Trait object dynamic-dispatch:

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

  let val: StackBox, S1> = StackBox::new(5usize).unwrap();

  assert!(*val == 5)

  }

  ```

  Any downcasting:

  ```rust use std::any::Any; use smallbox::SmallBox; use smallbox::space::S2;

  let num: SmallBox = SmallBox::new(1234u32);

  if let Some(num) = num.downcastref::() { asserteq!(*num, 1234); } else { unreachable!(); } ```

Roadmap

• check size statically.
• provide to_box() for SmallBox<T> of unsize version.

Contribution

All kinds of contribution are welcome.

• Issue Feel free to open an issue when you find typos, bugs, or have any question.
• Pull requests. Better implementation, more tests, more documents and typo fixes are all welcome.

License

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.