Lines Matching full:uuid
2 // Copyright 2018 The Uuid Project Developers.
14 //! Here's an example of a UUID:
20 //! A UUID is a unique 128-bit value, stored as 16 octets, and regularly
25 //! disparate areas, such as databases and network protocols. Typically a UUID
34 …itions [in draft](https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-04).
41 //! [dependencies.uuid]
50 //! When you want a UUID, you can generate one:
56 //! use uuid::Uuid;
58 //! let id = Uuid::new_v4();
63 //! If you have a UUID value, you can use its string literal form inline:
66 //! use uuid::{uuid, Uuid};
68 //! const ID: Uuid = uuid!("67e55044-10b1-426f-9247-bb680e5fe0c8");
71 //! # Working with different UUID versions
76 //! UUIDs, but cannot generate them. Depending on the kind of UUID you'd like to work with, there
87 //! version without any additional dependencies or features. It's a lower-level API than [`Uuid`]
91 //! ## Which UUID version should I use?
97 //! Some UUID versions supersede others. Prefer version 6 over version 1 and version 5 over version…
103 //! * `macro-diagnostics` - enhances the diagnostics of `uuid!` macro.
104 //! * `serde` - adds the ability to serialize and deserialize a UUID using
106 //! * `arbitrary` - adds an `Arbitrary` trait implementation to `Uuid` for
127 //! to unstable `uuid` features:
140 //! [dependencies.uuid]
152 //! disable default features when building `uuid`:
155 //! [dependencies.uuid]
173 //! Parse a UUID given in the simple format and print it as a URN:
176 //! # use uuid::Uuid;
177 //! # fn main() -> Result<(), uuid::Error> {
178 //! let my_uuid = Uuid::parse_str("a1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8")?;
185 //! Generate a random UUID and print it out in hexadecimal form:
189 //! # use uuid::Uuid;
192 //! let my_uuid = Uuid::new_v4();
202 //! * [RFC4122: A Universally Unique Identifier (UUID) URN Namespace](http://tools.ietf.org/html/rf…
203 //! * [Draft RFC: New UUID Formats, Version 4](https://datatracker.ietf.org/doc/html/draft-peabody-…
214 html_root_url = "https://docs.rs/uuid/1.3.0"
278 /// A 128-bit (16 byte) buffer containing the UUID.
282 /// The `Bytes` type is always guaranteed to be have the same ABI as [`Uuid`].
285 /// The version of the UUID, denoting the generating algorithm.
294 /// The "nil" (all zeros) UUID.
315 /// The "max" (all ones) UUID.
339 /// A Universally Unique Identifier (UUID).
343 /// Parse a UUID given in the simple format and print it as a urn:
346 /// # use uuid::Uuid;
347 /// # fn main() -> Result<(), uuid::Error> {
348 /// let my_uuid = Uuid::parse_str("a1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8")?;
355 /// Create a new random (V4) UUID and print it out in hexadecimal form:
358 /// // Note that this requires the `v4` feature enabled in the uuid crate.
359 /// # use uuid::Uuid;
362 /// let my_uuid = Uuid::new_v4();
371 /// A UUID can be formatted in one of a few ways:
376 /// * [`urn`](#method.urn): `urn:uuid:A1A2A3A4-B1B2-C1C2-D1D2-D3D4D5D6D7D8`.
379 /// The default representation when formatting a UUID with `Display` is
383 /// # use uuid::Uuid;
384 /// # fn main() -> Result<(), uuid::Error> {
385 /// let my_uuid = Uuid::parse_str("a1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8")?;
395 /// Other formats can be specified using adapter methods on the UUID:
398 /// # use uuid::Uuid;
399 /// # fn main() -> Result<(), uuid::Error> {
400 /// let my_uuid = Uuid::parse_str("a1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8")?;
403 /// "urn:uuid:a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
423 /// - The endianness is in terms of the fields of the UUID, not the environment.
427 /// - Endianness roundtrips, so if you create a UUID with `from_fields_le`
432 /// The `Uuid` type is always guaranteed to be have the same ABI as [`Bytes`].
436 pub struct Uuid(Bytes); struct
438 impl Uuid { impl
439 /// UUID namespace for Domain Name System (DNS).
440 pub const NAMESPACE_DNS: Self = Uuid([
445 /// UUID namespace for ISO Object Identifiers (OIDs).
446 pub const NAMESPACE_OID: Self = Uuid([
451 /// UUID namespace for Uniform Resource Locators (URLs).
452 pub const NAMESPACE_URL: Self = Uuid([
457 /// UUID namespace for X.500 Distinguished Names (DNs).
458 pub const NAMESPACE_X500: Self = Uuid([
463 /// Returns the variant of the UUID structure.
465 /// This determines the interpretation of the structure of the UUID.
467 /// validate the rest of the UUID as conforming to that variant.
474 /// # use uuid::{Uuid, Variant};
475 /// # fn main() -> Result<(), uuid::Error> {
476 /// let my_uuid = Uuid::parse_str("02f09a3f-1624-3b1d-8409-44eff7708208")?;
499 /// Returns the version number of the UUID.
502 /// This method is the future-proof alternative to [`Uuid::get_version`].
509 /// # use uuid::Uuid;
510 /// # fn main() -> Result<(), uuid::Error> {
511 /// let my_uuid = Uuid::parse_str("02f09a3f-1624-3b1d-8409-44eff7708208")?;
525 /// Returns the version of the UUID.
530 /// you can also use [`Uuid::get_version_num`] to unconditionally return a
539 /// # use uuid::{Uuid, Version};
540 /// # fn main() -> Result<(), uuid::Error> {
541 /// let my_uuid = Uuid::parse_str("02f09a3f-1624-3b1d-8409-44eff7708208")?;
571 /// Returns the four field values of the UUID.
573 /// These values can be passed to the [`Uuid::from_fields`] method to get
574 /// the original `Uuid` back.
584 /// the UUID version, and for V1 UUIDs, the last 12 bits represent the
588 /// UUID variant, and for V1 UUIDs, the next 13-15 bits indicate the clock
594 /// # use uuid::Uuid;
595 /// # fn main() -> Result<(), uuid::Error> {
596 /// let uuid = Uuid::nil();
598 /// assert_eq!(uuid.as_fields(), (0, 0, 0, &[0u8; 8]));
600 /// let uuid = Uuid::parse_str("a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8")?;
603 /// uuid.as_fields(),
630 /// Returns the four field values of the UUID in little-endian order.
633 /// big-endian order. This is based on the endianness of the UUID,
640 /// use uuid::Uuid;
642 /// # fn main() -> Result<(), uuid::Error> {
643 /// let uuid = Uuid::parse_str("a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8")?;
646 /// uuid.to_fields_le(),
673 /// The bytes in the UUID will be packed directly into a `u128`.
678 /// # use uuid::Uuid;
679 /// # fn main() -> Result<(), uuid::Error> {
680 /// let uuid = Uuid::parse_str("a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8")?;
683 /// uuid.as_u128(),
711 /// order. This is based on the endianness of the UUID, rather than the
716 /// [`Uuid::to_fields_le`], because the entire UUID is reversed, rather
722 /// # use uuid::Uuid;
723 /// # fn main() -> Result<(), uuid::Error> {
724 /// let uuid = Uuid::parse_str("a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8")?;
727 /// uuid.to_u128_le(),
754 /// The bytes in the UUID will be split into two `u64`.
761 /// # use uuid::Uuid;
762 /// # fn main() -> Result<(), uuid::Error> {
763 /// let uuid = Uuid::parse_str("a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8")?;
765 /// uuid.as_u64_pair(),
778 /// This method borrows the underlying byte value of the UUID.
783 /// # use uuid::Uuid;
790 /// let uuid1 = Uuid::from_bytes_ref(&bytes1);
793 /// let uuid2 = Uuid::from_bytes_ref(bytes2);
798 /// uuid2 as *const Uuid as *const u8,
806 /// Consumes self and returns the underlying byte value of the UUID.
811 /// # use uuid::Uuid;
818 /// let uuid = Uuid::from_bytes(bytes);
819 /// assert_eq!(bytes, uuid.into_bytes());
825 /// Returns the bytes of the UUID in little-endian order.
828 /// based on the endianness of the UUID, rather than the target environment
834 /// use uuid::Uuid;
836 /// # fn main() -> Result<(), uuid::Error> {
837 /// let uuid = Uuid::parse_str("a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8")?;
840 /// uuid.to_bytes_le(),
857 /// Tests if the UUID is nil (all zeros).
862 /// Tests if the UUID is max (all ones).
874 /// # use uuid::Uuid;
875 /// let uuid = Uuid::nil();
878 /// uuid.simple().encode_lower(&mut Uuid::encode_buffer()),
883 /// uuid.hyphenated()
884 /// .encode_lower(&mut Uuid::encode_buffer()),
889 /// uuid.urn().encode_lower(&mut Uuid::encode_buffer()),
890 /// "urn:uuid:00000000-0000-0000-0000-000000000000"
897 /// If the UUID is the correct version (v1, v6, or v7) this will return
898 /// the timestamp and counter portion parsed from a V1 UUID.
900 /// Returns `None` if the supplied UUID is not V1.
911 /// This method is unlikely to roundtrip a timestamp in a UUID due to the way
948 impl Default for Uuid { implementation
951 Uuid::nil() in default()
955 impl AsRef<[u8]> for Uuid { implementation
967 //! to change the way a [`Uuid`](../struct.Uuid.html) is serialized
991 pub const fn new() -> Uuid { in new()
992 Uuid::from_bytes([ in new()
998 pub const fn new2() -> Uuid { in new2()
999 Uuid::from_bytes([ in new2()
1021 let default_uuid = Uuid::default(); in test_uuid_default()
1022 let nil_uuid = Uuid::nil(); in test_uuid_default()
1032 let uuid = new(); in test_uuid_display() localVariable
1033 let s = uuid.to_string(); in test_uuid_display()
1036 assert_eq!(s, uuid.hyphenated().to_string()); in test_uuid_display()
1038 check!(buffer, "{}", uuid, 36, |c| c.is_lowercase() in test_uuid_display()
1049 let uuid = new(); in test_uuid_lowerhex() localVariable
1051 check!(buffer, "{:x}", uuid, 36, |c| c.is_lowercase() in test_uuid_lowerhex()
1079 let uuid = new(); in test_uuid_to_string() localVariable
1080 let s = uuid.to_string(); in test_uuid_to_string()
1094 Uuid::from_bytes([4, 54, 67, 12, 43, 2, 2, 76, 32, 50, 87, 5, 1, 33, 43, 87]); in test_non_conforming()
1102 let nil = Uuid::nil(); in test_nil()
1118 let max = Uuid::max(); in test_max()
1134 Uuid::NAMESPACE_DNS.hyphenated().to_string(), in test_predefined_namespaces()
1138 Uuid::NAMESPACE_URL.hyphenated().to_string(), in test_predefined_namespaces()
1142 Uuid::NAMESPACE_OID.hyphenated().to_string(), in test_predefined_namespaces()
1146 Uuid::NAMESPACE_X500.hyphenated().to_string(), in test_predefined_namespaces()
1155 let uuid = Uuid::new_v3(&Uuid::NAMESPACE_DNS, "rust-lang.org".as_bytes()); in test_get_version_v3() localVariable
1157 assert_eq!(uuid.get_version().unwrap(), Version::Md5); in test_get_version_v3()
1158 assert_eq!(uuid.get_version_num(), 3); in test_get_version_v3()
1165 let uuid2 = Uuid::parse_str("550e8400-e29b-41d4-a716-446655440000").unwrap(); in test_get_variant()
1166 let uuid3 = Uuid::parse_str("67e55044-10b1-426f-9247-bb680e5fe0c8").unwrap(); in test_get_variant()
1167 let uuid4 = Uuid::parse_str("936DA01F9ABD4d9dC0C702AF85C822A8").unwrap(); in test_get_variant()
1168 let uuid5 = Uuid::parse_str("F9168C5E-CEB2-4faa-D6BF-329BF39FA1E4").unwrap(); in test_get_variant()
1169 let uuid6 = Uuid::parse_str("f81d4fae-7dec-11d0-7765-00a0c91e6bf6").unwrap(); in test_get_variant()
1255 assert!(ss.starts_with("urn:uuid:")); in test_to_urn_string()
1276 let uuid = new(); in test_string_roundtrip() localVariable
1278 let hs = uuid.hyphenated().to_string(); in test_string_roundtrip()
1279 let uuid_hs = Uuid::parse_str(&hs).unwrap(); in test_string_roundtrip()
1280 assert_eq!(uuid_hs, uuid); in test_string_roundtrip()
1282 let ss = uuid.to_string(); in test_string_roundtrip()
1283 let uuid_ss = Uuid::parse_str(&ss).unwrap(); in test_string_roundtrip()
1284 assert_eq!(uuid_ss, uuid); in test_string_roundtrip()
1295 let u = Uuid::from_fields(d1, d2, d3, &d4); in test_from_fields()
1310 let u = Uuid::from_fields_le(d1, d2, d3, &d4); in test_from_fields_le()
1338 let u = Uuid::from_fields(d1_in, d2_in, d3_in, d4_in); in test_fields_roundtrip()
1355 let u = Uuid::from_fields_le(d1_in, d2_in, d3_in, d4_in); in test_fields_le_roundtrip()
1372 let u = Uuid::from_fields(d1_in, d2_in, d3_in, d4_in); in test_fields_le_are_actually_le()
1386 let u = Uuid::from_u128(v_in); in test_from_u128()
1398 let u = Uuid::from_u128_le(v_in); in test_from_u128_le()
1411 let u = Uuid::from_u64_pair(high_in, low_in); in test_from_u64_pair()
1423 let u = Uuid::from_u128(v_in); in test_u128_roundtrip()
1434 let u = Uuid::from_u128_le(v_in); in test_u128_le_roundtrip()
1446 let u = Uuid::from_u64_pair(high_in, low_in); in test_u64_pair_roundtrip()
1458 let u = Uuid::from_u128(v_in); in test_u128_le_is_actually_le()
1472 let u = Uuid::from_slice(&b).unwrap(); in test_from_slice()
1486 let u = Uuid::from_bytes(b); in test_from_bytes()
1513 let u = Uuid::from_slice(&b_in).unwrap(); in test_bytes_roundtrip()
1528 let u1 = Uuid::from_bytes(b); in test_bytes_le_roundtrip()
1532 let u2 = Uuid::from_bytes_le(b_le); in test_bytes_le_roundtrip()