Struct Ulid

Source

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

Expand description

A ULID which never is zero.

Because this Ulid can never become zero, size of Ulid and size of Option<Ulid> are guaranteed to be equal thanks to Rust null pointer optimization:

use std::mem::size_of;
use mr_ulid::Ulid;

assert_eq!(size_of::<Ulid>(), size_of::<Option<Ulid>>());

Parsing a zero value ULID will fail:

use mr_ulid::Ulid;

let s = "00000000000000000000000000";

assert!(s.parse::<Ulid>().is_err());

For a ULID which can become zero, check out the ZeroableUlid type. However, it is more idiomatic to just use Option<Ulid>.

Implementations§

Source §

impl Ulid

Source

pub const MIN: Self

Minimum allowed Ulid

The smallest value for Ulid is 1, because zero is explicitly not allowed.

§Example

use mr_ulid::Ulid;

assert_eq!(Ulid::MIN.to_u128(), 1);

Source

pub const MAX: Self

Maximum allowed Ulid

The largest value for Ulid is u128::MAX.

§Example

use mr_ulid::Ulid;

assert_eq!(Ulid::MAX.to_u128(), u128::MAX);

Source

pub fn new() -> Self

Generates a new unique ULID.

The generated ULIDs are guaranteed to be unique and monotonically increasing and never zero.

A lot of care is taken, that the ULIDs cannot overflow. You can create as many ULIDs as you like, and they will always be unique and strict monotonically increasing.

§Panics

With the standard entropy source (STANDARD_ENTROPY_SOURCE), this method will panic if the system date is somewhere after the year 10889 or before the Unix epoch (year 1970).

§Example

use mr_ulid::Ulid;

let u1 = Ulid::new();
let u2 = Ulid::new();

assert!(u1 != u2);
assert!(u1 < u2);

let t1 = u1.timestamp();
let t2 = u2.timestamp();

let r1 = u1.randomness();
let r2 = u2.randomness();

assert!((t1 < t2) || (t1 == t2 && r1 < r2));

Source

pub const fn timestamp(self) -> u64

Returns the timestamp part of a Ulid.

The timestamp is measured in milliseconds since the Unix epoch (1. January 1970). ULID timestamps are limited to 48 bits.

§Example

use mr_ulid::Ulid;

let u = Ulid::new();

assert!(u.timestamp() > 1704067200000); // 1st January 2024

Source

pub const fn randomness(self) -> u128

Returns the random part of a Ulid.

The randomness of a ULID is limited to 80 bits.

§Example

use mr_ulid::Ulid;

let u = Ulid::new();

assert!(u.randomness() < (1<<80));

Source

pub fn datetime(self) -> SystemTime

Returns the timestamp part of a Ulid as a SystemTime.

§Panics

In Rust the allowed range for SystemTime is not defined. So this method may panic if the timestamp of the ULID cannot represented with SystemTime. On most common systems that will not happen.

For a variant which never panics, see Ulid::try_datetime.

§Example

use std::time::SystemTime;
use mr_ulid::Ulid;

let u = Ulid::new();

assert!(u.datetime() <= SystemTime::now());

Source

pub const fn to_zeroable_ulid(self) -> ZeroableUlid

Converts this Ulid to a ZeroableUlid.

This method always succeeds, as every Ulid is a valid ZeroableUlid.

§Example

use mr_ulid::Ulid;

let u1 = Ulid::new();
let u2 = u1.to_zeroable_ulid();

assert_eq!(u1.to_u128(), u2.to_u128());

Source

pub const fn from_zeroable_ulid(zeroable: ZeroableUlid) -> Option<Self>

Creates a Ulid from a ZeroableUlid.

When the ZeroableUlid is zero, None is returned.

§Example

use mr_ulid::{Ulid, ZeroableUlid};

let u1 = ZeroableUlid::new();
assert!(Ulid::from_zeroable_ulid(u1).is_some());

let u2 = ZeroableUlid::zeroed(); // Create a ZeroableUlid with zero value
assert!(Ulid::from_zeroable_ulid(u2).is_none());

Source

pub const fn to_parts(self) -> (u64, u128)

Returns the timestamp and randomness parts of a Ulid as a pair.

§Example

use mr_ulid::Ulid;

let u = Ulid::new();
let (timestamp, randomness) = u.to_parts();

assert_eq!(timestamp, u.timestamp());
assert_eq!(randomness, u.randomness());

Source

pub const fn from_parts(timestamp: u64, randomness: u128) -> Result<Self, Error>

Creates a Ulid from a timestamp and randomness parts.

§Errors

Will fail if the timestamp (48 bits) or randomness (80 bits) are out of range, and will fail, if both values are zero, because Ulid is not allowed to be zero.

§Example

use mr_ulid::Ulid;

let u1 = Ulid::new();
let (timestamp, randomness) = u1.to_parts();
let u2 = Ulid::from_parts(timestamp, randomness)?;

assert_eq!(u1, u2);

assert!(Ulid::from_parts(0, 0).is_err());

Source

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

Converts a Ulid into binary bytes

The bytes are in network byte order (big endian).

§Example

use mr_ulid::Ulid;

let ulid: Ulid = "01JB05JV6H9ZA2YQ6X3K1DAGVA".parse()?;

assert_eq!(ulid.to_bytes(), [1, 146, 192, 89, 108, 209, 79, 212, 47, 92, 221, 28, 194, 213, 67, 106]);

Source

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

Creates a Ulid from a binary byte array.

The byte array must be in network byte order (big endian).

Returns None if all bytes in the byte array are zero, because Ulid is not allowed to be zero.

§Example

use mr_ulid::Ulid;

let bytes: [u8; 16] = [1, 146, 192, 89, 108, 209, 79, 212, 47, 92, 221, 28, 194, 213, 67, 106];
let u = Ulid::from_bytes(bytes)?;

assert_eq!(u.to_string(), "01JB05JV6H9ZA2YQ6X3K1DAGVA");

Source

pub const fn to_u128(self) -> u128

Converts a Ulid into a u128 integer.

§Example

use mr_ulid::Ulid;

let u: Ulid = "01JB07NQ643XZXVHZDY0JNYR02".parse()?;

assert_eq!(u.to_u128(), 2091207293934528941058695985186693122);

Source

pub const fn from_u128(n: u128) -> Option<Self>

Creates a Ulid from a u128 integer.

§Errors

Return None if the value was zero, because Ulid is not allowed to be zero.

§Example

use mr_ulid::Ulid;

let n = 2091207293934528941058695985186693122_u128;
let u = Ulid::from_u128(n)?;

assert_eq!(u.to_string(), "01JB07NQ643XZXVHZDY0JNYR02");

Source

pub const fn to_non_zero_u128(self) -> NonZero<u128>

Converts a Ulid into a NonZero<u128> integer.

§Example

use std::num::NonZero;

use mr_ulid::Ulid;

let u = Ulid::from_u128(42)?;

assert_eq!(u.to_non_zero_u128(), NonZero::new(42)?);

Source

pub const fn from_non_zero_u128(non_zero: NonZero<u128>) -> Self

Creates a Ulid from a NonZero<u128> integer.

Because the NonZero<u128> integer cannot be zero, this method always succeed.

§Example

use std::num::NonZero;

use mr_ulid::Ulid;

let n = NonZero::new(2091207293934528941058695985186693122)?;
let u = Ulid::from_non_zero_u128(n);

assert_eq!(u.to_string(), "01JB07NQ643XZXVHZDY0JNYR02");

Source

pub fn try_new() -> Option<Self>

Generates a new Ulid and never panics.

This is a variant of Ulid::new() which never panics (with the STANDARD_ENTROPY_SOURCE).

In the case of problems with the ULID-generator, this function returns None.

§Example

use mr_ulid::Ulid;

let u1 = Ulid::try_new()?;
let u2 = Ulid::try_new()?;

assert!(u1 != u2);
assert!(u1.timestamp() <= u2.timestamp());

Source

pub fn try_datetime(self) -> Option<SystemTime>

Returns the timestamp part of a Ulid as a SystemTime and never panics.

This is a variant of Ulid::datetime() which never panics.

In the case that the timestamp of a Ulid cannot be encoded in a SystemTime, this method returns None.

§Example

use std::time::SystemTime;
use mr_ulid::Ulid;

let u = Ulid::new();

let datetime: Option<SystemTime> = u.try_datetime();

Source

pub fn try_to_string(self) -> Option<String>

Return the string representation of a Ulid and never panics.

While the blanket implementation of std::string::ToString for std::fmt::Display may panic, this method is guaranteed to never panic, but returns None if the string representation cannot be created. One reason this can happen is if the allocation of memory for the string fails.

Source