Crates.io | smol-symbol |
lib.rs | smol-symbol |
version | 0.1.7 |
source | src |
created_at | 2023-07-09 02:59:51.268607 |
updated_at | 2023-07-20 04:01:39.640976 |
description | Provides compile-time globally unique, 25-character, 128-bit symbols similar to the Symbol type in Crystal Lang. |
homepage | https://sam0x17.dev |
repository | https://github.com/sam0x17/smol-symbol |
max_upload_size | |
id | 911803 |
size | 22,960 |
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.
#[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.