ulid-lite
About
An implementation of the ULID ("Universally Unique Lexicographically Sortable Identifier") standard.
A ULID is
- 128-bit compatible with UUID
- 1.21e+24 unique ULIDs per millisecond
- Lexicographically sortable!
- Canonically encoded as a 26 character string, as opposed to the 36 character UUID
- Uses Crockford's base32 for better efficiency and readability (5 bits per character)
- Case insensitive
- No special characters (URL safe)
Usage
From the command line
The bundled application generates a ULID and prints it to stdout:
$ ulid
01F5QNHN4G55VHQHA8XG1N6H9H
From Rust
Here is a minimal application that uses this crate:
use ulid;
The primary API is the ulid()
function, which returns a String
.
If you would like access to the individual bits, then call ulid_raw()
.
ulid
For more control, the ulid::Ulid
type is also available.
new
The Ulid
struct is a wrapper around a u128
, with a few extra methods.
let id = new;
// They implement Display, LowerHex and UpperHex
println!;
println!;
println!;
More recent ULIDs are higher than older ones:
use sleep;
use Duration;
let a = ulid;
sleep;
let b = ulid;
assert!;
To generate many ulid::Ulid
values, you're recommended to use UlidGenerator
.
It provides the ability to seed the internal pseudo-random number generator.
// use the system's clock as the initial seed...
let mut ulid_gen = new;
let ulids: = ulid_gen.take.collect;
// ...or use a fixed initial seed
let mut ulid_gen = from_seed;
let ulid = ulid_gen.ulid;
From C
A C API is available at lib/ulid.h
. Here is a minimal application that generates and prints a ULID:
int
libulid
also provides access to creating binary (128 bit)
ULIDs and converting those to strings (this example is
intentionally convoluted to showcase error handling):
int
Installation
Add ulid-lite
to your crate's Cargo.toml file:
[]
= "0.6.1"
Building from source
You can download and install ulid-lite
directly from the main branch of the upstream repository:
$ cargo install --git https://github.com/timClicks/ulid-lite.git
Building the C interface
To regenerate the ulid.h
header file, run make lib/ulid.h
.
To build the libulid
shared library, run make target/release/libulid.so
.
Contributing
You are very welcome to contribute to project in any form, however you must abide by the Rust Code of Conduct.
Non-code contributions
Your contribution is important! Please submit an issue with your suggested change.
Code contributions
Note: these instructions have only been tested on Ubuntu, please submit corrections/improvements for other operating systems.
Setting up a development environment
To begin, you require the following tools:
- A Rust installation that includes
rustc
,rustup
, andcargo
git
make
From the root of the project, run setup-devenv
to install dependencies that are managed by cargo
or rustup
, such as MIRI:
$ ./setup-devenv
Submitting changes
ulid-lite
follows the standard GitHub workflow for code changes.
Please fork the project, push commits to that fork and submit a pull request (PR).
Before submitting a PR, you should run make test && make
from the project's root directory, rather than cargo test
.
This will ensure that the MIRI tests run correctly and that artifacts can all be built.
Roadmap
PostgreSQL extension
I would like to use this crate to develop pg_ulid extension.
More features
- parsing pre-existing ULIDs
- monotonicity within the same millisecond
- overflow checks
More platforms
ulid-lite
is currently only built for Linux. Patches are welcome to support more platforms.
Why add another crate?
I wanted to implement a crate with a minimalist feel. It is intended to be easy and fast to build.
ulid-lite
has minimal dependencies. This keeps build times fast and binary size small.
ulid
does not take a long time to compile:
$ cargo clean
$ cargo build --release
Compiling libc v0.2.94
Compiling lazy_static v0.2.11
Compiling rand v0.4.6
Compiling rand v0.3.23
Compiling xorshift v0.1.3
Compiling ulid-lite v0.4.0 (/.../ulid-lite)
Finished release [optimized] target(s) in 5.68s
Perhaps more importantly however, ulid-lite
is very fast.
A single CPU core can generate about 35,700 ULIDs per millisecond.
$ cargo bench
...
running 2 tests
test benchmark_generation ... bench: 28 ns/iter (+/- 2)
test benchmark_serialized ... bench: 71 ns/iter (+/- 12)
Acknowledgements
I've relied on two other implementations to develop ulid-lite
: