Struct ulid::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.

Implementations

impl Ulid

pub fn new() -> Ulid

Creates a new Ulid with the current time (UTC)

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::FromEntropy;
use rand::rngs::SmallRng;
use ulid::Ulid;

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

pub fn from_datetime<T: TimeZone>(datetime: DateTime<T>) -> Ulid

Creates a new Ulid with the given datetime

This can be useful when migrating data to use Ulid identifiers

Example

use chrono::offset::Utc;
use ulid::Ulid;

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

pub fn from_datetime_with_source<T, R>(
    datetime: DateTime<T>,
    source: &mut R
) -> Ulid where
    T: TimeZone,
    R: Rng, 

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

Example

use chrono::offset::Utc;
use rand::FromEntropy;
use rand::rngs::SmallRng;
use ulid::Ulid;

let mut rng = SmallRng::from_entropy();
let ulid = Ulid::from_datetime_with_source(Utc::now(), &mut rng);

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

Creates a Ulid from a Crockford Base32 encoded string

An EncodingError will be returned when the given string is not formated 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 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 fn datetime(&self) -> DateTime<Utc>

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

Example

use chrono::Duration;
use chrono::offset::Utc;
use ulid::Ulid;

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

assert!((dt - ulid.datetime()) < Duration::milliseconds(1));

pub fn timestamp_ms(&self) -> u64

Gets the timestamp section of this ulid

Example

use chrono::offset::Utc;
use ulid::Ulid;

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

assert_eq!(ulid.timestamp_ms(), dt.timestamp_millis() as u64);

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 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());

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

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

impl From<(u64, u64)> for Ulid

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

Performs the conversion.

impl From<u128> for Ulid

fn from(value: u128) -> Ulid

Performs the conversion.

impl FromStr for Ulid

type Err = EncodingError

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, 

Feeds a slice of this type into the given [Hasher].

impl Into<(u64, u64)> for Ulid

fn into(self) -> (u64, u64)

Performs the conversion.

impl<'a> Into<String> for &'a Ulid

fn into(self) -> String

Performs the conversion.

impl Into<u128> for Ulid

fn into(self) -> u128

Performs the conversion.

impl Ord for Ulid

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

This method returns an [Ordering] between self and other.

#[must_use]fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl PartialEq<Ulid> for Ulid

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl PartialOrd<Ulid> 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: &Ulid) -> bool

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl StructuralEq for Ulid

impl StructuralPartialEq for Ulid