Struct TypedUuid

pub struct TypedUuid<T: TypedUuidKind> { /* private fields */ }

A UUID with type-level information about what it’s used for.

For more, see the library documentation.

Implementations

impl<T: TypedUuidKind> TypedUuid<T>

pub const fn nil() -> Self

The ‘nil UUID’ (all zeros).

The nil UUID is a special form of UUID that is specified to have all 128 bits set to zero.

References

• Nil UUID in RFC4122

pub const fn max() -> Self

The ‘max UUID’ (all ones).

The max UUID is a special form of UUID that is specified to have all 128 bits set to one.

References

• Max UUID in Draft RFC: New UUID Formats, Version 4

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

Creates a UUID from four field values.

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

Creates a UUID from four field values in little-endian order.

The bytes in the d1, d2 and d3 fields will be flipped to convert into big-endian order. This is based on the endianness of the UUID, rather than the target environment so bytes will be flipped on both big and little endian machines.

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

Creates a UUID from a 128bit value.

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

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

The entire value will be flipped to convert into big-endian order. This is based on the endianness of the UUID, rather than the target environment so bytes will be flipped on both big and little endian machines.

pub const fn from_u64_pair(d1: u64, d2: u64) -> Self

Creates a UUID from two 64bit values.

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

Creates a UUID using the supplied bytes.

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

Creates a UUID using the supplied bytes in little-endian order.

The individual fields encoded in the buffer will be flipped.

pub const fn get_version_num(&self) -> usize

Returns the version number of the UUID.

This represents the algorithm used to generate the value. This method is the future-proof alternative to Self::get_version.

References

• Version Field in RFC 9562

pub fn get_version(&self) -> Option<Version>

Returns the version of the UUID.

This represents the algorithm used to generate the value. If the version field doesn’t contain a recognized version then None is returned. If you’re trying to read the version for a future extension you can also use Uuid::get_version_num to unconditionally return a number. Future extensions may start to return Some once they’re standardized and supported.

References

• Version Field in RFC 9562

pub const fn upcast<U: TypedUuidKind>(self) -> TypedUuid<U>

where T: Into<U>,

Converts the UUID to one with looser semantics.

By default, UUID kinds are considered independent, and conversions between them must happen via the GenericUuid interface. But in some cases, there may be a relationship between two different UUID kinds, and you may wish to easily convert UUIDs from one kind to another.

Typically, a conversion from TypedUuid<T> to TypedUuid<U> is most useful when T’s semantics are a superset of U’s, or in other words, when every TypedUuid<T> is logically also a TypedUuid<U>.

For instance:

• Imagine you have TypedUuidKinds for different types of database connections, where DbConnKind is the general type and PgConnKind is a specific kind for Postgres.
• Since every Postgres connection is also a database connection, a cast from TypedUuid<PgConnKind> to TypedUuid<DbConnKind> makes sense.
• The inverse cast would not make sense, as a database connection may not necessarily be a Postgres connection.

This interface provides an alternative, safer way to perform this conversion. Indicate your intention to allow a conversion between kinds by implementing From<T> for U, as shown in the example below.

Examples

use newtype_uuid::{TypedUuid, TypedUuidKind, TypedUuidTag};

// Let's say that these UUIDs represent repositories for different
// version control systems, such that you have a generic RepoKind:
pub enum RepoKind {}
impl TypedUuidKind for RepoKind {
    fn tag() -> TypedUuidTag {
        const TAG: TypedUuidTag = TypedUuidTag::new("repo");
        TAG
    }
}

// You also have more specific kinds:
pub enum GitRepoKind {}
impl TypedUuidKind for GitRepoKind {
    fn tag() -> TypedUuidTag {
        const TAG: TypedUuidTag = TypedUuidTag::new("git_repo");
        TAG
    }
}
// (and HgRepoKind, JujutsuRepoKind, etc...)

// First, define a `From` impl. This impl indicates your desire
// to convert from one kind to another.
impl From<GitRepoKind> for RepoKind {
    fn from(value: GitRepoKind) -> Self {
        match value {}
    }
}

// Now you can convert between them:
let git_uuid: TypedUuid<GitRepoKind> =
    TypedUuid::from_u128(0xe9245204_34ea_4ca7_a1c6_2e94fa49df61);
let repo_uuid: TypedUuid<RepoKind> = git_uuid.upcast();

Trait Implementations

impl<T: TypedUuidKind> AsRef<[u8]> for TypedUuid<T>

fn as_ref(&self) -> &[u8]

Converts this type into a shared reference of the (usually inferred) input type.

impl<T: TypedUuidKind> Clone for TypedUuid<T>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: TypedUuidKind> Debug for TypedUuid<T>

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

Formats the value using the given formatter.

impl<T: TypedUuidKind> Default for TypedUuid<T>

fn default() -> Self

Returns the “default value” for a type.

impl<T: TypedUuidKind> Display for TypedUuid<T>

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

Formats the value using the given formatter.

impl<T: TypedUuidKind> From<TypedUuid<T>> for Vec<u8>

fn from(typed_uuid: TypedUuid<T>) -> Self

Converts to this type from the input type.

impl<T: TypedUuidKind> FromStr for TypedUuid<T>

type Err = ParseError

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<T: TypedUuidKind> GenericUuid for TypedUuid<T>

fn from_untyped_uuid(uuid: Uuid) -> Self

Creates a new instance of Self from an untyped Uuid.

fn into_untyped_uuid(self) -> Uuid

Converts self into an untyped Uuid.

fn as_untyped_uuid(&self) -> &Uuid

Returns the inner Uuid.

impl<T: TypedUuidKind> Hash for TypedUuid<T>

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<T: TypedUuidKind> Ord for TypedUuid<T>

fn cmp(&self, other: &Self) -> 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<T: TypedUuidKind> PartialEq for TypedUuid<T>

fn eq(&self, other: &Self) -> 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<T: TypedUuidKind> PartialOrd for TypedUuid<T>

fn partial_cmp(&self, other: &Self) -> 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<T: TypedUuidKind> Copy for TypedUuid<T>

impl<T: TypedUuidKind> Eq for TypedUuid<T>