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.

Tuple Fields

0: u128

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::prelude::*;
use ulid::Ulid;

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

pub fn from_datetime(datetime: OffsetDateTime) -> Ulid

Creates a new Ulid with the given datetime

This can be useful when migrating data to use Ulid identifiers

Example

use time::OffsetDateTime;
use ulid::Ulid;

let ulid = Ulid::from_datetime(OffsetDateTime::now_utc());

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

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

Example

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

let mut rng = StdRng::from_entropy();
let ulid = Ulid::from_datetime_with_source(OffsetDateTime::now_utc(), &mut rng);

pub fn datetime(&self) -> OffsetDateTime

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

Example

use time::Duration;
use time::OffsetDateTime;
use ulid::Ulid;

let dt = OffsetDateTime::now_utc();
let ulid = Ulid::from_datetime(dt);

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

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 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 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 ::time::OffsetDateTime;
use ulid::Ulid;

let dt = OffsetDateTime::now_utc();
let ulid = Ulid::from_datetime(dt);

assert_eq!(ulid.timestamp_ms(), (dt.unix_timestamp_nanos() / 1_000_000) as u64);

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>

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 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

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<'de> Deserialize<'de> for Ulid

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

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 From<(u64, u64)> for Ulid

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

Converts to this type from the input type.

impl From<Ulid> for Uuid

fn from(ulid: Ulid) -> Self

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 (u64, u64)

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

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

fn from(uuid: Uuid) -> Self

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, 

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

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

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: &Rhs) -> bool

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

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

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

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

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

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

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

impl Serialize for Ulid

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

Serialize this value into the given Serde serializer.

impl Copy for Ulid

impl Eq for Ulid

impl StructuralEq for Ulid

impl StructuralPartialEq for Ulid