From 8eb940e81ea41d61cb10c33aa553cb8c04b51b8b Mon Sep 17 00:00:00 2001 From: Caspar Krieger Date: Fri, 4 Apr 2025 11:42:24 +0800 Subject: [PATCH] Add docs on customizing string hashing Closes #89. --- src/lib.rs | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/src/lib.rs b/src/lib.rs index 48a398c..9570d28 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -123,6 +123,31 @@ //! Some operations are even slightly more efficient and it consumes less memory. //! However, all this is at the costs of a less efficient resolution of symbols. //! Note that the symbols generated by the `BufferBackend` are not contiguous. +//! +//! ## Customizing String Hashing +//! +//! To ensure only one copy of each string is interned, [`StringInterner`] relies on [hashbrown]'s +//! [hashmap](hashbrown::HashMap), which necessitates choosing a hashing function for hashing the +//! strings. +//! +//! By default, [`StringInterner`] will use hashbrown's [`DefaultHashBuilder`], which should be +//! appropriate for most users. However, you may customize the hash function via +//! [`StringInterner`]'s second type parameter: +//! +//! ``` +//! use std::hash::RandomState; +//! use string_interner::{StringInterner, DefaultBackend}; +//! +//! // create a StringInterner with the default backend but using std's RandomState hasher +//! let interned_strs: StringInterner = StringInterner::new(); +//! ``` +//! +//! NB: as of hashbrown v0.15.2, the [`DefaultHashBuilder`] is [foldhash's +//! RandomState](https://docs.rs/foldhash/latest/foldhash/fast/struct.RandomState.html), which +//! relies on a one-time random initialization of shared global state; if you need stable hashes +//! then you may wish to use [foldhash's +//! FixedState](https://docs.rs/foldhash/latest/foldhash/fast/struct.FixedState.html) (or similar) +//! instead. extern crate alloc; #[cfg(feature = "std")]