pub struct Uuid(/* private fields */);
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 withto_fields_le
.
§ABI
The Uuid
type is always guaranteed to be have the same ABI as Bytes
.
Implementations§
Source§impl Uuid
impl Uuid
Sourcepub const fn nil() -> Uuid
pub const fn nil() -> Uuid
Sourcepub const fn max() -> Uuid
pub const fn max() -> Uuid
Sourcepub const fn from_fields(d1: u32, d2: u16, d3: u16, d4: &[u8; 8]) -> Uuid
pub const fn from_fields(d1: u32, d2: u16, d3: u16, d4: &[u8; 8]) -> Uuid
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(),
);
Sourcepub const fn from_fields_le(d1: u32, d2: u16, d3: u16, d4: &[u8; 8]) -> Uuid
pub const fn from_fields_le(d1: u32, d2: u16, d3: u16, d4: &[u8; 8]) -> Uuid
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
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_le(d1, d2, d3, &d4);
assert_eq!(
"a4a3a2a1-b2b1-c2c1-d1d2-d3d4d5d6d7d8",
uuid.hyphenated().to_string(),
);
Sourcepub const fn from_u128(v: u128) -> Uuid
pub const fn from_u128(v: u128) -> Uuid
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(),
);
Sourcepub const fn from_u128_le(v: u128) -> Uuid
pub const fn from_u128_le(v: u128) -> Uuid
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(),
);
Sourcepub const fn from_u64_pair(high_bits: u64, low_bits: u64) -> Uuid
pub const fn from_u64_pair(high_bits: u64, low_bits: u64) -> Uuid
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(),
);
Sourcepub fn from_slice(b: &[u8]) -> Result<Uuid, Error>
pub fn from_slice(b: &[u8]) -> Result<Uuid, Error>
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(),
);
Sourcepub fn from_slice_le(b: &[u8]) -> Result<Uuid, Error>
pub fn from_slice_le(b: &[u8]) -> Result<Uuid, Error>
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"
);
Sourcepub const fn from_bytes(bytes: [u8; 16]) -> Uuid
pub const fn from_bytes(bytes: [u8; 16]) -> Uuid
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"
);
Sourcepub const fn from_bytes_le(b: [u8; 16]) -> Uuid
pub const fn from_bytes_le(b: [u8; 16]) -> Uuid
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(),
);
Sourcepub fn from_bytes_ref(bytes: &[u8; 16]) -> &Uuid
pub fn from_bytes_ref(bytes: &[u8; 16]) -> &Uuid
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,
));
Source§impl Uuid
impl Uuid
Sourcepub fn parse_str(input: &str) -> Result<Uuid, Error>
pub fn parse_str(input: &str) -> Result<Uuid, Error>
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());
Sourcepub const fn try_parse(input: &str) -> Result<Uuid, Error>
pub const fn try_parse(input: &str) -> Result<Uuid, Error>
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 of 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());
Sourcepub const fn try_parse_ascii(input: &[u8]) -> Result<Uuid, Error>
pub const fn try_parse_ascii(input: &[u8]) -> Result<Uuid, Error>
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());
Source§impl Uuid
impl Uuid
Sourcepub const fn hyphenated(self) -> Hyphenated
pub const fn hyphenated(self) -> Hyphenated
Get a Hyphenated
formatter.
Sourcepub fn as_hyphenated(&self) -> &Hyphenated
pub fn as_hyphenated(&self) -> &Hyphenated
Get a borrowed Hyphenated
formatter.
Source§impl Uuid
impl Uuid
Sourcepub const NAMESPACE_DNS: Uuid = _
pub const NAMESPACE_DNS: Uuid = _
UUID namespace for Domain Name System (DNS).
Sourcepub const NAMESPACE_OID: Uuid = _
pub const NAMESPACE_OID: Uuid = _
UUID namespace for ISO Object Identifiers (OIDs).
Sourcepub const NAMESPACE_URL: Uuid = _
pub const NAMESPACE_URL: Uuid = _
UUID namespace for Uniform Resource Locators (URLs).
Sourcepub const NAMESPACE_X500: Uuid = _
pub const NAMESPACE_X500: Uuid = _
UUID namespace for X.500 Distinguished Names (DNs).
Sourcepub const fn get_variant(&self) -> Variant
pub const fn get_variant(&self) -> Variant
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
Sourcepub const fn get_version_num(&self) -> usize
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 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
Sourcepub const fn get_version(&self) -> Option<Version>
pub const 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.
§Examples
Basic usage:
let my_uuid = Uuid::parse_str("02f09a3f-1624-3b1d-8409-44eff7708208")?;
assert_eq!(Some(Version::Md5), my_uuid.get_version());
§References
Sourcepub fn as_fields(&self) -> (u32, u16, u16, &[u8; 8])
pub fn as_fields(&self) -> (u32, u16, u16, &[u8; 8])
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],
)
);
Sourcepub fn to_fields_le(&self) -> (u32, u16, u16, &[u8; 8])
pub fn to_fields_le(&self) -> (u32, u16, u16, &[u8; 8])
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],
)
);
Sourcepub const fn as_u128(&self) -> u128
pub const fn as_u128(&self) -> u128
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,
);
Sourcepub const fn to_u128_le(&self) -> u128
pub const fn to_u128_le(&self) -> u128
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,
);
Sourcepub const fn as_u64_pair(&self) -> (u64, u64)
pub const fn as_u64_pair(&self) -> (u64, u64)
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),
);
Sourcepub const fn as_bytes(&self) -> &[u8; 16]
pub const fn as_bytes(&self) -> &[u8; 16]
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,
));
Sourcepub const fn into_bytes(self) -> [u8; 16]
pub const fn into_bytes(self) -> [u8; 16]
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());
Sourcepub const fn to_bytes_le(&self) -> [u8; 16]
pub const fn to_bytes_le(&self) -> [u8; 16]
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
])
);
Sourcepub const fn encode_buffer() -> [u8; 45]
pub const fn encode_buffer() -> [u8; 45]
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"
);
Sourcepub const fn get_timestamp(&self) -> Option<Timestamp>
pub const fn get_timestamp(&self) -> Option<Timestamp>
If the UUID is the correct version (v1, v6, or v7) this will return
the timestamp in a version-agnostic Timestamp
. For other versions
this will return None
.
§Roundtripping
This method is unlikely to roundtrip a timestamp in a UUID due to the way UUIDs encode timestamps. The timestamp returned from this method will be truncated to 100ns precision for version 1 and 6 UUIDs, and to millisecond precision for version 7 UUIDs.
Sourcepub const fn get_node_id(&self) -> Option<[u8; 6]>
pub const fn get_node_id(&self) -> Option<[u8; 6]>
If the UUID is the correct version (v1, or v6) this will return the
node value as a 6-byte array. For other versions this will return None
.