Struct ZeroableUlid 

pub struct ZeroableUlid(/* private fields */);

A ULID with even the value zero allowed.

This flavour of ULID can be zero. Sometimes ULIDs with zero value are used to signal the absence of a ULID. While this works, it could be considered a bad practice. In Rust an Option<Ulid> is a more idiomatic way to handle ULIDs with zero value. However, if you need to parse zero value ULIDs, this type helps.

Example

use mr_ulid::ZeroableUlid;

let s = "00000000000000000000000000";

assert!(s.parse::<ZeroableUlid>().is_ok());

Implementations

impl ZeroableUlid

pub const MIN: Self

Minimum allowed ZeroableUlid

The smallest value for ZeroableUlid is 0, because zero is explicitly allowed.

Example

use mr_ulid::ZeroableUlid;

assert_eq!(ZeroableUlid::MIN.to_u128(), 0);

pub const MAX: Self

Maximum allowed ZeroableUlid

The largest value for ZeroableUlid is u128::MAX.

Example

use mr_ulid::ZeroableUlid;

assert_eq!(ZeroableUlid::MAX.to_u128(), u128::MAX);

pub const fn zeroed() -> Self

Creates a ZeroableUlid with the value zero.

Chances are high, you’re looking for method ZeroableUlid::new(), which creates unique ZeroableUlids which are never zero.

Example

use mr_ulid::ZeroableUlid;

let u1 = ZeroableUlid::zeroed();
let u2 = ZeroableUlid::zeroed();

assert!(u1 == u2); // They are not unique!

assert!(u1.is_zero()); // They are both zero!
assert!(u2.is_zero());

pub fn new() -> Self

Generates a new unique ZeroableUlid.

The generated ZeroableUlids are guaranteed to be unique and monotonically increasing and never zero.

A lot of care is taken, that the ZeroableUlids cannot overflow. You can create as many ZeroableUlids as you like, and they will always be unique and strict monotonically increasing.

Panics

With the standard entropy source (STANDARD_ENTROPY_SOURCE), this method will panic if the system date is somewhere after the year 10889 or before the Unix epoch (year 1970).

Example

use mr_ulid::ZeroableUlid;

let u1 = ZeroableUlid::new();
let u2 = ZeroableUlid::new();

assert!(u1 != u2);
assert!(u1 < u2);

let t1 = u1.timestamp();
let t2 = u2.timestamp();

let r1 = u1.randomness();
let r2 = u2.randomness();

assert!((t1 < t2) || (t1 == t2 && r1 < r2));

pub const fn is_zero(self) -> bool

Tests if a ZeroableUlid is zero.

When a ZeroableUlid is zero, it returns true. Otherwise, it returns false.

Example

use mr_ulid::ZeroableUlid;

let u1 = ZeroableUlid::zeroed();
let u2 = ZeroableUlid::new();

assert!(u1.is_zero());
assert!(!u2.is_zero());

pub const fn timestamp(self) -> u64

Returns the timestamp part of a ZeroableUlid.

The timestamp is measured in milliseconds since the Unix epoch (1. January 1970). ULID timestamps are limited to 48 bits.

Example

use mr_ulid::ZeroableUlid;

let u = ZeroableUlid::new();

assert!(u.timestamp() > 1704067200000); // 1st January 2024

pub const fn randomness(self) -> u128

Returns the random part of a ZeroableUlid.

The randomness of a ZeroableUlid is limited to 80 bits.

Example

use mr_ulid::ZeroableUlid;

let u = ZeroableUlid::new();

assert!(u.randomness() < (1<<80));

pub fn datetime(self) -> SystemTime

Returns the timestamp part of a ZeroableUlid as a SystemTime.

Panics

In Rust the allowed range for SystemTime is not defined. So this method may panic if the timestamp of the ZeroableUlid cannot represented with SystemTime. On most common systems that will not happen.

For a variant which never panics, see ZeroableUlid::try_datetime.

Example

use std::time::SystemTime;
use mr_ulid::ZeroableUlid;

let u = ZeroableUlid::new();

assert!(u.datetime() <= SystemTime::now());

pub const fn to_ulid(self) -> Option<Ulid>

Converts this ZeroableUlid to a Ulid.

When the ZeroableUlid is zero, None is returned.

Example

use mr_ulid::ZeroableUlid;

let u1 = ZeroableUlid::new();

assert!(!u1.is_zero());
assert!(u1.to_ulid().is_some());

let u2 = ZeroableUlid::zeroed(); // Creates a ZeroableUlid with value zero

assert!(u2.is_zero());
assert!(u2.to_ulid().is_none());

pub const fn from_ulid(ulid: Ulid) -> Self

Creates a ZeroableUlid from a Ulid.

This method always succeeds, as every Ulid is a valid ZeroableUlid.

Example

use mr_ulid::{Ulid, ZeroableUlid};

let u1 = Ulid::new();
let u2 = ZeroableUlid::from_ulid(u1);

assert!(!u2.is_zero());
assert_eq!(u1.to_u128(), u2.to_u128());

pub const fn to_parts(self) -> (u64, u128)

Returns the timestamp and randomness parts of a ZeroableUlid as a pair.

Example

use mr_ulid::ZeroableUlid;

let u = ZeroableUlid::new();
let (timestamp, randomness) = u.to_parts();

assert_eq!(timestamp, u.timestamp());
assert_eq!(randomness, u.randomness());

pub const fn from_parts(timestamp: u64, randomness: u128) -> Result<Self, Error>

Creates a ZeroableUlid from a timestamp and randomness parts.

Errors

Will fail if the timestamp (48 bits) or randomness (80 bits) are out of range.

Example

use mr_ulid::ZeroableUlid;

let u1 = ZeroableUlid::zeroed();
let (timestamp, randomness) = u1.to_parts();
let u2 = ZeroableUlid::from_parts(timestamp, randomness)?;

assert_eq!(u1, u2);

assert_eq!(ZeroableUlid::from_parts(0, 0)?, ZeroableUlid::zeroed());

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

Converts a ZeroableUlid into binary bytes

The bytes are in network byte order (big endian).

Example

use mr_ulid::ZeroableUlid;

let u: ZeroableUlid = "01JB05JV6H9ZA2YQ6X3K1DAGVA".parse()?;

assert_eq!(u.to_bytes(), [1, 146, 192, 89, 108, 209, 79, 212, 47, 92, 221, 28, 194, 213, 67, 106]);

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

Creates a ZeroableUlid from a binary byte array.

The byte array must be in network byte order (big endian).

Example

use mr_ulid::ZeroableUlid;

let bytes: [u8; 16] = [1, 146, 192, 89, 108, 209, 79, 212, 47, 92, 221, 28, 194, 213, 67, 106];
let u = ZeroableUlid::from_bytes(bytes);

assert_eq!(u.to_string(), "01JB05JV6H9ZA2YQ6X3K1DAGVA");

pub const fn to_u128(self) -> u128

Converts a ZeroableUlid into a u128 integer.

Example

use mr_ulid::ZeroableUlid;

let u: ZeroableUlid = "01JB07NQ643XZXVHZDY0JNYR02".parse()?;

assert_eq!(u.to_u128(), 2091207293934528941058695985186693122);

pub const fn from_u128(n: u128) -> Self

Creates a ZeroableUlid from a u128 integer.

Example

use mr_ulid::ZeroableUlid;

let n = 2091207293934528941058695985186693122_u128;
let u = ZeroableUlid::from_u128(n);

assert_eq!(u.to_string(), "01JB07NQ643XZXVHZDY0JNYR02");

pub fn try_new() -> Option<Self>

Generates a new ZeroableUlid and never panics.

This is a variant of ZeroableUlid::new() which never panics (with the STANDARD_ENTROPY_SOURCE).

In the case of problems with the ULID-generator, this function returns None.

Example

use mr_ulid::ZeroableUlid;

let u1 = ZeroableUlid::try_new()?;
let u2 = ZeroableUlid::try_new()?;

assert!(u1 != u2);
assert!(u1.timestamp() <= u2.timestamp());

pub fn try_datetime(self) -> Option<SystemTime>

Returns the timestamp part of a ZeroableUlid as a SystemTime and never panics.

This is a variant of ZeroableUlid::datetime() which never panics.

In the case that the timestamp of a ZeroableUlid cannot be encoded in a SystemTime, this method returns None.

Example

use std::time::SystemTime;
use mr_ulid::ZeroableUlid;

let u = ZeroableUlid::new();

let datetime: Option<SystemTime> = u.try_datetime();

pub fn try_to_string(self) -> Option<String>

Return the string representation of a ZeroableUlid and never panics.

While the blanket implementation of std::string::ToString for std::fmt::Display may panic, this method is guaranteed to never panic, but returns None if the string representation cannot be created. One reason this can happen is if the allocation of memory for the string fails.

pub const unsafe fn from_parts_unchecked( timestamp: u64, randomness: u128, ) -> Self

Creates a ZeroableUlid from timestamp and randomness parts without checking.

This results in undefined behaviour if timestamp or randomness parts are too large.

Safety

• Timestamp must be less than 2⁴⁸.
• Randomness must be less than 2⁸⁰.

Trait Implementations

impl Clone for ZeroableUlid

fn clone(&self) -> ZeroableUlid

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ZeroableUlid

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

Formats the value using the given formatter.

impl Default for ZeroableUlid

fn default() -> ZeroableUlid

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for ZeroableUlid

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

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for ZeroableUlid

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

Formats the value using the given formatter.

impl From<&[u8; 16]> for ZeroableUlid

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

Converts to this type from the input type.

impl From<[u8; 16]> for ZeroableUlid

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

Converts to this type from the input type.

impl From<Ulid> for ZeroableUlid

fn from(non_zero: Ulid) -> Self

Converts to this type from the input type.

impl From<ZeroableUlid> for [u8; 16]

fn from(ulid: ZeroableUlid) -> Self

Converts to this type from the input type.

impl From<ZeroableUlid> for u128

fn from(ulid: ZeroableUlid) -> Self

Converts to this type from the input type.

impl From<u128> for ZeroableUlid

fn from(n: u128) -> Self

Converts to this type from the input type.

impl FromStr for ZeroableUlid

type Err = Error

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 ZeroableUlid

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 ZeroableUlid

fn cmp(&self, other: &ZeroableUlid) -> 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 ZeroableUlid

fn eq(&self, other: &ZeroableUlid) -> 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 ZeroableUlid

fn partial_cmp(&self, other: &ZeroableUlid) -> 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 Serialize for ZeroableUlid

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

where S: Serializer,

Serialize this value into the given Serde serializer.

impl TryFrom<&[u8]> for ZeroableUlid

type Error = Error

The type returned in the event of a conversion error.

fn try_from(bytes: &[u8]) -> Result<Self, Self::Error>

Performs the conversion.

impl TryFrom<ZeroableUlid> for Ulid

type Error = Error

The type returned in the event of a conversion error.

fn try_from(zeroable: ZeroableUlid) -> Result<Self, Self::Error>

Performs the conversion.

impl Copy for ZeroableUlid

impl Eq for ZeroableUlid

impl StructuralPartialEq for ZeroableUlid