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
90 //! version without any additional dependencies or features. It's a lower-level API than [`Uuid`]
94 //! ## Which UUID version should I use?
100 //! Some UUID versions supersede others. Prefer version 6 over version 1 and version 5 over version…
106 //! * `macro-diagnostics` - enhances the diagnostics of `uuid!` macro.
107 //! * `serde` - adds the ability to serialize and deserialize a UUID using
109 //! * `borsh` - adds the ability to serialize and deserialize a UUID using
111 //! * `arbitrary` - adds an `Arbitrary` trait implementation to `Uuid` for
116 //! * `bytemuck` - adds a `Pod` trait implementation to `Uuid` for byte manipulation
130 //! to unstable `uuid` features:
143 //! [dependencies.uuid]
155 //! disable default features when building `uuid`:
158 //! [dependencies.uuid]
176 //! Parse a UUID given in the simple format and print it as a URN:
179 //! # use uuid::Uuid;
180 //! # fn main() -> Result<(), uuid::Error> {
181 //! let my_uuid = Uuid::parse_str("a1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8")?;
188 //! Generate a random UUID and print it out in hexadecimal form:
192 //! # use uuid::Uuid;
195 //! let my_uuid = Uuid::new_v4();
205 //! * [RFC4122: A Universally Unique Identifier (UUID) URN Namespace](http://tools.ietf.org/html/rf…
206 //! * [Draft RFC: New UUID Formats, Version 4](https://datatracker.ietf.org/doc/html/draft-peabody-…
217 html_root_url = "https://docs.rs/uuid/1.7.0"
286 /// A 128-bit (16 byte) buffer containing the UUID.
290 /// The `Bytes` type is always guaranteed to be have the same ABI as [`Uuid`].
293 /// The version of the UUID, denoting the generating algorithm.
302 /// The "nil" (all zeros) UUID.
320 /// The "max" (all ones) UUID.
343 /// A Universally Unique Identifier (UUID).
347 /// Parse a UUID given in the simple format and print it as a urn:
350 /// # use uuid::Uuid;
351 /// # fn main() -> Result<(), uuid::Error> {
352 /// let my_uuid = Uuid::parse_str("a1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8")?;
359 /// Create a new random (V4) UUID and print it out in hexadecimal form:
362 /// // Note that this requires the `v4` feature enabled in the uuid crate.
363 /// # use uuid::Uuid;
366 /// let my_uuid = Uuid::new_v4();
375 /// A UUID can be formatted in one of a few ways:
380 /// * [`urn`](#method.urn): `urn:uuid:A1A2A3A4-B1B2-C1C2-D1D2-D3D4D5D6D7D8`.
383 /// The default representation when formatting a UUID with `Display` is
387 /// # use uuid::Uuid;
388 /// # fn main() -> Result<(), uuid::Error> {
389 /// let my_uuid = Uuid::parse_str("a1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8")?;
399 /// Other formats can be specified using adapter methods on the UUID:
402 /// # use uuid::Uuid;
403 /// # fn main() -> Result<(), uuid::Error> {
404 /// let my_uuid = Uuid::parse_str("a1a2a3a4b1b2c1c2d1d2d3d4d5d6d7d8")?;
407 /// "urn:uuid:a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8",
427 /// - The endianness is in terms of the fields of the UUID, not the environment.
431 /// - Endianness roundtrips, so if you create a UUID with `from_fields_le`
436 /// The `Uuid` type is always guaranteed to be have the same ABI as [`Bytes`].
451 pub struct Uuid(Bytes); struct
453 impl Uuid { impl
454 /// UUID namespace for Domain Name System (DNS).
455 pub const NAMESPACE_DNS: Self = Uuid([
460 /// UUID namespace for ISO Object Identifiers (OIDs).
461 pub const NAMESPACE_OID: Self = Uuid([
466 /// UUID namespace for Uniform Resource Locators (URLs).
467 pub const NAMESPACE_URL: Self = Uuid([
472 /// UUID namespace for X.500 Distinguished Names (DNs).
473 pub const NAMESPACE_X500: Self = Uuid([
478 /// Returns the variant of the UUID structure.
480 /// This determines the interpretation of the structure of the UUID.
482 /// validate the rest of the UUID as conforming to that variant.
489 /// # use uuid::{Uuid, Variant};
490 /// # fn main() -> Result<(), uuid::Error> {
491 /// let my_uuid = Uuid::parse_str("02f09a3f-1624-3b1d-8409-44eff7708208")?;
514 /// Returns the version number of the UUID.
517 /// This method is the future-proof alternative to [`Uuid::get_version`].
524 /// # use uuid::Uuid;
525 /// # fn main() -> Result<(), uuid::Error> {
526 /// let my_uuid = Uuid::parse_str("02f09a3f-1624-3b1d-8409-44eff7708208")?;
540 /// Returns the version of the UUID.
545 /// you can also use [`Uuid::get_version_num`] to unconditionally return a
554 /// # use uuid::{Uuid, Version};
555 /// # fn main() -> Result<(), uuid::Error> {
556 /// let my_uuid = Uuid::parse_str("02f09a3f-1624-3b1d-8409-44eff7708208")?;
582 /// Returns the four field values of the UUID.
584 /// These values can be passed to the [`Uuid::from_fields`] method to get
585 /// the original `Uuid` back.
595 /// the UUID version, and for V1 UUIDs, the last 12 bits represent the
599 /// UUID variant, and for V1 UUIDs, the next 13-15 bits indicate the clock
605 /// # use uuid::Uuid;
606 /// # fn main() -> Result<(), uuid::Error> {
607 /// let uuid = Uuid::nil();
609 /// assert_eq!(uuid.as_fields(), (0, 0, 0, &[0u8; 8]));
611 /// let uuid = Uuid::parse_str("a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8")?;
614 /// uuid.as_fields(),
641 /// Returns the four field values of the UUID in little-endian order.
644 /// big-endian order. This is based on the endianness of the UUID,
651 /// use uuid::Uuid;
653 /// # fn main() -> Result<(), uuid::Error> {
654 /// let uuid = Uuid::parse_str("a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8")?;
657 /// uuid.to_fields_le(),
684 /// The bytes in the UUID will be packed directly into a `u128`.
689 /// # use uuid::Uuid;
690 /// # fn main() -> Result<(), uuid::Error> {
691 /// let uuid = Uuid::parse_str("a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8")?;
694 /// uuid.as_u128(),
707 /// order. This is based on the endianness of the UUID, rather than the
712 /// [`Uuid::to_fields_le`], because the entire UUID is reversed, rather
718 /// # use uuid::Uuid;
719 /// # fn main() -> Result<(), uuid::Error> {
720 /// let uuid = Uuid::parse_str("a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8")?;
723 /// uuid.to_u128_le(),
735 /// The bytes in the UUID will be split into two `u64`.
742 /// # use uuid::Uuid;
743 /// # fn main() -> Result<(), uuid::Error> {
744 /// let uuid = Uuid::parse_str("a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8")?;
746 /// uuid.as_u64_pair(),
759 /// This method borrows the underlying byte value of the UUID.
764 /// # use uuid::Uuid;
771 /// let uuid1 = Uuid::from_bytes_ref(&bytes1);
774 /// let uuid2 = Uuid::from_bytes_ref(bytes2);
779 /// uuid2 as *const Uuid as *const u8,
788 /// Consumes self and returns the underlying byte value of the UUID.
793 /// # use uuid::Uuid;
800 /// let uuid = Uuid::from_bytes(bytes);
801 /// assert_eq!(bytes, uuid.into_bytes());
808 /// Returns the bytes of the UUID in little-endian order.
811 /// based on the endianness of the UUID, rather than the target environment
817 /// use uuid::Uuid;
819 /// # fn main() -> Result<(), uuid::Error> {
820 /// let uuid = Uuid::parse_str("a1a2a3a4-b1b2-c1c2-d1d2-d3d4d5d6d7d8")?;
823 /// uuid.to_bytes_le(),
840 /// Tests if the UUID is nil (all zeros).
845 /// Tests if the UUID is max (all ones).
856 /// # use uuid::Uuid;
857 /// let uuid = Uuid::nil();
860 /// uuid.simple().encode_lower(&mut Uuid::encode_buffer()),
865 /// uuid.hyphenated()
866 /// .encode_lower(&mut Uuid::encode_buffer()),
871 /// uuid.urn().encode_lower(&mut Uuid::encode_buffer()),
872 /// "urn:uuid:00000000-0000-0000-0000-000000000000"
879 /// If the UUID is the correct version (v1, v6, or v7) this will return
880 /// the timestamp and counter portion parsed from a V1 UUID.
882 /// Returns `None` if the supplied UUID is not V1.
893 /// This method is unlikely to roundtrip a timestamp in a UUID due to the way
928 impl Default for Uuid { implementation
931 Uuid::nil() in default()
935 impl AsRef<[u8]> for Uuid { implementation
943 impl From<Uuid> for std::vec::Vec<u8> {
944 fn from(value: Uuid) -> Self { in from()
950 impl std::convert::TryFrom<std::vec::Vec<u8>> for Uuid { implementation
954 Uuid::from_slice(&value) in try_from()
963 //! 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()
1035 let default_uuid = Uuid::default(); in test_uuid_default()
1036 let nil_uuid = Uuid::nil(); in test_uuid_default()
1053 let uuid = new(); in test_uuid_display() localVariable
1054 let s = uuid.to_string(); in test_uuid_display()
1057 assert_eq!(s, uuid.hyphenated().to_string()); in test_uuid_display()
1059 check!(buffer, "{}", uuid, 36, |c| c.is_lowercase() in test_uuid_display()
1077 let uuid = new(); in test_uuid_lowerhex() localVariable
1079 check!(buffer, "{:x}", uuid, 36, |c| c.is_lowercase() in test_uuid_lowerhex()
1121 let uuid = new(); in test_uuid_to_string() localVariable
1122 let s = uuid.to_string(); in test_uuid_to_string()
1143 Uuid::from_bytes([4, 54, 67, 12, 43, 2, 2, 76, 32, 50, 87, 5, 1, 33, 43, 87]); in test_non_conforming()
1158 let nil = Uuid::nil(); in test_nil()
1185 let max = Uuid::max(); in test_max()
1213 Uuid::NAMESPACE_DNS.hyphenated().to_string(), in test_predefined_namespaces()
1217 Uuid::NAMESPACE_URL.hyphenated().to_string(), in test_predefined_namespaces()
1221 Uuid::NAMESPACE_OID.hyphenated().to_string(), in test_predefined_namespaces()
1225 Uuid::NAMESPACE_X500.hyphenated().to_string(), in test_predefined_namespaces()
1241 let uuid = Uuid::new_v3(&Uuid::NAMESPACE_DNS, "rust-lang.org".as_bytes()); in test_get_version_v3() localVariable
1243 assert_eq!(uuid.get_version().unwrap(), Version::Md5); in test_get_version_v3()
1244 assert_eq!(uuid.get_version_num(), 3); in test_get_version_v3()
1258 let uuid2 = Uuid::parse_str("550e8400-e29b-41d4-a716-446655440000").unwrap(); in test_get_variant()
1259 let uuid3 = Uuid::parse_str("67e55044-10b1-426f-9247-bb680e5fe0c8").unwrap(); in test_get_variant()
1260 let uuid4 = Uuid::parse_str("936DA01F9ABD4d9dC0C702AF85C822A8").unwrap(); in test_get_variant()
1261 let uuid5 = Uuid::parse_str("F9168C5E-CEB2-4faa-D6BF-329BF39FA1E4").unwrap(); in test_get_variant()
1262 let uuid6 = Uuid::parse_str("f81d4fae-7dec-11d0-7765-00a0c91e6bf6").unwrap(); in test_get_variant()
1380 assert!(ss.starts_with("urn:uuid:")); in test_to_urn_string()
1415 let uuid = new(); in test_string_roundtrip() localVariable
1417 let hs = uuid.hyphenated().to_string(); in test_string_roundtrip()
1418 let uuid_hs = Uuid::parse_str(&hs).unwrap(); in test_string_roundtrip()
1419 assert_eq!(uuid_hs, uuid); in test_string_roundtrip()
1421 let ss = uuid.to_string(); in test_string_roundtrip()
1422 let uuid_ss = Uuid::parse_str(&ss).unwrap(); in test_string_roundtrip()
1423 assert_eq!(uuid_ss, uuid); in test_string_roundtrip()
1441 let u = Uuid::from_fields(d1, d2, d3, &d4); in test_from_fields()
1463 let u = Uuid::from_fields_le(d1, d2, d3, &d4); in test_from_fields_le()
1505 let u = Uuid::from_fields(d1_in, d2_in, d3_in, d4_in); in test_fields_roundtrip()
1529 let u = Uuid::from_fields_le(d1_in, d2_in, d3_in, d4_in); in test_fields_le_roundtrip()
1553 let u = Uuid::from_fields(d1_in, d2_in, d3_in, d4_in); in test_fields_le_are_actually_le()
1574 let u = Uuid::from_u128(v_in); in test_from_u128()
1593 let u = Uuid::from_u128_le(v_in); in test_from_u128_le()
1613 let u = Uuid::from_u64_pair(high_in, low_in); in test_from_u64_pair()
1632 let u = Uuid::from_u128(v_in); in test_u128_roundtrip()
1650 let u = Uuid::from_u128_le(v_in); in test_u128_le_roundtrip()
1669 let u = Uuid::from_u64_pair(high_in, low_in); in test_u64_pair_roundtrip()
1688 let u = Uuid::from_u128(v_in); in test_u128_le_is_actually_le()
1709 let u = Uuid::from_slice(&b).unwrap(); in test_from_slice()
1730 let u = Uuid::from_bytes(b); in test_from_bytes()
1776 let uv: Uuid = v.try_into().unwrap(); in test_convert_vec()
1796 let u = Uuid::from_slice(&b_in).unwrap(); in test_bytes_roundtrip()
1818 let u1 = Uuid::from_bytes(b); in test_bytes_le_roundtrip()
1822 let u2 = Uuid::from_bytes_le(b_le); in test_bytes_le_roundtrip()