Struct string_cache::Atom

pub struct Atom<Static> { /* fields omitted */ }

Represents a string that has been interned.

While the type definition for Atom indicates that it generic on a particular implementation of an atom set, you don't need to worry about this. Atoms can be static and come from a StaticAtomSet generated by the string_cache_codegen crate, or they can be dynamic and created by you on an EmptyStaticAtomSet.

Atom implements Clone but not Copy, since internally atoms are reference-counted; this means that you may need to .clone() an atom to keep copies to it in different places, or when passing it to a function that takes an Atom rather than an &Atom.

Creating an atom at runtime

If you use string_cache_codegen to generate a precomputed list of atoms, your code may then do something like read data from somewhere and extract tokens that need to be compared to the atoms. In this case, you can use Atom::from(&str) or Atom::from(String). These create a reference-counted atom which will be automatically freed when all references to it are dropped.

This means that your application can safely have a loop which tokenizes data, creates atoms from the tokens, and compares the atoms to a predefined set of keywords, without running the risk of arbitrary memory consumption from creating large numbers of atoms — as long as your application does not store clones of the atoms it creates along the way.

For example, the following is safe and will not consume arbitrary amounts of memory:

let untrusted_data = "large amounts of text ...";

for token in untrusted_data.split_whitespace() {
    let atom = Atom::from(token); // interns the string

    if atom == Atom::from("keyword") {
        // handle that keyword
    } else if atom == Atom::from("another_keyword") {
        // handle that keyword
    } else {
        println!("unknown keyword");
    }
} // atom is dropped here, so it is not kept around in memory

Methods

impl<Static: StaticAtomSet> Atom<Static>

pub fn get_hash(&self) -> u32

Get the hash of the string as it is stored in the set.

impl<Static: StaticAtomSet> Atom<Static>

pub fn to_ascii_uppercase(&self) -> Self

Like to_ascii_uppercase.

pub fn to_ascii_lowercase(&self) -> Self

Like to_ascii_lowercase.

pub fn eq_ignore_ascii_case(&self, other: &Self) -> bool

Like eq_ignore_ascii_case.

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

Like eq_ignore_ascii_case, but takes an unhashed string as other.

Trait Implementations

impl<Static> Drop for Atom<Static>

fn drop(&mut self)

Executes the destructor for this type.

impl<Static: StaticAtomSet> AsRef<str> for Atom<Static>

fn as_ref(&self) -> &str

Performs the conversion.

impl<'a, Static: StaticAtomSet> From<Cow<'a, str>> for Atom<Static>

fn from(string_to_add: Cow<'a, str>) -> Self

Performs the conversion.

impl<'a, Static: StaticAtomSet> From<&'a Atom<Static>> for Atom<Static>

fn from(atom: &'a Self) -> Self

Performs the conversion.

impl<'a, Static: StaticAtomSet> From<&'a str> for Atom<Static>

fn from(string_to_add: &str) -> Self

Performs the conversion.

impl<Static: StaticAtomSet> From<String> for Atom<Static>

fn from(string_to_add: String) -> Self

Performs the conversion.

impl<Static: StaticAtomSet> Clone for Atom<Static>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<Static: StaticAtomSet> Default for Atom<Static>

fn default() -> Self

Returns the "default value" for a type.

impl<Static: Eq> Eq for Atom<Static>

impl<Static: StaticAtomSet> Ord for Atom<Static>

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

This method returns an Ordering between self and other.

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

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

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl<Static: PartialEq> PartialEq<Atom<Static>> for Atom<Static>

fn eq(&self, other: &Atom<Static>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Atom<Static>) -> bool

This method tests for !=.

impl<Static: StaticAtomSet> PartialEq<str> for Atom<Static>

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

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<Static: StaticAtomSet> PartialEq<Atom<Static>> for str

fn eq(&self, other: &Atom<Static>) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<Static: StaticAtomSet> PartialEq<String> for Atom<Static>

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

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<Static: StaticAtomSet> PartialOrd<Atom<Static>> for Atom<Static>

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

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

#[must_use] fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use] fn le(&self, other: &Rhs) -> bool

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

#[must_use] fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use] fn ge(&self, other: &Rhs) -> bool

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

impl<Static: StaticAtomSet> Display for Atom<Static>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<Static: StaticAtomSet> Debug for Atom<Static>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<Static: StaticAtomSet> Deref for Atom<Static>

type Target = str

The resulting type after dereferencing.

fn deref(&self) -> &str

Dereferences the value.

impl<Static: StaticAtomSet> Hash for Atom<Static>

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, 

Feeds a slice of this type into the given [Hasher].

impl<Static: StaticAtomSet> Serialize for Atom<Static>

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error> where
    S: Serializer, 

Serialize this value into the given Serde serializer.

impl<'a, Static: StaticAtomSet> Deserialize<'a> for Atom<Static>

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error> where
    D: Deserializer<'a>, 

Deserialize this value from the given Serde deserializer.

impl<Static: StaticAtomSet> PrecomputedHash for Atom<Static>

fn precomputed_hash(&self) -> u32

Return the precomputed hash for this item.