Struct Ulid 

pub struct Ulid(/* private fields */);

Available on crate feature ulid only.

A 128-bit ULID.

Internally stored as 16 big-endian bytes: 6 bytes of millisecond timestamp followed by 10 bytes of randomness.

Example

use id_forge::ulid::Ulid;

let id = Ulid::new();
assert_eq!(id.to_string().len(), 26);

Implementations

impl Ulid

pub const fn nil() -> Self

The Nil ULID: all 128 bits set to zero.

Example

use id_forge::ulid::Ulid;

assert_eq!(Ulid::nil().to_string(), "00000000000000000000000000");

pub const fn max() -> Self

The Max ULID: all 128 bits set to one — the largest value the 26-character display can represent (7ZZZ… since the spec reserves the top two bits of the leading character).

Example

use id_forge::ulid::Ulid;

assert_eq!(Ulid::max().to_string(), "7ZZZZZZZZZZZZZZZZZZZZZZZZZ");

pub fn new() -> Self

Construct a new ULID at the current wall-clock millisecond.

Two ULIDs minted in the same millisecond by the same process are strictly ordered: the second one is the first one’s random suffix plus one. Across milliseconds, the randomness is freshly drawn.

Example

use id_forge::ulid::Ulid;

let a = Ulid::new();
let b = Ulid::new();
assert!(b > a);

Examples found in repository

examples/basic.rs (line 13)

fn main() {
    let v4 = Uuid::v4();
    println!("UUID v4:    {v4} (version={})", v4.version());
    println!("UUID v7:    {}", Uuid::v7());
    println!("UUID nil:   {}", Uuid::nil());

    let a = Ulid::new();
    let b = Ulid::new();
    println!("ULID a:     {a}");
    println!("ULID b:     {b} (monotonic: {})", b > a);

    let gen = Snowflake::new(1);
    let sf = gen.next_id();
    let (ts_offset, worker, seq) = Snowflake::parts(sf);
    println!(
        "Snowflake:  {sf}  (ts+epoch={}, worker={worker}, seq={seq})",
        ts_offset + gen.epoch_ms()
    );

    println!("NanoID 21:  {}", nanoid::generate());
    println!("NanoID 8:   {}", nanoid::with_length(8));

    assert_eq!(v4, Uuid::parse_str(&v4.to_string()).unwrap());
    assert_eq!(a, Ulid::parse_str(&a.to_string()).unwrap());
}

examples/ulid_monotonic.rs (line 18)

fn main() {
    println!("== Single-millisecond burst ==");

    // 1000 ULIDs back-to-back. Most will share the same ms prefix;
    // the monotonic factory guarantees b > a for every consecutive pair.
    let mut ids: Vec<Ulid> = (0..1000).map(|_| Ulid::new()).collect();

    let same_ms = ids
        .windows(2)
        .filter(|w| w[0].timestamp_ms() == w[1].timestamp_ms())
        .count();
    println!("count        = {}", ids.len());
    println!("same-ms pairs = {same_ms} of {}", ids.len() - 1);

    let strictly_increasing = ids.windows(2).all(|w| w[1] > w[0]);
    println!("monotonic    = {strictly_increasing}");

    let unique: HashSet<&Ulid> = ids.iter().collect();
    println!("unique       = {} of {}", unique.len(), ids.len());

    println!("\n== First and last of the burst ==");
    let first = ids.first().unwrap();
    let last = ids.last().unwrap();
    println!("first        = {first}");
    println!("last         = {last}");
    println!("ts_first     = {} ms", first.timestamp_ms());
    println!("ts_last      = {} ms", last.timestamp_ms());

    println!("\n== Crockford base32 round-trip ==");
    let sample = Ulid::new();
    let s = sample.to_string();
    let parsed = Ulid::parse_str(&s).unwrap();
    println!("sample       = {sample}");
    println!("parsed       = {parsed}");
    println!("equal        = {}", sample == parsed);

    println!("\n== Substitutions accepted by parse_str ==");
    let with_subs = Ulid::parse_str("0IIIIIIIIIIIIIIIIIIIIIIIII").unwrap();
    let canonical = Ulid::parse_str("01111111111111111111111111").unwrap();
    println!("\"0III...\" == \"0111...\" = {}", with_subs == canonical);

    println!("\n== Sorting by Display is sorting by time ==");
    ids.sort_by_key(|u| u.to_string());
    let same = ids.windows(2).all(|w| w[1] >= w[0]);
    println!("string sort  = byte sort = {same}");
}

pub const fn from_bytes(bytes: &[u8; 16]) -> Self

Wrap a 16-byte big-endian representation as-is.

Example

use id_forge::ulid::Ulid;

let id = Ulid::new();
let copy = Ulid::from_bytes(id.as_bytes());
assert_eq!(id, copy);

pub const fn as_bytes(&self) -> &[u8; 16]

Return the raw 16-byte big-endian representation.

Example

use id_forge::ulid::Ulid;

assert_eq!(Ulid::nil().as_bytes(), &[0u8; 16]);

pub const fn timestamp_ms(&self) -> u64

Return the 48-bit millisecond timestamp prefix.

Example

use id_forge::ulid::Ulid;

let id = Ulid::new();
assert!(id.timestamp_ms() > 0);

Examples found in repository

examples/ulid_monotonic.rs (line 22)

fn main() {
    println!("== Single-millisecond burst ==");

    // 1000 ULIDs back-to-back. Most will share the same ms prefix;
    // the monotonic factory guarantees b > a for every consecutive pair.
    let mut ids: Vec<Ulid> = (0..1000).map(|_| Ulid::new()).collect();

    let same_ms = ids
        .windows(2)
        .filter(|w| w[0].timestamp_ms() == w[1].timestamp_ms())
        .count();
    println!("count        = {}", ids.len());
    println!("same-ms pairs = {same_ms} of {}", ids.len() - 1);

    let strictly_increasing = ids.windows(2).all(|w| w[1] > w[0]);
    println!("monotonic    = {strictly_increasing}");

    let unique: HashSet<&Ulid> = ids.iter().collect();
    println!("unique       = {} of {}", unique.len(), ids.len());

    println!("\n== First and last of the burst ==");
    let first = ids.first().unwrap();
    let last = ids.last().unwrap();
    println!("first        = {first}");
    println!("last         = {last}");
    println!("ts_first     = {} ms", first.timestamp_ms());
    println!("ts_last      = {} ms", last.timestamp_ms());

    println!("\n== Crockford base32 round-trip ==");
    let sample = Ulid::new();
    let s = sample.to_string();
    let parsed = Ulid::parse_str(&s).unwrap();
    println!("sample       = {sample}");
    println!("parsed       = {parsed}");
    println!("equal        = {}", sample == parsed);

    println!("\n== Substitutions accepted by parse_str ==");
    let with_subs = Ulid::parse_str("0IIIIIIIIIIIIIIIIIIIIIIIII").unwrap();
    let canonical = Ulid::parse_str("01111111111111111111111111").unwrap();
    println!("\"0III...\" == \"0111...\" = {}", with_subs == canonical);

    println!("\n== Sorting by Display is sorting by time ==");
    ids.sort_by_key(|u| u.to_string());
    let same = ids.windows(2).all(|w| w[1] >= w[0]);
    println!("string sort  = byte sort = {same}");
}

pub fn parse_str(input: &str) -> Result<Self, ParseError>

Parse a 26-character Crockford base32 ULID, case-insensitive.

Accepts the substitution rules from the spec: I, L decode to 1; O decodes to 0. U is reserved and rejected. Returns ParseError on length, character, or leading-bits violations.

Example

use id_forge::ulid::Ulid;

let id = Ulid::parse_str("01ARZ3NDEKTSV4RRFFQ69G5FAV").unwrap();
assert_eq!(id.to_string(), "01ARZ3NDEKTSV4RRFFQ69G5FAV");

Examples found in repository

examples/basic.rs (line 30)

fn main() {
    let v4 = Uuid::v4();
    println!("UUID v4:    {v4} (version={})", v4.version());
    println!("UUID v7:    {}", Uuid::v7());
    println!("UUID nil:   {}", Uuid::nil());

    let a = Ulid::new();
    let b = Ulid::new();
    println!("ULID a:     {a}");
    println!("ULID b:     {b} (monotonic: {})", b > a);

    let gen = Snowflake::new(1);
    let sf = gen.next_id();
    let (ts_offset, worker, seq) = Snowflake::parts(sf);
    println!(
        "Snowflake:  {sf}  (ts+epoch={}, worker={worker}, seq={seq})",
        ts_offset + gen.epoch_ms()
    );

    println!("NanoID 21:  {}", nanoid::generate());
    println!("NanoID 8:   {}", nanoid::with_length(8));

    assert_eq!(v4, Uuid::parse_str(&v4.to_string()).unwrap());
    assert_eq!(a, Ulid::parse_str(&a.to_string()).unwrap());
}

examples/ulid_monotonic.rs (line 44)

fn main() {
    println!("== Single-millisecond burst ==");

    // 1000 ULIDs back-to-back. Most will share the same ms prefix;
    // the monotonic factory guarantees b > a for every consecutive pair.
    let mut ids: Vec<Ulid> = (0..1000).map(|_| Ulid::new()).collect();

    let same_ms = ids
        .windows(2)
        .filter(|w| w[0].timestamp_ms() == w[1].timestamp_ms())
        .count();
    println!("count        = {}", ids.len());
    println!("same-ms pairs = {same_ms} of {}", ids.len() - 1);

    let strictly_increasing = ids.windows(2).all(|w| w[1] > w[0]);
    println!("monotonic    = {strictly_increasing}");

    let unique: HashSet<&Ulid> = ids.iter().collect();
    println!("unique       = {} of {}", unique.len(), ids.len());

    println!("\n== First and last of the burst ==");
    let first = ids.first().unwrap();
    let last = ids.last().unwrap();
    println!("first        = {first}");
    println!("last         = {last}");
    println!("ts_first     = {} ms", first.timestamp_ms());
    println!("ts_last      = {} ms", last.timestamp_ms());

    println!("\n== Crockford base32 round-trip ==");
    let sample = Ulid::new();
    let s = sample.to_string();
    let parsed = Ulid::parse_str(&s).unwrap();
    println!("sample       = {sample}");
    println!("parsed       = {parsed}");
    println!("equal        = {}", sample == parsed);

    println!("\n== Substitutions accepted by parse_str ==");
    let with_subs = Ulid::parse_str("0IIIIIIIIIIIIIIIIIIIIIIIII").unwrap();
    let canonical = Ulid::parse_str("01111111111111111111111111").unwrap();
    println!("\"0III...\" == \"0111...\" = {}", with_subs == canonical);

    println!("\n== Sorting by Display is sorting by time ==");
    ids.sort_by_key(|u| u.to_string());
    let same = ids.windows(2).all(|w| w[1] >= w[0]);
    println!("string sort  = byte sort = {same}");
}

Trait Implementations

impl Clone for Ulid

fn clone(&self) -> Ulid

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Ulid

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Ulid

fn default() -> Self

Returns the “default value” for a type.

impl Display for Ulid

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromStr for Ulid

type Err = ParseError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for Ulid

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Ulid

fn cmp(&self, other: &Ulid) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Ulid

fn eq(&self, other: &Ulid) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Ulid

fn partial_cmp(&self, other: &Ulid) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Copy for Ulid

impl Eq for Ulid

impl StructuralPartialEq for Ulid