1 unstable release
new 0.9.0 | Mar 25, 2025 |
---|
#634 in Encoding
66KB
1K
SLoC
fixed_str
fixed_str is a Rust crate that provides fixed–capacity, null–padded UTF‑8 string types designed for performance–critical, memory–sensitive, or FFI contexts. With predictable layout and safe UTF‑8 handling, it’s ideal for embedded applications, binary serialization, and other environments where precise control over memory is paramount.
Overview
fixed_str
introduces a primary type, FixedStr<N>
, which uses a [u8; N]
array as its internal storage. Unused bytes are zero–padded and the first null byte (\0
) serves as the string terminator.
The null byte terminator (\0
) also forms the basis for all conversion and comparison, considering the effective string rather than the underlying fixed-size byte array.
Key Features
- Fixed Capacity & Layout: Each string is backed by a fixed-size array, ensuring predictable, constant memory usage.
- Null-Terminated Semantics: The string’s visible content stops at the first
\0
, while preserving the underlying data. - Safe UTF‑8 Truncation: Truncation respects UTF‑8 boundaries—if a character cannot fully fit, it won’t be partially included.
- Const–Safe Construction: Use
FixedStr::new_const
to create fixed strings in constant contexts (with the caveat that UTF‑8 isn’t revalidated). - Incremental Building: The
FixedStrBuf
builder allows you to construct fixed strings piece–by–piece with proper boundary checks. - Serialization Support: Integrates with Serde for human–readable serialization and binrw for binary formats.
- no_std Compatible: Works in embedded and bare–metal systems.
- Standard Trait Implementations: Implements traits like
Clone
,Copy
,Debug
,Display
,PartialEq
, and more.
Installation
Add the following to your Cargo.toml
:
[dependencies]
fixed_str = "0.9"
Or run:
cargo add fixed_str [--feature serde]
Optional feature flags include:
- std – Enables standard library–dependent conversions and formatting (enabled by default).
- serde – For Serde serialization/deserialization.
- binrw – For binary serialization support.
- const_mut_refs – Opt-in for
const_mut_refs
(enabled by default, disable for compatibility with rustc versions <1.83).
Usage Examples
Creating a Fixed String
use fixed_str::FixedStr;
fn main() {
// Create a FixedStr with 10 bytes of storage.
let s = FixedStr::<10>::new("Hello, world!");
// Output will be "Hello, wor" due to safe UTF‑8 truncation.
println!("{}", s);
}
Using the Builder: FixedStrBuf
use fixed_str::{FixedStrBuf, FixedStr};
fn main() {
let mut buf = FixedStrBuf::<12>::new();
buf.try_push_str("Hello").unwrap();
buf.try_push_char(' ').unwrap();
buf.push_str_lossy("world! 👋");
let fixed: FixedStr<12> = buf.finalize();
println!("{}", fixed); // Likely prints "Hello world!"
}
Converting & Viewing
- as_str(): Returns the string up to the first null byte.
- effective_bytes(): Returns the underlying bytes up to the first null byte.
- into_string(): Converts the fixed string into an owned
String
(requires thestd
feature).
API Overview
Constructors
FixedStr::new(&str) -> Self
: Create a fixed string with proper UTF‑8 truncation.FixedStr::new_const(&str) -> Self
: Const–fn compile-time construction with safe truncation.
Modifiers
set(&mut self, &str)
: Replace the content (truncated at the first\0
).clear()
: Zero out the internal buffer.truncate(len: usize)
: Truncate the visible portion to a specified length.
Views & Conversions
as_str() -> &str
: View the string up to the null terminator.try_as_str() -> Result<&str, FixedStrError>
: UTF‑8 checked view.as_bytes() -> &[u8]
: Raw byte view of the entire buffer.effective_bytes() -> &[u8]
: View of the bytes until the first\0
.into_string() -> String
: Convert into an ownedString
(requiresstd
).to_string_lossy() -> String
: Lossy conversion if needed.
License
This project is dual–licensed under either the MIT license or the Apache License, Version 2.0. See LICENSE-MIT and LICENSE-APACHE for details.
Links
Dependencies
~0–430KB