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 fn new_v4() -> Self

Creates a new, random UUID v4 of this type.

pub fn new_v7(ts: Timestamp) -> Self

Creates a new, random UUID v7 of this type.

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 is_nil(&self) -> bool

Returns true if the UUID is nil (all zeros).

pub const fn is_max(&self) -> bool

Returns true if the UUID is the max value (all ones).

pub fn as_fields(&self) -> (u32, u16, u16, &[u8; 8])

Returns the four field values of the UUID.

These values can be passed to Self::from_fields to reconstruct the original UUID. The first field represents the initial eight hex digits as a big-endian u32. The second and third fields represent subsequent hex digit groups as u16 values. The final field contains the last two groups of hex digits as an 8-byte array.

Examples

let uuid: TypedUuid<ExampleKind> =
    "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8".parse().unwrap();

assert_eq!(
    uuid.as_fields(),
    (
        0xa1a2a3a4,
        0xb1b2,
        0xc1c2,
        &[0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8],
    )
);

pub fn to_fields_le(&self) -> (u32, u16, u16, &[u8; 8])

Returns the four field values in little-endian order.

The bytes within integer fields are converted from 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.

Examples

let uuid: TypedUuid<ExampleKind> =
    "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8".parse().unwrap();

assert_eq!(
    uuid.to_fields_le(),
    (
        0xa4a3a2a1,
        0xb2b1,
        0xc2c1,
        &[0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8],
    )
);

pub const fn as_u128(&self) -> u128

Returns a 128-bit value containing the UUID bytes.

Examples

let uuid: TypedUuid<ExampleKind> =
    "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8".parse().unwrap();

assert_eq!(
    uuid.as_u128(),
    0xa1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8u128,
);

pub fn to_u128_le(&self) -> u128

Returns a 128-bit little-endian value.

The bytes in the u128 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.

Note that this will produce a different result than Self::to_fields_le, because the entire UUID is reversed, rather than reversing the individual fields in-place.

Examples

let uuid: TypedUuid<ExampleKind> =
    "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8".parse().unwrap();

assert_eq!(
    uuid.to_u128_le(),
    0xd8d7d6d5d4d3d2d1c2c1b2b1a4a3a2a1u128,
);

pub const fn as_u64_pair(&self) -> (u64, u64)

Returns two 64-bit values representing the UUID.

The first u64 contains the most significant 64 bits; the second contains the least significant bits.

Examples

let uuid: TypedUuid<ExampleKind> =
    "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8".parse().unwrap();

assert_eq!(
    uuid.as_u64_pair(),
    (0xa1a2a3a4b1b2c1c2, 0xd1d2d3d4d5d6d7d8),
);

pub const fn as_bytes(&self) -> &Bytes

Returns a slice of 16 octets containing the value.

This method borrows the underlying byte value of the UUID.

Examples

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

let uuid = TypedUuid::<ExampleKind>::from_bytes(bytes);
let bytes2 = uuid.as_bytes();

assert_eq!(&bytes, bytes2);

pub const fn into_bytes(self) -> Bytes

Consumes self and returns the underlying byte value of the UUID.

Examples

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

let uuid = TypedUuid::<ExampleKind>::from_bytes(bytes);

assert_eq!(bytes, uuid.into_bytes());

pub fn to_bytes_le(&self) -> Bytes

Returns the bytes of the UUID in little-endian order.

The bytes will be flipped to convert into little-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.

Examples

let uuid: TypedUuid<ExampleKind> =
    "a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8".parse().unwrap();

assert_eq!(
    uuid.to_bytes_le(),
    [
        0xa4, 0xa3, 0xa2, 0xa1,
        0xb2, 0xb1,
        0xc2, 0xc1,
        0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
    ]
);

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> Arbitrary for TypedUuid<T>

where T: TypedUuidKind,

Generates random TypedUuid<T> instances.

Currently, this always returns a version 4 UUID. Support for other kinds of UUIDs might be added via Self::Parameters in the future.

type Parameters = TypedUuidParams

The type of parameters that arbitrary_with accepts for configuration of the generated Strategy. Parameters must implement Default.

type Strategy = BoxedStrategy<TypedUuid<T>>

The type of Strategy used to generate values of type Self.

fn arbitrary_with(_args: Self::Parameters) -> Self::Strategy

Generates a Strategy for producing arbitrary values of type the implementing type (Self). The strategy is passed the arguments given in args.

fn arbitrary() -> Self::Strategy

Generates a Strategy for producing arbitrary values of type the implementing type (Self).

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 duplicate 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<'de, T: TypedUuidKind> Deserialize<'de> for TypedUuid<T>

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

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> JsonSchema for TypedUuid<T>

where T: TypedUuidKind + JsonSchema,

Implements JsonSchema for TypedUuid<T>, if T implements JsonSchema.

• schema_name is set to "TypedUuidFor", concatenated by the schema name of T.
• schema_id is set to format!("newtype_uuid::TypedUuid<{}>", T::schema_id()).
• json_schema is the same as the one for Uuid, with the x-rust-type extension to allow automatic replacement in typify and progenitor.

fn schema_name() -> String

The name of the generated JSON Schema.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn is_referenceable() -> bool

Whether JSON Schemas generated for this type should be re-used where possible using the $ref keyword.

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> Serialize for TypedUuid<T>

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

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

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