diff --git a/doc/uuid/name_generator_md5.adoc b/doc/uuid/name_generator_md5.adoc index 89a29b9..c3846e7 100644 --- a/doc/uuid/name_generator_md5.adoc +++ b/doc/uuid/name_generator_md5.adoc @@ -20,8 +20,7 @@ public: 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 uuid operator()( Ch const* name ) const noexcept; template uuid operator()( std::basic_string const& name ) const noexcept; @@ -34,22 +33,12 @@ public: === name_generator_md5 -The class `name_generator_md5` generates name-based version 3 UUIDs (using MD5 as the hashing algorithm.) +The class `name_generator_md5` generates name-based version 3 UUIDs, using MD5 as the hashing algorithm. + +Its interface and its operation are the same as those of `name_generator_sha1`, with the only difference being that it uses MD5 instead of SHA1. There is no reason to use `name_generator_md5` except for compatibility. `name_generator_sha1` should be preferred in almost all cases. -``` -explicit name_generator_md5( uuid const& namespace_uuid ); -``` - -Effects: :: Constructs a `name_generator_md5` that uses `namespace_uuid` as the namespace. - -``` -uuid operator()( char const* name ) const; -``` - -Returns: :: A name-based UUID version 3 produced from a digest of the namespace passed to the constructor and the characters of the string `name`, treated as octets. - Example: :: + ``` @@ -57,46 +46,24 @@ using namespace boost::uuids; name_generator_md5 gen( ns::dns() ); -uuid udoc = gen( "boost.org" ); +uuid u1 = gen( "boost.org" ); -std::cout << "\"boost.org\" UUID in DNS namespace, MD5 version: " << udoc << std::endl; +std::cout << "\"boost.org\" UUID in DNS namespace, MD5 version: " << u1 << std::endl; // Output: // "boost.org" UUID in DNS namespace, MD5 version: 888eca9c-e655-31a2-a46b-a2a821f6b150 -``` -``` -uuid operator()( wchar_t const* name ) const; -``` +uuid u2 = gen( L"boost.org" ); -Returns: :: A name-based UUID version 3 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`. - -Example: :: -+ -``` -using namespace boost::uuids; - -name_generator_md5 gen( ns::dns() ); - -uuid udoc = gen( L"boost.org" ); - -std::cout << "L\"boost.org\" UUID in DNS namespace, MD5 version: " << udoc << std::endl; +std::cout << "L\"boost.org\" UUID in DNS namespace, MD5 version: " << u2 << std::endl; // Output: // L"boost.org" UUID in DNS namespace, MD5 version: 48149232-8cda-361b-b355-0bdb71d2cab3 -``` -``` -template - uuid operator()( std::basic_string const& name ) const; -``` +uuid u3 = gen( u"boost.org" ); -Requires: :: `Ch` must be either `char` or `wchar_t`. - -Returns: :: As if `operator()( name.c_str() )`. +std::cout << "u\"boost.org\" UUID in DNS namespace, MD5 version: " << u3 << std::endl; +// Output: +// u"boost.org" UUID in DNS namespace, MD5 version: 888eca9c-e655-31a2-a46b-a2a821f6b150 ``` -uuid operator()( void const* buffer, std::size_t byte_count ) const; -``` - -Returns: :: A name-based UUID version 3 produced from a digest of the namespace passed to the constructor and the `byte_count` octets starting from `buffer`. diff --git a/doc/uuid/name_generator_sha1.adoc b/doc/uuid/name_generator_sha1.adoc index 0d9f87a..a34f8ae 100644 --- a/doc/uuid/name_generator_sha1.adoc +++ b/doc/uuid/name_generator_sha1.adoc @@ -20,8 +20,7 @@ public: 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 uuid operator()( Ch const* name ) const noexcept; template uuid operator()( std::basic_string const& name ) const noexcept; @@ -34,7 +33,7 @@ public: === name_generator_sha1 -The class `name_generator_sha1` generates name-based version 5 UUIDs (using SHA1 as the hashing algorithm.) +The class `name_generator_sha1` generates name-based version 5 UUIDs, using SHA1 as the hashing algorithm. ``` explicit name_generator_sha1( uuid const& namespace_uuid ); @@ -43,10 +42,18 @@ explicit name_generator_sha1( uuid const& namespace_uuid ); Effects: :: Constructs a `name_generator_sha1` that uses `namespace_uuid` as the namespace. ``` -uuid operator()( char const* name ) const; +template uuid operator()( Ch const* name ) const noexcept; ``` -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. +Requires: :: `Ch` must be one of `char`, `wchar_t`, `char8_t`, `char16_t`, or `char32_t`. + +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`, converted to octets. + +Remarks: :: The characters of `name` are converted to a sequence of octets in the following manner: ++ +* If `Ch` is `char` or `char8_t`, the characters are processed as octets directly; +* If `Ch` is `wchar_t`, the characters are converted to `uint32_t` and then serialized to four octets each using little-endian representation; +* Otherwise, the character sequence is converted to UTF-8 and the result is processed as octets. Example: :: + @@ -55,33 +62,26 @@ using namespace boost::uuids; name_generator_sha1 gen( ns::dns() ); -uuid udoc = gen( "boost.org" ); +uuid u1 = gen( "boost.org" ); -std::cout << "\"boost.org\" UUID in DNS namespace, SHA1 version: " << udoc << std::endl; +std::cout << "\"boost.org\" UUID in DNS namespace, SHA1 version: " << u1 << std::endl; // Output: // "boost.org" UUID in DNS namespace, SHA1 version: 0043f363-bbb4-5369-840a-322df6ec1926 -``` -``` -uuid operator()( wchar_t const* name ) const; -``` +uuid u2 = gen( L"boost.org" ); -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`. - -Example: :: -+ -``` -using namespace boost::uuids; - -name_generator_sha1 gen( ns::dns() ); - -uuid udoc = gen( L"boost.org" ); - -std::cout << "L\"boost.org\" UUID in DNS namespace, SHA1 version: " << udoc << std::endl; +std::cout << "L\"boost.org\" UUID in DNS namespace, SHA1 version: " << u2 << std::endl; // Output: // L"boost.org" UUID in DNS namespace, SHA1 version: c31c5016-3493-5dc2-8484-5813d495cc18 + +uuid u3 = gen( u"boost.org" ); + +std::cout << "u\"boost.org\" UUID in DNS namespace, SHA1 version: " << u3 << std::endl; + +// Output: +// u"boost.org" UUID in DNS namespace, SHA1 version: 0043f363-bbb4-5369-840a-322df6ec1926 ``` ``` @@ -89,7 +89,7 @@ template uuid operator()( std::basic_string const& name ) const; ``` -Requires: :: `Ch` must be either `char` or `wchar_t`. +Requires: :: `Ch` must be one of `char`, `wchar_t`, `char8_t`, `char16_t`, or `char32_t`. Returns: :: As if `operator()( name.c_str() )`.