Struct uuid::Uuid [−][src]
#[repr(transparent)]pub struct Uuid(_);
Expand description
A Universally Unique Identifier (UUID).
Examples
To 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());
To 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 a [u8; 16]
.
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.
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
.
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());
Get a Hyphenated
formatter.
Get a borrowed Hyphenated
formatter.
Create a new UUID (version 1) using a time value + sequence + NodeId.
When generating Timestamp
s using a ClockSequence
, this function
is only guaranteed to produce unique values if the following conditions
hold:
- The NodeId is unique for this process,
- The Context is shared across all threads which are generating v1 UUIDs,
- The
ClockSequence
implementation reliably returns unique clock sequences (this crate providesContext
for this purpose. However you can create your ownClockSequence
implementation, ifContext
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.ord
:
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.ord
:
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. Currently only the RFC4122 variant is generated by this module. Callers should only trust the value returned by this method if they trust the UUID itself.
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 contents.
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 contents.
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.
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 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 UUID data.
The bytes in the UUID will be packed into a u128
, like the
Uuid::as_bytes
method.
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 UUID data.
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 UUID data.
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),
);
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
Deserialize this value from the given Serde deserializer. Read more
Performs the conversion.
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
Auto Trait Implementations
impl RefUnwindSafe for Uuid
impl UnwindSafe for Uuid
Blanket Implementations
Mutably borrows from an owned value. Read more
type Output = T
type Output = T
Should always be Self