Struct rusty_ulid::Ulid

pub struct Ulid { /* fields omitted */ }

The ULID data type.

Methods

impl Ulid

pub fn generate() -> Ulid

Creates a new ULID.

Examples

use rusty_ulid::Ulid;

let ulid = Ulid::generate();

assert_ne!(0, ulid.timestamp());

let ulid_string = ulid.to_string();
// every ulid has exactly 26 characters
assert_eq!(ulid_string.len(), 26);

Panics

Panics if called after +10889-08-02T05:31:50.655Z.

pub fn next_monotonic(previous_ulid: Ulid) -> Ulid

Creates the next monotonic ULID for the given previous_ulid.

If the random part of previous_ulid would overflow, this function returns a ULID with the random part set to zero.

Examples

use rusty_ulid::Ulid;

let previous_ulid = Ulid::from(0);
let ulid = Ulid::next_monotonic(previous_ulid);

assert_ne!(0, ulid.timestamp());

Panics

Panics if called after +10889-08-02T05:31:50.655Z.

pub fn next_strictly_monotonic(previous_ulid: Ulid) -> Option<Ulid>

Creates the next strictly monotonic ULID for the given previous_ulid.

If the random part of previous_ulid would overflow, this function returns None.

Examples

use rusty_ulid::Ulid;

let previous_ulid = Ulid::from(0);
let ulid = Ulid::next_strictly_monotonic(previous_ulid);

if let Some(ulid) = ulid {
    assert_ne!(0, ulid.timestamp());
}

Panics

Panics if called after +10889-08-02T05:31:50.655Z.

pub fn from_timestamp_with_rng<R>(timestamp: u64, rng: &mut R) -> Ulid where
    R: Rng, 

Creates a new ULID with the given timestamp obtaining randomness from rng.

Examples

use rusty_ulid::Ulid;

let ulid = Ulid::from_timestamp_with_rng(0, &mut rand::thread_rng());

let timestamp = ulid.timestamp();

assert_eq!(timestamp, 0);

Panics

Panics if timestamp is larger than 0xFFFF_FFFF_FFFF.

pub fn next_monotonic_from_timestamp_with_rng<R>(
    previous_ulid: Ulid,
    timestamp: u64,
    rng: &mut R
) -> Ulid where
    R: Rng, 

Creates the next monotonic ULID with the given previous_ulid, timestamp obtaining randomness from rng.

If the random part of previous_ulid would overflow, this function returns a ULID with the random part set to zero.

Examples

use rusty_ulid::Ulid;

let previous_ulid = Ulid::from(0);
let ulid = Ulid::next_monotonic_from_timestamp_with_rng(previous_ulid, 0, &mut rand::thread_rng());

assert_eq!(ulid, Ulid::from(1));

use rusty_ulid::Ulid;

let previous_ulid = Ulid::from(0x0000_0000_0000_FFFF_FFFF_FFFF_FFFF_FFFE);
let ulid = Ulid::next_monotonic_from_timestamp_with_rng(previous_ulid, 0, &mut rand::thread_rng());

assert_eq!(ulid, Ulid::from(0x0000_0000_0000_FFFF_FFFF_FFFF_FFFF_FFFF));

use rusty_ulid::Ulid;

let previous_ulid = Ulid::from(0x0000_0000_0000_FFFF_FFFF_FFFF_FFFF_FFFF);
let ulid = Ulid::next_monotonic_from_timestamp_with_rng(previous_ulid, 0, &mut rand::thread_rng());

// overflow results in zero random part
assert_eq!(ulid, Ulid::from(0));

Panics

Panics if timestamp is larger than 0xFFFF_FFFF_FFFF.

pub fn next_strictly_monotonic_from_timestamp_with_rng<R>(
    previous_ulid: Ulid,
    timestamp: u64,
    rng: &mut R
) -> Option<Ulid> where
    R: Rng, 

Creates the next strictly monotonic ULID with the given previous_ulid, timestamp obtaining randomness from rng.

If the random part of previous_ulid would overflow, this function returns None.

Examples

use rusty_ulid::Ulid;

let previous_ulid = Ulid::from(0);
let ulid = Ulid::next_strictly_monotonic_from_timestamp_with_rng(previous_ulid, 0, &mut rand::thread_rng());

assert_eq!(ulid, Some(Ulid::from(1)));

use rusty_ulid::Ulid;

let previous_ulid = Ulid::from(0x0000_0000_0000_FFFF_FFFF_FFFF_FFFF_FFFE);
let ulid = Ulid::next_strictly_monotonic_from_timestamp_with_rng(previous_ulid, 0, &mut rand::thread_rng());

assert_eq!(ulid, Some(Ulid::from(0x0000_0000_0000_FFFF_FFFF_FFFF_FFFF_FFFF)));

use rusty_ulid::Ulid;

let previous_ulid = Ulid::from(0x0000_0000_0000_FFFF_FFFF_FFFF_FFFF_FFFF);
let ulid = Ulid::next_strictly_monotonic_from_timestamp_with_rng(previous_ulid, 0, &mut rand::thread_rng());

// overflow results in None
assert_eq!(ulid, None);

Panics

Panics if timestamp is larger than 0xFFFF_FFFF_FFFF.

pub fn timestamp(&self) -> u64

Returns the timestamp of this ULID as number of non-leap milliseconds since January 1, 1970 0:00:00 UTC (aka "UNIX timestamp").

Examples

use rusty_ulid::Ulid;
use std::str::FromStr;

let ulid = Ulid::from_str("01CAH7NXGRDJNE9B1NY7PQGYV7")?;
let timestamp = ulid.timestamp();

assert_eq!(timestamp, 1523144390168);

pub fn datetime(&self) -> DateTime<Utc>

Returns the timestamp of this ULID as a DateTime<Utc>.

Examples

use rusty_ulid::Ulid;
use std::str::FromStr;

let ulid = Ulid::from_str("01CAH7NXGRDJNE9B1NY7PQGYV7")?;
let datetime = ulid.datetime();

assert_eq!(datetime.to_string(), "2018-04-07 23:39:50.168 UTC");

pub fn increment(self) -> Ulid

Returns a new ULID with the random part incremented by one.

Overflowing the random part resets it to zero without influencing the timestamp.

Examples

use rusty_ulid::Ulid;

let ulid = Ulid::from(0);
let incremented = ulid.increment();

assert_eq!(incremented, Ulid::from(1));

use rusty_ulid::Ulid;

let ulid = Ulid::from(0x0000_0000_0000_FFFF_FFFF_FFFF_FFFF_FFFE);
let incremented = ulid.increment();

assert_eq!(incremented, Ulid::from(0x0000_0000_0000_FFFF_FFFF_FFFF_FFFF_FFFF));

use rusty_ulid::Ulid;

let ulid = Ulid::from(0x0000_0000_0000_FFFF_FFFF_FFFF_FFFF_FFFF);
let incremented = ulid.increment();

assert_eq!(incremented, Ulid::from(0));

pub fn to_string(&self) -> String

Returns the string representaton of this ULID.

Examples

use rusty_ulid::Ulid;

let ulid = Ulid::from(0);

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

use rusty_ulid::Ulid;

let ulid = Ulid::from(0xFFFF_FFFF_FFFF_FFFF_FFFF_FFFF_FFFF_FFFF);

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

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

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

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

impl From<[u8; 16]> for Ulid

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

Examples

use rusty_ulid::Ulid;

let bytes: [u8; 16] = [
    0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88,
    0x99, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xF0, 0x0F,
];

let ulid = Ulid::from(bytes);

let expected_ulid = Ulid::from(0x1122_3344_5566_7788_99AA_BBCC_DDEE_F00F);

assert_eq!(ulid, expected_ulid);

use rusty_ulid::Ulid;

let bytes: [u8; 16] = [
    0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88,
    0x99, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xF0, 0x0F,
];

let ulid : Ulid = bytes.into();

let expected_ulid = Ulid::from(0x1122_3344_5566_7788_99AA_BBCC_DDEE_F00F);

assert_eq!(ulid, expected_ulid);

impl From<(u64, u64)> for Ulid

fn from(value: (u64, u64)) -> Self

Examples

use rusty_ulid::Ulid;

let tuple = (0x1122_3344_5566_7788, 0x99AA_BBCC_DDEE_F00F);

let ulid = Ulid::from(tuple);

let expected_ulid = Ulid::from(0x1122_3344_5566_7788_99AA_BBCC_DDEE_F00F);

assert_eq!(ulid, expected_ulid);

use rusty_ulid::Ulid;

let tuple = (0x1122_3344_5566_7788, 0x99AA_BBCC_DDEE_F00F);

let ulid : Ulid = tuple.into();

let expected_ulid = Ulid::from(0x1122_3344_5566_7788_99AA_BBCC_DDEE_F00F);

assert_eq!(ulid, expected_ulid);

impl From<Ulid> for [u8; 16]

fn from(ulid: Ulid) -> Self

Examples

use rusty_ulid::Ulid;

let ulid = Ulid::from(0x1122_3344_5566_7788_99AA_BBCC_DDEE_F00F);

let bytes = <[u8; 16]>::from(ulid);

let expected_bytes: [u8; 16] = [
    0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88,
    0x99, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xF0, 0x0F,
];

assert_eq!(bytes, expected_bytes);

use rusty_ulid::Ulid;

let ulid = Ulid::from(0x1122_3344_5566_7788_99AA_BBCC_DDEE_F00F);

let bytes: [u8; 16] = ulid.into();

let expected_bytes: [u8; 16] = [
    0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88,
    0x99, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xF0, 0x0F,
];

assert_eq!(bytes, expected_bytes);

impl From<Ulid> for (u64, u64)

fn from(ulid: Ulid) -> Self

Examples

use rusty_ulid::Ulid;

let ulid = Ulid::from(0x1122_3344_5566_7788_99AA_BBCC_DDEE_F00F);

let tuple = <(u64, u64)>::from(ulid);

let expected_tuple = (0x1122_3344_5566_7788, 0x99AA_BBCC_DDEE_F00F);

assert_eq!(tuple, expected_tuple);

use rusty_ulid::Ulid;

let ulid = Ulid::from(0x1122_3344_5566_7788_99AA_BBCC_DDEE_F00F);

let tuple : (u64, u64) = ulid.into();

let expected_tuple = (0x1122_3344_5566_7788, 0x99AA_BBCC_DDEE_F00F);

assert_eq!(tuple, expected_tuple);

impl From<Ulid> for u128

fn from(ulid: Ulid) -> Self

Examples

use rusty_ulid::Ulid;

let ulid = Ulid::from((0x1122_3344_5566_7788, 0x99AA_BBCC_DDEE_F00F));

let value = <u128>::from(ulid);

let expected_value = 0x1122_3344_5566_7788_99AA_BBCC_DDEE_F00F;

assert_eq!(value, expected_value);

use rusty_ulid::Ulid;

let ulid = Ulid::from((0x1122_3344_5566_7788, 0x99AA_BBCC_DDEE_F00F));

let value : u128 = ulid.into();

let expected_value = 0x1122_3344_5566_7788_99AA_BBCC_DDEE_F00F;

assert_eq!(value, expected_value);

impl From<u128> for Ulid

fn from(value: u128) -> Self

Examples

use rusty_ulid::Ulid;

let value = 0x1122_3344_5566_7788_99AA_BBCC_DDEE_F00F;

let ulid = Ulid::from(value);

let expected_ulid = Ulid::from((0x1122_3344_5566_7788, 0x99AA_BBCC_DDEE_F00F));

assert_eq!(ulid, expected_ulid);

use rusty_ulid::Ulid;

let value = 0x1122_3344_5566_7788_99AA_BBCC_DDEE_F00F;

let ulid : Ulid = value.into();

let expected_ulid = Ulid::from((0x1122_3344_5566_7788, 0x99AA_BBCC_DDEE_F00F));

assert_eq!(ulid, expected_ulid);

impl FromStr for Ulid

type Err = DecodingError

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.

#[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 Serialize for Ulid

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

Serialize this value into the given Serde serializer.

impl StructuralEq for Ulid

impl StructuralPartialEq for Ulid

impl<'_> TryFrom<&'_ [u8]> for Ulid

type Error = DecodingError

The type returned in the event of a conversion error.

fn try_from(bytes: &[u8]) -> Result<Ulid, DecodingError>

Returns a ULID for the given slice of bytes or DecodingError::InvalidLength if the slice does not contain exactly 16 bytes.

Examples

use rusty_ulid::Ulid;
use std::convert::TryFrom;
use std::convert::TryInto;

let bytes: [u8; 18] = [
    0x00,
    0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88,
    0x99, 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xF0, 0x0F,
    0x00,
];

let ulid : Ulid = Ulid::try_from(&bytes[1..17])?;

let expected_ulid = Ulid::from(0x1122_3344_5566_7788_99AA_BBCC_DDEE_F00F);

assert_eq!(ulid, expected_ulid);

let ulid : Ulid = (&bytes[1..17]).try_into()?;

let expected_ulid = Ulid::from(0x1122_3344_5566_7788_99AA_BBCC_DDEE_F00F);

assert_eq!(ulid, expected_ulid);

use rusty_ulid::Ulid;
use rusty_ulid::DecodingError;
use std::convert::TryFrom;

let mut bytes: [u8; 17] = [0; 17];
let result = Ulid::try_from(&bytes[0..]);

assert_eq!(result, Err(DecodingError::InvalidLength))

use rusty_ulid::Ulid;
use rusty_ulid::DecodingError;
use std::convert::TryFrom;

let mut bytes: [u8; 15] = [0; 15];
let result = Ulid::try_from(&bytes[0..]);

assert_eq!(result, Err(DecodingError::InvalidLength))