Struct Ulid

pub struct Ulid(pub u128);

A Ulid is a unique 128-bit lexicographically sortable identifier

Canonically, it is represented as a 26 character Crockford Base32 encoded string.

Of the 128-bits, the first 48 are a unix timestamp in milliseconds. The remaining 80 are random. The first 48 provide for lexicographic sorting and the remaining 80 ensure that the identifier is unique.

Tuple Fields

0: u128

Implementations

impl Ulid

pub fn new() -> Ulid

Creates a new Ulid with the current time (UTC)

Using this function to generate Ulids will not guarantee monotonic sort order. See [ulid::Generator] for a monotonic sort order.

Example

use ulid::Ulid;

let my_ulid = Ulid::new();

pub fn with_source<R: Rng>(source: &mut R) -> Ulid

Creates a new Ulid using data from the given random number generator

Example

use rand::prelude::*;
use ulid::Ulid;

let mut rng = StdRng::from_entropy();
let ulid = Ulid::with_source(&mut rng);

pub fn from_datetime(datetime: SystemTime) -> Ulid

Creates a new Ulid with the given datetime

This can be useful when migrating data to use Ulid identifiers.

This will take the maximum of the [SystemTime] argument and [SystemTime::UNIX_EPOCH] as earlier times are not valid for a Ulid timestamp

Example

use std::time::{SystemTime, Duration};
use ulid::Ulid;

let ulid = Ulid::from_datetime(SystemTime::now());

pub fn from_datetime_with_source<R>( datetime: SystemTime, source: &mut R, ) -> Ulid

where R: Rng + ?Sized,

Creates a new Ulid with the given datetime and random number generator

This will take the maximum of the [SystemTime] argument and [SystemTime::UNIX_EPOCH] as earlier times are not valid for a Ulid timestamp

Example

use std::time::{SystemTime, Duration};
use rand::prelude::*;
use ulid::Ulid;

let mut rng = StdRng::from_entropy();
let ulid = Ulid::from_datetime_with_source(SystemTime::now(), &mut rng);

pub fn datetime(&self) -> SystemTime

Gets the datetime of when this Ulid was created accurate to 1ms

Example

use std::time::{SystemTime, Duration};
use ulid::Ulid;

let dt = SystemTime::now();
let ulid = Ulid::from_datetime(dt);

assert!(
    dt + Duration::from_millis(1) >= ulid.datetime()
    && dt - Duration::from_millis(1) <= ulid.datetime()
);

impl Ulid

pub const TIME_BITS: u8 = 48u8

The number of bits in a Ulid’s time portion

pub const RAND_BITS: u8 = 80u8

The number of bits in a Ulid’s random portion

pub const fn from_parts(timestamp_ms: u64, random: u128) -> Ulid

Create a Ulid from separated parts.

NOTE: Any overflow bits in the given args are discarded

Example

use ulid::Ulid;

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

let ulid2 = Ulid::from_parts(ulid.timestamp_ms(), ulid.random());

assert_eq!(ulid, ulid2);

pub const fn from_string(encoded: &str) -> Result<Ulid, DecodeError>

Creates a Ulid from a Crockford Base32 encoded string

An DecodeError will be returned when the given string is not formatted properly.

Example

use ulid::Ulid;

let text = "01D39ZY06FGSCTVN4T2V9PKHFZ";
let result = Ulid::from_string(text);

assert!(result.is_ok());
assert_eq!(&result.unwrap().to_string(), text);

pub const fn nil() -> Ulid

The ‘nil Ulid’.

The nil Ulid is special form of Ulid that is specified to have all 128 bits set to zero.

Example

use ulid::Ulid;

let ulid = Ulid::nil();

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

pub const fn timestamp_ms(&self) -> u64

Gets the timestamp section of this ulid

Example

use std::time::{SystemTime, Duration};
use ulid::Ulid;

let dt = SystemTime::now();
let ulid = Ulid::from_datetime(dt);

assert_eq!(u128::from(ulid.timestamp_ms()), dt.duration_since(SystemTime::UNIX_EPOCH).unwrap_or(Duration::ZERO).as_millis());

pub const fn random(&self) -> u128

Gets the random section of this ulid

Example

use ulid::Ulid;

let text = "01D39ZY06FGSCTVN4T2V9PKHFZ";
let ulid = Ulid::from_string(text).unwrap();
let ulid_next = ulid.increment().unwrap();

assert_eq!(ulid.random() + 1, ulid_next.random());

pub fn to_str<'buf>( &self, buf: &'buf mut [u8], ) -> Result<&'buf mut str, EncodeError>

👎Deprecated since 1.2.0: Use the infallible array_to_str instead.

Creates a Crockford Base32 encoded string that represents this Ulid

Example

use ulid::Ulid;

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

let mut buf = [0; ulid::ULID_LEN];
let new_text = ulid.to_str(&mut buf).unwrap();

assert_eq!(new_text, text);

pub fn array_to_str<'buf>(&self, buf: &'buf mut [u8; 26]) -> &'buf mut str

Creates a Crockford Base32 encoded string that represents this Ulid

Example

use ulid::Ulid;

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

let mut buf = [0; ulid::ULID_LEN];
let new_text = ulid.array_to_str(&mut buf);

assert_eq!(new_text, text);

pub fn to_string(&self) -> String

Creates a Crockford Base32 encoded string that represents this Ulid

Example

use ulid::Ulid;

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

assert_eq!(&ulid.to_string(), text);

pub const fn is_nil(&self) -> bool

Test if the Ulid is nil

Example

use ulid::Ulid;

let ulid = Ulid::new();
assert!(!ulid.is_nil());

let nil = Ulid::nil();
assert!(nil.is_nil());

pub const fn increment(&self) -> Option<Ulid>

Increment the random number, make sure that the ts millis stays the same

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

Creates a Ulid using the provided bytes array.

Example

use ulid::Ulid;
let bytes = [0xFF; 16];

let ulid = Ulid::from_bytes(bytes);

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

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

Returns the bytes of the Ulid in big-endian order.

Example

use ulid::Ulid;

let text = "7ZZZZZZZZZZZZZZZZZZZZZZZZZ";
let ulid = Ulid::from_string(text).unwrap();

assert_eq!(ulid.to_bytes(), [0xFF; 16]);

Trait Implementations

impl Clone for Ulid

fn clone(&self) -> Ulid

Returns a copy 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<(), Error>

Formats the value using the given formatter.

impl From<[u8; 16]> for Ulid

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

Converts to this type from the input type.

impl From<(u64, u64)> for Ulid

fn from((msb, lsb): (u64, u64)) -> Self

Converts to this type from the input type.

impl From<Ulid> for [u8; 16]

fn from(ulid: Ulid) -> Self

Converts to this type from the input type.

impl From<Ulid> for (u64, u64)

fn from(ulid: Ulid) -> (u64, u64)

Converts to this type from the input type.

impl From<Ulid> for String

fn from(ulid: Ulid) -> String

Converts to this type from the input type.

impl From<Ulid> for u128

fn from(ulid: Ulid) -> u128

Converts to this type from the input type.

impl From<u128> for Ulid

fn from(value: u128) -> Ulid

Converts to this type from the input type.

impl FromStr for Ulid

type Err = DecodeError

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 TryFrom<&str> for Ulid

type Error = DecodeError

The type returned in the event of a conversion error.

fn try_from(value: &str) -> Result<Self, Self::Error>

Performs the conversion.

impl Copy for Ulid

impl Eq for Ulid

impl StructuralPartialEq for Ulid