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
/*!
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 serial_int::SerialGenerator;
# use lazy_static::lazy_static;
# use std::{sync::{Arc, Mutex}, thread};
#
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);
}
lazy_static! {
static ref USER_ID_GEN: Mutex<SerialGenerator>
= Mutex::new(SerialGenerator::new());
}
struct User {
id: u32,
email: String,
}
impl User {
pub fn new(email: &str) -> Self {
User {
id: USER_ID_GEN.lock().unwrap().generate(),
email: email.to_string(),
}
}
}
```
*/
#![warn(missing_docs)]
mod serial;
mod serial_generator;
mod tests;
pub use serial::Serial;
pub use serial_generator::SerialGenerator;