Struct Symbol

pub struct Symbol(/* private fields */);

Interned string with very fast comparison and hashing.

Symbols should typically be used as extremely fast program-internal identifiers.

Comparison

Symbol comparison is just comparison between single pointers, which are guaranteed to be identical for identical strings. No O(n) string comparisons occur.

The implementation of Ord between symbols also does not perform string comparison, but rather compares pointer values. However, the PartialOrd<str> implementations do compare strings.

Hashing

The hash value of a symbol is not predictable, as it depends on specific pointer values, which are determined by both linking order and heap layout (for dynamically created symbols). In particular, the hash value of Symbol is not the same as the hash value of the underlying str.

For this reason, Symbol does not implement Borrow<str>, which would imply that it would hash to the same value as its corresponding string value. To prevent accidents, Symbol also does not implement Deref<Target = str> (this restriction may be lifted in future).

The hash value of symbols may change even between invocations of the same binary, so should not be relied upon in any way.

Leaks

Once created, symbols are never freed, and there is no way to “garbage-collect” symbols. This means that dynamically creating symbols from user input or runtime data is a great way to create memory leaks. Use only for static or semi-static identifiers, or otherwise trusted input.

Implementations

impl Symbol

pub fn new(string: impl AsRef<str>) -> Symbol

Create a deduplicated symbol at runtime.

All calls to this function with the same string argument will return a bit-identical Symbol.

This function has some overhead, because it needs to take at least a global read-lock, and potentially a write-lock if the string has not been seen before. Additionally, opposed to new_static(), this function also needs to allocate a copy of the string on the heap and leak it.

When the string is statically known at compile time, prefer the sym!(...) macro. When the string is statically known to live forever, prefer new_static().

Please note that symbols are never “garbage collected”, so creating an unbounded number of symbols in this way can be considered a memory leak. In particular, creating symbols from untrusted user input is a denial-of-service hazard.

pub fn new_static(string: &'static &'static str) -> Symbol

Create a deduplicated symbol at runtime from a static reference to a static string.

If the symbol has not previously been registered, this sidesteps the need to allocate and leak the string. Using this function does not allocate memory, outside of what is needed for registering the symbol for subsequent lookups.

This function has some overhead, because it needs to take at least a global read lock, and potentially a write-lock if the string has not been seen before.

When the string is statically known at compile time, prefer the sym!(...) macro.

The use case for this function is the scenario when a string is only known at runtime, but the caller wants to allocate it. For example, the string could be part of a larger (manually leaked) allocation.

pub fn get(string: impl AsRef<str>) -> Option<Symbol>

Get a previously registered symbol.

This returns None if the string has not previously been registered.

This function has some overhead, because it needs to acquire a global read-lock, but it is faster than Symbol::new() and never leaks memory.

pub unsafe fn new_unchecked(registered_symbol: &'static &'static str) -> Symbol

New pre-interned symbol

Safety

registered_symbol must be a globally unique string reference (i.e., it has already been interned through the global registry).

The only valid external usage of this function is to call it with a value previously returned from Symbol::inner().

pub const fn as_str(&self) -> &'static str

Get the string representation of this symbol.

This operation is guaranteed to not take any locks, and is effectively free.

pub const fn inner(&self) -> &'static &'static str

Get the underlying representation of this symbol.

pub const fn as_ptr(&self) -> NonNull<&'static str>

Get the underlying pointer value of this symbol.

This is the basis for computing equality and hashes. Symbols representing the same string always have the same pointer value.

pub fn to_ffi(&self) -> u64

Convert the symbol to an FFI-friendly u64.

pub unsafe fn from_ffi(value: u64) -> Symbol

Reconstitute a symbol from a value previously produced by to_ffi().

Safety

value must be produced from a previous call to to_ffi() in the current process, and by the exact same version of this crate.

In effect, this function can only be used for roundtrips through foreign code.

pub fn try_from_ffi(value: u64) -> Option<Symbol>

Reconstitute a symbol from a value previously produced by to_ffi(), checking if it is valid.

This involves taking a global read-lock to determine the validity of value.

pub const fn len(&self) -> usize

Length of the underlying string.

pub const fn is_empty(&self) -> bool

Whether or not this is the empty symbol.

Trait Implementations

impl AsRef<Symbol> for StaticSymbol

fn as_ref(&self) -> &Symbol

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<str> for Symbol

fn as_ref(&self) -> &str

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<Symbol> for StaticSymbol

fn borrow(&self) -> &Symbol

Immutably borrows from an owned value.

impl Clone for Symbol

fn clone(&self) -> Symbol

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Symbol

Note: This impl forwards string formatting options to the underlying string.

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Display for Symbol

Note: This impl forwards string formatting options to the underlying string.

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl From<&StaticSymbol> for Symbol

fn from(value: &StaticSymbol) -> Symbol

Converts to this type from the input type.

impl From<&str> for Symbol

fn from(value: &str) -> Symbol

Converts to this type from the input type.

impl<'a> From<Cow<'a, str>> for Symbol

fn from(value: Cow<'a, str>) -> Symbol

Converts to this type from the input type.

impl From<StaticSymbol> for Symbol

fn from(value: StaticSymbol) -> Symbol

Converts to this type from the input type.

impl From<String> for Symbol

fn from(value: String) -> Symbol

Converts to this type from the input type.

impl Hash for Symbol

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Symbol

fn cmp(&self, other: &Symbol) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq<&str> for Symbol

fn eq(&self, other: &&str) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<StaticSymbol> for Symbol

fn eq(&self, other: &StaticSymbol) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Symbol> for &str

fn eq(&self, other: &Symbol) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Symbol> for StaticSymbol

fn eq(&self, other: &Symbol) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<Symbol> for str

fn eq(&self, other: &Symbol) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq<str> for Symbol

fn eq(&self, other: &str) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq for Symbol

fn eq(&self, other: &Symbol) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd<&str> for Symbol

fn partial_cmp(&self, other: &&str) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<Symbol> for &str

fn partial_cmp(&self, other: &Symbol) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<Symbol> for str

fn partial_cmp(&self, other: &Symbol) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd<str> for Symbol

fn partial_cmp(&self, other: &str) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialOrd for Symbol

fn partial_cmp(&self, other: &Symbol) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Copy for Symbol

impl Eq for Symbol