{"id":17950340,"url":"https://github.com/geeknoid/frozen-collections","last_synced_at":"2025-08-21T03:17:25.746Z","repository":{"id":230449319,"uuid":"779406046","full_name":"geeknoid/frozen-collections","owner":"geeknoid","description":"Fast partially immutable collections for Rust","archived":false,"fork":false,"pushed_at":"2025-07-09T12:26:47.000Z","size":398,"stargazers_count":34,"open_issues_count":5,"forks_count":6,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-28T09:44:48.542Z","etag":null,"topics":["collections","map","no-std","rust","set"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/frozen-collections","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/geeknoid.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-03-29T19:06:31.000Z","updated_at":"2025-07-23T15:36:30.000Z","dependencies_parsed_at":"2024-04-16T06:23:58.620Z","dependency_job_id":"1b2e17a8-68fd-4f0c-b685-0a0a605b8550","html_url":"https://github.com/geeknoid/frozen-collections","commit_stats":null,"previous_names":["geeknoid/frozen_map"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/geeknoid/frozen-collections","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geeknoid%2Ffrozen-collections","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geeknoid%2Ffrozen-collections/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geeknoid%2Ffrozen-collections/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geeknoid%2Ffrozen-collections/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/geeknoid","download_url":"https://codeload.github.com/geeknoid/frozen-collections/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geeknoid%2Ffrozen-collections/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271420156,"owners_count":24756491,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-21T02:00:08.990Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["collections","map","no-std","rust","set"],"created_at":"2024-10-29T09:38:43.051Z","updated_at":"2025-08-21T03:17:25.728Z","avatar_url":"https://github.com/geeknoid.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Frozen Collections - Fast _Partially_ Immutable Collections\n\n[![crate.io](https://img.shields.io/crates/v/frozen-collections.svg)](https://crates.io/crates/frozen-collections)\n[![docs.rs](https://docs.rs/frozen-collections/badge.svg)](https://docs.rs/frozen-collections)\n[![CI](https://github.com/geeknoid/frozen-collections/workflows/main/badge.svg)](https://github.com/geeknoid/frozen-collections/actions)\n[![Coverage](https://codecov.io/gh/geeknoid/frozen-collections/graph/badge.svg?token=FCUG0EL5TI)](https://codecov.io/gh/geeknoid/frozen-collections)\n[![Minimum Supported Rust Version 1.87](https://img.shields.io/badge/MSRV-1.87-blue.svg)]()\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n\n* [Summary](#summary)\n* [Handling Compile-Time Data](#handling-compile-time-data)\n  * [Short Form](#short-form)\n  * [Long Form](#long-form)\n* [Using in a Build Script](#using-in-a-build-script)\n* [Handling Runtime Data](#handling-runtime-data)\n* [Traits](#traits)\n* [Performance Considerations](#performance-considerations)\n* [Analysis and Optimizations](#analysis-and-optimizations)\n* [Cargo Features](#cargo-features)\n\n## Summary\n\nFrozen collections are designed to deliver improved\nread performance relative to the standard [`HashMap`](https://doc.rust-lang.org/std/collections/hash/map/struct.HashMap.html) and\n[`HashSet`](https://doc.rust-lang.org/std/collections/hash/set/struct.HashSet.html) types. They are ideal for use with long-lasting collections\nwhich get initialized when an application starts and remain unchanged\npermanently, or at least extended periods of time. This is a common\npattern in service applications.\n\nAs part of creating a frozen collection, analysis is performed over the data that the collection\nwill hold to determine the best layout and algorithm to use to deliver optimal performance.\nDepending on the situation, sometimes the analysis is done at compile-time, whereas in\nother cases it is done at runtime when the collection is initialized.\nThis analysis can take some time, but the value in spending this time up front\nis that the collections provide faster read-time performance.\n\nFrozen maps are only partially immutable. The keys associated with a frozen map are determined\nat creation time and cannot change, but the values can be updated at will if you have a\nmutable reference to the map. Frozen sets, however, are completely immutable and so never\nchange after creation.\n\nSee [BENCHMARKS.md](./BENCHMARKS.md) for current benchmark numbers.\n\n## Handling Compile-Time Data\n\nIf you know the keys and values that will be in your collection at compile time, you can use\none of eight macros to create frozen collections:\n[`fz_hash_map!`](https://docs.rs/frozen-collections/latest/frozen_collections/macro.fz_hash_map.html),\n[`fz_ordered_map!`](https://docs.rs/frozen-collections/latest/frozen_collections/macro.fz_ordered_map.html),\n[`fz_scalar_map!`](https://docs.rs/frozen-collections/latest/frozen_collections/macro.fz_scalar_map.html),\n[`fz_string_map!`](https://docs.rs/frozen-collections/latest/frozen_collections/macro.fz_string_map.html),\n[`fz_hash_set!`](https://docs.rs/frozen-collections/latest/frozen_collections/macro.fz_hash_set.html),\n[`fz_ordered_set!`](https://docs.rs/frozen-collections/latest/frozen_collections/macro.fz_ordered_set.html),\n[`fz_scalar_set!`](https://docs.rs/frozen-collections/latest/frozen_collections/macro.fz_scalar_set.html), or\n[`fz_string_set!`](https://docs.rs/frozen-collections/latest/frozen_collections/macro.fz_string_set.html).\nThese macros analyze the data you provide\nand return a custom implementation type optimized for the data. All the\npossible types implement the\n[`Map`](https://docs.rs/frozen-collections/latest/frozen_collections/trait.Map.html) or\n[`Set`](https://docs.rs/frozen-collections/latest/frozen_collections/trait.Set.html) traits.\n\nThe macros exist in a short form and a long form, described below.\n\n### Short Form\n\nWith the short form, you supply the data that\ngoes into the collection and get in return an initialized collection of an unnamed\ntype. For example:\n\n```rust\nuse frozen_collections::*;\n\nlet m = fz_string_map!({\n    \"Alice\": 1,\n    \"Bob\": 2,\n    \"Sandy\": 3,\n    \"Tom\": 4,\n});\n```\n\nAt build time, the macro analyzes the data supplied and determines the best map\nimplementation type to use. As such, the type of `m` is not known to this code. `m` will\nalways implement the [`Map`](https://docs.rs/frozen-collections/latest/frozen_collections/trait.Map.html) trait however, so you can leverage type inference even though\nyou don't know the actual type of `m`:\n\n```rust\nuse frozen_collections::*;\n\nfn main() {\n    let m = fz_string_map!({\n        \"Alice\": 1,\n        \"Bob\": 2,\n        \"Sandy\": 3,\n        \"Tom\": 4,\n    });\n\n    more(m);\n}\n\nfn more\u003cM\u003e(m: M)\nwhere\n    M: Map\u003c\u0026'static str, i32\u003e\n{\n    assert!(m.contains_key(\u0026\"Alice\"));\n}\n```\n\n### Long Form\n\nThe long form lets you provide a type alias name which will be created to\ncorrespond to the collection implementation type chosen by the macro invocation.\nNote that you must use the long form if you want to declare a static frozen collection.\n\n```rust\nuse frozen_collections::*;\n\nfz_string_map!(static MAP: MyMapType\u003c\u0026'static str, i32\u003e, {\n    \"Alice\": 1,\n    \"Bob\": 2,\n    \"Sandy\": 3,\n    \"Tom\": 4,\n});\n```\n\nThe above creates a static variable called `MAP` with keys that are strings and values which are\nintegers. As before, you don't know the specific implementation type selected by the macro, but\nthis time you have a type alias (i.e. `MyMapType`) representing that type. You can then use this alias\nanywhere you'd like to in your code where you'd like to mention the type explicitly.\n\nTo use the long form for non-static uses, replace `static` with `let`:\n\n```rust\nuse frozen_collections::*;\n\nfz_string_map!(let m: MyMapType\u003c\u0026'static str, i32\u003e, {\n    \"Alice\": 1,\n    \"Bob\": 2,\n    \"Sandy\": 3,\n    \"Tom\": 4,\n});\n\nmore(m);\n\nstruct S {\n    m: MyMapType,\n}\n \nfn more(m: MyMapType) {\n    assert!(m.contains_key(\"Alice\"));\n}\n```\n\n## Using in a Build Script\n\nYou can use the\n[`CollectionEmitter`](https://docs.rs/frozen-collections/latest/frozen_collections/emit/struct.CollectionEmitter.html),\nstruct to initialize a frozen collection from a build\nscript and output the results in a file that then gets compiled into your application. Due\nto the fact build scripts run in a richer environment than procedural macros, the resulting\nefficiency of collections generated from build scripts can be slightly faster than the ones\ngenerated with the macros.\n\n## Handling Runtime Data\n\nIf you don't know the exact keys and values that will be in your collection at compile time,\nyou use the dedicated map and collection types to hold your data:\n[`FzHashMap`](https://docs.rs/frozen-collections/latest/frozen_collections/struct.FzHashMap.html),\n[`FzOrderedMap`](https://docs.rs/frozen-collections/latest/frozen_collections/struct.FzOrderedMap.html),\n[`FzScalarMap`](https://docs.rs/frozen-collections/latest/frozen_collections/struct.FzScalarMap.html),\n[`FzStringMap`](https://docs.rs/frozen-collections/latest/frozen_collections/struct.FzStringMap.html),\n[`FzHashSet`](https://docs.rs/frozen-collections/latest/frozen_collections/struct.FzHashSet.html),\n[`FzOrderedSet`](https://docs.rs/frozen-collections/latest/frozen_collections/struct.FzOrderedSet.html),\n[`FzScalarSet`](https://docs.rs/frozen-collections/latest/frozen_collections/struct.FzScalarSet.html), or\n[`FzStringSet`](https://docs.rs/frozen-collections/latest/frozen_collections/struct.FzStringSet.html).\nThese\ntypes analyze the data you provide at runtime and determine the best strategy to handle your\ndata dynamically.\n\n```rust\nuse frozen_collections::*;\n\nlet v = vec![\n    (\"Alice\", 1),\n    (\"Bob\", 2),\n    (\"Sandy\", 3),\n    (\"Tom\", 4),\n];\n\nlet m = FzStringMap::new(v);\n```\n\nNote that in general, if possible, it's more efficient to use the macros to create your frozen\ncollection instances.\n\n## Traits\n\nThe maps produced by this crate implement the following traits:\n\n- [`Map`](https://docs.rs/frozen-collections/latest/frozen_collections/trait.Map.html). The primary representation of a map.\n- [`MapQuery`](https://docs.rs/frozen-collections/latest/frozen_collections/trait.MapQuery.html). A dyn compatible trait for querying maps.\n- [`MapIteration`](https://docs.rs/frozen-collections/latest/frozen_collections/trait.MapIteration.html). A dyn compatible trait for iterating over maps.\n- [`MapExtras`](https://docs.rs/frozen-collections/latest/frozen_collections/trait.MapExtras.html). A trait for extra map operations.\n\nThe sets produced by this crate implement the following traits:\n\n- [`Set`](https://docs.rs/frozen-collections/latest/frozen_collections/trait.Set.html). The primary representation of a set.\n- [`SetQuery`](https://docs.rs/frozen-collections/latest/frozen_collections/trait.SetQuery.html). A dyn compatible trait for querying sets.\n- [`SetIteration`](https://docs.rs/frozen-collections/latest/frozen_collections/trait.SetIteration.html). A dyn compatible trait for iterating over sets.\n- [`SetOps`](https://docs.rs/frozen-collections/latest/frozen_collections/trait.SetOps.html). A trait for set operations like union and intersections.\n- [`SetExtras`](https://docs.rs/frozen-collections/latest/frozen_collections/trait.SetExtras.html). A trait for extra set operations.\n\n## Performance Considerations\n\nThe analysis performed when creating maps tries to find the best concrete implementation type\ngiven the data at hand. The macros perform analysis at build time and generally produce slightly\nfaster results. The collection types meanwhile perform analysis at runtime, and the resulting\ncollections are slightly slower.\n\nWhen creating static collections using the macros, the collections produced can often be embedded directly as constant data\ninto the binary of the application, thus requiring no initialization time and no heap space.\nThis also happens to be the fastest form for these collections. When possible, this happens\nautomatically. You don't need to do anything special to enable this behavior.\n\n## Analysis and Optimizations\n\nUnlike normal collections, the frozen collections require you to provide all the data for\nthe collection when you create the collection. The data you supply is analyzed which determines\nwhich specific underlying implementation strategy to use and how to lay out data internally.\n\nThe available implementation strategies are:\n\n- **Scalar as Hash**. When the keys are of an integer or enum type, this uses the keys themselves\n  as hash codes, avoiding the overhead of hashing.\n\n- **Length as Hash**. When the keys are of a string type, the lengths of the keys\n  are used as hash code, avoiding the overhead of hashing.\n\n- **Dense Scalar Lookup**. When the keys represent a contiguous range of integer or enum values,\n  lookups use a simple array instead of hashing.\n\n- **Sparse Scalar Lookup**. When the keys represent a sparse range of integer or enum values,\n  lookups use a sparse array instead of hashing.\n\n- **Left-Hand Substring Hashing**. When the keys are of a string type, this uses sub-slices of\n  the keys for hashing, reducing the overhead of hashing.\n\n- **Right-Hand Substring Hashing**. Similar to the Left-Hand Substring Hashing from above, but\n  using right-aligned sub-slices instead.\n\n- **Linear Scan**. For very small collections, this avoids hashing completely by scanning through\n  the entries in linear order.\n\n- **Ordered Scan**. For very small collections where the keys implement the [`Ord`](https://doc.rust-lang.org/std/cmp/trait.Ord.html) trait,\n  this avoids hashing completely by scanning through the entries in linear order. Unlike the\n  Linear Scan strategy, this one can early exit when keys are not found during the scan.\n\n- **Classic Hashing**. This is the fallback when none of the previous strategies apply. The\n  frozen implementations are generally faster than\n  [`HashMap`](https://doc.rust-lang.org/std/collections/hash/map/struct.HashMap.html) and\n  [`HashSet`](https://doc.rust-lang.org/std/collections/hash/set/struct.HashSet.html).\n\n- **Binary Search**. For relatively small collections where the keys implement the [`Ord`](https://doc.rust-lang.org/std/cmp/trait.Ord.html) trait,\n  classic binary searching is used.\n\n- **Eytzinger Search**. For larger collections where the keys implement the [`Ord`](https://doc.rust-lang.org/std/cmp/trait.Ord.html) trait,\na cache-friendly Eytzinger search is used.\n\n## Cargo Features\n\nYou can specify the following features when you include the `frozen_collections` crate in your\n`Cargo.toml` file:\n\n- **`macros`**. Enables the macros for creating frozen collections.\n- **`emit`**. Enables the [`CollectionEmitter`](https://docs.rs/frozen-collections/latest/frozen_collections/emit/struct.CollectionEmitter.html) struct that lets you create frozen collections from a build script.\n- **`serde`**. Enables serialization and deserialization support for the frozen collections.\n- **`std`**. Enables small features only available when building with the standard library.\n\nAll features are enabled by default.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeeknoid%2Ffrozen-collections","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgeeknoid%2Ffrozen-collections","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeeknoid%2Ffrozen-collections/lists"}