Update documentation

doc/uuid/name_generator.adoc

@@ -7,74 +7,18 @@
 
 [source,c++]
 ----
+#include <boost/uuid/name_generator_sha1.hpp>
+#include <boost/uuid/name_generator_md5.hpp>
+
 namespace boost {
 namespace uuids {
 
-template<class NameHashProvider>
-class basic_name_generator {
-public:
-    typedef uuid result_type;
+// only provided for backward compatibility
 
-    explicit basic_name_generator(uuid const& namespace_uuid);
-
-    uuid operator()(const char* name) const;
-    uuid operator()(const wchar_t* name) const;
-    tempate <typename ch, typename char_traits, typename alloc>
-        uuid operator()(std::basic_string<ch, char_traits, alloc> const& name) const;
-    uuid operator()(void const* buffer, std::size_t byte_count) const;
-};
-
-typedef basic_name_generator<detail::md5> name_generator_md5;
-typedef basic_name_generator<detail::sha1> name_generator_sha1;
-typedef name_generator_sha1 name_generator; // deprecated
+typedef name_generator_sha1 name_generator;
 typedef name_generator_sha1 name_generator_latest;
 
 }} //namespace boost::uuids
 ----
 
-=== Name Generator
-
-RFC 4122 specifies that a name-based *uuid* is derived from content in a namespace. A *uuid* with identical content in an identical namespace shall yield the same *uuid* as long as the same hasing algorithm is used.
-
-==== Hashing Algorithms
-
-RFC 4122 defines two hashing mechanisms for *uuid* generation:
-
-* MD5
-* SHA1
-
-Since RFC 4122 was written, both of these hash algorithms have been rendered insecure. In anticipation of a new RFC for *uuid* arriving, `name_generator` has been deprecated, and replaced with:
-
-* `boost::uuids::name_generator_latest`
-* `boost::uuids::name_generator_md5`
-* `boost::uuids::name_generator_sha1`
-
-`name_generator`, while deprecated, remains a type alias for `name_generator_sha1` so the behavior is identical to previous releases. When the successor to SHA1 is chosen, it will be implemented under a new name similar to those above. If your application does not rely on stable hashing over time, you can use `name_generator_latest` to always use the latest hashing algorithm available.
-
-// todo: cross reference this
-Consumers are free to use their own hash provider as long as it satisfies the <<NameHashProvider>> concept.
-
-==== Namespaces
-
-There are four well-known namespaces defined in RFC https://tools.ietf.org/html/rfc4122#appendix-C[4122, Appendix C] which are defined as:
-
-```c++
-boost::uuids::ns::dns()     // == {6ba7b810-9dad-11d1-80b4-00c04fd430c8}
-boost::uuids::ns::url()     // == {6ba7b811-9dad-11d1-80b4-00c04fd430c8}
-boost::uuids::ns::oid()     // == {6ba7b812-9dad-11d1-80b4-00c04fd430c8}
-boost::uuids::ns::x500dn()  // == {6ba7b814-9dad-11d1-80b4-00c04fd430c8}
-```
-
-Of course, you are free to use your own namespace if you prefer. Here is an example of name generator usage:
-
-```c++
-boost::uuids::name_generator_sha1 gen(boost::uuids::ns::dns());
-boost::uuids::uuid udoc = gen("boost.org");
-std::cout << "boost.org uuid in dns namespace, sha1 version: " << udoc << std::endl;
-```
-
-produces the output:
-
-```txt
-boost.org uuid in dns namespace, sha1 version: 0043f363-bbb4-5369-840a-322df6ec1926
-```
+This header makes `name_generator_sha1` and `name_generator_md5` available and declares the compatibility aliases `name_generator` and `name_generator_latest`.

doc/uuid/name_generator_md5.adoc

@@ -0,0 +1,87 @@
+[#name_generator_md5]
+== <boost/uuid/name_generator_md5.hpp>
+
+:idprefix: name_generator_md5_
+
+=== Synopsis
+
+[source,c++]
+----
+#include <boost/uuid/namespaces.hpp>
+
+namespace boost {
+namespace uuids {
+
+class name_generator_md5
+{
+public:
+
+    typedef uuid result_type;
+
+    explicit name_generator_md5( uuid const& namespace_uuid ) noexcept;
+
+    uuid operator()( char const* name ) const noexcept;
+    uuid operator()( wchar_t const * name ) const noexcept;
+
+    template<class Ch, class Traits, class Alloc>
+      uuid operator()( std::basic_string<Ch, Traits, Alloc> const& name ) const noexcept;
+
+    uuid operator()( void const* buffer, std::size_t byte_count ) const noexcept;
+};
+
+}} //namespace boost::uuids
+----
+
+=== name_generator_md5
+
+The class `name_generator_md5` generates name-based version 3 UUIDs (using MD5 as the hashing algorithm.)
+
+There is no reason to use `name_generator_md5` except for compatibility. `name_generator_sha1` should be preferred in almost all cases.
+
+```cpp
+explicit name_generator_md5( uuid const& namespace_uuid );
+```
+
+Effects: :: Constructs a `name_generator_md5` that uses `namespace_uuid` as the namespace.
+
+```cpp
+uuid operator()( char const* name ) const;
+```
+
+Returns: :: A name-based UUID version 5 produced from a digest of the namespace passed to the constructor and the characters of the string `name`, treated as octets.
+
+Example: ::
++
+```cpp
+using namespace boost::uuids;
+
+name_generator_md5 gen( ns::dns() );
+
+uuid udoc = gen( "boost.org" );
+
+std::cout << "boost.org UUID in DNS namespace, MD5 version: " << udoc << std::endl;
+
+// Output:
+//   boost.org UUID in DNS namespace, MD5 version: 0043f363-bbb4-5369-840a-322df6ec1926
+```
+
+```cpp
+uuid operator()( wchar_t const * name ) const;
+```
+
+Returns: :: A name-based UUID version 5 produced from a digest of the namespace passed to the constructor and the string `name`, converted to octets formed from a little-endian serialization of the characters of `name` converted to `uint32_t`.
+
+```cpp
+template<class Ch, class Traits, class Alloc>
+  uuid operator()( std::basic_string<Ch, Traits, Alloc> const& name ) const;
+```
+
+Requires: :: `Ch` must be either `char` or `wchar_t`.
+
+Returns: :: As if `operator()( name.c_str() )`.
+
+```cpp
+uuid operator()( void const* buffer, std::size_t byte_count ) const;
+```
+
+Returns: :: A name-based UUID version 5 produced from a digest of the namespace passed to the constructor and the octets in the range `[(char const*)buffer, (char const*)buffer + byte_count)`.

doc/uuid/name_generator_sha1.adoc

@@ -0,0 +1,85 @@
+[#name_generator_sha1]
+== <boost/uuid/name_generator_sha1.hpp>
+
+:idprefix: name_generator_sha1_
+
+=== Synopsis
+
+[source,c++]
+----
+#include <boost/uuid/namespaces.hpp>
+
+namespace boost {
+namespace uuids {
+
+class name_generator_sha1
+{
+public:
+
+    typedef uuid result_type;
+
+    explicit name_generator_sha1( uuid const& namespace_uuid ) noexcept;
+
+    uuid operator()( char const* name ) const noexcept;
+    uuid operator()( wchar_t const * name ) const noexcept;
+
+    template<class Ch, class Traits, class Alloc>
+      uuid operator()( std::basic_string<Ch, Traits, Alloc> const& name ) const noexcept;
+
+    uuid operator()( void const* buffer, std::size_t byte_count ) const noexcept;
+};
+
+}} //namespace boost::uuids
+----
+
+=== name_generator_sha1
+
+The class `name_generator_sha1` generates name-based version 5 UUIDs (using SHA1 as the hashing algorithm.)
+
+```cpp
+explicit name_generator_sha1( uuid const& namespace_uuid );
+```
+
+Effects: :: Constructs a `name_generator_sha1` that uses `namespace_uuid` as the namespace.
+
+```cpp
+uuid operator()( char const* name ) const;
+```
+
+Returns: :: A name-based UUID version 5 produced from a digest of the namespace passed to the constructor and the characters of the string `name`, treated as octets.
+
+Example: ::
++
+```cpp
+using namespace boost::uuids;
+
+name_generator_sha1 gen( ns::dns() );
+
+uuid udoc = gen( "boost.org" );
+
+std::cout << "boost.org UUID in DNS namespace, SHA1 version: " << udoc << std::endl;
+
+// Output:
+//   boost.org UUID in DNS namespace, SHA1 version: 0043f363-bbb4-5369-840a-322df6ec1926
+```
+
+```cpp
+uuid operator()( wchar_t const * name ) const;
+```
+
+Returns: :: A name-based UUID version 5 produced from a digest of the namespace passed to the constructor and the string `name`, converted to octets formed from a little-endian serialization of the characters of `name` converted to `uint32_t`.
+
+```cpp
+template<class Ch, class Traits, class Alloc>
+  uuid operator()( std::basic_string<Ch, Traits, Alloc> const& name ) const;
+```
+
+Requires: :: `Ch` must be either `char` or `wchar_t`.
+
+Returns: :: As if `operator()( name.c_str() )`.
+
+```cpp
+uuid operator()( void const* buffer, std::size_t byte_count ) const;
+```
+
+Returns: :: A name-based UUID version 5 produced from a digest of the namespace passed to the constructor and the octets in the range `[(char const*)buffer, (char const*)buffer + byte_count)`.

doc/uuid/namespaces.adoc

@@ -0,0 +1,49 @@
+[#namespaces]
+== <boost/uuid/namespaces.hpp>
+
+:idprefix: namespaces_
+
+=== Synopsis
+
+[source,c++]
+----
+namespace boost {
+namespace uuids {
+namespace ns {
+
+uuid dns() noexcept;
+uuid url() noexcept;
+uuid oid() noexcept;
+uuid x500dn() noexcept;
+
+}}} //namespace boost::uuids::ns
+----
+
+=== Namespaces
+
+This header provides definitions of the four namespaces defined in https://tools.ietf.org/html/rfc4122#appendix-C[RFC 4122, Appendix C].
+
+```cpp
+uuid dns() noexcept;
+```
+
+Returns: :: The DNS namespace from RFC 4122, `{6ba7b810-9dad-11d1-80b4-00c04fd430c8}`.
+
+```cpp
+uuid url() noexcept;
+```
+
+Returns: :: The URL namespace from RFC 4122, `{6ba7b811-9dad-11d1-80b4-00c04fd430c8}`.
+
+
+```cpp
+uuid oid() noexcept;
+```
+
+Returns: :: The OID namespace from RFC 4122, `{6ba7b812-9dad-11d1-80b4-00c04fd430c8}`.
+
+```cpp
+uuid x500dn() noexcept;
+```
+
+Returns: :: The X.500 DN namespace from RFC 4122, `{6ba7b814-9dad-11d1-80b4-00c04fd430c8}`.

doc/uuid/reference.adoc

@@ -6,7 +6,9 @@ include::uuid.adoc[]
 include::uuid_generators.adoc[]
 include::nil_generator.adoc[]
 include::string_generator.adoc[]
+include::namespaces.adoc[]
+include::name_generator_sha1.adoc[]
+include::name_generator_md5.adoc[]
 include::name_generator.adoc[]
 include::random_generator.adoc[]
 include::uuid_io.adoc[]
-include::uuid_serialize.adoc[]

doc/uuid/uuid_serialize.adoc

@@ -1,22 +0,0 @@
-[#uuid_serialize]
-== <boost/uuid/uuid_serialize.hpp>
-
-:idprefix: uuid_serialize_
-
-=== Synopsis
-
-[source,c++]
-----
-namespace boost {
-namespace uuids {
-
-BOOST_CLASS_IMPLEMENTATION(boost::uuids::uuid, boost::serialization::primitive_type)
-
-}} // namespace boost::uuids
-----
-
-=== Serialization
-
-Serialization is accomplished with the https://www.boost.org/libs/serialization/doc/index.html[Boost Serialization] library. A *uuid* is serialized as a https://www.boost.org/libs/serialization/doc/serialization.html#primitiveoperators[primitive type], thus only the *uuid* value will be saved to/loaded from an archive.
-
-Include `boost/uuid/uuid_serialize.hpp` to enable serialization for **uuid**s.

include/boost/uuid/detail/basic_name_generator.hpp

@@ -10,6 +10,7 @@
 // accompanying file LICENSE_1_0.txt or copy at
 //  https://www.boost.org/LICENSE_1_0.txt)
 
+#include <boost/uuid/namespaces.hpp>
 #include <boost/uuid/uuid.hpp>
 #include <boost/uuid/detail/static_assert.hpp>
 #include <boost/config.hpp>
@@ -21,47 +22,61 @@ namespace boost {
 namespace uuids {
 namespace detail {
 
-//! \brief Generate a name based UUID using
-//!        the provided hashing algorithm that
-//!        implements the NameHashProvider concept.
 template<class HashAlgo>
 class basic_name_generator
 {
-  public:
+private:
+
+    uuid namespace_uuid_;
+
+public:
+
     typedef uuid result_type;
     typedef typename HashAlgo::digest_type digest_type;
 
-    explicit basic_name_generator(uuid const& namespace_uuid_)
-        : namespace_uuid(namespace_uuid_)
+    explicit basic_name_generator( uuid const& namespace_uuid ) noexcept
+        : namespace_uuid_( namespace_uuid )
     {}
 
-    uuid operator()(const char* name) const {
+    uuid operator()( char const* name ) const noexcept
+    {
         HashAlgo hash;
-        hash.process_bytes(namespace_uuid.begin(), namespace_uuid.size());
-        process_characters(hash, name, std::strlen(name));
-        return hash_to_uuid(hash);
+
+        hash.process_bytes( namespace_uuid_.begin(), namespace_uuid_.size() );
+        process_characters( hash, name, std::strlen( name ) );
+
+        return hash_to_uuid( hash );
     }
 
-    uuid operator()(const wchar_t* name) const {
+    uuid operator()( wchar_t const* name ) const noexcept
+    {
         HashAlgo hash;
-        hash.process_bytes(namespace_uuid.begin(), namespace_uuid.size());
-        process_characters(hash, name, std::wcslen(name));
-        return hash_to_uuid(hash);
+
+        hash.process_bytes( namespace_uuid_.begin(), namespace_uuid_.size() );
+        process_characters( hash, name, std::wcslen( name ) );
+
+        return hash_to_uuid( hash );
     }
 
-    template <typename ch, typename char_traits, typename alloc>
-    uuid operator()(std::basic_string<ch, char_traits, alloc> const& name) const {
+    template<class Ch, class Traits, class Alloc>
+    uuid operator()( std::basic_string<Ch, Traits, Alloc> const& name ) const noexcept
+    {
         HashAlgo hash;
-        hash.process_bytes(namespace_uuid.begin(), namespace_uuid.size());
-        process_characters(hash, name.c_str(), name.length());
-        return hash_to_uuid(hash);
+
+        hash.process_bytes( namespace_uuid_.begin(), namespace_uuid_.size() );
+        process_characters( hash, name.c_str(), name.length() );
+
+        return hash_to_uuid( hash );
     }
 
-    uuid operator()(void const* buffer, std::size_t byte_count) const {
+    uuid operator()( void const* buffer, std::size_t byte_count ) const noexcept
+    {
         HashAlgo hash;
-        hash.process_bytes(namespace_uuid.begin(), namespace_uuid.size());
-        hash.process_bytes(buffer, byte_count);
-        return hash_to_uuid(hash);
+
+        hash.process_bytes( namespace_uuid_.begin(), namespace_uuid_.size() );
+        hash.process_bytes( buffer, byte_count );
+
+        return hash_to_uuid( hash );
     }
 
 private:
@@ -70,29 +85,33 @@ private:
     // sizeof(wchar_t).  We want the name string on any
     // platform / compiler to generate the same uuid
     // except for char
-    template <typename char_type>
-    void process_characters(HashAlgo& hash, char_type const*const characters, std::size_t count) const {
-        BOOST_UUID_STATIC_ASSERT(sizeof(uint32_t) >= sizeof(char_type));
+    template<class Ch>
+    void process_characters( HashAlgo& hash, Ch const* characters, std::size_t count ) const noexcept
+    {
+        BOOST_UUID_STATIC_ASSERT( sizeof(std::uint32_t) >= sizeof(Ch) );
 
-        for (std::size_t i=0; i<count; i++) {
-            std::size_t c = characters[i];
-            hash.process_byte(static_cast<unsigned char>((c >>  0) & 0xFF));
-            hash.process_byte(static_cast<unsigned char>((c >>  8) & 0xFF));
-            hash.process_byte(static_cast<unsigned char>((c >> 16) & 0xFF));
-            hash.process_byte(static_cast<unsigned char>((c >> 24) & 0xFF));
+        for( std::size_t i = 0; i < count; ++i)
+        {
+            std::size_t c = characters[ i ];
+
+            hash.process_byte( static_cast<unsigned char>( (c >>  0) & 0xFF ) );
+            hash.process_byte( static_cast<unsigned char>( (c >>  8) & 0xFF ) );
+            hash.process_byte( static_cast<unsigned char>( (c >> 16) & 0xFF ) );
+            hash.process_byte( static_cast<unsigned char>( (c >> 24) & 0xFF ) );
         }
     }
 
-    void process_characters(HashAlgo& hash, char const*const characters, std::size_t count) const {
-        hash.process_bytes(characters, count);
+    void process_characters( HashAlgo& hash, char const* characters, std::size_t count ) const noexcept
+    {
+        hash.process_bytes( characters, count );
     }
 
-    uuid hash_to_uuid(HashAlgo& hash) const
+    uuid hash_to_uuid( HashAlgo& hash ) const noexcept
     {
         digest_type digest;
         hash.get_digest(digest);
 
-        BOOST_UUID_STATIC_ASSERT(sizeof(digest_type) >= 16);
+        BOOST_UUID_STATIC_ASSERT( sizeof(digest_type) >= 16 );
 
         uuid u;
         std::memcpy( u.data, digest, 16 );
@@ -108,44 +127,9 @@ private:
 
         return u;
     }
-
-private:
-    uuid namespace_uuid;
 };
 
 } // namespace detail
-
-namespace ns {
-
-BOOST_FORCEINLINE uuid dns() {
-    uuid result = {{
-        0x6b, 0xa7, 0xb8, 0x10, 0x9d, 0xad, 0x11, 0xd1 ,
-        0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8 }};
-    return result;
-}
-
-BOOST_FORCEINLINE uuid url() {
-    uuid result = {{
-        0x6b, 0xa7, 0xb8, 0x11, 0x9d, 0xad, 0x11, 0xd1 ,
-        0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8 }};
-    return result;
-}
-
-BOOST_FORCEINLINE uuid oid() {
-    uuid result = {{
-        0x6b, 0xa7, 0xb8, 0x12, 0x9d, 0xad, 0x11, 0xd1 ,
-        0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8 }};
-    return result;
-}
-
-BOOST_FORCEINLINE uuid x500dn() {
-    uuid result = {{
-        0x6b, 0xa7, 0xb8, 0x14, 0x9d, 0xad, 0x11, 0xd1 ,
-        0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8 }};
-    return result;
-}
-
-} // ns
 } // uuids
 } // boost
 

include/boost/uuid/namespaces.hpp

@@ -0,0 +1,49 @@
+#ifndef BOOST_UUID_NAMESPACES_HPP_INCLUDED
+#define BOOST_UUID_NAMESPACES_HPP_INCLUDED
+
+// Copyright 2010 Andy Tompkins
+// Copyright 2024 Peter Dimov
+// Distributed under the Boost Software License, Version 1.0.
+// https://www.boost.org/LICENSE_1_0.txt
+
+#include <boost/uuid/uuid.hpp>
+
+namespace boost {
+namespace uuids {
+namespace ns {
+
+inline uuid dns() noexcept
+{
+    uuid result = {{
+        0x6b, 0xa7, 0xb8, 0x10, 0x9d, 0xad, 0x11, 0xd1 ,
+        0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8 }};
+    return result;
+}
+
+inline uuid url() noexcept
+{
+    uuid result = {{
+        0x6b, 0xa7, 0xb8, 0x11, 0x9d, 0xad, 0x11, 0xd1 ,
+        0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8 }};
+    return result;
+}
+
+inline uuid oid() noexcept
+{
+    uuid result = {{
+        0x6b, 0xa7, 0xb8, 0x12, 0x9d, 0xad, 0x11, 0xd1 ,
+        0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8 }};
+    return result;
+}
+
+inline uuid x500dn() noexcept
+{
+    uuid result = {{
+        0x6b, 0xa7, 0xb8, 0x14, 0x9d, 0xad, 0x11, 0xd1 ,
+        0x80, 0xb4, 0x00, 0xc0, 0x4f, 0xd4, 0x30, 0xc8 }};
+    return result;
+}
+
+}}} // namespace boost::uuids::ns
+
+#endif // BOOST_UUID_NAMESPACES_HPP_INCLUDED