Struct Uuid 

pub struct Uuid(/* private fields */);

A 128-bit UUID (RFC 9562).

Implementations

impl Uuid

pub fn new_v4() -> Uuid

Available on crate feature std only.

Generate a new version 4 (random) UUID.

Examples

use uuid::{Uuid, Version};

let uuid = Uuid::new_v4();
assert_eq!(uuid.version(), Version::V4);

pub fn new_v7() -> Uuid

Available on crate feature std only.

Generate a new version 7 UUID with a 32-bit monotonic counter.

The 48-bit timestamp is milliseconds since the Unix epoch. A 32-bit monotonic counter occupies rand_a (12 bits) and the most-significant 20 bits of rand_b, guaranteeing up to 2³² UUIDs within a single millisecond per thread (per RFC 9562 §6.2, Method 1).

The counter is seeded with 31 random bits each time the timestamp advances and incremented on repeated calls within the same millisecond. If the counter does overflow, this function spin-waits for the next millisecond tick.

The 128-bit layout follows RFC 9562:

 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                           unix_ts_ms                          |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|          unix_ts_ms           |  ver  |       rand_a          |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|var|                        rand_b                             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                            rand_b                             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

The 32-bit counter spans rand_a (12 bits) and the most- significant 20 bits of rand_b (bytes 6–10).

Panics

Panics if the system clock is before the Unix epoch.

Examples

use uuid::{Uuid, Version};

let uuid = Uuid::new_v7();
assert_eq!(uuid.version(), Version::V7);

impl Uuid

pub fn parse(input: impl AsRef<[u8]>) -> Result<Uuid, Error>

Parse a UUID from its canonical 8-4-4-4-12 hexadecimal string form.

Accepts both lowercase and uppercase hex characters.

Errors

Returns Error::InvalidUuid if the input is not exactly 36 characters, contains misplaced hyphens, or has non-hexadecimal characters.

Examples

use uuid::Uuid;

let uuid = Uuid::parse("f47ac10b-58cc-4372-a567-0e02b2c3d479").unwrap();
assert_eq!(uuid.to_string(), "f47ac10b-58cc-4372-a567-0e02b2c3d479");

pub const fn from_bytes(bytes: [u8; 16]) -> Uuid

Create a UUID from a 16-byte array.

Examples

use uuid::Uuid;

let uuid = Uuid::from_bytes([0; 16]);
assert_eq!(uuid, Uuid::nil());

pub fn from_slice(bytes: &[u8]) -> Result<Uuid, Error>

Create a UUID from a byte slice of length 16.

Errors

Returns Error::InvalidUuid if the slice is not exactly 16 bytes.

Examples

use uuid::Uuid;

let uuid = Uuid::from_slice(&[0; 16]).unwrap();
assert_eq!(uuid, Uuid::nil());

pub const fn as_bytes(&self) -> [u8; 16]

Return the 16-byte array representation.

Examples

use uuid::Uuid;

let uuid = Uuid::nil();
assert_eq!(uuid.as_bytes(), [0; 16]);

pub const fn from_u128(v: u128) -> Uuid

Create a UUID from a u128 value (big-endian).

Examples

use uuid::Uuid;

let uuid = Uuid::from_u128(0);
assert_eq!(uuid, Uuid::nil());

pub const fn as_u128(&self) -> u128

Return the UUID as a u128 value (big-endian).

Examples

use uuid::Uuid;

let uuid = Uuid::max();
assert_eq!(uuid.as_u128(), !0);

pub const fn nil() -> Uuid

The Nil UUID: all 128 bits set to zero.

Examples

use uuid::Uuid;

assert_eq!(Uuid::nil().to_string(), "00000000-0000-0000-0000-000000000000");

pub const fn max() -> Uuid

The Max UUID: all 128 bits set to one.

Examples

use uuid::Uuid;

assert_eq!(Uuid::max().to_string(), "ffffffff-ffff-ffff-ffff-ffffffffffff");

pub const fn version(&self) -> Version

Return the Version of this UUID.

Examples

use uuid::{Uuid, Version};

assert_eq!(Uuid::nil().version(), Version::Nil);
assert_eq!(Uuid::max().version(), Version::Max);

pub fn timestamp(&self) -> Option<u64>

Return the Unix millisecond timestamp embedded in a UUIDv7.

Only UUID version 7 (Unix Epoch time-based) carries a meaningful timestamp. All other versions return None.

The timestamp is a 48-bit value representing milliseconds since the Unix epoch (1970-01-01 00:00:00 UTC).

Examples

use uuid::Uuid;

let uuid = Uuid::nil();
assert_eq!(uuid.timestamp(), None);

Trait Implementations

impl Clone for Uuid

fn clone(&self) -> Uuid

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for Uuid

impl Debug for Uuid

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

Formats the value using the given formatter.

impl Decode<'_, Postgres> for Uuid

Available on crate feature sqlx only.

fn decode(value: PgValueRef<'_>) -> Result<Self, BoxDynError>

Decode a new value of this type using a raw value from the database.

impl<'de> Deserialize<'de> for Uuid

Available on crate feature serde only.

fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Uuid, D::Error>

Deserialize this value from the given Serde deserializer.

impl Display for Uuid

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

Formats the UUID as a lowercase 8-4-4-4-12 hyphenated string.

Examples

let uuid = uuid::Uuid::nil();
assert_eq!(uuid.to_string(), "00000000-0000-0000-0000-000000000000");

impl Encode<'_, Postgres> for Uuid

Available on crate feature sqlx only.

fn encode_by_ref( &self, buf: &mut PgArgumentBuffer, ) -> Result<IsNull, BoxDynError>

Writes the value of self into buf without moving self.

fn encode( self, buf: &mut <DB as Database>::ArgumentBuffer, ) -> Result<IsNull, Box<dyn Error + Send + Sync>>

where Self: Sized,

Writes the value of self into buf in the expected format for the database.

fn produces(&self) -> Option<<DB as Database>::TypeInfo>

fn size_hint(&self) -> usize

impl Eq for Uuid

impl FromStr for Uuid

type Err = Error

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Uuid, Error>

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

impl PartialEq for Uuid

fn eq(&self, other: &Uuid) -> 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 PgHasArrayType for Uuid

Available on crate feature sqlx only.

fn array_type_info() -> PgTypeInfo

fn array_compatible(ty: &PgTypeInfo) -> bool

impl Serialize for Uuid

Available on crate feature serde only.

fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Uuid

impl Type<Postgres> for Uuid

Available on crate feature sqlx only.

fn type_info() -> PgTypeInfo

Returns the canonical SQL type for this Rust type.

fn compatible(ty: &<DB as Database>::TypeInfo) -> bool

Determines if this Rust type is compatible with the given SQL type.