4 releases
0.2.0 | Sep 6, 2024 |
---|---|
0.1.7 | Jul 20, 2023 |
0.1.6 | Jul 13, 2023 |
0.1.5 | Jul 9, 2023 |
#81 in Value formatting
127 downloads per month
17KB
165 lines
smol-symbol 💠
This crate provides the ability to create globally unique (per input value), human-readable
Symbol
s at compile-time as well as at run-time, that are meant to be reminiscent of the
Symbol
type in the Crystal programming language.
Where this crate differs is the alphabet and length of our Symbol
is a bit more restrictive,
allowing us to encode the entire text of each Symbol
as a u128
internally. The only caveat
is we are limited to 25 characters of length and an alphabet consisting of lowercase a-z as
well as _
. No other characters are permitted.
The Symbol
type can be created at compile-time using the convenient s!
macro, and can also
be created using the TryFrom<AsRef<str>>
impl at runtime, though this is not as efficient as
doing this at compile-time using the s!
macro.
The Symbol
type can also be turned into a String
via a convenient Into<String>
impl.
We also provide the ability to define custom alphabets that use the more general CustomSymbol
type via a handy custom_alphabet!
macro, allowing you to alter these restrictions directly
(smaller alphabet = larger max length for a symbol) and add support for other languages or less
restrictive character sets. The only invariant that can't be customized at the moment is
CustomSymbol
will always use a u128
as its backing data store.
Example
#[test]
fn symbol_example() {
// Symbols can be stored in variables
let sym1 = s!(hello_world);
// Symbols can be used in const contexts
const SYM2: Symbol = s!(goodnight);
// Symbols can be compared with each other
let sym3 = s!(hello_world);
assert_eq!(sym1, sym3);
assert_ne!(sym1, SYM2);
assert_ne!(s!(this_is_a_triumph), s!(im_making_a_note_here));
// Symbols are 16 bytes
assert_eq!(std::mem::size_of_val(&sym1), 16);
assert_eq!(std::mem::size_of_val(&sym1), std::mem::size_of::<u128>());
// Symbols can even be created dynamically at runtime!
let some_string = String::from("some_random_string");
let dynamic_sym = Symbol::try_from(some_string).unwrap();
assert_eq!(dynamic_sym, s!(some_random_string));
// Can't be longer than 25 characters
assert!(Symbol::try_from("this_is_too_long_to_store_").is_err());
assert!(Symbol::try_from("this_is_just_short_enough").is_ok());
// Character alphabet is limited to lowercase a-z and _
assert!(Symbol::try_from("this-is-invalid").is_err());
assert!(Symbol::try_from("this is_invalid").is_err());
assert!(Symbol::try_from("this.is.invalid").is_err());
}
See the docs for Symbol
and s!
for more detailed information.
Dependencies
~3–11MB
~118K SLoC