#intern #interner #symbol #utf8 #bytestring

intaglio

UTF-8 string and bytestring interner and symbol table

5 stable releases

1.2.1 Feb 15, 2021
1.2.0 Dec 23, 2020
1.1.1 Aug 8, 2020
1.1.0 Jul 4, 2020
1.0.1 Jun 29, 2020

#8 in Caching

Download history 200/week @ 2020-11-14 395/week @ 2020-11-21 394/week @ 2020-11-28 337/week @ 2020-12-05 326/week @ 2020-12-12 439/week @ 2020-12-19 433/week @ 2020-12-26 878/week @ 2021-01-02 367/week @ 2021-01-09 207/week @ 2021-01-16 148/week @ 2021-01-23 151/week @ 2021-01-30 219/week @ 2021-02-06 465/week @ 2021-02-13 230/week @ 2021-02-20 200/week @ 2021-02-27

1,513 downloads per month

MIT license

79KB
1.5K SLoC

intaglio

GitHub Actions Discord Twitter
Crate API API trunk

UTF-8 string and bytestring interner and symbol table. Used to implement storage for the Ruby Symbol table and the constant name table in Artichoke Ruby.

Symbol objects represent names and some strings inside the Ruby interpreter. They are generated using the :name and :"string" literals syntax, and by the various to_sym methods. The same Symbol object will be created for a given name or string for the duration of a program's execution, regardless of the context or meaning of that name.

Intaglio is a UTF-8 and bytestring interner, which means it stores a single copy of an immutable &str or &[u8] that can be referred to by a stable u32 token.

Interned strings and bytestrings are cheap to compare and copy because they are represented as a u32 integer.

Intaglio is an alternate name for an engraved gem, a gemstone that has been carved with an image. The Intaglio crate is used to implement an immutable Symbol store in Artichoke Ruby.

Usage

Add this to your Cargo.toml:

[dependencies]
intaglio = "1.2"

Then intern UTF-8 strings like:

fn intern_and_get() -> Result<(), Box<dyn std::error::Error>> {
    let mut table = intaglio::SymbolTable::new();
    let name: &'static str = "abc";
    let sym = table.intern(name)?;
    let retrieved = table.get(sym);
    assert_eq!(Some(name), retrieved);
    assert_eq!(sym, table.intern("abc".to_string())?);
    Ok(())
}

Or intern bytestrings like:

fn intern_and_get() -> Result<(), Box<dyn std::error::Error>> {
    let mut table = intaglio::bytes::SymbolTable::new();
    let name: &'static [u8] = b"abc";
    let sym = table.intern(name)?;
    let retrieved = table.get(sym);
    assert_eq!(Some(name), retrieved);
    assert_eq!(sym, table.intern(b"abc".to_vec())?);
    Ok(())
}

Implementation

Intaglio interns owned and borrowed strings with no additional copying by leveraging Cow and a bit of unsafe code. CI runs drop tests under Miri and LeakSanitizer.

Crate features

All features are enabled by default.

  • bytes - Enables an additional symbol table implementation for interning bytestrings (Vec<u8> and &'static [u8]).

License

intaglio is licensed under the MIT License (c) Ryan Lopopolo.

No runtime deps