Struct Builder

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

A builder for creating a UUID.

This type is useful if you need to mutate individual fields of a Uuid while constructing it. Since the Uuid type is Copy, it doesn’t offer any methods to mutate in place. They live on the Builder instead.

The Builder type also always exposes APIs to construct Uuids for any version without needing crate features or additional dependencies. It’s a lower-level API than the methods on Uuid.

Examples

Creating a version 4 UUID from externally generated random bytes:

let random_bytes = rng();

let uuid = Builder::from_random_bytes(random_bytes).into_uuid();

assert_eq!(Some(Version::Random), uuid.get_version());
assert_eq!(Variant::RFC4122, uuid.get_variant());

Implementations

impl Builder

pub const fn from_bytes(b: Bytes) -> Self

Creates a Builder using the supplied bytes.

Examples

Basic usage:

let bytes = [
    0xa1, 0xa2, 0xa3, 0xa4,
    0xb1, 0xb2,
    0xc1, 0xc2,
    0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
];

let uuid = Builder::from_bytes(bytes).into_uuid();

assert_eq!(
    "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
    uuid.hyphenated().to_string(),
);

pub const fn from_bytes_le(b: Bytes) -> Self

Creates a Builder using the supplied bytes in little endian order.

The individual fields encoded in the buffer will be flipped.

Examples

Basic usage:

let bytes = [
    0xa1, 0xa2, 0xa3, 0xa4,
    0xb1, 0xb2,
    0xc1, 0xc2,
    0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
];

let uuid = Builder::from_bytes_le(bytes).into_uuid();

assert_eq!(
    "a4a3a2a1-b2b1-c2c1-d1d2-d3d4d5d6d7d8",
    uuid.hyphenated().to_string(),
);

pub const fn from_gregorian_timestamp( ticks: u64, counter: u16, node_id: &[u8; 6], ) -> Self

Creates a Builder for a version 1 UUID using the supplied timestamp, counter, and node ID.

pub const fn from_md5_bytes(md5_bytes: Bytes) -> Self

Creates a Builder for a version 3 UUID using the supplied MD5 hashed bytes.

pub const fn from_random_bytes(random_bytes: Bytes) -> Self

Creates a Builder for a version 4 UUID using the supplied random bytes.

This method assumes the bytes are already sufficiently random, it will only set the appropriate bits for the UUID version and variant.

Examples

let random_bytes = rng();
let uuid = Builder::from_random_bytes(random_bytes).into_uuid();

assert_eq!(Some(Version::Random), uuid.get_version());
assert_eq!(Variant::RFC4122, uuid.get_variant());

pub const fn from_sha1_bytes(sha1_bytes: Bytes) -> Self

Creates a Builder for a version 5 UUID using the supplied SHA-1 hashed bytes.

This method assumes the bytes are already a SHA-1 hash, it will only set the appropriate bits for the UUID version and variant.

pub const fn from_sorted_gregorian_timestamp( ticks: u64, counter: u16, node_id: &[u8; 6], ) -> Self

Creates a Builder for a version 6 UUID using the supplied timestamp, counter, and node ID.

This method will encode the ticks, counter, and node ID in a sortable UUID.

pub const fn from_unix_timestamp_millis( millis: u64, counter_random_bytes: &[u8; 10], ) -> Self

Creates a Builder for a version 7 UUID using the supplied Unix timestamp and counter bytes.

This method will set the variant field within the counter bytes without attempting to shift the data around it. Callers using the counter as a monotonic value should be careful not to store significant data in the 2 least significant bits of the 3rd byte.

Examples

Creating a UUID using the current system timestamp:

use std::time::{Duration, SystemTime};
let ts = SystemTime::now().duration_since(SystemTime::UNIX_EPOCH)?;

let random_bytes = rng();

let uuid = Builder::from_unix_timestamp_millis(ts.as_millis().try_into()?, &random_bytes).into_uuid();

assert_eq!(Some(Version::SortRand), uuid.get_version());
assert_eq!(Variant::RFC4122, uuid.get_variant());

pub const fn from_custom_bytes(custom_bytes: Bytes) -> Self

Creates a Builder for a version 8 UUID using the supplied user-defined bytes.

This method won’t interpret the given bytes in any way, except to set the appropriate bits for the UUID version and variant.

pub fn from_slice(b: &[u8]) -> Result<Self, Error>

Creates a Builder using the supplied bytes.

Errors

This function will return an error if b has any length other than 16.

Examples

Basic usage:

let bytes = [
    0xa1, 0xa2, 0xa3, 0xa4,
    0xb1, 0xb2,
    0xc1, 0xc2,
    0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
];

let uuid = Builder::from_slice(&bytes)?.into_uuid();

assert_eq!(
    "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
    uuid.hyphenated().to_string(),
);

pub fn from_slice_le(b: &[u8]) -> Result<Self, Error>

Creates a Builder using the supplied bytes in little endian order.

The individual fields encoded in the buffer will be flipped.

Errors

This function will return an error if b has any length other than 16.

Examples

Basic usage:

let bytes = [
    0xa1, 0xa2, 0xa3, 0xa4,
    0xb1, 0xb2,
    0xc1, 0xc2,
    0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
];

let uuid = Builder::from_slice_le(&bytes)?.into_uuid();

assert_eq!(
    "a4a3a2a1-b2b1-c2c1-d1d2-d3d4d5d6d7d8",
    uuid.hyphenated().to_string(),
);

pub const fn from_fields(d1: u32, d2: u16, d3: u16, d4: &[u8; 8]) -> Self

Creates a Builder from four field values.

Examples

Basic usage:

let d1 = 0xa1a2a3a4;
let d2 = 0xb1b2;
let d3 = 0xc1c2;
let d4 = [0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8];

let uuid = Builder::from_fields(d1, d2, d3, &d4).into_uuid();

assert_eq!(
    uuid.hyphenated().to_string(),
    "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8"
);

pub const fn from_fields_le(d1: u32, d2: u16, d3: u16, d4: &[u8; 8]) -> Self

Creates a Builder from four field values.

Examples

Basic usage:

let d1 = 0xa1a2a3a4;
let d2 = 0xb1b2;
let d3 = 0xc1c2;
let d4 = [0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8];

let uuid = Builder::from_fields_le(d1, d2, d3, &d4).into_uuid();

assert_eq!(
    uuid.hyphenated().to_string(),
    "a4a3a2a1-b2b1-c2c1-d1d2-d3d4d5d6d7d8"
);

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

Creates a Builder from a 128bit value.

Examples

Basic usage:

let v = 0xa1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8u128;

let uuid = Builder::from_u128(v).into_uuid();

assert_eq!(
    "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
    uuid.hyphenated().to_string(),
);

pub const fn from_u128_le(v: u128) -> Self

Creates a UUID from a 128bit value in little-endian order.

Examples

Basic usage:

let v = 0xa1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8u128;

let uuid = Builder::from_u128_le(v).into_uuid();

assert_eq!(
    "d8d7d6d5-d4d3-d2d1-c2c1-b2b1a4a3a2a1",
    uuid.hyphenated().to_string(),
);

pub const fn nil() -> Self

Creates a Builder with an initial Uuid::nil.

Examples

Basic usage:

let uuid = Builder::nil().into_uuid();

assert_eq!(
    "00000000-0000-0000-0000-000000000000",
    uuid.hyphenated().to_string(),
);

pub fn set_variant(&mut self, v: Variant) -> &mut Self

Specifies the variant of the UUID.

pub const fn with_variant(self, v: Variant) -> Self

Specifies the variant of the UUID.

pub fn set_version(&mut self, v: Version) -> &mut Self

Specifies the version number of the UUID.

pub const fn with_version(self, v: Version) -> Self

Specifies the version number of the UUID.

pub const fn as_uuid(&self) -> &Uuid

Get a reference to the underlying Uuid.

Examples

Basic usage:

let builder = Builder::nil();

let uuid1 = builder.as_uuid();
let uuid2 = builder.as_uuid();

assert_eq!(uuid1, uuid2);

pub const fn into_uuid(self) -> Uuid

Convert the builder into a Uuid.

Examples

Basic usage:

let uuid = Builder::nil().into_uuid();

assert_eq!(
    uuid.hyphenated().to_string(),
    "00000000-0000-0000-0000-000000000000"
);

Trait Implementations

impl Debug for Builder

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

Formats the value using the given formatter.