Struct ambient_api::global::Ulid

source ·

pub struct Ulid(pub u128);

Expand description

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§

source §

impl Ulid

source

pub fn new() -> Ulid

Creates a new Ulid with the current time (UTC)

Example

use ulid::Ulid;

let my_ulid = Ulid::new();

source

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

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

source

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

source

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

source

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

source §

impl Ulid

source

pub const TIME_BITS: u8 = 48u8

The number of bits in a Ulid’s time portion

source

pub const RAND_BITS: u8 = 80u8

The number of bits in a Ulid’s random portion

source

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

source

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

source

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

source

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

source

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

source

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

source

pub fn to_string(&self) -> String

Available on crate feature std only.

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

source

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

source

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

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

source

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

source

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§

source §

impl Clone for Ulid

source §

fn clone(&self) -> Ulid

Returns a copy of the value. Read more

1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more

source §

impl Debug for Ulid

source §

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

Formats the value using the given formatter. Read more

source §

impl Default for Ulid

source §

fn default() -> Ulid

Returns the “default value” for a type. Read more

source §

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

source §

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

Deserialize this value from the given Serde deserializer. Read more

source §

impl Display for Ulid

source §

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

Formats the value using the given formatter. Read more

source §