Crate smol_symbol

Expand description

smol-symbol 💠

This crate provides the ability to create globally unique (per input value), human-readable Symbols 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 _.

The Symbol type can be created at compile-time using the convenient s! macro, and can also be created using the From<Into<String>> impl at runtime, though this is not as efficient as using the s! macro.

The Symbol type can also be turned into a String via a convenient Into<String>.

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_type_example() {
    // Symbols can be stored in variables and compared
    let sym1 = s!(hello_world);
    assert_eq!(s!(hello_world), sym1);
    assert_ne!(s!(goodbye), s!(hello));

    // Symbols can be used in const contexts
    const MY_SYM: Symbol = s!(this_is_a_triumph);
    assert_eq!(MY_SYM, s!(this_is_a_triumph));

    // Symbols can be converted directly to Strings
    assert_eq!(sym1.to_string().as_str(), "hello_world");
}

See the docs for Symbol and s! for more detailed information.

Macros

custom_alphabet
Allows you to define a custom alphabet for use with CustomSymbol and the s! macro. The macro takes two idents separated by a comma as input. The first ident should be the name of the alphabet you would like to create, and the second ident should contain all of the characters you would like to use in your alphabet (symbols must be comprised only of characters that are valid in an ident.
s
Generates a Symbol or CustomSymbol at const-eval time based on the provided ident and (optional) path to a custom Alphabet., e.g.:

Structs

CustomSymbol
The base type used for Symbol and any custom Alphabet’s that have been created using custom_alphabet!.
DefaultAlphabet
SymbolParsingError
Thrown when an attempt was made to parse an invalid CustomSymbol / Symbol. This can occur when the underlying ident or string is too long, too short, or contains invalid character (characters not in the specified Alphabet).

Constants

PARSING_ERROR_MSG

Traits

Alphabet
Represents a custom alphabet for use with CustomSymbol. To create one of these you should use the custom_alphabet! macro, as there are several functions you need to define in addition to implementing the trait.

Type Definitions

Symbol
A compact representation for a (maximum of) 25-character identifier consisting of only lowercase a-z as well as _. Internally this data is converted to a u128, allowing for trivial comparison operations between symbols.