ulid-rs

To use ulid-rs in your Rust project, import the Ulid struct. You can generate new identifiers, convert them to strings, and parse them back from strings.

use ulid::Ulid;

// Generate a ulid
let ulid = Ulid::generate();

// Generate a string for a ulid
let s = ulid.to_string();

// Create from a String
let res = Ulid::from_string(&s);

assert_eq!(ulid, res.unwrap());

A Ulid is a unique 128-bit lexicographically sortable identifier. It is canonically represented as a 26-character Crockford Base32 encoded string.

The 128 bits are divided into:

• 48 bits: A Unix timestamp in milliseconds (provides lexicographic sorting).
• 80 bits: Random data (ensures uniqueness).

Constants:

• Ulid::TIME_BITS: 48
• Ulid::RAND_BITS: 80

The ulid crate provides several optional features to customize its behavior:

• std (default): Enables the use of std and rand. Disable this flag if you require #[no_std] support.
• serde: Enables serialization and deserialization of Ulid types via serde. ULIDs are serialized using their canonical 26-character representation. It also provides an optional ulid_as_u128 module for serializing through the inner u128 primitive.
• uuid: Enables infallible conversions between ULIDs and UUIDs from the uuid crate using the std::convert::From trait.

The Ulid struct is the primary interface for working with Universally Unique Lexicographically Sortable Identifiers.

Key operations include:

• Ulid::generate(): Creates a new ULID.
• ulid.to_string(): Converts the ULID to its canonical 26-character string representation.
• Ulid::from_string(&str): Parses a string into a Ulid instance.

use ulid::Ulid;

let ulid = Ulid::generate();
let s = ulid.to_string();
let res = Ulid::from_string(&s);

Convert a 26-character Base32 encoded string back into its original u128 value using decode. This function is a const fn and supports case-insensitive decoding (both uppercase and lowercase characters are valid).

Possible errors:

• DecodeError::InvalidLength: The input string is not exactly 26 characters long.
• DecodeError::InvalidChar: The string contains characters not present in the ULID Base32 alphabet.

let encoded = "21850M2GA1850M2GA1850M2GA1";
let val = decode(encoded).unwrap();
assert_eq!(val, 0x41414141414141414141414141414141);

You can retrieve the constituent parts of a Ulid using these methods:

• ulid.timestamp_ms() -> u64: Returns the 48-bit timestamp portion.
• ulid.random() -> u128: Returns the 80-bit random portion.

use ulid::Ulid;

let ulid = Ulid::from_string("01D39ZY06FGSCTVN4T2V9PKHFZ").unwrap();
let ts = ulid.timestamp_ms();
let rand = ulid.random();

For performance-critical or no_std environments, use encode_to_array. This function encodes a u128 directly into a provided mutable byte array of size ULID_LEN. This is a const fn and can be used in constant contexts.

let mut buffer: [u8; ULID_LEN] = [0; ULID_LEN];
let val: u128 = 0x41414141414141414141414141414141;
encode_to_array(val, &mut buffer);

The Generator struct provides a way to generate ULIDs that are guaranteed to be monotonically increasing (each call returns a ULID larger than the previous one). This is useful for maintaining sort order when generating IDs in rapid succession or within the same millisecond.

To use it, create a new generator and call generate(). If the random bits of the current ULID reach their maximum capacity within the same millisecond, the generator will return an Overflow error, which must be handled to continue generating monotonic IDs.

use ulid::Generator;

let mut generator = Generator::new();

let ulid1 = generator.generate().unwrap();
let ulid2 = generator.generate().unwrap();

assert!(ulid1 < ulid2);

The Ulid type implements several conversion traits:

To other types:

• Into<u128>: Converts to the underlying 128-bit integer.
• Into<[u8; 16]>: Converts to a big-endian byte array.
• Into<String>: Converts to a Base32 string (requires std).
• Into<(u64, u64)>: Converts to a tuple of two 64-bit integers.

From other types:

• From<u128>
• From<[u8; 16]>
• From<(u64, u64)>

use ulid::Ulid;

let ulid = Ulid::generate();

// To u128
let val: u128 = ulid.into();

// To bytes
let bytes: [u8; 16] = ulid.into();

// From bytes
let ulid_from_bytes = Ulid::from(bytes);

The increment() method increases the random portion of the ULID by 1 while keeping the timestamp identical.

Warning: If the random component is already at its maximum value (bitmask!(80)), the function will return an Err containing the overflowed ULID (where the timestamp has been incremented).

use ulid::Ulid;

let ulid = Ulid::from_string("01BX5ZZKBKAZZZZZZZZZZZZZZ").unwrap();

match ulid.increment() {
    Ok(next_ulid) => println!("Next: {}", next_ulid),
    Err(overflowed) => println!("Overflowed to: {}", overflowed),
}