From 32500cdf37067fed91bd56a83d171bb4b1e36013 Mon Sep 17 00:00:00 2001 From: Peter MIKOLA Date: Fri, 3 May 2024 16:36:20 +0200 Subject: [PATCH 1/2] update docs to updated RFC (from 4122 to 9562) --- CONTRIBUTING.md | 4 ++-- README.md | 3 +-- src/builder.rs | 4 ++-- src/lib.rs | 21 +++++++++------------ src/timestamp.rs | 30 ++++++++++++++++-------------- src/v1.rs | 6 +++--- src/v3.rs | 3 ++- src/v4.rs | 2 +- src/v5.rs | 3 ++- src/v6.rs | 6 +++--- src/v7.rs | 2 +- src/v8.rs | 2 +- 12 files changed, 43 insertions(+), 43 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d2830b02..40e93b5f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -124,10 +124,10 @@ 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. [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 [u-r-l-o]: https://users.rust-lang.org [Discussions]: https://github.com/uuid-rs/uuid/discussions diff --git a/README.md b/README.md index 36d71836..2158207f 100644 --- a/README.md +++ b/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 diff --git a/src/builder.rs b/src/builder.rs index 2dd68a2c..5dfcaf6d 100644 --- a/src/builder.rs +++ b/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 /// diff --git a/src/lib.rs b/src/lib.rs index b5de83ca..42a0d80b 100644 --- a/src/lib.rs +++ b/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 { match self.get_version_num() { 0 if self.is_nil() => Some(Version::Nil), diff --git a/src/timestamp.rs b/src/timestamp.rs index 27112d17..46cd7ca9 100644 --- a/src/timestamp.rs +++ b/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, 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 diff --git a/src/v1.rs b/src/v1.rs index ad65c63d..cf5ba14d 100644 --- a/src/v1.rs +++ b/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 diff --git a/src/v3.rs b/src/v3.rs index ed356d42..84a1e260 100644 --- a/src/v3.rs +++ b/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 diff --git a/src/v4.rs b/src/v4.rs index 3c424730..2760c881 100644 --- a/src/v4.rs +++ b/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 diff --git a/src/v5.rs b/src/v5.rs index 265aa1a4..f29ce733 100644 --- a/src/v5.rs +++ b/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 diff --git a/src/v6.rs b/src/v6.rs index 25fe60e6..3485ef81 100644 --- a/src/v6.rs +++ b/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 diff --git a/src/v7.rs b/src/v7.rs index ea8f4746..70f8937b 100644 --- a/src/v7.rs +++ b/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); diff --git a/src/v8.rs b/src/v8.rs index b853ac71..dc3d19ef 100644 --- a/src/v8.rs +++ b/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() } From f1189474b94a4edd1bf92bbb5014b384319fc63f Mon Sep 17 00:00:00 2001 From: Peter MIKOLA Date: Wed, 15 May 2024 14:36:42 +0200 Subject: [PATCH 2/2] put obsolete RFC back to the doc for reference --- CONTRIBUTING.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 40e93b5f..930da90f 100644 --- a/CONTRIBUTING.md +++ b/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 9562][rfc-uuid] 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-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