logo

Struct uuid::Uuid

source · [−]
#[repr(transparent)]
pub struct Uuid(_);
Expand description

A Universally Unique Identifier (UUID).

Examples

Parse a UUID given in the simple format and print it as a urn:

let my_uuid = Uuid::parse_str("a1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8")?;

println!("{}", my_uuid.urn());

Create a new random (V4) UUID and print it out in hexadecimal form:

// Note that this requires the `v4` feature enabled in the uuid crate.
let my_uuid = Uuid::new_v4();

println!("{}", my_uuid);

Formatting

A UUID can be formatted in one of a few ways:

  • simple: a1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8.
  • hyphenated: a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8.
  • urn: urn:uuid:A1A2A3A4-B1B2-C1C2-D1D2-D3D4D5D6D7D8.
  • braced: {a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8}.

The default representation when formatting a UUID with Display is hyphenated:

let my_uuid = Uuid::parse_str("a1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8")?;

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

Other formats can be specified using adapter methods on the UUID:

let my_uuid = Uuid::parse_str("a1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8")?;

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

Endianness

The specification for UUIDs encodes the integer fields that make up the value in big-endian order. This crate assumes integer inputs are already in the correct order by default, regardless of the endianness of the environment. Most methods that accept integers have a _le variant (such as from_fields_le) that assumes any integer values will need to have their bytes flipped, regardless of the endianness of the environment.

Most users won’t need to worry about endianness unless they need to operate on individual fields (such as when converting between Microsoft GUIDs). The important things to remember are:

  • The endianness is in terms of the fields of the UUID, not the environment.
  • The endianness is assumed to be big-endian when there’s no _le suffix somewhere.
  • Byte-flipping in _le methods applies to each integer.
  • Endianness roundtrips, so if you create a UUID with from_fields_le you’ll get the same values back out with to_fields_le.

ABI

The Uuid type is always guaranteed to be have the same ABI as Bytes.

Implementations

The ‘nil UUID’.

The nil UUID is a special form of UUID that is specified to have all 128 bits set to zero, as defined in IETF RFC 4122 Section 4.1.7.

Examples

Basic usage:

let uuid = Uuid::nil();

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

Creates a UUID 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 = Uuid::from_fields(d1, d2, d3, &d4);

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

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.

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

let uuid = Uuid::from_fields_le(d1, d2, d3, &d4);

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

Creates a UUID from a 128bit value.

Examples

Basic usage:

let v = 0xa1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8u128;

let uuid = Uuid::from_u128(v);

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

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.

Examples

Basic usage:

let v = 0xa1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8u128;

let uuid = Uuid::from_u128_le(v);

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

Creates a UUID from two 64bit values.

Examples

Basic usage:

let hi = 0xa1a2a3a4b1b2c1c2u64;
let lo = 0xd1d2d3d4d5d6d7d8u64;

let uuid = Uuid::from_u64_pair(hi, lo);

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

Creates a UUID 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 = Uuid::from_slice(&bytes)?;

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

Creates a UUID 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 = Uuid::from_slice_le(&bytes)?;

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

Creates a UUID 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 = Uuid::from_bytes(bytes);

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

Creates a UUID 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 = Uuid::from_bytes_le(bytes);

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

Creates a reference to a UUID from a reference to 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 = Uuid::from_bytes_ref(&bytes);

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

assert!(std::ptr::eq(
    uuid as *const Uuid as *const u8,
    &bytes as *const [u8; 16] as *const u8,
));

Parses a Uuid from a string of hexadecimal digits with optional hyphens.

Any of the formats generated by this module (simple, hyphenated, urn, Microsoft GUID) are supported by this parsing function.

Prefer try_parse unless you need detailed user-facing diagnostics. This method will be eventually deprecated in favor of try_parse.

Examples

Parse a hyphenated UUID:

let uuid = Uuid::parse_str("550e8400-e29b-41d4-a716-446655440000")?;

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

Parses a Uuid from a string of hexadecimal digits with optional hyphens.

This function is similar to parse_str, in fact parse_str shares the same underlying parser. The difference is that if try_parse fails, it won’t generate very useful error messages. The parse_str function will eventually be deprecated in favor or try_parse.

To parse a UUID from a byte stream instead of a UTF8 string, see try_parse_ascii.

Examples

Parse a hyphenated UUID:

let uuid = Uuid::try_parse("550e8400-e29b-41d4-a716-446655440000")?;

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

Parses a Uuid from a string of hexadecimal digits with optional hyphens.

The input is expected to be a string of ASCII characters. This method can be more convenient than try_parse if the UUID is being parsed from a byte stream instead of from a UTF8 string.

Examples

Parse a hyphenated UUID:

let uuid = Uuid::try_parse_ascii(b"550e8400-e29b-41d4-a716-446655440000")?;

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

Get a Hyphenated formatter.

Get a borrowed Hyphenated formatter.

Get a Simple formatter.

Get a borrowed Simple formatter.

Get a Urn formatter.

Get a borrowed Urn formatter.

Get a Braced formatter.

Get a borrowed Braced formatter.

Create a new UUID (version 1) using a time value + sequence + NodeId.

When generating Timestamps using a ClockSequence, this function is only guaranteed to produce unique values if the following conditions hold:

  1. The NodeId is unique for this process,
  2. The Context is shared across all threads which are generating v1 UUIDs,
  3. The ClockSequence implementation reliably returns unique clock sequences (this crate provides Context for this purpose. However you can create your own ClockSequence implementation, if Context does not meet your needs).

The NodeID must be exactly 6 bytes long.

Note that usage of this method requires the v1 feature of this crate to be enabled.

Examples

A UUID can be created from a unix Timestamp with a ClockSequence. RFC4122 requires the clock sequence is seeded with a random value:

let context = Context::new(random_seed());
let ts = Timestamp::from_unix(&context, 1497624119, 1234);

let uuid = Uuid::new_v1(ts, &[1, 2, 3, 4, 5, 6]);

assert_eq!(
    uuid.hyphenated().to_string(),
    "f3b4958c-52a1-11e7-802a-010203040506"
);

The timestamp can also be created manually as per RFC4122:

let context = Context::new(42);
let ts = Timestamp::from_rfc4122(1497624119, 0);

let uuid = Uuid::new_v1(ts, &[1, 2, 3, 4, 5, 6]);

assert_eq!(
    uuid.hyphenated().to_string(),
    "5943ee37-0000-1000-8000-010203040506"
);

Returns an optional Timestamp storing the timestamp and counter portion parsed from a V1 UUID.

Returns None if the supplied UUID is not V1.

The V1 timestamp format defined in RFC4122 specifies a 60-bit integer representing the number of 100-nanosecond intervals since 00:00:00.00, 15 Oct 1582.

Timestamp offers several options for converting the raw RFC4122 value into more commonly-used formats, such as a unix timestamp.

Creates a UUID using a name from a namespace, based on the MD5 hash.

A number of namespaces are available as constants in this crate:

Note that usage of this method requires the v3 feature of this crate to be enabled.

Examples

Generating a MD5 DNS UUID for rust-lang.org:

let uuid = Uuid::new_v3(&Uuid::NAMESPACE_DNS, b"rust-lang.org");

assert_eq!(Some(Version::Md5), uuid.get_version());

Creates a random UUID.

This uses the getrandom crate to utilise the operating system’s RNG as the source of random numbers. If you’d like to use a custom generator, don’t use this method: generate random bytes using your custom generator and pass them to the uuid::Builder::from_random_bytes function instead.

Note that usage of this method requires the v4 feature of this crate to be enabled.

Examples

Basic usage:

let uuid = Uuid::new_v4();

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

Creates a UUID using a name from a namespace, based on the SHA-1 hash.

A number of namespaces are available as constants in this crate:

Note that usage of this method requires the v5 feature of this crate to be enabled.

Examples

Generating a SHA1 DNS UUID for rust-lang.org:

let uuid = Uuid::new_v5(&Uuid::NAMESPACE_DNS, b"rust-lang.org");

assert_eq!(Some(Version::Sha1), uuid.get_version());

UUID namespace for Domain Name System (DNS).

UUID namespace for ISO Object Identifiers (OIDs).

UUID namespace for Uniform Resource Locators (URLs).

UUID namespace for X.500 Distinguished Names (DNs).

Returns the variant of the UUID structure.

This determines the interpretation of the structure of the UUID. This method simply reads the value of the variant byte. It doesn’t validate the rest of the UUID as conforming to that variant.

Examples

Basic usage:

let my_uuid = Uuid::parse_str("02f09a3f-1624-3b1d-8409-44eff7708208")?;

assert_eq!(Variant::RFC4122, my_uuid.get_variant());
References

Returns the version number of the UUID.

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

Examples

Basic usage:

let my_uuid = Uuid::parse_str("02f09a3f-1624-3b1d-8409-44eff7708208")?;

assert_eq!(3, my_uuid.get_version_num());
References

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.

Examples

Basic usage:

let my_uuid = Uuid::parse_str("02f09a3f-1624-3b1d-8409-44eff7708208")?;

assert_eq!(Some(Version::Md5), my_uuid.get_version());
References

Returns the four field values of the UUID.

These values can be passed to the Uuid::from_fields method to get the original Uuid back.

  • The first field value represents the first group of (eight) hex digits, taken as a big-endian u32 value. For V1 UUIDs, this field represents the low 32 bits of the timestamp.
  • The second field value represents the second group of (four) hex digits, taken as a big-endian u16 value. For V1 UUIDs, this field represents the middle 16 bits of the timestamp.
  • The third field value represents the third group of (four) hex digits, taken as a big-endian u16 value. The 4 most significant bits give the UUID version, and for V1 UUIDs, the last 12 bits represent the high 12 bits of the timestamp.
  • The last field value represents the last two groups of four and twelve hex digits, taken in order. The first 1-3 bits of this indicate the UUID variant, and for V1 UUIDs, the next 13-15 bits indicate the clock sequence and the last 48 bits indicate the node ID.
Examples
let uuid = Uuid::nil();

assert_eq!(uuid.as_fields(), (0, 0, 0, &[0u8; 8]));

let uuid = Uuid::parse_str("a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8")?;

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

Returns the four field values of the UUID in little-endian order.

The bytes in the returned integer fields will be 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
use uuid::Uuid;

let uuid = Uuid::parse_str("a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8")?;

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

Returns a 128bit value containing the value.

The bytes in the UUID will be packed directly into a u128.

Examples
let uuid = Uuid::parse_str("a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8")?;

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

Returns a 128bit little-endian value containing the 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 Uuid::to_fields_le, because the entire UUID is reversed, rather than reversing the individual fields in-place.

Examples
let uuid = Uuid::parse_str("a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8")?;

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

Returns two 64bit values containing the value.

The bytes in the UUID will be split into two u64. The first u64 represents the 64 most significant bits, the second one represents the 64 least significant.

Examples
let uuid = Uuid::parse_str("a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8")?;
assert_eq!(
    uuid.as_u64_pair(),
    (0xa1a2a3a4b1b2c1c2, 0xd1d2d3d4d5d6d7d8),
);

Returns a slice of 16 octets containing the value.

This method borrows the underlying byte value of the UUID.

Examples
let bytes1 = [
    0xa1, 0xa2, 0xa3, 0xa4,
    0xb1, 0xb2,
    0xc1, 0xc2,
    0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, 0xd8,
];
let uuid1 = Uuid::from_bytes_ref(&bytes1);

let bytes2 = uuid1.as_bytes();
let uuid2 = Uuid::from_bytes_ref(bytes2);

assert_eq!(uuid1, uuid2);

assert!(std::ptr::eq(
    uuid2 as *const Uuid as *const u8,
    &bytes1 as *const [u8; 16] as *const u8,
));

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 = Uuid::from_bytes(bytes);
assert_eq!(bytes, uuid.into_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
use uuid::Uuid;

let uuid = Uuid::parse_str("a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8")?;

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

Tests if the UUID is nil.

A buffer that can be used for encode_... calls, that is guaranteed to be long enough for any of the format adapters.

Examples
let uuid = Uuid::nil();

assert_eq!(
    uuid.simple().encode_lower(&mut Uuid::encode_buffer()),
    "00000000000000000000000000000000"
);

assert_eq!(
    uuid.hyphenated()
        .encode_lower(&mut Uuid::encode_buffer()),
    "00000000-0000-0000-0000-000000000000"
);

assert_eq!(
    uuid.urn().encode_lower(&mut Uuid::encode_buffer()),
    "urn:uuid:00000000-0000-0000-0000-000000000000"
);

Trait Implementations

Generate an arbitrary value of Self from the given unstructured data. Read more

Generate an arbitrary value of Self from the entirety of the given unstructured data. Read more

Get a size hint for how many bytes out of an Unstructured this type needs to construct itself. Read more

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

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

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

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

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

Immutably borrows from an owned value. Read more

Immutably borrows from an owned value. Read more

Immutably borrows from an owned value. Read more

Immutably borrows from an owned value. Read more

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

Deserialize this value from the given Serde deserializer. Read more

Formats the value using the given formatter. Read more

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

The associated error which can be returned from parsing.

Parses a string s to return a value of this type. Read more

Feeds this value into the given Hasher. Read more

Feeds a slice of this type into the given Hasher. Read more

Formats the value using the given formatter.

This method returns an Ordering between self and other. Read more

Compares and returns the maximum of two values. Read more

Compares and returns the minimum of two values. Read more

Restrict a value to a certain interval. Read more

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=.

This method returns an ordering between self and other values if one exists. Read more

This method tests less than (for self and other) and is used by the < operator. Read more

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more

This method tests greater than (for self and other) and is used by the > operator. Read more

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more

Serialize this value into the given Serde serializer. Read more

The type returned in the event of a conversion error.

Performs the conversion.

Formats the value using the given formatter.

Serialize self into Serializer Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Should always be Self

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

Uses borrowed data to replace owned data, usually by cloning. Read more

Converts the given value to a String. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.