Struct nuuid::Uuid

#[repr(transparent)]
pub struct Uuid(_);

Universally Unique Identifier, or UUID.

This type is repr(transparent) and guaranteed to have the same layout as [u8; 16].

The various methods on Uuid assume each field is laid out Most Significant Byte First/MSB/Big-Endian/Network Endian.

This type is also serde(transparent), when serde is enabled.

Implementations

impl Uuid

pub const fn nil() -> Self

The special Nil UUID, where all bits are set to zero.

pub const fn max() -> Self

Available on crate feature experimental_uuid only.

The special Max UUID, where all bits are set to one.

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

Create a UUID from bytes.

pub const fn to_bytes(self) -> Bytes

Return the UUID as it’s bytes.

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

Create a UUID from mixed-endian bytes.

The resulting UUID will be stored in-memory as big-endian.

This will primarily come up when interacting with Microsoft GUIDs/UUIDs

The following fields are expected to be little-endian instead of big-endian:

• time_low
• time_mid
• time_hi_and_version

Other fields are left unchanged

pub const fn to_bytes_me(self) -> Bytes

Return the UUID as mixed-endian bytes.

See Uuid::from_bytes_me for details.

pub const fn is_nil(self) -> bool

Returns true if the UUID is nil.

pub const fn variant(self) -> Variant

The UUID Variant

Warning

Many UUIDs out in the wild are incorrectly generated, so this value can’t be relied upon.

pub const fn version(self) -> Version

The UUID Version

For “incorrect” or non-RFC UUIDs, this value may be nonsensical.

If the version bits do not match any known version, Version::Reserved is returned instead. As new versions are recognized, this may change.

Warning

Many UUIDs out in the wild are incorrectly generated, so this value can’t be relied upon.

pub const fn timestamp(self) -> u64

The 60-bit UUID timestamp

This value will only make sense for Version::Time or Version::Database UUIDs

The value of this will depend on Uuid::version

pub const fn clock_sequence(self) -> u16

The 14-bit UUID clock sequence

This value will only make sense for Version::Time or Version::Database UUIDs

The value of this will depend on Uuid::version

pub const fn node(self) -> [u8; 6]

The 48-bit UUID Node ID

pub fn to_str(self, buf: &mut [u8; 36]) -> &mut str

Write UUID as a lowercase ASCII string into buf, and returns it as a string.

Examples

const EXAMPLE_UUID: &str = "662aa7c7-7598-4d56-8bcc-a72c30f998a2";
let uuid = Uuid::parse(EXAMPLE_UUID)?;

let mut buf = [0u8; 36];
let string = uuid.to_str(&mut buf);
assert_eq!(string, EXAMPLE_UUID);

With an array

let uuid = Uuid::new_v4();
let mut buf = [0u8; 36];
let string = uuid.to_str(&mut buf);

With a slice

let uuid = Uuid::new_v4();
let mut data = [0u8; 50];
let string = uuid.to_str((&mut data[..36]).try_into().unwrap());

With a slice, incorrectly.

The problem here is that the slices length is unconstrained, and could be more or less than 36.

let uuid = Uuid::new_v4();
let mut data = [0u8; 50];
let string = uuid.to_str((&mut data[..]).try_into().unwrap());

pub fn to_urn(self, buf: &mut [u8; 45]) -> &mut str

Write a UUID as a lowercase ASCII string into buf, and return it as a string.

For usage examples see Uuid::to_str.

pub fn to_str_upper(self, buf: &mut [u8; 36]) -> &mut str

Uuid::to_str, but uppercase.

pub fn to_urn_upper(self, buf: &mut [u8; 45]) -> &mut str

Uuid::to_urn, but the UUID is uppercase.

impl Uuid

pub fn parse(s: &str) -> Result<Self, ParseUuidError>

Parse a Uuid from a string

This method is case insensitive and supports the following formats:

• urn:uuid: urn:uuid:662aa7c7-7598-4d56-8bcc-a72c30f998a2
• “Braced” {662aa7c7-7598-4d56-8bcc-a72c30f998a2}
• “Hyphenate” 662aa7c7-7598-4d56-8bcc-a72c30f998a2
• “Simple” 662aa7c775984d568bcca72c30f998a2

Example

Uuid::parse("662aa7c7-7598-4d56-8bcc-a72c30f998a2").unwrap();
Uuid::parse("662AA7C7-7598-4D56-8BCC-A72C30F998A2").unwrap();

Uuid::parse("urn:uuid:662aa7c7-7598-4d56-8bcc-a72c30f998a2").unwrap();
Uuid::parse("urn:uuid:662AA7C7-7598-4D56-8BCC-A72C30F998A2").unwrap();

Uuid::parse("662aa7c775984d568bcca72c30f998a2").unwrap();
Uuid::parse("662AA7C775984D568BCCA72C30F998A2").unwrap();

Uuid::parse("{662aa7c7-7598-4d56-8bcc-a72c30f998a2}").unwrap();
Uuid::parse("{662AA7C7-7598-4D56-8BCC-A72C30F998A2}").unwrap();

pub fn parse_me(s: &str) -> Result<Self, ParseUuidError>

Parse a Uuid from a string that is in mixed-endian

This method is bad and should never be needed, but there are UUIDs in the wild that do this.

These UUIDs are being displayed wrong, but you still need to parse them correctly.

See Uuid::from_bytes_me for details.

pub fn new_v4() -> Self

Available on crate feature getrandom only.

Create a new Version 4(Random) UUID.

This requires the getrandom feature.

If generating a lot of UUID’s very quickly, prefer Uuid::new_v4_rng.

Example

let uuid = Uuid::new_v4();

pub fn new_v4_rng(rng: &mut Rng) -> Self

Create a new Version 4(Random) UUID, using the provided Rng

This method is useful if you need to generate a lot of UUID’s very quickly, since it won’t create and seed a new RNG each time.

Providing a good seed is left to you, however. If a bad seed is used, the resulting UUIDs may not be sufficiently random or unique.

Example

let mut rng = Rng::from_seed(seed);
for _ in 0..10 {
    let uuid = Uuid::new_v4_rng(&mut rng);
}

pub fn new_v3(namespace: Uuid, name: &[u8]) -> Self

Create a new Version 3 UUID with the provided name and namespace.

Note

Version 3 UUID’s use the obsolete MD5 algorithm, Uuid::new_v5 should be preferred.

Example

let uuid = Uuid::new_v3(NAMESPACE_DNS, b"example.com");

pub fn new_v5(namespace: Uuid, name: &[u8]) -> Self

Create a new Version 5 UUID with the provided name and namespace.

Example

let uuid = Uuid::new_v5(NAMESPACE_DNS, b"example.com");

pub fn new_v1(timestamp: u64, counter: u16, node: [u8; 6]) -> Self

Create a new Version 1 UUID using the provided 60-bit timestamp, 14-bit counter, and node.

The 4 high bits of timestamp are ignored

The 2 high bits of counter are ignored

Example

let uuid = Uuid::new_v1(TIMESTAMP, RANDOM, RANDOM_OR_MAC);

pub fn new_v6(timestamp: u64, counter: u16, node: [u8; 6]) -> Self

Available on crate feature experimental_uuid only.

Create a new Version 6 UUID

This is identical to Version 1 UUIDs (see Uuid::new_v1), except that the timestamp fields are re-ordered

Example

let uuid = Uuid::new_v6(TIMESTAMP, RANDOM, PSEUDO);

pub fn new_v7(timestamp: u64, rand_a: u16, rand_b: u64) -> Self

Available on crate feature experimental_uuid only.

Create a new Version 7 UUID

This is similar to Version 1 and 6 UUIDs, but uses the UNIX epoch timestamp source.

Example

let uuid = Uuid::new_v7(TIMESTAMP, RAND_A, RAND_B);

pub fn new_v8(bytes: Bytes) -> Self

Available on crate feature experimental_uuid only.

Create a new Version 8 UUID

This will set the version and variant bits as needed, and the input will otherwise be unchanged.

Example

let uuid = Uuid::new_v8(*b"I Am 16 bytes!!!");

Trait Implementations

impl AsRef<[u8]> for Uuid

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

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

impl AsRef<[u8; 16]> for Uuid

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

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

impl Clone for Uuid

fn clone(&self) -> Uuid

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Uuid

Display the Uuid debug representation

The alternate(#) flag can be used to get more more detailed debug information.

Example

let uuid = Uuid::parse("662aa7c7-7598-4d56-8bcc-a72c30f998a2").unwrap();
assert_eq!(format!("{:?}", uuid), "Uuid(662AA7C7-7598-4D56-8BCC-A72C30F998A2)");
assert_eq!(format!("{:#?}", uuid), r#"Uuid(662AA7C7-7598-4D56-8BCC-A72C30F998A2) {
    Version: Random(4),
    Variant: Rfc4122(1),
}"#);

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

Formats the value using the given formatter.

impl Default for Uuid

fn default() -> Uuid

Returns the “default value” for a type.

impl Display for Uuid

Display the Uuid in uppercase hex.

Example

let uuid = Uuid::parse("662aa7c7-7598-4d56-8bcc-a72c30f998a2").unwrap();
assert_eq!(format!("{}", uuid), "662AA7C7-7598-4D56-8BCC-A72C30F998A2");

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

Formats the value using the given formatter.

impl FromStr for Uuid

See Uuid::parse for details.

fn from_str(s: &str) -> Result<Self, Self::Err>

See Uuid::parse for details.

type Err = ParseUuidError

The associated error which can be returned from parsing.

impl Hash for Uuid

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 LowerHex for Uuid

Display the Uuid in lowercase

The alternate(#) flag can be used to get a URN.

Example

let uuid = Uuid::parse("662aa7c7-7598-4d56-8bcc-a72c30f998a2").unwrap();
assert_eq!(format!("{:x}", uuid), "662aa7c7-7598-4d56-8bcc-a72c30f998a2");
assert_eq!(format!("{:#x}", uuid), "urn:uuid:662aa7c7-7598-4d56-8bcc-a72c30f998a2");

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

Formats the value using the given formatter.

impl Ord for Uuid

fn cmp(&self, other: &Uuid) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval.

impl PartialEq<Uuid> for Uuid

fn eq(&self, other: &Uuid) -> bool

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

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd<Uuid> for Uuid

fn partial_cmp(&self, other: &Uuid) -> Option<Ordering>

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

fn lt(&self, other: &Rhs) -> bool

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

fn le(&self, other: &Rhs) -> bool

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

fn gt(&self, other: &Rhs) -> bool

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

fn ge(&self, other: &Rhs) -> bool

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

impl UpperHex for Uuid

Display the Uuid in uppercase

The alternate(#) flag can be used to get a URN.

Example

let uuid = Uuid::parse("662aa7c7-7598-4d56-8bcc-a72c30f998a2").unwrap();
assert_eq!(format!("{:X}", uuid), "662AA7C7-7598-4D56-8BCC-A72C30F998A2");
assert_eq!(format!("{:#X}", uuid), "urn:uuid:662AA7C7-7598-4D56-8BCC-A72C30F998A2");

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

Formats the value using the given formatter.

impl Copy for Uuid

impl Eq for Uuid

impl StructuralEq for Uuid

impl StructuralPartialEq for Uuid