Crate simble

Simple, tiny symbols. Human-readable strings up to 8 bytes long that can be stored inline and manipulated efficiently.

use simble::*;

let foo: Symbol = "foo".parse()?;
let foos: Symbol = "foosball".parse()?;
// symbol/symbol comparisons are efficient (1 instruction on any 64-bit platform; no pointer-following)
assert!(foo != foos);
// comparison is lexical: shorter comes first
assert!(foo < foos);
// Symbols can be formatted or turned into Strings
assert_eq!(format!("{}", foo), "foo");
assert_eq!(foo.to_string(), "foo");

let foo2 = foo.to_printable();
assert_eq!(&foo2, "foo");
let bar: Printable = "bar".parse()?;
// one of these is true, but which is unspecified
assert!(foo2 < bar || foo2 > bar);

let toobig: Result<Symbol, _> = "ninechars".parse();
assert!(toobig.is_err());

// compile-time parsing on nightly:
#[cfg(feature = "nightly")]
const consts: Printable = printable("consts");
assert_eq!(&consts, "consts");
const hackery: Symbol = symbol("hackery");
assert_eq!(&hackery.to_printable(), "hackery");

Value restrictions

• NUL characters ("\0".parse()) are not allowed*
• The empty symbol ("".parse()) is not allowed*

*These restrictions are to be considered unstable and may be lifted with only a patch version increase.

Storage size

Both Lexical and Printable have the same memory layout as a u64.

Further, with features="nightly" Lexical is implemented as a non-zero type so that Option<Lexical> can also be 8 bytes.

Whether Printable is a non-zero type is unspecified.

Structs

Bytes	Iterator over the bytes of a symbol.
Error	Error constructing a symbol.
Lexical	Symbol that compares lexicographically and consistently with the C locale. Interconvertible with Printable that can be borrowed as &str or &[u8].
Printable	Symbol that can be borrowed directly as a &str or &[u8]. Comparison is supported, but order is unspecified and must not be relied on (for predictable sorting, use Lexical).

Type Definitions

Symbol

Alias for Lexical, which is the default Symbol type because it sorts without surprises. If consistent sort order is not important, you can just use Printable exclusively: use simble::Printable as Symbol.