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
2025-12-26 21:33:11 +02:00
parent c8f97785a4
commit b945f3ee23
3 changed files with 117 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
doc/uuid/changes.adoc
View File

@@ -8,6 +8,7 @@
* Added `from_chars` to `boost/uuid/uuid_io.hpp`.
* Added a `noexcept` `operator()` overload to `string_generator`.
* `string_generator` now supports the Unicode character types in addition to `char` and `wchar_t`.
* Most `uuid` accessors, operations, and `to_chars` are now `constexpr` when possible (on {cpp}14 and higher and on recent compilers).
== Changes in Boost 1.90.0

158
doc/uuid/uuid.adoc
View File

@@ -20,8 +20,8 @@ public:
// constructors
uuid() = default;
uuid( std::uint8_t const (&r)[ 16 ] );
constexpr uuid() = default;
constexpr uuid( std::uint8_t const (&r)[ 16 ] );
// iteration
@@ -36,16 +36,16 @@ public:
using size_type = std::size_t;
using difference_type = std::ptrdiff_t;
iterator begin() noexcept;
iterator end() noexcept;
constexpr iterator begin() noexcept;
constexpr iterator end() noexcept;
const_iterator begin() const noexcept;
const_iterator end() const noexcept;
constexpr const_iterator begin() const noexcept;
constexpr const_iterator end() const noexcept;
// data
std::uint8_t* data() noexcept;
std::uint8_t const* data() const noexcept;
constexpr std::uint8_t* data() noexcept;
constexpr std::uint8_t const* data() const noexcept;
// size
@@ -54,7 +54,7 @@ public:
// is_nil
bool is_nil() const noexcept;
constexpr bool is_nil() const noexcept;
// variant
@@ -66,7 +66,7 @@ public:
variant_future // future definition
};
variant_type variant() const noexcept;
constexpr variant_type variant() const noexcept;
// version
@@ -83,7 +83,7 @@ public:
version_custom_v8 = 8
};
version_type version() const noexcept;
constexpr version_type version() const noexcept;
// time-based fields
@@ -91,44 +91,44 @@ public:
using clock_seq_type = std::uint16_t;
using node_type = std::array<std::uint8_t, 6>;
timestamp_type timestamp_v1() const noexcept;
constexpr timestamp_type timestamp_v1() const noexcept;
uuid_clock::time_point time_point_v1() const noexcept;
timestamp_type timestamp_v6() const noexcept;
constexpr timestamp_type timestamp_v6() const noexcept;
uuid_clock::time_point time_point_v6() const noexcept;
timestamp_type timestamp_v7() const noexcept;
constexpr timestamp_type timestamp_v7() const noexcept;
std::chrono::time_point<std::chrono::system_clock, std::chrono::milliseconds>
time_point_v7() const noexcept;
clock_seq_type clock_seq() const noexcept;
node_type node_identifier() const noexcept;
constexpr clock_seq_type clock_seq() const noexcept;
constexpr node_type node_identifier() const noexcept;
// swap
void swap( uuid& rhs ) noexcept;
constexpr void swap( uuid& rhs ) noexcept;
};
// operators
bool operator==( uuid const& lhs, uuid const& rhs ) noexcept;
bool operator!=( uuid const& lhs, uuid const& rhs ) noexcept;
constexpr bool operator==( uuid const& lhs, uuid const& rhs ) noexcept;
constexpr bool operator!=( uuid const& lhs, uuid const& rhs ) noexcept;
bool operator<( uuid const& lhs, uuid const& rhs ) noexcept;
bool operator>( uuid const& lhs, uuid const& rhs ) noexcept;
bool operator<=( uuid const& lhs, uuid const& rhs ) noexcept;
bool operator>=( uuid const& lhs, uuid const& rhs ) noexcept;
constexpr bool operator<( uuid const& lhs, uuid const& rhs ) noexcept;
constexpr bool operator>( uuid const& lhs, uuid const& rhs ) noexcept;
constexpr bool operator<=( uuid const& lhs, uuid const& rhs ) noexcept;
constexpr bool operator>=( uuid const& lhs, uuid const& rhs ) noexcept;
std::strong_ordering operator<=>( uuid const& lhs, uuid const& rhs ) noexcept;
constexpr std::strong_ordering operator<=>( uuid const& lhs, uuid const& rhs ) noexcept;
// free swap
void swap( uuid& lhs, uuid& rhs ) noexcept;
constexpr void swap( uuid& lhs, uuid& rhs ) noexcept;
// hash_value
std::size_t hash_value( uuid const& u ) noexcept;
constexpr std::size_t hash_value( uuid const& u ) noexcept;
}} // namespace boost::uuids
@@ -144,7 +144,7 @@ template<> struct std::hash<boost::uuids::uuid>;
=== Constructors
```
uuid() = default;
constexpr uuid() = default;
```
Effects: :: Zero-initializes `data_`.
@@ -152,11 +152,13 @@ Effects: :: Zero-initializes `data_`.
Postconditions: :: `is_nil()`.
```
uuid( std::uint8_t const (&r)[ 16 ] );
constexpr uuid( std::uint8_t const (&r)[ 16 ] );
```
Effects: :: Initializes the elements of `data_` from the corresponding elements of `r`.
NOTE: This constructor is only `constexpr` under {cpp}14 or later.
Example: ::
+
```
@@ -168,19 +170,27 @@ uuid dns = {{ 0x6b, 0xa7, 0xb8, 0x10, 0x9d, 0xad, 0x11, 0xd1, 0x80, 0xb4, 0x00,
Both constant and mutable iterators are provided.
```
iterator begin() noexcept;
const_iterator begin() const noexcept;
constexpr iterator begin() noexcept;
```
```
constexpr const_iterator begin() const noexcept;
```
Returns: :: `data()`.
NOTE: The non-const overload is only `constexpr` under {cpp}14 or later.
```
iterator end() noexcept;
const_iterator end() const noexcept;
constexpr iterator end() noexcept;
```
```
constexpr const_iterator end() const noexcept;
```
Returns: :: `data() + size()`.
NOTE: The non-const overload is only `constexpr` under {cpp}14 or later.
Example: ::
+
```
@@ -203,14 +213,16 @@ for( uuid::iterator it = u.begin(); it != u.end(); ++it )
=== Data
```
std::uint8_t* data() noexcept;
constexpr std::uint8_t* data() noexcept;
```
```
std::uint8_t const* data() const noexcept;
constexpr std::uint8_t const* data() const noexcept;
```
Returns: :: `data_`.
NOTE: The non-const overload is only `constexpr` under {cpp}14 or later.
=== Size
The size of a `uuid` (in octets) is fixed at 16.
@@ -238,40 +250,48 @@ static_assert( uuid::static_size() == 16 );
=== is_nil
```
bool is_nil() const noexcept;
constexpr bool is_nil() const noexcept;
```
Returns: :: `true` when the `uuid` is equal to the nil UUID, `{00000000-0000-0000-0000-000000000000}`, otherwise `false`.
NOTE: This function is only `constexpr` under {cpp}14 or later, and under GCC 9 or later, Clang 9 or later, or MSVC 14.25 or later.
=== Variant
Three bits of a `uuid` determine the variant.
```
variant_type variant() const noexcept;
constexpr variant_type variant() const noexcept;
```
Returns: :: The UUID variant; usually `variant_rfc_4122` for non-nil UUIDs.
NOTE: This function is only `constexpr` under {cpp}14 or later.
=== Version
Four bits of a `uuid` determine the version, that is the mechanism used to generate the `uuid`.
```
version_type version() const noexcept;
constexpr version_type version() const noexcept;
```
Returns: :: The UUID version.
NOTE: This function is only `constexpr` under {cpp}14 or later.
=== Time-based Fields
```
timestamp_type timestamp_v1() const noexcept;
constexpr 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.
NOTE: This function is only `constexpr` under {cpp}14 or later.
```
uuid_clock::time_point time_point_v1() const noexcept;
```
@@ -279,12 +299,14 @@ uuid_clock::time_point time_point_v1() const noexcept;
Returns: :: The timestamp of a version 1 UUID, expressed as a `<chrono>` `time_point`.
```
timestamp_type timestamp_v6() const noexcept;
constexpr timestamp_type timestamp_v6() const noexcept;
```
Returns: :: The UUIDv6 timestamp (number of 100ns intervals since 00:00:00.00, 15 October 1582).
The value is only meaningful for version 6 UUIDs.
NOTE: This function is only `constexpr` under {cpp}14 or later.
```
uuid_clock::time_point time_point_v6() const noexcept;
```
@@ -292,12 +314,14 @@ uuid_clock::time_point time_point_v6() const noexcept;
Returns: :: The timestamp of a version 6 UUID, expressed as a `<chrono>` `time_point`.
```
timestamp_type timestamp_v7() const noexcept;
constexpr timestamp_type timestamp_v7() const noexcept;
```
Returns: :: The UUIDv7 timestamp (number of milliseconds since the Unix epoch - midnight 1 Jan 1970 UTC).
The value is only meaningful for version 7 UUIDs.
NOTE: This function is only `constexpr` under {cpp}14 or later.
```
std::chrono::time_point<std::chrono::system_clock, std::chrono::milliseconds>
time_point_v7() const noexcept;
@@ -306,89 +330,113 @@ std::chrono::time_point<std::chrono::system_clock, std::chrono::milliseconds>
Returns: :: The timestamp of a version 7 UUID, expressed as a `<chrono>` `time_point`.
```
clock_seq_type clock_seq() const noexcept;
constexpr 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).
NOTE: This function is only `constexpr` under {cpp}14 or later.
```
node_type node_identifier() const noexcept;
constexpr node_type node_identifier() const noexcept;
```
Returns: :: The node identifier of a time-based UUID.
The value is only meaningful for time-based UUIDs (version 1 and version 6).
NOTE: This function is only `constexpr` under {cpp}14 or later.
=== Swap
```
void swap( uuid& rhs ) noexcept;
constexpr void swap( uuid& rhs ) noexcept;
```
Effects: :: Exchanges the values of `*this` and `rhs`.
NOTE: This function is only `constexpr` under {cpp}14 or later.
=== Operators
```
bool operator==( uuid const& lhs, uuid const& rhs ) noexcept;
constexpr bool operator==( uuid const& lhs, uuid const& rhs ) noexcept;
```
Returns: :: As if `std::memcmp( lhs.data(), rhs.data(), 16 ) == 0`.
NOTE: This function is only `constexpr` under {cpp}14 or later, and under GCC 9 or later, Clang 9 or later, or MSVC 14.25 or later.
```
bool operator!=( uuid const& lhs, uuid const& rhs ) noexcept;
constexpr bool operator!=( uuid const& lhs, uuid const& rhs ) noexcept;
```
Returns: :: `!(lhs == rhs)`.
NOTE: This function is only `constexpr` under {cpp}14 or later, and under GCC 9 or later, Clang 9 or later, or MSVC 14.25 or later.
```
bool operator<( uuid const& lhs, uuid const& rhs ) noexcept;
constexpr bool operator<( uuid const& lhs, uuid const& rhs ) noexcept;
```
Returns: :: As if `std::memcmp( lhs.data(), rhs.data(), 16 ) < 0`.
NOTE: This function is only `constexpr` under {cpp}14 or later, and under GCC 9 or later, Clang 9 or later, or MSVC 14.25 or later.
```
bool operator>( uuid const& lhs, uuid const& rhs ) noexcept;
constexpr bool operator>( uuid const& lhs, uuid const& rhs ) noexcept;
```
Returns: :: `rhs < lhs`.
NOTE: This function is only `constexpr` under {cpp}14 or later, and under GCC 9 or later, Clang 9 or later, or MSVC 14.25 or later.
```
bool operator<=( uuid const& lhs, uuid const& rhs ) noexcept;
constexpr bool operator<=( uuid const& lhs, uuid const& rhs ) noexcept;
```
Returns: :: `!(rhs < lhs)`.
NOTE: This function is only `constexpr` under {cpp}14 or later, and under GCC 9 or later, Clang 9 or later, or MSVC 14.25 or later.
```
bool operator>=( uuid const& lhs, uuid const& rhs ) noexcept;
constexpr bool operator>=( uuid const& lhs, uuid const& rhs ) noexcept;
```
Returns: :: `!(lhs < rhs)`.
NOTE: This function is only `constexpr` under {cpp}14 or later, and under GCC 9 or later, Clang 9 or later, or MSVC 14.25 or later.
```
std::strong_ordering operator<=>( uuid const& lhs, uuid const& rhs ) noexcept;
constexpr std::strong_ordering operator<=>( uuid const& lhs, uuid const& rhs ) noexcept;
```
Returns: :: As if `std::memcmp( lhs.data(), rhs.data(), 16 ) \<\=> 0`.
NOTE: This function is only `constexpr` under {cpp}14 or later, and under GCC 9 or later, Clang 9 or later, or MSVC 14.25 or later.
=== Free Swap
```
void swap( uuid& lhs, uuid& rhs ) noexcept;
constexpr void swap( uuid& lhs, uuid& rhs ) noexcept;
```
Effects: :: `lhs.swap( rhs );`
NOTE: This function is only `constexpr` under {cpp}14 or later.
=== hash_value
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].
```
std::size_t hash_value( uuid const& u ) noexcept;
constexpr std::size_t hash_value( uuid const& u ) noexcept;
```
Returns: :: The hash value of the `uuid`.
NOTE: This function is only `constexpr` under {cpp}14 or later.
Example: ::
+
```
@@ -410,16 +458,18 @@ This specialization allows instances of `uuid` to be used with `std::hash`.
```
template<> struct std::hash<boost::uuids::uuid>
{
std::size_t operator()( boost::uuids::uuid const& v ) const noexcept;
constexpr std::size_t operator()( boost::uuids::uuid const& v ) const noexcept;
}
```
```
std::size_t operator()( boost::uuids::uuid const& v ) const noexcept;
constexpr std::size_t operator()( boost::uuids::uuid const& v ) const noexcept;
```
Returns: :: `boost::uuids::hash_value( v )`.
NOTE: This function is only `constexpr` under {cpp}14 or later.
Example: ::
+
```

18
doc/uuid/uuid_io.adoc
View File

@@ -25,13 +25,13 @@ template<class Ch, class Traits>
// to_chars
template<class OutputIterator>
OutputIterator to_chars( uuid const& u, OutputIterator out );
constexpr OutputIterator to_chars( uuid const& u, OutputIterator out );
template<class Ch>
bool to_chars( uuid const& u, Ch* first, Ch* last ) noexcept;
constexpr bool to_chars( uuid const& u, Ch* first, Ch* last ) noexcept;
template<class Ch, std::size_t N>
Ch* to_chars( uuid const& u, Ch (&buffer)[ N ] ) noexcept;
constexpr Ch* to_chars( uuid const& u, Ch (&buffer)[ N ] ) noexcept;
// to_string
@@ -136,11 +136,13 @@ assert( u1 == u3 );
```
template<class OutputIterator>
OutputIterator to_chars( uuid const& u, OutputIterator out );
constexpr OutputIterator to_chars( uuid const& u, OutputIterator out );
```
Effects: :: Outputs the string representation of `u` (exactly 36 characters of type `char`) to the output iterator `out`.
NOTE: This function is only `constexpr` under {cpp}14 or later, and under GCC 9 or later, Clang 9 or later, or MSVC 14.25 or later.
Example: ::
+
```
@@ -155,13 +157,15 @@ to_chars( u, std::back_inserter( v ) );
```
template<class Ch>
bool to_chars( uuid const& u, Ch* first, Ch* last ) noexcept;
constexpr bool to_chars( uuid const& u, Ch* first, Ch* last ) noexcept;
```
Requires: :: `Ch` must be a character type (one of `char`, `wchar_t`, `char8_t`, `char16_t`, `char32_t`).
Effects: :: If `last - first >= 36`, writes the string representation of `u` (exactly 36 characters, not null terminated) into the buffer starting at `first` and returns `true`. Otherwise, returns `false`.
NOTE: This function is only `constexpr` under {cpp}14 or later, and under GCC 9 or later, Clang 9 or later, or MSVC 14.25 or later.
Example: ::
+
```
@@ -179,7 +183,7 @@ std::cout << std::string( buf, 36 ) << std::endl;
```
template<class Ch, std::size_t N>
Ch* to_chars( uuid const& u, Ch (&buffer)[ N ] ) noexcept;
constexpr Ch* to_chars( uuid const& u, Ch (&buffer)[ N ] ) noexcept;
```
Requires: :: `Ch` must be a character type (one of `char`, `wchar_t`, `char8_t`, `char16_t`, `char32_t`); `N` must be at least 37.
@@ -188,6 +192,8 @@ Effects: :: Writes the string representation of `u` (exactly 37 characters, incl
Returns: :: `buffer + 36`.
NOTE: This function is only `constexpr` under {cpp}14 or later, and under GCC 9 or later, Clang 9 or later, or MSVC 14.25 or later.
Example: ::
+
```