Crate qstr 

Cache-efficient, stack-allocated string types.

Overview

qstr provides fixed-capacity string types optimised for locality and cache efficiency. String data is stored on the stack, avoiding heap allocations and pointer indirection. These types are suitable for embedded environments, WebAssembly, parsers and other peformance-sensitive contexts.

Available types

• Variable-length strings with fixed capacity (BoundedStr)
• Fixed-length strings (FixedStr)
• Fixed-capacity string vectors (StrVec)

Feature flags

• std (default): Disable for no_std compatibility
• serde: Support for serialisation/deserialisation with serde

Minimum Supported Rust Version (MSRV)

Rust v1.87+ is required due to the use of slice::copy_from_slice.

Example

use qstr::BStr15;
use qstr::StrVec;
use qstr::Align16;

let str: BStr15 = "aws:us:east:1".into();
let vec: StrVec<u16, 15, Align16> = str.split(":");

assert_eq!(
  vec.iter().collect::<Vec<_>>(),
  vec!["aws", "us", "east", "1"]
);

Aliases

Aliases are provided for common N byte sizes:

• BStrN types are aliases for BoundedStr<N>
• FStrN types are aliases for FixedStr<N>
• StrVecN types are aliases for StrVec<Bitmap(N), N>

N always denotes the total number of storable characters rather than the total struct size. The sizes were chosen with cache efficiency in mind such that most values will fit into a single cache line.

Copy semantics

Unlike String and Vec<String>, all qstr reside fully on the stack and therefore implement Copy. They can be passed by value or returned from functions without cloning.

Safety

unsafe is required internally only for str::from_utf8_unchecked calls. The correct usage is enforced at compile time by keeping the data buffers private and marking FixedStr::from_bytes as unsafe.

Structs

Align8

Zero-sized type (ZST) to enforce 8-byte memory alignment

Align16

Zero-sized type (ZST) to enforce 16-byte memory alignment

Align32

Zero-sized type (ZST) to enforce 32-byte memory alignment

Align64

Zero-sized type (ZST) to enforce 64-byte memory alignment

Align128

Zero-sized type (ZST) to enforce 128-byte memory alignment

BoundedStr

Bounded stack-allocated string

ExceedsCapacity

Length exceeds string’s capacity

FixedStr

Fixed stack-allocated string

StrVec

Stack-allocated, appendable string vector

Type Aliases

BStr7

Variable-length string with a maximum capacity of 7 characters

BStr15

Variable-length string with a maximum capacity of 15 characters

BStr31

Variable-length string with a maximum capacity of 31 characters

BStr63

Variable-length string with a maximum capacity of 63 characters

BStr127

Variable-length string with a maximum capacity of 127 characters

FStr8

Fixed-length string with a capacity of 8 characters

FStr16

Fixed-length string with a capacity of 16 characters

FStr24

Fixed-length string with a capacity of 24 characters

FStr32

Fixed-length string with a capacity of 32 characters

FStr64

Fixed-length string with a capacity of 64 characters

FStr128

Fixed-length string with a capacity of 128 characters

StrVec28

String vector supporting up to 28 items, with a combined capacity of 28 characters

StrVec56

String vector supporting up to 56 items, with a combined capacity of 56 characters

StrVec112

String vector supporting up to 112 items, with a combined capacity of 112 characters