Crate serial_int
source · [−]Expand description
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.
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.
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.
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.
#![no_std]
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
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(),
}
}
}
Structs
A generator that creates instances of a Serial type.
Traits
Defines how a type is used by SerialGenerator.