Frozen collections

.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "cargo"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    open-pull-requests-limit: 10
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"

.github/workflows/main.yml

@@ -0,0 +1,57 @@
+name: main
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        toolchain:
+          - 1.83.0
+          - beta
+          - nightly
+
+    steps:
+      - uses: actions/checkout@v4
+      - run: rustup update ${{ matrix.toolchain }} && rustup default ${{ matrix.toolchain }}
+      - run: rustup component add clippy
+      - run: rustup component add rustfmt
+      - name: Build
+        run: cargo build --verbose --all-targets
+      - name: Check
+        run: cargo check --verbose --all-targets
+      - name: Clippy
+        run: cargo clippy --verbose --all-targets
+      - name: Format
+        run: cargo fmt -- --check
+      - name: Tests
+        run: cargo test --verbose
+      - name: Doc Tests
+        run: cargo test --doc --verbose
+
+  coverage:
+    runs-on: ubuntu-latest
+    env:
+      CARGO_TERM_COLOR: always
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Rust
+        run: rustup update stable
+      - name: Install cargo-llvm-cov
+        uses: taiki-e/install-action@cargo-llvm-cov
+      - name: Generate code coverage
+        run: cargo llvm-cov --all-features --workspace --lcov --output-path lcov.info
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }} # not required for public repos
+          files: lcov.info
+          fail_ci_if_error: true

.gitignore

@@ -0,0 +1,4 @@
+/target
+/Cargo.lock
+/.idea
+/mutants*

BENCHMARKS.md

@@ -0,0 +1,114 @@
+# Benchmarks
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Benchmark Results](#benchmark-results)
+    - [dense_scalar](#dense_scalar)
+    - [sparse_scalar](#sparse_scalar)
+    - [random_scalar](#random_scalar)
+    - [random_string](#random_string)
+    - [prefixed_string](#prefixed_string)
+    - [hashed](#hashed)
+    - [ordered](#ordered)
+
+## Overview
+
+These benchmarks compare the performance of the frozen collecitons relative
+to the classic Rust collections.
+
+The frozen collections have different optimizations depending on the type of data they
+storeta and how it is declared. The benchmarks probe those different features to show
+the effect of the different optimizations on effective performance.
+
+When you see `HashSet(classic)` vs. `HashSet(ahash)` this reflects the performance difference between the
+normal hasher used by the standard collections as opposed to the performnace that the
+`ahash` hasher provides.
+
+The benchmarks assume a 50% hit rate when probing for lookup, meaning that
+half the queries are for non-existing data. Some algorithms perform differently between
+present vs. non-existing cases, so real world performance of these algorithms depends on the
+real world hit rate you experience.
+
+## Benchmark Results
+
+### dense_scalar
+
+Scalar sets where the values are in a contiguous range.
+
+|            | `HashSet(classic)`          | `HashSet(ahash)`                | `fz_scalar_set(vector)`          | `fz_scalar_set(literals)`           |
+|:-----------|:----------------------------|:--------------------------------|:---------------------------------|:----------------------------------- |
+| **`3`**    | `45.63 ns` (✅ **1.00x**)    | `17.59 ns` (🚀 **2.59x faster**) | `4.74 ns` (🚀 **9.63x faster**)   | `4.31 ns` (🚀 **10.59x faster**)     |
+| **`16`**   | `242.30 ns` (✅ **1.00x**)   | `95.88 ns` (🚀 **2.53x faster**) | `28.13 ns` (🚀 **8.61x faster**)  | `24.36 ns` (🚀 **9.95x faster**)     |
+| **`256`**  | `4.05 us` (✅ **1.00x**)     | `1.51 us` (🚀 **2.69x faster**)  | `470.94 ns` (🚀 **8.61x faster**) | `412.29 ns` (🚀 **9.83x faster**)    |
+| **`1000`** | `15.72 us` (✅ **1.00x**)    | `6.12 us` (🚀 **2.57x faster**)  | `1.82 us` (🚀 **8.65x faster**)   | `1.59 us` (🚀 **9.86x faster**)      |
+
+### sparse_scalar
+
+Scalar sets where the values are in a non-contiguous range.
+
+|            | `HashSet(classic)`          | `HashSet(ahash)`                | `fz_scalar_set(vector)`           | `fz_scalar_set(literals)`           |
+|:-----------|:----------------------------|:--------------------------------|:----------------------------------|:----------------------------------- |
+| **`3`**    | `49.63 ns` (✅ **1.00x**)    | `17.57 ns` (🚀 **2.82x faster**) | `4.60 ns` (🚀 **10.80x faster**)   | `5.89 ns` (🚀 **8.42x faster**)      |
+| **`16`**   | `251.71 ns` (✅ **1.00x**)   | `91.15 ns` (🚀 **2.76x faster**) | `20.71 ns` (🚀 **12.15x faster**)  | `23.82 ns` (🚀 **10.57x faster**)    |
+| **`256`**  | `4.03 us` (✅ **1.00x**)     | `1.57 us` (🚀 **2.57x faster**)  | `330.83 ns` (🚀 **12.18x faster**) | `379.66 ns` (🚀 **10.61x faster**)   |
+| **`1000`** | `15.72 us` (✅ **1.00x**)    | `6.09 us` (🚀 **2.58x faster**)  | `1.27 us` (🚀 **12.39x faster**)   | `1.46 us` (🚀 **10.76x faster**)     |
+
+### random_scalar
+
+Scalar sets where the values are randomly distributed.
+
+|            | `HashSet(classic)`          | `HashSet(ahash)`                | `fz_scalar_set(vector)`          | `fz_scalar_set(literals)`           |
+|:-----------|:----------------------------|:--------------------------------|:---------------------------------|:----------------------------------- |
+| **`3`**    | `48.23 ns` (✅ **1.00x**)    | `17.15 ns` (🚀 **2.81x faster**) | `9.19 ns` (🚀 **5.25x faster**)   | `11.41 ns` (🚀 **4.23x faster**)     |
+| **`16`**   | `251.72 ns` (✅ **1.00x**)   | `96.97 ns` (🚀 **2.60x faster**) | `53.23 ns` (🚀 **4.73x faster**)  | `53.32 ns` (🚀 **4.72x faster**)     |
+| **`256`**  | `4.03 us` (✅ **1.00x**)     | `1.55 us` (🚀 **2.60x faster**)  | `814.80 ns` (🚀 **4.94x faster**) | `814.97 ns` (🚀 **4.94x faster**)    |
+| **`1000`** | `15.68 us` (✅ **1.00x**)    | `6.15 us` (🚀 **2.55x faster**)  | `3.27 us` (🚀 **4.79x faster**)   | `3.22 us` (🚀 **4.86x faster**)      |
+
+### random_string
+
+String sets where the values are random.
+
+|            | `HashSet(classic)`          | `HashSet(ahash)`                 | `fz_string_set(vector)`          | `fz_string_set(literals)`           |
+|:-----------|:----------------------------|:---------------------------------|:---------------------------------|:----------------------------------- |
+| **`3`**    | `82.65 ns` (✅ **1.00x**)    | `42.94 ns` (🚀 **1.92x faster**)  | `39.36 ns` (🚀 **2.10x faster**)  | `26.20 ns` (🚀 **3.15x faster**)     |
+| **`16`**   | `434.62 ns` (✅ **1.00x**)   | `225.46 ns` (🚀 **1.93x faster**) | `221.74 ns` (🚀 **1.96x faster**) | `141.19 ns` (🚀 **3.08x faster**)    |
+| **`256`**  | `6.79 us` (✅ **1.00x**)     | `3.58 us` (🚀 **1.90x faster**)   | `3.49 us` (🚀 **1.95x faster**)   | `2.56 us` (🚀 **2.66x faster**)      |
+| **`1000`** | `27.72 us` (✅ **1.00x**)    | `14.98 us` (🚀 **1.85x faster**)  | `13.96 us` (🚀 **1.99x faster**)  | `10.23 us` (🚀 **2.71x faster**)     |
+
+### prefixed_string
+
+String sets where the values are random, but share a common prefix.
+
+|            | `HashSet(classic)`          | `HashSet(ahash)`                 | `fz_string_set(vector)`          | `fz_string_set(literals)`           |
+|:-----------|:----------------------------|:---------------------------------|:---------------------------------|:----------------------------------- |
+| **`3`**    | `81.22 ns` (✅ **1.00x**)    | `43.76 ns` (🚀 **1.86x faster**)  | `35.47 ns` (🚀 **2.29x faster**)  | `24.98 ns` (🚀 **3.25x faster**)     |
+| **`16`**   | `459.80 ns` (✅ **1.00x**)   | `243.87 ns` (🚀 **1.89x faster**) | `214.12 ns` (🚀 **2.15x faster**) | `135.28 ns` (🚀 **3.40x faster**)    |
+| **`256`**  | `7.55 us` (✅ **1.00x**)     | `4.00 us` (🚀 **1.89x faster**)   | `3.68 us` (🚀 **2.05x faster**)   | `2.84 us` (🚀 **2.66x faster**)      |
+| **`1000`** | `30.38 us` (✅ **1.00x**)    | `16.47 us` (🚀 **1.84x faster**)  | `14.06 us` (🚀 **2.16x faster**)  | `10.64 us` (🚀 **2.85x faster**)     |
+
+### hashed
+
+Sets with a complex key type that is hashable.
+
+|            | `HashSet(classic)`          | `HashSet(ahash)`                 | `fz_hash_set(vector)`            | `fz_hash_set(literals)`           |
+|:-----------|:----------------------------|:---------------------------------|:---------------------------------|:--------------------------------- |
+| **`3`**    | `92.20 ns` (✅ **1.00x**)    | `50.63 ns` (🚀 **1.82x faster**)  | `40.94 ns` (🚀 **2.25x faster**)  | `57.09 ns` (✅ **1.61x faster**)   |
+| **`16`**   | `515.48 ns` (✅ **1.00x**)   | `265.23 ns` (🚀 **1.94x faster**) | `207.83 ns` (🚀 **2.48x faster**) | `231.67 ns` (🚀 **2.23x faster**)  |
+| **`256`**  | `8.34 us` (✅ **1.00x**)     | `4.33 us` (🚀 **1.93x faster**)   | `3.80 us` (🚀 **2.20x faster**)   | `3.75 us` (🚀 **2.22x faster**)    |
+| **`1000`** | `33.77 us` (✅ **1.00x**)    | `17.59 us` (🚀 **1.92x faster**)  | `16.08 us` (🚀 **2.10x faster**)  | `15.52 us` (🚀 **2.18x faster**)   |
+
+### ordered
+
+Sets with a complex key type that is ordered.
+
+|            | `BTreeSet`                | `fz_hash_set(vector)`            | `fz_ordered_set(literals)`           |
+|:-----------|:--------------------------|:---------------------------------|:------------------------------------ |
+| **`3`**    | `70.62 ns` (✅ **1.00x**)  | `62.25 ns` (✅ **1.13x faster**)  | `59.52 ns` (✅ **1.19x faster**)      |
+| **`16`**   | `954.52 ns` (✅ **1.00x**) | `984.68 ns` (✅ **1.03x slower**) | `990.07 ns` (✅ **1.04x slower**)     |
+| **`256`**  | `30.65 us` (✅ **1.00x**)  | `27.37 us` (✅ **1.12x faster**)  | `27.01 us` (✅ **1.13x faster**)      |
+| **`1000`** | `219.26 us` (✅ **1.00x**) | `199.92 us` (✅ **1.10x faster**) | `199.09 us` (✅ **1.10x faster**)     |
+
+---
+Made with [criterion-table](https://github.com/nu11ptr/criterion-table)
+

CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 0.1.0 - 2024-12-07
+
+### Added
+
+- Initial release

Cargo.toml

@@ -0,0 +1,45 @@
+[workspace]
+resolver = "2"
+members = [
+    "frozen-collections",
+    "frozen-collections-core",
+    "frozen-collections-macros",
+    "codegen",
+]
+
+[workspace.package]
+version = "0.1.0"
+edition = "2021"
+categories = ["data-structures", "no-std", "collections"]
+keywords = ["map", "set", "collection"]
+repository = "https://github.com/geeknoid/frozen-collections"
+license = "MIT"
+authors = ["Martin Taillefer <martin@taillefer.org>"]
+readme = "README.md"
+rust-version = "1.83.0"
+
+[workspace.lints.clippy]
+pedantic = { level = "warn", priority = -1 }
+correctness = { level = "warn", priority = -1 }
+complexity = { level = "warn", priority = -1 }
+perf = { level = "warn", priority = -1 }
+cargo = { level = "warn", priority = -1 }
+nursery = { level = "warn", priority = -1 }
+wildcard_imports = "allow"
+too_many_lines = "allow"
+multiple_crate_versions = "allow"
+from-iter-instead-of-collect = "allow"
+into_iter_without_iter = "allow"
+inline_always = "allow"
+unnecessary_wraps = "allow"
+cognitive_complexity = "allow"
+
+[profile.bench]
+codegen-units = 1
+lto = "fat"
+
+[profile.release]         # Modify profile settings via config.
+codegen-units = 1
+lto = "fat"
+debug = true             # Include debug info.
+strip = "none"           # Removes symbols or debuginfo.

LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) 2024 Martin Taillefer
+
+Permission is hereby granted, free of charge, to any
+person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the
+Software without restriction, including without
+limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software
+is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice
+shall be included in all copies or substantial portions
+of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
+SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.