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 str8, str16, str32, through str256.

The size of (std::mem::size_of) types str8 and zstr<8> are 8 bytes, compared to 16 bytes for &str, providing more efficient ways of representing very small strings.

Version 0.2.x adds unicode support and a module for zero_terminated strings in the structure zstr. These strings are more memory efficient than fstr but less efficient in terms of run time.

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. This structure represents the best combination 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 internal “tiny string” type tstr is not exported and can only be used through the aliases. These strings implement that same functions and traits as fstr and zstr so the documentation for these structures also apply to the hidden type.

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 str8str256 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

types for small strings that use a more efficient representation underneath. A str8 can hold a string of up to 7 bytes (7 ascii chars). The same functions for fstr and zstr are provided for these types. The size of str8 is 8 bytes.

A str16 can hold a string of up to 15 bytes. See docs for fstr or zstr. The size of str16 is 16 bytes, which is the same as for &str.

A str32 can hold a string of up to 31 bytes. See docs for fstr or zstr

A str64 can hold a string of up to 63 bytes. See docs for fstr or zstr

A str28 can hold a string of up to 127 bytes. See docs for fstr or zstr

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.