Struct Ulid 

pub struct Ulid { /* private fields */ }

The ULID data type.

Implementations

impl Ulid

pub fn generate() -> Self

Creates a new ULID.

Examples

use rusty_ulid::Ulid;

let ulid = Ulid::generate();

assert_ne!(0, ulid.timestamp());

let ulid_string = ulid.to_string();
// every ulid has exactly 26 characters
assert_eq!(ulid_string.len(), 26);

Panics

Panics if called after +10889-08-02T05:31:50.655Z.

pub fn next_monotonic(previous_ulid: Self) -> Self

Creates the next monotonic ULID for the given previous_ulid.

If the random part of previous_ulid would overflow, this function returns a ULID with the random part set to zero.

Examples

use rusty_ulid::Ulid;

let previous_ulid = Ulid::from(0);
let ulid = Ulid::next_monotonic(previous_ulid);

assert_ne!(0, ulid.timestamp());

Panics

Panics if called after +10889-08-02T05:31:50.655Z.

pub fn next_strictly_monotonic(previous_ulid: Self) -> Option<Self>

Creates the next strictly monotonic ULID for the given previous_ulid.

If the random part of previous_ulid would overflow, this function returns None.

Examples

use rusty_ulid::Ulid;

let previous_ulid = Ulid::from(0);
let ulid = Ulid::next_strictly_monotonic(previous_ulid);

if let Some(ulid) = ulid {
    assert_ne!(0, ulid.timestamp());
}

Panics

Panics if called after +10889-08-02T05:31:50.655Z.

pub fn from_timestamp_with_rng<R>(timestamp: u64, rng: &mut R) -> Self

where R: Rng,

Creates a new ULID with the given timestamp obtaining randomness from rng.

Examples

use rusty_ulid::Ulid;

let ulid = Ulid::from_timestamp_with_rng(0, &mut rand::rng());

let timestamp = ulid.timestamp();

assert_eq!(timestamp, 0);

Panics

Panics if timestamp is larger than 0xFFFF_FFFF_FFFF.

pub fn next_monotonic_from_timestamp_with_rng<R>( previous_ulid: Self, timestamp: u64, rng: &mut R, ) -> Self

where R: Rng,

Creates the next monotonic ULID with the given previous_ulid, timestamp obtaining randomness from rng.

If the random part of previous_ulid would overflow, this function returns a ULID with the random part set to zero.

Examples

use rusty_ulid::Ulid;

let previous_ulid = Ulid::from(0);
let ulid = Ulid::next_monotonic_from_timestamp_with_rng(previous_ulid, 0, &mut rand::rng());

assert_eq!(ulid, Ulid::from(1));

use rusty_ulid::Ulid;

let previous_ulid = Ulid::from(0x0000_0000_0000_FFFF_FFFF_FFFF_FFFF_FFFE);
let ulid = Ulid::next_monotonic_from_timestamp_with_rng(previous_ulid, 0, &mut rand::rng());

assert_eq!(ulid, Ulid::from(0x0000_0000_0000_FFFF_FFFF_FFFF_FFFF_FFFF));

use rusty_ulid::Ulid;

let previous_ulid = Ulid::from(0x0000_0000_0000_FFFF_FFFF_FFFF_FFFF_FFFF);
let ulid = Ulid::next_monotonic_from_timestamp_with_rng(previous_ulid, 0, &mut rand::rng());

// overflow results in zero random part
assert_eq!(ulid, Ulid::from(0));

Panics

Panics if timestamp is larger than 0xFFFF_FFFF_FFFF.

pub fn next_monotonic_from_timestamp_with_rng_and_postprocessor<R>( previous_ulid: Option<Self>, timestamp: u64, rng: &mut R, postprocessor: Option<&dyn Fn(Self) -> Self>, ) -> Self

where R: Rng,

Creates the next monotonic ULID with the given previous_ulid, timestamp obtaining randomness from rng. If a new ULID is created instead of simply incrementing the previous ULID, then postprocessor is used (if available) to transform the new ULID before returning it.

If the random part of previous_ulid would overflow, this function returns a ULID with the random part set to zero.

Examples

use rusty_ulid::Ulid;

let previous_ulid = Ulid::from(0);
let ulid = Ulid::next_monotonic_from_timestamp_with_rng_and_postprocessor(Some(previous_ulid), 0, &mut rand::rng(), None);

assert_eq!(ulid, Ulid::from(1));

use rusty_ulid::Ulid;

let previous_ulid = Ulid::from(0x0000_0000_0000_FFFF_FFFF_FFFF_FFFF_FFFE);
let ulid = Ulid::next_monotonic_from_timestamp_with_rng_and_postprocessor(Some(previous_ulid), 0, &mut rand::rng(), None);

assert_eq!(ulid, Ulid::from(0x0000_0000_0000_FFFF_FFFF_FFFF_FFFF_FFFF));

use rusty_ulid::Ulid;

let previous_ulid = Ulid::from(0x0000_0000_0000_FFFF_FFFF_FFFF_FFFF_FFFF);
let ulid = Ulid::next_monotonic_from_timestamp_with_rng_and_postprocessor(Some(previous_ulid), 0, &mut rand::rng(), None);

// overflow results in zero random part
assert_eq!(ulid, Ulid::from(0));

use rusty_ulid::Ulid;

fn postprocessor_fn(ulid: Ulid) -> Ulid {
    // zero out lowest 32 bits
    Ulid::from(u128::from(ulid) & 0xFFFF_FFFF_FFFF_FFFF_FFFF_FFFF_0000_0000)
}

let previous_ulid = Ulid::from(0);
let ulid = Ulid::next_monotonic_from_timestamp_with_rng_and_postprocessor(
    Some(previous_ulid),
    1,
    &mut rand::rng(),
    Some(&postprocessor_fn),
);

assert_eq!(0, u128::from(ulid) & 0xFFFF_FFFF);

let ulid = Ulid::next_monotonic_from_timestamp_with_rng_and_postprocessor(
    None,
    1,
    &mut rand::rng(),
    Some(&postprocessor_fn),
);

assert_eq!(0, u128::from(ulid) & 0xFFFF_FFFF);
assert_ne!(0, u128::from(ulid));

Panics

Panics if timestamp is larger than 0xFFFF_FFFF_FFFF.

pub fn next_strictly_monotonic_from_timestamp_with_rng<R>( previous_ulid: Self, timestamp: u64, rng: &mut R, ) -> Option<Self>

where R: Rng,

Creates the next strictly monotonic ULID with the given previous_ulid, timestamp obtaining randomness from rng.

If the random part of previous_ulid would overflow, this function returns None.

Examples

use rusty_ulid::Ulid;

let previous_ulid = Ulid::from(0);
let ulid = Ulid::next_strictly_monotonic_from_timestamp_with_rng(previous_ulid, 0, &mut rand::rng());

assert_eq!(ulid, Some(Ulid::from(1)));

use rusty_ulid::Ulid;

let previous_ulid = Ulid::from(0x0000_0000_0000_FFFF_FFFF_FFFF_FFFF_FFFE);
let ulid = Ulid::next_strictly_monotonic_from_timestamp_with_rng(previous_ulid, 0, &mut rand::rng());

assert_eq!(ulid, Some(Ulid::from(0x0000_0000_0000_FFFF_FFFF_FFFF_FFFF_FFFF)));

use rusty_ulid::Ulid;

let previous_ulid = Ulid::from(0x0000_0000_0000_FFFF_FFFF_FFFF_FFFF_FFFF);
let ulid = Ulid::next_strictly_monotonic_from_timestamp_with_rng(previous_ulid, 0, &mut rand::rng());

// overflow results in None
assert_eq!(ulid, None);

Panics

Panics if timestamp is larger than 0xFFFF_FFFF_FFFF.

pub fn next_strictly_monotonic_from_timestamp_with_rng_and_postprocessor<R>( previous_ulid: Option<Self>, timestamp: u64, rng: &mut R, postprocessor: Option<&dyn Fn(Self) -> Self>, ) -> Option<Self>

where R: Rng,

Creates the next strictly monotonic ULID with the given previous_ulid, timestamp obtaining randomness from rng.

If the random part of previous_ulid would overflow, this function returns None.

Examples

use rusty_ulid::Ulid;

let previous_ulid = Ulid::from(0);
let ulid = Ulid::next_strictly_monotonic_from_timestamp_with_rng_and_postprocessor(
    Some(previous_ulid),
    0,
    &mut rand::rng(),
    None,
);

assert_eq!(ulid, Some(Ulid::from(1)));

use rusty_ulid::Ulid;

let previous_ulid = Ulid::from(0x0000_0000_0000_FFFF_FFFF_FFFF_FFFF_FFFE);
let ulid = Ulid::next_strictly_monotonic_from_timestamp_with_rng_and_postprocessor(
    Some(previous_ulid),
    0,
    &mut rand::rng(),
    None,
);

assert_eq!(
    ulid,
    Some(Ulid::from(0x0000_0000_0000_FFFF_FFFF_FFFF_FFFF_FFFF))
);

use rusty_ulid::Ulid;

let previous_ulid = Ulid::from(0x0000_0000_0000_FFFF_FFFF_FFFF_FFFF_FFFF);
let ulid = Ulid::next_strictly_monotonic_from_timestamp_with_rng_and_postprocessor(
    Some(previous_ulid),
    0,
    &mut rand::rng(),
    None,
);

// overflow results in None
assert_eq!(ulid, None);

use rusty_ulid::Ulid;

fn postprocessor_fn(ulid: Ulid) -> Ulid {
    // zero out lowest 32 bits
    Ulid::from(u128::from(ulid) & 0xFFFF_FFFF_FFFF_FFFF_FFFF_FFFF_0000_0000)
}

let previous_ulid = Ulid::from(0);
let ulid = Ulid::next_strictly_monotonic_from_timestamp_with_rng_and_postprocessor(
    Some(previous_ulid),
    1,
    &mut rand::rng(),
    Some(&postprocessor_fn),
);
let ulid = ulid.unwrap();

assert_eq!(0, u128::from(ulid) & 0xFFFF_FFFF);

let ulid = Ulid::next_strictly_monotonic_from_timestamp_with_rng_and_postprocessor(
    None,
    1,
    &mut rand::rng(),
    Some(&postprocessor_fn),
);
let ulid = ulid.unwrap();

assert_eq!(0, u128::from(ulid) & 0xFFFF_FFFF);
assert_ne!(0, u128::from(ulid));

Panics

Panics if timestamp is larger than 0xFFFF_FFFF_FFFF.

pub fn timestamp(&self) -> u64

Returns the timestamp of this ULID as number of non-leap milliseconds since January 1, 1970 0:00:00 UTC (aka “UNIX timestamp”).

Examples

use rusty_ulid::Ulid;
use std::str::FromStr;

let ulid = Ulid::from_str("01CAH7NXGRDJNE9B1NY7PQGYV7")?;
let timestamp = ulid.timestamp();

assert_eq!(timestamp, 1523144390168);

pub fn offsetdatetime(&self) -> OffsetDateTime

Returns the timestamp of this ULID as a OffsetDateTime.

Examples

use rusty_ulid::Ulid;
use std::str::FromStr;

let ulid = Ulid::from_str("01CAH7NXGRDJNE9B1NY7PQGYV7")?;
let datetime = ulid.offsetdatetime();

assert_eq!(datetime.to_string(), "2018-04-07 23:39:50.168 +00:00:00");

pub fn increment(self) -> Self

Returns a new ULID with the random part incremented by one.

Overflowing the random part resets it to zero without influencing the timestamp.

Examples

use rusty_ulid::Ulid;

let ulid = Ulid::from(0);
let incremented = ulid.increment();

assert_eq!(incremented, Ulid::from(1));

use rusty_ulid::Ulid;

let ulid = Ulid::from(0x0000_0000_0000_FFFF_FFFF_FFFF_FFFF_FFFE);
let incremented = ulid.increment();

assert_eq!(incremented, Ulid::from(0x0000_0000_0000_FFFF_FFFF_FFFF_FFFF_FFFF));

use rusty_ulid::Ulid;

let ulid = Ulid::from(0x0000_0000_0000_FFFF_FFFF_FFFF_FFFF_FFFF);
let incremented = ulid.increment();

assert_eq!(incremented, Ulid::from(0));

pub fn to_string(&self) -> String

Returns the string representaton of this ULID.

Examples

use rusty_ulid::Ulid;

let ulid = Ulid::from(0);

assert_eq!(ulid.to_string(), "00000000000000000000000000");

use rusty_ulid::Ulid;

let ulid = Ulid::from(0xFFFF_FFFF_FFFF_FFFF_FFFF_FFFF_FFFF_FFFF);

assert_eq!(ulid.to_string(), "7ZZZZZZZZZZZZZZZZZZZZZZZZZ");

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 Copy for Ulid

impl Debug for Ulid

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Ulid

Available on crate feature serde only.

fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>

Deserialize this value from the given Serde deserializer.

impl Display for Ulid

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

Formats the value using the given formatter.

impl Eq for Ulid

impl From<(u64, u64)> for Ulid

fn from(value: (u64, u64)) -> Self

Examples

use rusty_ulid::Ulid;

let tuple = (0x1122_3344_5566_7788, 0x99AA_BBCC_DDEE_F00F);

let ulid = Ulid::from(tuple);

let expected_ulid = Ulid::from(0x1122_3344_5566_7788_99AA_BBCC_DDEE_F00F);

assert_eq!(ulid, expected_ulid);

use rusty_ulid::Ulid;

let tuple = (0x1122_3344_5566_7788, 0x99AA_BBCC_DDEE_F00F);

let ulid : Ulid = tuple.into();

let expected_ulid = Ulid::from(0x1122_3344_5566_7788_99AA_BBCC_DDEE_F00F);

assert_eq!(ulid, expected_ulid);

impl From<Ulid> for [u8; 16]

fn from(ulid: Ulid) -> Self

Examples

use rusty_ulid::Ulid;

let ulid = Ulid::from(0x1122_3344_5566_7788_99AA_BBCC_DDEE_F00F);

let bytes = <[u8; 16]>::from(ulid);

let expected_bytes: [u8; 16] = [
    0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88,
    0x99, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xF0, 0x0F,
];

assert_eq!(bytes, expected_bytes);

use rusty_ulid::Ulid;

let ulid = Ulid::from(0x1122_3344_5566_7788_99AA_BBCC_DDEE_F00F);

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

let expected_bytes: [u8; 16] = [
    0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88,
    0x99, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xF0, 0x0F,
];

assert_eq!(bytes, expected_bytes);

impl From<Ulid> for (u64, u64)

fn from(ulid: Ulid) -> Self

Examples

use rusty_ulid::Ulid;

let ulid = Ulid::from(0x1122_3344_5566_7788_99AA_BBCC_DDEE_F00F);

let tuple = <(u64, u64)>::from(ulid);

let expected_tuple = (0x1122_3344_5566_7788, 0x99AA_BBCC_DDEE_F00F);

assert_eq!(tuple, expected_tuple);

use rusty_ulid::Ulid;

let ulid = Ulid::from(0x1122_3344_5566_7788_99AA_BBCC_DDEE_F00F);

let tuple : (u64, u64) = ulid.into();

let expected_tuple = (0x1122_3344_5566_7788, 0x99AA_BBCC_DDEE_F00F);

assert_eq!(tuple, expected_tuple);

impl From<Ulid> for u128

fn from(ulid: Ulid) -> Self

Examples

use rusty_ulid::Ulid;

let ulid = Ulid::from((0x1122_3344_5566_7788, 0x99AA_BBCC_DDEE_F00F));

let value = <u128>::from(ulid);

let expected_value = 0x1122_3344_5566_7788_99AA_BBCC_DDEE_F00F;

assert_eq!(value, expected_value);

use rusty_ulid::Ulid;

let ulid = Ulid::from((0x1122_3344_5566_7788, 0x99AA_BBCC_DDEE_F00F));

let value : u128 = ulid.into();

let expected_value = 0x1122_3344_5566_7788_99AA_BBCC_DDEE_F00F;

assert_eq!(value, expected_value);

impl From<[u8; 16]> for Ulid

fn from(bytes: [u8; 16]) -> Self

Examples

use rusty_ulid::Ulid;

let bytes: [u8; 16] = [
    0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88,
    0x99, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xF0, 0x0F,
];

let ulid = Ulid::from(bytes);

let expected_ulid = Ulid::from(0x1122_3344_5566_7788_99AA_BBCC_DDEE_F00F);

assert_eq!(ulid, expected_ulid);

use rusty_ulid::Ulid;

let bytes: [u8; 16] = [
    0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88,
    0x99, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xF0, 0x0F,
];

let ulid : Ulid = bytes.into();

let expected_ulid = Ulid::from(0x1122_3344_5566_7788_99AA_BBCC_DDEE_F00F);

assert_eq!(ulid, expected_ulid);

impl From<u128> for Ulid

fn from(value: u128) -> Self

Examples

use rusty_ulid::Ulid;

let value = 0x1122_3344_5566_7788_99AA_BBCC_DDEE_F00F;

let ulid = Ulid::from(value);

let expected_ulid = Ulid::from((0x1122_3344_5566_7788, 0x99AA_BBCC_DDEE_F00F));

assert_eq!(ulid, expected_ulid);

use rusty_ulid::Ulid;

let value = 0x1122_3344_5566_7788_99AA_BBCC_DDEE_F00F;

let ulid : Ulid = value.into();

let expected_ulid = Ulid::from((0x1122_3344_5566_7788, 0x99AA_BBCC_DDEE_F00F));

assert_eq!(ulid, expected_ulid);

impl FromStr for Ulid

type Err = DecodingError

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

Equality operator ==.

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

Inequality operator !=.

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 Serialize for Ulid

Available on crate feature serde only.

fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Ulid

impl TryFrom<&[u8]> for Ulid

fn try_from(bytes: &[u8]) -> Result<Self, DecodingError>

Returns a ULID for the given slice of bytes or DecodingError::InvalidLength if the slice does not contain exactly 16 bytes.

Examples

use rusty_ulid::Ulid;
use std::convert::TryFrom;
use std::convert::TryInto;

let bytes: [u8; 18] = [
    0x00,
    0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88,
    0x99, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xF0, 0x0F,
    0x00,
];

let ulid : Ulid = Ulid::try_from(&bytes[1..17])?;

let expected_ulid = Ulid::from(0x1122_3344_5566_7788_99AA_BBCC_DDEE_F00F);

assert_eq!(ulid, expected_ulid);

let ulid : Ulid = (&bytes[1..17]).try_into()?;

let expected_ulid = Ulid::from(0x1122_3344_5566_7788_99AA_BBCC_DDEE_F00F);

assert_eq!(ulid, expected_ulid);

use rusty_ulid::Ulid;
use rusty_ulid::DecodingError;
use std::convert::TryFrom;

let mut bytes: [u8; 17] = [0; 17];
let result = Ulid::try_from(&bytes[0..]);

assert_eq!(result, Err(DecodingError::InvalidLength))

use rusty_ulid::Ulid;
use rusty_ulid::DecodingError;
use std::convert::TryFrom;

let mut bytes: [u8; 15] = [0; 15];
let result = Ulid::try_from(&bytes[0..]);

assert_eq!(result, Err(DecodingError::InvalidLength))

type Error = DecodingError

The type returned in the event of a conversion error.