Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve table to describe backend properties #84

Merged
merged 4 commits into from
Feb 11, 2025
+23 −20
Merged

Improve table to describe backend properties #84

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
fbb33ca
improve table to describe backend properties
Robbepop Feb 11, 2025
697c0ee
apply rustfmt
Robbepop Feb 11, 2025
27976f1
improve legend table
Robbepop Feb 11, 2025
23796f8
simplify legend further
Robbepop Feb 11, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 23 additions & 20 deletions src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,26 +81,29 @@
//!
//! The `string_interner` crate provides different backends with different strengths.
//! The table below compactly shows when to use which backend according to the following
//! performance characteristics.
//!
//! - **Fill:** Efficiency of filling an empty string interner.
//! - **Resolve:** Efficiency of resolving a symbol of an interned string.
//! - **Allocations:** The number of allocations performed by the backend.
//! - **Footprint:** The total heap memory consumed by the backend.
//! - **Iteration:** Efficiency of iterating over the interned strings.
//! - **Contiguous:** True if the returned symbols have contiguous values.
//! - **Stable Refs:** If the string references are stable after the first insertion.
//!
//! | **Property** | **BucketBackend** | **StringBackend** | **BufferBackend** |
//! |:-------------|:-----------------:|:-----------------:|:-----------------:|
//! | **Fill** | ok | good | best |
//! | **Resolve** | best | good | bad |
//! | Allocations | ok | good | best |
//! | Footprint | ok | good | best |
//! | Iteration | best | good | bad |
//! | | | | |
//! | Contiguous | yes | yes | no |
//! | Stable Refs | yes | no | no |
//! performance characteristics and properties.
//!
//! | **Property** | **BucketBackend** | **StringBackend** | **BufferBackend** | | Explanation |
//! |:-------------|:-----------------:|:-----------------:|:-----------------:|:--|:--|
//! | Fill | 🤷 | 👍 | ⭐ | | Efficiency of filling an empty string interner. |
//! | Fill Duplicates | 1) | 1) | 1) | | Efficiency of filling a string interner with strings that are already interned. |
//! | Resolve | ⭐ | 👍 | 👎 | | Efficiency of resolving a symbol of an interned string. |
//! | Allocations | 🤷 | 👍 | ⭐ | | The number of allocations performed by the backend. |
//! | Footprint | 🤷 | 👍 | ⭐ | | The total heap memory consumed by the backend. |
//! | Iteration | ⭐ | 👍 | 👎 | | Efficiency of iterating over the interned strings. |
//! | | | | | | |
//! | Contiguous | ✅ | ✅ | ❌ | | The returned symbols have contiguous values. |
//! | Stable Refs | ✅ | ❌ | ❌ | | The interned strings have stable references. |
//! | Static Strings | ✅ | ❌ | ❌ | | Allows to intern `&'static str` without heap allocations. |
//!
//! 1. Performance of interning pre-interned string is the same for all backends since
//! this is implemented in the `StringInterner` front-end via a `HashMap` query for
//! all `StringInterner` instances.
//!
//! ### Legend
//!
//! | ⭐ | **best performance** | 👍 | **good performance** | 🤷 | **okay performance** | 👎 | **bad performance** |
//! |-|-|-|-|-|-|-|-|
//!
//! ## When to use which backend?
//!
Expand Down