Merge pull request #1 from b-vitamins/paged-index

Paged index

Cargo.toml

@@ -20,9 +20,6 @@ serde = { version = "1.0.197", features = ["derive"] }
 criterion = "0.4.0"
 hashbrown = "0.14.3"
 
-[features]
-default = []
-
 [[bench]]
 name = "set"
 path = "bench/set.rs"
@@ -31,9 +28,7 @@ harness = false
 [[bin]]
 name = "memory_set"
 path = "bin/memory_usage_set.rs"
-harness = false
 
 [[bin]]
 name = "memory_hashset"
 path = "bin/memory_usage_hashset.rs"
-harness = false

src/lib.rs

@@ -3,49 +3,51 @@
 //! ![Crates.io](https://img.shields.io/crates/v/fastset)
 //! ![docs.rs](https://img.shields.io/docsrs/fastset)
 //! ![License](https://img.shields.io/crates/l/fastset)
-//! ![GitHub Workflow Status](https://github.com/b-vitamins/fastset/actions/workflows/rust.yml/badge.svg)
+//! ![GitHub Workflow Status](https://img.shields.io/github/workflow/status/b-vitamins/fastset/Rust)
 //!
-//! Fast set implementation for dense, bounded integer collections. Provides quick updates and random access.
+//! Fast set implementation for dense, bounded integer collections, offering quick updates and random access.
 //!
-//! The `fastset` crate provides a custom `Set` implementation, optimized for managing collections of `usize` //! values. Use cases involve having to manage indices of other data structures of a special kind, whose //! elements are densely packed within a known range and the insert and delete operations are voluminous, i.e., //! operation predictability and performance take precedence over memory footprint.
+//! ## Features
 //!
-//! Example use cases:
-//!     - For storing lattice sites of interest in stochastic cellular automata simulations
-//!     - Managing available or used indices in large arrays.
-//!     - Tracking slots in memory pools.
-//!     
-//! fastset::Set is not a good solution for memory contrained applications or for applications with storage need //! for sparse elements spread over a extended range.
+//! - Tailored for `usize` elements, ideal for index-based applications.
+//! - Fast insertions, deletions, and random access through direct memory operations.
+//! - Paging mechanism to enhance memory usage efficiency.
+//! - `random` method for selecting random elements, crucial for simulations.
 //!
-//! ## Features
+//! ## Use Cases:
+//! - Tracking interest points within stochastic cellular automata simulations.
+//! - Managing available or used indices in arrays.
+//! - Tracking slots in memory pools.
+
+//! 0.4.0 introduces a paging mechanism that reduces the memory-footprint of fastset::Set. 
+//! With the paging feature, `fastset::Set` achieves ~ 100% reduction in peak heap memory allocations 
+//! with no additional performance overhead. The integers used were twice as sparse as the page size.
 //!
-//! - Tailored specifically for handling `usize` values, ideal for indexing scenarios.
-//! - Uses direct memory access for fast insertions, deletions, and random access.
-//! - Includes a `random` method to retrieve a random element from the set, essential for simulations and randomized algorithms.
+//! Note that fastset::Set is still not a good solution for memory contrained applications
+//! or for applications with storage need for sparse elements spread over an extended range.
 //!
 //! ## Benchmarks
 //!
-//! Benchmarks comparing `fastset::Set` with `hashbrown::HashSet` and `std::collections::HashSet`:
-//! 
-//! | Operation | `Set (fastset)`      | `HashSet (hashbrown)` | `HashSet (std)`    |
-//! |-----------|----------------------|-----------------------|--------------------|
-//! | insert    | 1.1345-1.1362 ns     | 4.6160-4.6201 ns      | 14.055-14.190 ns   |
-//! | remove    | 1.2500-1.2527 ns     | 2.9729-2.9758 ns      | 10.454-10.462 ns   |
-//! | contains  | 937.21-939.16 ps     | 1.0470-1.0492 ns      | 13.678-13.687 ns   |
-//! | random    | 610.19-615.55 ps     | N/A                   | N/A                |
-//!
-//! Benchmarks were conducted on a machine with the following specifications:
-//! - Processor: AMD Ryzen™ 5 5600G with Radeon™ Graphics x 12
-//! - Memory: 58.8 GiB
-//! - Operating System: Guix System
-//! - OS Type: 64-bit
+//! Performance comparisons between `fastset::Set`, `hashbrown::HashSet`, and `std::collections::HashSet`:
+//!
+//! | Operation | `fastset::Set` | `hashbrown::HashSet` | `std::collections::HashSet` |
+//! |-----------|----------------|----------------------|-----------------------------|
+//! | insert    | 1.1632 ns      | 4.7105 ns            | 14.136 ns                   |
+//! | remove    | 1.1647 ns      | 3.0459 ns            | 10.625 ns                   |
+//! | contains  | 932.81 ps      | 985.38 ps            | 13.827 ns                   |
+//! | random    | 651.26 ps      | N/A                  | N/A                         |
+//!
+//! Benchmarks were performed on the following system:
+//! - CPU: AMD Ryzen™ 5 5600G with Radeon™ Graphics x 12
+//! - RAM: 58.8 GiB
+//! - OS: Guix System, 64-bit
 //!
 //! ## Usage
 //!
 //! ```rust
 //! use fastset::{set, Set};
 //! use nanorand::WyRand;
 //!
-//! fn main() {
 //!     // Create a set with some initial elements
 //!     let mut set = set![5, 10, 15, 20, 25, 30];
 //!
@@ -85,10 +87,8 @@
 //!
 //!     // Display the current elements and the set length
 //!     println!("Final set: {}, Length: {}", set, set.len());
-//! }
 //! ```
 //!
-//!
 mod set;
 pub use set::{Set, SetOps};
 /// The maximum capacity for the Set.