smallnum
Compile-time size optimization for numeric primitives. Macros return smallest numeric type capable of fitting a static bounds. For unsigned integers, macro input is a maximum. For signed integers, macro input may be a maximum or a minimum.
- Can save memory at zero runtime cost.
- Embedded-friendly:
!#[no_std]
. - Safe:
#![forbid(unsafe_code)]
.
What is this for?
-
Saving memory: aiding the compiler in memory layout optimization (aka "struct packing").
- See zero-cost examples below.
-
Improving ergonomics: creating APIs that abstract away the underlying integer type.
- E.g. method params/returns use
usize
, but stored asu16
internally. Upcast is free. Downcast checks for loss of precision.
- E.g. method params/returns use
Doesn't #[repr(packed)]
already save memory?
Not safely. The difference is subtle but important:
-
#[repr(packed)]
removes all padding between struct fields. This incurs a performance penalty for misaligned accesses at best, and causes undefined behavior at worst. It's something you generally want to avoid. -
smallnum
aids packing while maintaining the target's native alignment, without removing padding. It can actually improve [data cache] performance while being fully safe.
For extreme size optimization, you're free to combine smallnum
with #[repr(packed)]
.
Example: Collection Index
When the size of a collection is known at compile-time, the variable used to index it can be size-optimized.
- Target: Value for collection/container index operator
- Yield:
x * 1
where:x < size_of<usize>()
use ;
use size_of_val;
const MAX_SIZE: usize = 500;
let mut my_array: = ;
let idx: usize = 5;
let small_idx: small_unsigned! = 5;
// Equivalent values
my_array = 0xff;
assert_eq!;
// Memory savings (6 bytes on a 64-bit system)
assert_eq!;
Notice that having the trait SmallUnsigned
in scope allows small_idx.usize()
to be called.
This function returns a usize
for convenient indexing, regardless of which type the macro selected (u16
in the above example, hence the 6 byte savings over a 64-bit host's u64
).
Example: Tree Node Metadata
When the maximum capacity of a tree is known at compile time, metadata stored in every node can be size-optimized.
- Target: Internal metatdata
- Yield:
x * n
where:x <= size_of<usize>()
n == node_cnt
use small_unsigned;
use size_of;
const MAX_CAPACITY: usize = 50_000;
// Regular node in a binary tree
// Node with size-optimized metadata
// Per-node memory savings (8 bytes on a 64-bit system)
assert_eq!;
Example: Index-based Graphs
When implementing an {index,arena}-based graph whose maximum capacity is known at compile-time, indexes stored in every structure (edge or node) can be size-optimized.
- Target: Internal "pointer" representation
- Yield:
(x + y) * n
where:x <= size_of<usize>()
y <= size_of<Option<usize>>()
n == edge_cnt
use small_unsigned;
use size_of;
const MAX_CAPACITY: usize = 50_000;
// Based on "Modeling graphs in Rust using vector indices" by Niko Matsakis (April 2015)
// http://smallcultfollowing.com/babysteps/blog/2015/04/06/modeling-graphs-in-rust-using-vector-indices/
// Unoptimized indexes
pub type NodeIdx = usize;
pub type EdgeIdx = usize;
// Optimized indexes
pub type SmallNodeIdx = small_unsigned!;
pub type SmallEdgeIdx = small_unsigned!;
// Per-edge memory savings (18 bytes on a 64-bit system)
assert_eq!;
Advanced Examples
See examples/
directory, cargo run --example <file_name>
.
Macro <-> Type Selection Set
small_unsigned!
<-> (u8
,u16
,u32
,u64
,u128
)small_signed!
<-> (i8
,i16
,i32
,i64
,i128
)
License and Contributing
Licensed under the MIT license. Contributions are welcome!