1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
//! # fastset Crate
//!
//! The `fastset` crate provides a custom `Set` implementation, optimized for managing collections of `usize` values. It is particularly tailored for use cases involving indices of other data structures, where elements are densely packed within a known range and the application demands high volumes of insert and delete operations.
//!
//! ## Rationale
//!
//! In many applications, especially those dealing with indices or identifiers, the need arises for a data structure that can efficiently handle a dense range of `usize` values. Traditional set implementations might not always offer the best balance between performance and memory usage for such specific scenarios. The `fastset` crate addresses this by offering a `Set` that:
//! - **Specializes in `usize` elements**, making it ideal for scenarios like indexing.
//! - **Optimizes for densely packed elements**, leveraging this characteristic to enhance performance.
//! - **Provides high-performance operations**, especially for insertions and deletions, critical for applications requiring dynamic set manipulations.
//! - **Has predictable memory usage**, which, while not minimal, is bounded and directly related to the specified maximum element value.
//!
//! ## Applicability
//!
//! The `fastset` `Set` is designed for environments where operation predictability and performance take precedence over minimal memory usage. It excels in managing dense, bounded collections of `usize` elements, particularly in scenarios with a high frequency of insertions and deletions. Example use cases include:
//! - Managing available or used indices in large arrays.
//! - Tracking slots in memory pools.
//! - Any application where elements are dense, have a bounded range, and require frequent dynamic manipulation.
//!
//! However, it may not be the best fit for applications where sparse elements span a wide range or where minimizing memory footprint is a primary concern.
//!
//! ## Key Features
//!
//! - **Specialized for `usize`**: Tailored specifically for handling `usize` values, ideal for indexing scenarios.
//! - **Optimized for Dense Elements**: Efficiency is maximized when elements are closely packed within a pre-determined range.
//! - **High-Performance Operations**: Engineered for fast insertions, deletions, and random access.
//! - **Predictable Memory Usage**: While not designed for minimal memory footprint, its usage is predictable and directly related to the maximum element value specified upon creation.
//! - **Random Access**: Includes a `random` method to retrieve a random element from the set, essential for simulations and randomized algorithms.
//!
//! ## Note
//!
//! This crate was developed in the context of Monte Carlo simulations of spin systems. In such simulations, it's required to track and provide fast access to elements of a given sign (positive or negative energy) from an array whose elements (spin energies) are rapidly changing signs due to Monte Carlo updates. The `fastset` `Set` facilitates relatively efficient tracking and manipulation of these elements over extended periods, improving the performance of simulations.
//!
//! ## Usage
//!
//! ```rust
//! use fastset::Set;
//! use nanorand::{WyRand, Rng};
//!
//! // Initialize a new Set with an anticipated maximum element value.
//! let mut set = Set::new(100);
//!
//! // Insert elements into the set.
//! set.insert(5);
//! set.insert(10);
//! set.insert(15);
//!
//! // Randomly select an element from the set.
//! let mut rng = WyRand::new();
//! if let Some(random_element) = set.random(&mut rng) {
//! println!("Randomly selected element: {}", random_element);
//! }
//!
//! // Check for element presence, remove elements, and iterate over the set as before.
//! assert!(set.contains(&10));
//! set.remove(&10);
//!
//! println!("Elements in the set after removal:");
//! for element in set.iter() {
//! println!("Element: {}", element);
//! }
//! ```
//!
//! This example showcases the basic functionality provided by the `fastset` crate, including the crucial `random` method for Monte Carlo simulations and other applications requiring random access to elements.
pub use ;
/// The maximum capacity for the Set.
///
/// CAUTION: Setting the set's largest element or capacity near MAX_CAPACITY
/// can significantly impact memory usage. For instance, with MAX_CAPACITY
/// set to 1 billion, the `Set` could require approximately 16 GB of memory
/// under certain conditions due to storage of elements, their indicators,
/// and indexing structures. Ensure adequate memory is available when
/// approaching this limit.
const MAX_CAPACITY: usize = 1_000_000_000;
/// Macro for creating a `Set` with the given elements.
///
/// # Example
///
/// ```
/// use fastset::{Set, set};
/// let set = set![1, 2, 3];
/// ```
/// Macro for removing elements from a `Set`.
///
/// # Example
///
/// ```
/// # use fastset::{Set, remove};
/// let mut my_set = Set::new(10);
/// my_set.insert(1);
/// my_set.insert(2);
///
/// remove!(my_set, 1, 2);
/// ```
/// Macro for inserting elements into a `Set`.
///
/// # Example
///
/// ```
/// # use fastset::{Set, insert};
/// let mut my_set = Set::new(10);
///
/// insert!(my_set, 1, 2, 3);
/// ```
/// Macro for selecting a random element from a `Set`.
///
/// If no random number generator is provided, it will use `WyRand` as the default.
///
/// # Example
///
/// ```
/// # use fastset::{Set, random};
/// # use nanorand::{WyRand, Rng};
/// let mut my_set = Set::new(10);
/// my_set.insert(1);
/// my_set.insert(2);
///
/// let random_elem = random!(my_set); // Use default RNG
///
/// let mut rng = WyRand::new();
/// let random_elem_custom_rng = random!(my_set, &mut rng); // Use custom RNG
/// ```