Expand description
Library for strings of fixed maximum lengths that can be copied and stack-allocated using const generics.
The structures provided by this crate are fstr, zstr and tstr. However, tstr is not exported and can only be used through the type aliases str4, str8, str16, through str256.
The size of (std::mem::size_of) types str8 and zstr<8> are 8 bytes, compared to 16 bytes for &str (on most systems), providing more efficient ways of representing very small strings. Unicode is supported.
The three versions of strings implemented are as follows.
- A fstr<N> stores a string of up to N bytes. It is represented underneath using a [u8;N] array and a separate usize variable holding the length.
- A zstr<N> stores a zero-terminated string, without a separate length variable, and can hold strings of up to N-1 bytes.
- The types str4, str8 through str256 are aliases for internal type
tstr<8> through tstr<256> respectively. These strings are stored
in an array of u8 bytes with the first byte holding the length of the
string. Each tstr<N> can store strings of up to N-1 bytes, with
maximum N=256. tstr
combines the best of fstr and zstr in terms of speed
and memory efficiency. However, because Rust does not currently provide
a why to specify conditions on const generics at compile time, such as
where N<=256, the tstr type is not exported and can only be used through the aliases. These strings implement the same functions and traits as fstr and zstr so the documentation for these structures also apply to the alias types.
Version 0.2.6 impls AsRef
For version 0.2.2, the str8 through str256 type aliases where
changed to refer to another, internal type distinct from fstr and
zstr. This type represents strings of up to 255 bytes with a
[u8;N] underneath where it’s assumed that N<=256. The first
byte of the array holds the length of the string in bytes.
For version 0.2.2 the fsiter construct and direct iterator
implmentation for fstr has been removed. Use the fstr::chars
function instead.
Examples
let a:fstr<8> = fstr::from("abcdefg"); //creates fstr from &str
let a1:fstr<8> = a; // copied, not moved
let a2:&str = a.to_str();
let a3:String = a.to_string();
assert_eq!(a.nth_ascii(2), 'c');
let ab = a.substr(1,5); // copies substring to new fstr
assert_eq!(ab,"bcde"); // can compare with &str
assert!(a<ab); // implements Ord trait (and Hash, Debug, Display)
let mut u:fstr<8> = fstr::from("aλb"); //unicode support
for x in u.nth(1) {assert_eq!(x,'λ');} // nth returns Option<char>
assert!(u.set(1,'μ')); // changes a character of the same character class
assert!(!u.set(1,'c')); // .set returns false on failure
assert!(u.set(2,'c'));
assert_eq!(u, "aμc");
assert_eq!(u.len(),4); // length in bytes
assert_eq!(u.charlen(),3); // length in chars
let mut ac:fstr<16> = a.resize(); // copies to larger capacity string
let remainder:&str = ac.push("hijklmnopqrst"); //appends string, returns left over
assert_eq!(ac.len(),16);
assert_eq!(remainder, "qrst");
ac.truncate(10); // shortens string in place
assert_eq!(&ac,"abcdefghij");zstr and the type aliases str8…str256 implement the same capabilities as fstr.
Re-exports
pub use zero_terminated::*;Modules
Structs
main type: string of size up to const N:
Type Definitions
strings of up to three 8-bit chars, good enough to represent abbreviations such as those for states and airports. Each str<4> is exactly 32 bits.
Each type strN is represented underneath by a [u8;N] with N<=256.
The first byte of the array always holds the length of the string.
Each such type can hold a string of up to N-1 bytes, with max size=255.
These types represent the best compromise between fstr and zstr in
terms of speed and memory efficiency.