boost/uuid
2
0
Fork 0
mirror of https://github.com/boostorg/uuid.git synced 2026-01-19 04:42:16 +00:00
Code Issues Projects Releases Wiki Activity

Update documentation

Browse Source
This commit is contained in:
Peter Dimov
2024-05-01 02:44:40 +03:00
parent 9d564b0b67
commit 76771675bb
10 changed files with 107 additions and 120 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
doc/uuid.adoc
View File

@@ -12,6 +12,7 @@
include::uuid/introduction.adoc[]
include::uuid/changes.adoc[]
include::uuid/configuration.adoc[]
include::uuid/examples.adoc[]
include::uuid/reference.adoc[]

33
doc/uuid/basic_random_generator.adoc
View File

@@ -1,5 +1,5 @@
[#basic_random_generator]
== <boost/uuid/basic_random_generator.hpp>
== <boost/uuid/{zwsp}basic_random_generator.hpp>
:idprefix: basic_random_generator_
@@ -24,8 +24,9 @@ public:
typedef uuid result_type;
basic_random_generator();
explicit basic_random_generator(UniformRandomNumberGenerator& gen);
explicit basic_random_generator(UniformRandomNumberGenerator* pGen);
explicit basic_random_generator( UniformRandomNumberGenerator& gen );
explicit basic_random_generator( UniformRandomNumberGenerator* pGen );
result_type operator()();
};
@@ -35,13 +36,15 @@ public:
=== basic_random_generator
The class template `basic_random_generator` class generates a random number based UUID from a random number generator
The class template `basic_random_generator` generates a version 4 random number-based UUID from a random number generator
(one that conforms to the standard concept https://en.cppreference.com/w/cpp/named_req/UniformRandomBitGenerator[UniformRandomBitGenerator]
or to the Boost.Random concept https://www.boost.org/doc/libs/1_85_0/doc/html/boost_random/reference.html#boost_random.reference.concepts.uniform_random_number_generator[UniformRandomNumberGenerator]).
The default constructor will properly seed the random number generator if it requires the behavior for proper operation.
The default constructor will seed the random number generator with entropy obtained from `std::random_device`.
Additional constructors allow you to provide your own `UniformRandomNumberGenerator` and you are responsible for properly seeding it if necessary.
```cpp
```
basic_random_generator();
```
@@ -51,39 +54,39 @@ Effects: :: Value-initializes `g_` and initializes `p_` to `nullptr`.
`generate( first, last )` member function that fills the range
`[first, last)` using entropy obtained from `std::random_device`.
NOTE: Random number generators conforming to the standard https://en.cppreference.com/w/cpp/named_req/RandomNumberEngine[RandomNumberEngine]
NOTE: Random number generators conforming to the standard concept https://en.cppreference.com/w/cpp/named_req/RandomNumberEngine[RandomNumberEngine]
or the Boost.Random concept https://www.boost.org/doc/libs/1_85_0/doc/html/boost_random/reference.html#boost_random.reference.concepts.pseudo_random_number_generator[PseudoRandomNumberGenerator]
provide such `seed` member functions.
```cpp
explicit basic_random_generator(UniformRandomNumberGenerator& gen);
```
explicit basic_random_generator( UniformRandomNumberGenerator& gen );
```
Effects: :: Value-initializes `g_` and initializes `p_` to `&gen`.
```cpp
explicit basic_random_generator(UniformRandomNumberGenerator* pGen);
```
explicit basic_random_generator( UniformRandomNumberGenerator* pGen );
```
Effects: :: Value-initializes `g_` and initializes `p_` to `pGen`.
```cpp
```
result_type operator()();
```
Effects: :: Generates and returns a version 4 UUID using random numbers
obtained from `*p_`, if `p_ != nullptr`, and from `g_`, otherwise.
obtained from `*p_`, if `p_ != nullptr`, or from `g_`, otherwise.
Example: ::
+
```cpp
```
using namespace boost::uuids;
basic_random_generator<boost::mt19937> bulkgen;
for( int i = 0; i < 1000; ++i )
{
u = bulkgen();
uuid u = bulkgen();
// do something with u
}
```

55
doc/uuid/changes.adoc
View File

@@ -7,43 +7,26 @@
* {cpp}03 is no longer supported, a {cpp}11 compiler is required.
This includes GCC 4.8 or later, MSVC 14.0 or later, and MinGW-w64.
* Removed direct dependencies on Core, Io, Move, NumericConversion, StaticAssert,
TTI, Random, ContainerHash. The library now only has five Boost dependencies
(as opposed to 39 in Boost 1.85.)
* Removed direct dependencies on Core, Io, Move, NumericConversion, StaticAssert, TTI, Random, ContainerHash.
The library now only has five Boost dependencies (as opposed to 39 in Boost 1.85.)
* Moved `std::hash` support from `uuid_hash.hpp` to `uuid.hpp`.
* Moved serialization support from `uuid_serialize.hpp` to `uuid.hpp`.
* Added convenience header `<boost/uuid.hpp>`.
* Improved quality and speed of `hash_value`.
* Removed platform-specific entropy providers; the implementation now
uses `std::random_device` as the source of entropy.
* Since `basic_name_generator` had only two valid instantiations, both of
which are already provided (`name_generator_md5` and `name_generator_sha1`),
it was made a private implementation detail and is no longer part of the
public interface.
* While `name_generator` and `name_generator_latest` are still provided for
compatibility, their use is no longer encouraged.
* The definitions of the well-known RFC 4122 namespaces have been moved to
their own header, `boost/uuid/namespaces.hpp`.
* Improved the quality and speed of `hash_value`.
* Removed platform-specific entropy providers; the implementation now uses `std::random_device` as the source of entropy.
* Since `basic_name_generator` had only two valid instantiations, both of which are already provided (`name_generator_md5` and `name_generator_sha1`),
it was made a private implementation detail and is no longer part of the public interface.
* While `name_generator` and `name_generator_latest` are still provided for compatibility, their use is no longer encouraged.
* The definitions of the well-known RFC 4122 namespaces have been moved to their own header, `boost/uuid/namespaces.hpp`.
* Added `operator\<\=>`.
* The generic (non-SIMD) implementations of `is_nil`, `operator==`,
`operator<`, `swap`, and `operator\<\=>` now use `__uint128_t` operations
when that type is available, and `uint64_t` operations otherwise.
* `basic_random_generator` has been moved to its own header,
`boost/uuid/basic_random_generator.hpp`.
* `basic_random_generator` has been changed to hold the underlying generator
by value, to avoid dynamic allocation and restore copyability.
* `random_generator_pure` is now an alias for
`basic_random_generator<std::random_device>` and its use is discouraged.
* `random_generator_md19937` is now an alias for
`basic_random_generator<std::mt19937>` and its use is discouraged.
* `random_generator` now uses a cryptographically strong pseudorandom number
generator (ChaCha20), seeded with entropy from `std::random_device`. It's
the recommended way to generate version 4 UUIDs.
* Added `time_generator_v1`, a generator that produces version 1 time-based
UUIDs.
* Added `uuid_clock`, a `<chrono>`-compatible clock with an epoch and a
resolution as specified in RFC 4122.
* Accessors for the timestamp, the time point, the clock sequence, and the
node identifier have been added to `uuid`.
* Improved the `what()` strings of the `std::runtime_error` exceptions
thrown by `string_generator`.
* The generic (non-SIMD) implementations of `is_nil`, `operator==`, `operator<`, `swap`, and `operator\<\=>` now use `__uint128_t` operations when that type is available, and `uint64_t` operations otherwise.
* `basic_random_generator` has been moved to its own header, `boost/uuid/basic_random_generator.hpp`.
* `basic_random_generator` has been changed to hold the underlying generator by value, to avoid dynamic allocation and restore copyability.
* `random_generator_pure` is now an alias for `basic_random_generator<std::random_device>` and its use is discouraged.
* `random_generator_mt19937` is now an alias for `basic_random_generator<std::mt19937>` and its use is discouraged.
* `random_generator` now uses a cryptographically strong pseudorandom number generator (ChaCha20/12), seeded with entropy from `std::random_device`.
It's the recommended way to generate version 4 UUIDs.
* Added `time_generator_v1`, a generator that produces version 1 time-based UUIDs.
* Added `uuid_clock`, a `<chrono>`-compatible clock with an epoch and a resolution as specified in RFC 4122.
* Accessors for the timestamp, the time point, the clock sequence, and the node identifier have been added to `uuid`.
* Improved the `what()` strings of the `std::runtime_error` exceptions thrown by `string_generator`.

26
doc/uuid/name_generator_md5.adoc
View File

@@ -1,5 +1,5 @@
[#name_generator_md5]
== <boost/uuid/name_generator_md5.hpp>
== <boost/uuid/{zwsp}name_generator_md5.hpp>
:idprefix: name_generator_md5_
@@ -21,7 +21,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;
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;
@@ -38,21 +38,21 @@ The class `name_generator_md5` generates name-based version 3 UUIDs (using MD5 a
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.
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: ::
+
```cpp
```
using namespace boost::uuids;
name_generator_md5 gen( ns::dns() );
@@ -65,15 +65,15 @@ std::cout << "\"boost.org\" UUID in DNS namespace, MD5 version: " << udoc << std
// "boost.org" UUID in DNS namespace, MD5 version: 888eca9c-e655-31a2-a46b-a2a821f6b150
```
```cpp
uuid operator()( wchar_t const * name ) const;
```
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`.
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: ::
+
```cpp
```
using namespace boost::uuids;
name_generator_md5 gen( ns::dns() );
@@ -86,7 +86,7 @@ std::cout << "L\"boost.org\" UUID in DNS namespace, MD5 version: " << udoc << st
// L"boost.org" UUID in DNS namespace, MD5 version: 48149232-8cda-361b-b355-0bdb71d2cab3
```
```cpp
```
template<class Ch, class Traits, class Alloc>
uuid operator()( std::basic_string<Ch, Traits, Alloc> const& name ) const;
```
@@ -95,8 +95,8 @@ 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)`.
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`.

22
doc/uuid/name_generator_sha1.adoc
View File

@@ -1,5 +1,5 @@
[#name_generator_sha1]
== <boost/uuid/name_generator_sha1.hpp>
== <boost/uuid/{zwsp}name_generator_sha1.hpp>
:idprefix: name_generator_sha1_
@@ -21,7 +21,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;
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;
@@ -36,13 +36,13 @@ public:
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;
```
@@ -50,7 +50,7 @@ Returns: :: A name-based UUID version 5 produced from a digest of the namespace
Example: ::
+
```cpp
```
using namespace boost::uuids;
name_generator_sha1 gen( ns::dns() );
@@ -63,15 +63,15 @@ std::cout << "\"boost.org\" UUID in DNS namespace, SHA1 version: " << udoc << st
// "boost.org" UUID in DNS namespace, SHA1 version: 0043f363-bbb4-5369-840a-322df6ec1926
```
```cpp
uuid operator()( wchar_t const * name ) const;
```
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`.
Example: ::
+
```cpp
```
using namespace boost::uuids;
name_generator_sha1 gen( ns::dns() );
@@ -84,7 +84,7 @@ std::cout << "L\"boost.org\" UUID in DNS namespace, SHA1 version: " << udoc << s
// L"boost.org" UUID in DNS namespace, SHA1 version: c31c5016-3493-5dc2-8484-5813d495cc18
```
```cpp
```
template<class Ch, class Traits, class Alloc>
uuid operator()( std::basic_string<Ch, Traits, Alloc> const& name ) const;
```
@@ -93,8 +93,8 @@ 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)`.
Returns: :: A name-based UUID version 5 produced from a digest of the namespace passed to the constructor and the `byte_count` octets starting from `buffer`.

8
doc/uuid/namespaces.adoc
View File

@@ -23,26 +23,26 @@ uuid x500dn() noexcept;
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 UUID from RFC 4122, `{6ba7b810-9dad-11d1-80b4-00c04fd430c8}`.
```cpp
```
uuid url() noexcept;
```
Returns: :: The URL namespace UUID from RFC 4122, `{6ba7b811-9dad-11d1-80b4-00c04fd430c8}`.
```cpp
```
uuid oid() noexcept;
```
Returns: :: The OID namespace UUID from RFC 4122, `{6ba7b812-9dad-11d1-80b4-00c04fd430c8}`.
```cpp
```
uuid x500dn() noexcept;
```

8
doc/uuid/nil_generator.adoc
View File

@@ -25,7 +25,7 @@ uuid nil_uuid() noexcept;
The `nil_generator` class always generates a nil `uuid`.
```cpp
```
uuid operator()() const noexcept;
```
@@ -33,7 +33,7 @@ Returns: :: A nil UUID.
Example: ::
+
```cpp
```
using namespace boost::uuid;
nil_generator gen;
@@ -44,7 +44,7 @@ assert( u.is_nil() );
=== nil_uuid
```cpp
```
uuid nil_uuid() noexcept;
```
@@ -52,7 +52,7 @@ Returns: :: A nil UUID.
Example: ::
+
```cpp
```
using namespace boost::uuid;
uuid u = nil_uuid();

8
doc/uuid/random_generator.adoc
View File

@@ -1,5 +1,5 @@
[#random_generator]
== <boost/uuid/random_generator.hpp>
== <boost/uuid/{zwsp}random_generator.hpp>
:idprefix: random_generator_
@@ -44,14 +44,14 @@ typedef basic_random_generator<std::random_device> random_generator_pure;
The class `random_generator` generates UUIDs using a cryptographically strong random number generator, seeded with entropy from `std::random_device`.
It's the recommended way to generate version 4 random-based UUIDs.
```cpp
```
random_generator();
```
Effects: :: Initializes `g_`, an instance of a cryptographically strong
random number generator, using entropy obtained from `std::random_device`.
```cpp
```
result_type operator()();
```
@@ -60,7 +60,7 @@ Effects: :: Generates and returns a version 4 UUID using random numbers
Example: ::
+
```cpp
```
using namespace boost::uuids;
random_generator gen;

12
doc/uuid/string_generator.adoc
View File

@@ -50,7 +50,7 @@ hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh
Invalid input will generate a `std::runtime_error` exception.
```cpp
```
template<class Ch, class Traits, class Alloc>
uuid operator()( std::basic_string<Ch, Traits, Alloc> const& s ) const;
```
@@ -61,7 +61,7 @@ Effects: :: Parses the string `s` into a `uuid` and returns the result.
Example: ::
+
```cpp
```
using namespace boost::uuids;
string_generator gen;
@@ -70,7 +70,7 @@ uuid u1 = gen( std::string( "0123456789abcdef0123456789abcdef" ) );
uuid u2 = gen( std::wstring( L"01234567-89AB-CDEF-0123-456789ABCDEF" ) );
```
```cpp
```
uuid operator()( char const* s ) const;
uuid operator()( wchar_t const* s ) const;
```
@@ -79,7 +79,7 @@ Effects: :: Parses the string `s` into a `uuid` and returns the result.
Example: ::
+
```cpp
```
using namespace boost::uuids;
string_generator gen;
@@ -88,7 +88,7 @@ uuid u1 = gen( "{01234567-89ab-cdef-0123-456789abcdef}" );
uuid u2 = gen( L"01234567-89ab-cdef-0123-456789abcdef" );
```
```cpp
```
template<class CharIterator>
uuid operator()( CharIterator begin, CharIterator end ) const;
```
@@ -99,7 +99,7 @@ Effects: :: Parses the character sequence `[begin, end)` into a `uuid` and retur
Example: ::
+
```cpp
```
using namespace boost::uuids;
string_generator gen;

54
doc/uuid/uuid.adoc
View File

@@ -123,14 +123,14 @@ template<> struct std::hash<boost::uuids::uuid>;
Both constant and mutable iterators are provided.
```cpp
```
iterator begin() noexcept;
const_iterator begin() const noexcept;
```
Returns: :: `data + 0`.
```cpp
```
iterator end() noexcept;
const_iterator end() const noexcept;
```
@@ -139,7 +139,7 @@ Returns: :: `data + 16`.
Example: ::
+
```cpp
```
using namespace boost::uuids;
uuid u;
@@ -160,7 +160,7 @@ for( uuid::iterator it = u.begin(); it != u.end(); ++it )
The size of a `uuid` (in octets) is fixed at 16.
```cpp
```
constexpr size_type size() const noexcept;
```
```
@@ -171,7 +171,7 @@ Returns: :: `16`.
Example: ::
+
```cpp
```
using namespace boost::uuids;
uuid u;
@@ -182,7 +182,7 @@ static_assert( uuid::static_size() == 16 );
=== is_nil
```cpp
```
bool is_nil() const noexcept;
```
@@ -192,7 +192,7 @@ Returns: :: `true` when the `uuid` is equal to the nil UUID, `{00000000-0000-000
Three bits of a `uuid` determine the variant.
```cpp
```
variant_type variant() const noexcept;
```
@@ -202,7 +202,7 @@ Returns: :: The UUID variant; usually `variant_rfc_4122` for non-nil UUIDs.
Four bits of a `uuid` determine the version, that is the mechanism used to generate the `uuid`.
```cpp
```
version_type version() const noexcept;
```
@@ -210,27 +210,27 @@ Returns: :: The UUID version.
=== Time-based Fields
```cpp
```
timestamp_type timestamp_v1() const noexcept;
```
Returns: :: The UUIDv1 timestamp (number of 100ns intervals since 00:00:00.00, 15 October 1582).
The value is only meaningful for version 1 UUIDs.
```cpp
```
uuid_clock::time_point time_point_v1() const noexcept;
```
Returns: :: The timestamp of a version 1 UUID, expressed as a `<chrono>` `time_point`.
```cpp
```
clock_seq_type clock_seq() const noexcept;
```
Returns: :: The clock sequence of a time-based UUID.
The value is only meaningful for time-based UUIDs (version 1 and version 6).
```cpp
```
node_type node_identifier() const noexcept;
```
@@ -239,7 +239,7 @@ Returns: :: The node identifier of a time-based UUID.
=== Swap
```cpp
```
void swap( uuid& rhs ) noexcept;
```
@@ -247,43 +247,43 @@ Effects: :: Exchanges the values of `*this` and `rhs`.
=== Operators
```cpp
```
bool operator==( uuid const& lhs, uuid const& rhs ) noexcept;
```
Returns: :: As if `std::memcmp( lhs.data, rhs.data, 16 ) == 0`.
```cpp
```
bool operator!=( uuid const& lhs, uuid const& rhs ) noexcept;
```
Returns: :: `!(lhs == rhs)`.
```cpp
```
bool operator<( uuid const& lhs, uuid const& rhs ) noexcept;
```
Returns: :: As if `std::memcmp( lhs.data, rhs.data, 16 ) < 0`.
```cpp
```
bool operator>( uuid const& lhs, uuid const& rhs ) noexcept;
```
Returns: :: `rhs < lhs`.
```cpp
```
bool operator<=( uuid const& lhs, uuid const& rhs ) noexcept;
```
Returns: :: `!(rhs < lhs)`.
```cpp
```
bool operator>=( uuid const& lhs, uuid const& rhs ) noexcept;
```
Returns: :: `!(lhs < rhs)`.
```cpp
```
std::strong_ordering operator<=>( uuid const& lhs, uuid const& rhs ) noexcept;
```
@@ -291,7 +291,7 @@ Returns: :: As if `std::memcmp( lhs.data, rhs.data, 16 ) \<\=> 0`.
=== Free Swap
```cpp
```
void swap( uuid& lhs, uuid& rhs ) noexcept;
```
@@ -301,7 +301,7 @@ Effects: :: `lhs.swap( rhs );`
This function allows instances of `uuid` to be used with https://www.boost.org/doc/libs/release/libs/container_hash/doc/html/hash.html#ref_boostcontainer_hashhash_hpp[boost::hash].
```cpp
```
std::size_t hash_value( uuid const& u ) noexcept;
```
@@ -309,13 +309,13 @@ Returns: :: The hash value of the `uuid`.
Example: ::
+
```cpp
```
boost::unordered_flat_map<boost::uuids::uuid, int> hash_map;
```
=== Serialization
```cpp
```
BOOST_CLASS_IMPLEMENTATION(boost::uuids::uuid, boost::serialization::primitive_type)
```
@@ -325,14 +325,14 @@ BOOST_CLASS_IMPLEMENTATION(boost::uuids::uuid, boost::serialization::primitive_t
This specialization allows instances of `uuid` to be used with `std::hash`.
```cpp
```
template<> struct std::hash<boost::uuids::uuid>
{
std::size_t operator()( boost::uuids::uuid const& v ) const noexcept;
}
```
```cpp
```
std::size_t operator()( boost::uuids::uuid const& v ) const noexcept;
```
@@ -340,6 +340,6 @@ Returns: :: `boost::uuids::hash_value( v )`.
Example: ::
+
```cpp
```
std::unordered_map<boost::uuids::uuid, int> hash_map;
```