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
/*!
Serial (or auto-increment) integers make great unique identifers. They do
not need to be large (i.e. using more memory) to prevent collisions and they
are always unique until they reach their max value, mimicking the behavior
of PostgreSQL's `SERIAL` data type. Creating serial values has minimal
performance impact because it relies on simple adding rather than hashing or
randomizing.
This crate provides a generator (that is also an iterator) that outputs
serial values. By default, any unsigned integer from the standard library
can be generated. This is essentially a counter, a simple iterator for
integers. This crate is appropriately tiny.
For safety and stability, the generator "saturates" the values instead of
overflowing. This guarantees that the output values are unique to that
generator (except for the greatest possible value, e.g. u8::MAX or
u32::MAX).
# Panics
None
# Examples
A simple example.
```rust
# use serial_int::SerialGenerator;
#
let mut gen = SerialGenerator::<u32>::new();
assert_eq!(0, gen.generate());
assert_eq!(1, gen.generate());
```
## Using the "serde_impl" feature
Serialize a generator with Serde.
```rust
# use serial_int::SerialGenerator;
# use toml;
#
let mut gen = SerialGenerator::<u8>::new();
gen.generate();
gen.generate();
let gen_string = toml::to_string(&gen).unwrap();
assert_eq!("value = 2\n", gen_string);
```
Deserialize a generator with Serde.
```rust
# use serial_int::SerialGenerator;
# use toml;
#
let gen = SerialGenerator::<u8>::new();
let gen_from_toml =
toml::from_str::<SerialGenerator<u8>>("value = 0\n").unwrap();
assert_eq!(gen_from_toml, gen);
```
## Using `no_std`
No feature flags are needed.
```rust
#![no_std]
# use serial_int::SerialGenerator;
fn main() {
let mut gen = SerialGenerator::<u8>::new();
let serial_ids = [gen.generate(), gen.generate()];
assert_eq!([0, 1], serial_ids);
}
```
## Other
A complex example showing the use of `static` and concurrency
```rust
# use std::{sync::{Arc, Mutex, OnceLock}, thread};
# use serial_int::*;
static ID_GENERATOR: OnceLock<Mutex<SerialGenerator<u64>>> = OnceLock::new();
fn generate_id() -> u64 {
ID_GENERATOR
.get_or_init(|| Mutex::new(SerialGenerator::new()))
.lock()
.expect("A thread panicked while trying to generate an ID.")
.generate()
}
struct User {
id: u64,
email: String,
}
impl User {
pub fn new(email: &str) -> Self {
User {
id: generate_id(),
email: email.to_string(),
}
}
}
fn main() {
let users_mutex = Arc::new(Mutex::new(Vec::new()));
let users_clone = Arc::clone(&users_mutex);
let handle = thread::spawn(move || {
let alice = User::new("alice@domain.xyz");
let mary = User::new("mary@domain.xyz");
let mut users = users_clone.lock().unwrap();
users.push(alice);
users.push(mary);
});
handle.join().unwrap();
let bob = User::new("bob@domain.xyz");
let fred = User::new("fred@domain.xyz");
let mut users = users_mutex.lock().unwrap();
users.push(bob);
users.push(fred);
assert_eq!(0, users[0].id);
assert_eq!(1, users[1].id);
assert_eq!(2, users[2].id);
assert_eq!(3, users[3].id);
}
```
*/
pub use Serial;
pub use SerialGenerator;