Merge pull request #753 from Mikopet/update-rfc

update docs to updated RFC (from 4122 to 9562)

CONTRIBUTING.md

@@ -124,10 +124,12 @@ For people new to Uuid, and just starting to contribute, or even for more
 seasoned developers, some useful places to look for information are:
 
 * The Wikipedia entry on [Universally Unique Identifier][wiki-uuid].
-* [RFC 4122] which gives the specification of Uuids.
+* [RFC 9562][rfc-uuid] which gives the specification of UUIDs.
+* [RFC 4122][rfc-uuid-obsolete] for reference to the obsolete RFC.
 
 [wiki-uuid]: https://en.wikipedia.org/wiki/Universally_unique_identifier
-[RFC 4122]: https://www.ietf.org/rfc/rfc4122.txt
+[rfc-uuid]: https://www.ietf.org/rfc/rfc9562.html
+[rfc-uuid-obsolete]: https://www.ietf.org/rfc/rfc4122.html
 
 [u-r-l-o]: https://users.rust-lang.org
 [Discussions]: https://github.com/uuid-rs/uuid/discussions

README.md

@@ -71,8 +71,7 @@ For more details on using `uuid`, [see the library documentation](https://docs.r
 
 * [`uuid` library docs](https://docs.rs/uuid/1.8.0/uuid).
 * [Wikipedia: Universally Unique Identifier](http://en.wikipedia.org/wiki/Universally_unique_identifier).
-* [RFC4122: A Universally Unique IDentifier (UUID) URN Namespace](http://tools.ietf.org/html/rfc4122).
-* [Revision of RFC4122: Universally Unique IDentifiers (UUID)](https://www.ietf.org/archive/id/draft-ietf-uuidrev-rfc4122bis-14.html).
+* [RFC 9562: Universally Unique IDentifiers (UUID)](https://www.ietf.org/rfc/rfc9562.html).
 
 ---
 # License

src/builder.rs

@@ -54,7 +54,7 @@ impl Uuid {
     ///
     /// # References
     ///
-    /// * [Nil UUID in RFC4122](https://tools.ietf.org/html/rfc4122.html#section-4.1.7)
+    /// * [Nil UUID in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-5.9)
     ///
     /// # Examples
     ///
@@ -80,7 +80,7 @@ impl Uuid {
     ///
     /// # References
     ///
-    /// * [Max UUID in Draft RFC: New UUID Formats, Version 4](https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-04#section-5.4)
+    /// * [Max UUID in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-5.10)
     ///
     /// # Examples
     ///

src/lib.rs

@@ -30,8 +30,7 @@
 //! practical purposes, it can be assumed that an unintentional collision would
 //! be extremely unlikely.
 //!
-//! UUIDs have a number of standardized encodings that are specified in [RFC4122](http://tools.ietf.org/html/rfc4122),
-//! with recent additions [in draft](https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-04).
+//! UUIDs have a number of standardized encodings that are specified in [RFC 9562](https://www.ietf.org/rfc/rfc9562.html).
 //!
 //! # Getting started
 //!
@@ -84,8 +83,6 @@
 //! * `v7` - Version 7 UUIDs using a Unix timestamp.
 //! * `v8` - Version 8 UUIDs using user-defined data.
 //!
-//! Versions that are in draft are also supported. See the _unstable features_ section for details.
-//!
 //! This library also includes a [`Builder`] type that can be used to help construct UUIDs of any
 //! version without any additional dependencies or features. It's a lower-level API than [`Uuid`]
 //! that can be used when you need control over implicit requirements on things like a source
@@ -202,8 +199,7 @@
 //! # References
 //!
 //! * [Wikipedia: Universally Unique Identifier](http://en.wikipedia.org/wiki/Universally_unique_identifier)
-//! * [RFC4122: A Universally Unique Identifier (UUID) URN Namespace](http://tools.ietf.org/html/rfc4122)
-//! * [Draft RFC: New UUID Formats, Version 4](https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-04)
+//! * [RFC 9562: Universally Unique IDentifiers (UUID)](https://www.ietf.org/rfc/rfc9562.html).
 //!
 //! [`wasm-bindgen`]: https://crates.io/crates/wasm-bindgen
 //! [`cargo-web`]: https://crates.io/crates/cargo-web
@@ -295,7 +291,7 @@ pub type Bytes = [u8; 16];
 ///
 /// # References
 ///
-/// * [Version in RFC4122](https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.3)
+/// * [Version Field in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-4.2)
 #[derive(Clone, Copy, Debug, PartialEq)]
 #[non_exhaustive]
 #[repr(u8)]
@@ -326,14 +322,15 @@ pub enum Version {
 ///
 /// # References
 ///
-/// * [Variant in RFC4122](http://tools.ietf.org/html/rfc4122#section-4.1.1)
+/// * [Variant Field in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-4.1)
 #[derive(Clone, Copy, Debug, PartialEq)]
 #[non_exhaustive]
 #[repr(u8)]
 pub enum Variant {
     /// Reserved by the NCS for backward compatibility.
     NCS = 0u8,
-    /// As described in the RFC4122 Specification (default).
+    /// As described in the RFC 9562 Specification (default).
+    /// (for backward compatibility it is not yet renamed)
     RFC4122,
     /// Reserved by Microsoft for backward compatibility.
     Microsoft,
@@ -498,7 +495,7 @@ impl Uuid {
     ///
     /// # References
     ///
-    /// * [Variant in RFC4122](http://tools.ietf.org/html/rfc4122#section-4.1.1)
+    /// * [Variant Field in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-4.1)
     pub const fn get_variant(&self) -> Variant {
         match self.as_bytes()[8] {
             x if x & 0x80 == 0x00 => Variant::NCS,
@@ -533,7 +530,7 @@ impl Uuid {
     ///
     /// # References
     ///
-    /// * [Version in RFC4122](https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.3)
+    /// * [Version Field in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-4.2)
     pub const fn get_version_num(&self) -> usize {
         (self.as_bytes()[6] >> 4) as usize
     }
@@ -563,7 +560,7 @@ impl Uuid {
     ///
     /// # References
     ///
-    /// * [Version in RFC4122](https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.3)
+    /// * [Version Field in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-4.2)
     pub const fn get_version(&self) -> Option<Version> {
         match self.get_version_num() {
             0 if self.is_nil() => Some(Version::Nil),

src/timestamp.rs

@@ -17,12 +17,13 @@
 //!
 //! # References
 //!
-//! * [Timestamp in RFC4122](https://www.rfc-editor.org/rfc/rfc4122#section-4.1.4)
-//! * [Timestamp in Draft RFC: New UUID Formats, Version 4](https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-04#section-6.1)
+//! * [UUID Version 1 in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-5.1)
+//! * [UUID Version 7 in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-5.7)
+//! * [Timestamp Considerations in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-6.1)
 
 use crate::Uuid;
 
-/// The number of 100 nanosecond ticks between the RFC4122 epoch
+/// The number of 100 nanosecond ticks between the RFC 9562 epoch
 /// (`1582-10-15 00:00:00`) and the Unix epoch (`1970-01-01 00:00:00`).
 pub const UUID_TICKS_BETWEEN_EPOCHS: u64 = 0x01B2_1DD2_1381_4000;
 
@@ -34,9 +35,8 @@ pub const UUID_TICKS_BETWEEN_EPOCHS: u64 = 0x01B2_1DD2_1381_4000;
 ///
 /// # References
 ///
-/// * [Timestamp in RFC4122](https://www.rfc-editor.org/rfc/rfc4122#section-4.1.4)
-/// * [Timestamp in Draft RFC: New UUID Formats, Version 4](https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-04#section-6.1)
-/// * [Clock Sequence in RFC4122](https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.5)
+/// * [Timestamp Considerations in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-6.1)
+/// * [UUID Generator States in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-6.3)
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct Timestamp {
     pub(crate) seconds: u64,
@@ -70,12 +70,12 @@ impl Timestamp {
         }
     }
 
-    /// Construct a `Timestamp` from an RFC4122 timestamp and counter, as used
+    /// Construct a `Timestamp` from an RFC 9562 timestamp and counter, as used
     /// in versions 1 and 6 UUIDs.
     ///
     /// # Overflow
     ///
-    /// If conversion from RFC4122 ticks to the internal timestamp format would overflow
+    /// If conversion from RFC 9562 ticks to the internal timestamp format would overflow
     /// it will wrap.
     pub const fn from_rfc4122(ticks: u64, counter: u16) -> Self {
         #[cfg(not(any(feature = "v1", feature = "v6")))]
@@ -97,7 +97,7 @@ impl Timestamp {
     ///
     /// # Overflow
     ///
-    /// If conversion from RFC4122 ticks to the internal timestamp format would overflow
+    /// If conversion from RFC 9562 ticks to the internal timestamp format would overflow
     /// it will wrap.
     pub fn from_unix(context: impl ClockSequence<Output = u16>, seconds: u64, nanos: u32) -> Self {
         #[cfg(not(any(feature = "v1", feature = "v6")))]
@@ -118,12 +118,12 @@ impl Timestamp {
         }
     }
 
-    /// Get the value of the timestamp as an RFC4122 timestamp and counter,
+    /// Get the value of the timestamp as an RFC 9562 timestamp and counter,
     /// as used in versions 1 and 6 UUIDs.
     ///
     /// # Overflow
     ///
-    /// If conversion from RFC4122 ticks to the internal timestamp format would overflow
+    /// If conversion from RFC 9562 ticks to the internal timestamp format would overflow
     /// it will wrap.
     #[cfg(any(feature = "v1", feature = "v6"))]
     pub const fn to_rfc4122(&self) -> (u64, u16) {
@@ -137,7 +137,7 @@ impl Timestamp {
     ///
     /// # Overflow
     ///
-    /// If conversion from RFC4122 ticks to the internal timestamp format would overflow
+    /// If conversion from RFC 9562 ticks to the internal timestamp format would overflow
     /// it will wrap.
     pub const fn to_unix(&self) -> (u64, u32) {
         (self.seconds, self.nanos)
@@ -329,7 +329,9 @@ fn now() -> (u64, u32) {
 ///
 /// # References
 ///
-/// * [Clock Sequence in RFC4122](https://datatracker.ietf.org/doc/html/rfc4122#section-4.1.5)
+/// * [UUID Version 1 in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-5.1)
+/// * [UUID Version 6 in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-5.6)
+/// * [UUID Generator States in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-6.3)
 pub trait ClockSequence {
     /// The type of sequence returned by this counter.
     type Output;
@@ -427,7 +429,7 @@ pub mod context {
         type Output = u16;
 
         fn generate_sequence(&self, _seconds: u64, _nanos: u32) -> Self::Output {
-            // RFC4122 reserves 2 bits of the clock sequence so the actual
+            // RFC 9562 reserves 2 bits for Variant field, so the actual `clock_seq`
             // maximum value is smaller than `u16::MAX`. Since we unconditionally
             // increment the clock sequence we want to wrap once it becomes larger
             // than what we can represent in a "u14". Otherwise there'd be patches

src/v1.rs

@@ -48,7 +48,7 @@ impl Uuid {
     /// # Examples
     ///
     /// A UUID can be created from a unix [`Timestamp`] with a
-    /// [`ClockSequence`]. RFC4122 requires the clock sequence
+    /// [`ClockSequence`]. RFC 9562 requires the clock sequence
     /// is seeded with a random value:
     ///
     /// ```
@@ -66,7 +66,7 @@ impl Uuid {
     /// );
     /// ```
     ///
-    /// The timestamp can also be created manually as per RFC4122:
+    /// The timestamp can also be created manually as per RFC 9562:
     ///
     /// ```
     /// # use uuid::{Uuid, Timestamp, Context, ClockSequence};
@@ -83,7 +83,7 @@ impl Uuid {
     ///
     /// # References
     ///
-    /// * [Version 1 UUIDs in RFC4122](https://www.rfc-editor.org/rfc/rfc4122#section-4.2)
+    /// * [UUID Version 1 in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-5.1)
     ///
     /// [`Timestamp`]: v1/struct.Timestamp.html
     /// [`ClockSequence`]: v1/trait.ClockSequence.html

src/v3.rs

@@ -27,7 +27,8 @@ impl Uuid {
     ///
     /// # References
     ///
-    /// * [Version 3 and 5 UUIDs in RFC4122](https://www.rfc-editor.org/rfc/rfc4122#section-4.3)
+    /// * [UUID Version 3 in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-5.3)
+    /// * [Name-Based UUID Generation in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-6.5)
     ///
     /// [`NAMESPACE_DNS`]: #associatedconstant.NAMESPACE_DNS
     /// [`NAMESPACE_OID`]: #associatedconstant.NAMESPACE_OID

src/v4.rs

@@ -26,7 +26,7 @@ impl Uuid {
     ///
     /// # References
     ///
-    /// * [Version 4 UUIDs in RFC4122](https://www.rfc-editor.org/rfc/rfc4122#section-4.4)
+    /// * [UUID Version 4 in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-5.4)
     ///
     /// [`getrandom`]: https://crates.io/crates/getrandom
     /// [from_random_bytes]: struct.Builder.html#method.from_random_bytes

src/v5.rs

@@ -26,7 +26,8 @@ impl Uuid {
     ///
     /// # References
     ///
-    /// * [Version 3 and 5 UUIDs in RFC4122](https://www.rfc-editor.org/rfc/rfc4122#section-4.3)
+    /// * [UUID Version 5 in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-5.5)
+    /// * [Name-Based UUID Generation in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-6.5)
     ///
     /// [`NAMESPACE_DNS`]: struct.Uuid.html#associatedconst.NAMESPACE_DNS
     /// [`NAMESPACE_OID`]: struct.Uuid.html#associatedconst.NAMESPACE_OID

src/v6.rs

@@ -49,7 +49,7 @@ impl Uuid {
     /// # Examples
     ///
     /// A UUID can be created from a unix [`Timestamp`] with a
-    /// [`ClockSequence`]. RFC4122 requires the clock sequence
+    /// [`ClockSequence`]. RFC 9562 requires the clock sequence
     /// is seeded with a random value:
     ///
     /// ```rust
@@ -66,7 +66,7 @@ impl Uuid {
     /// );
     /// ```
     ///
-    /// The timestamp can also be created manually as per RFC4122:
+    /// The timestamp can also be created manually as per RFC 9562:
     ///
     /// ```
     /// # use uuid::{Uuid, Timestamp, Context, ClockSequence};
@@ -84,7 +84,7 @@ impl Uuid {
     ///
     /// # References
     ///
-    /// * [Version 6 UUIDs in Draft RFC: New UUID Formats, Version 4](https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-04#section-5.1)
+    /// * [UUID Version 6 in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-5.6)
     ///
     /// [`Timestamp`]: timestamp/struct.Timestamp.html
     /// [`ClockSequence`]: timestamp/trait.ClockSequence.html

src/v7.rs

@@ -43,7 +43,7 @@ impl Uuid {
     ///
     /// # References
     ///
-    /// * [Version 7 UUIDs in Draft RFC: New UUID Formats, Version 4](https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-04#section-5.2)
+    /// * [UUID Version 7 in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-5.7)
     pub fn new_v7(ts: Timestamp) -> Self {
         let (secs, nanos) = ts.to_unix();
         let millis = (secs * 1000).saturating_add(nanos as u64 / 1_000_000);

src/v8.rs

@@ -24,7 +24,7 @@ impl Uuid {
     ///
     /// # References
     ///
-    /// * [Version 8 UUIDs in Draft RFC: New UUID Formats, Version 4](https://datatracker.ietf.org/doc/html/draft-peabody-dispatch-new-uuid-format-04#section-5.3)
+    /// * [UUID Version 8 in RFC 9562](https://www.ietf.org/rfc/rfc9562.html#section-5.8)
     pub fn new_v8(buf: [u8; 16]) -> Uuid {
         Builder::from_custom_bytes(buf).into_uuid()
     }