serial_int

Safe, easy-to-use auto-increment integers

• Docs
• Repository
• Issues
• GitHub mirror

Serial (or auto-increment) integers make great unique identifiers because they do not need to be large (i.e. using more memory) to prevent collisions. 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).

Features

• Usability
  • Straightforward, documented API
  • Includes support for all unsigned integers in the standard library
  • Iterator implementation
  • Serde support via feature flag
  • no_std
• Safety
  • Panic-free
  • No dependencies
  • Full test coverage
• Extensibility
  • Support custom serial types with single trait
  • Tests use trait generics, making it easy to test new implementations

Usage

Use a generator to create unique identifiers.

let mut gen = SerialGenerator::<u32>::new();

assert_eq!(0, gen.generate());
assert_eq!(1, gen.generate());

More examples are available in the docs.

Contributing

How to contribute

Submit a patch. If you add a new implementation of Serial, add a submodule to tests using the provided functions. Please run the "test.sh" script before submitting a contribution.

This project is maintained on Sourcehut. Contributions through this platform are preferred. You may submit a ticket if you encounter a problem or want to request a feature. You may use the mailing list to contribute patches or public discussion.

Contributions are also welcome on the Github mirror.

🦀🔧 Contributors 🔧🦀

• Jeff Anderson 🐙 - Sourcehut | Github | https://jeffa.io
• Yash Karandikar 🧞 - Sourcehut | Github | https://karx.xyz/
• devalain 👾 - Github