From bfee791f4721bb8c47b8c2b628cefae1805f4670 Mon Sep 17 00:00:00 2001 From: Peter Dimov Date: Tue, 23 Dec 2025 19:48:35 +0200 Subject: [PATCH] Update documentation --- doc/uuid/changes.adoc | 6 +++++ doc/uuid/string_generator.adoc | 43 +++++++++++++++++++++++++--------- doc/uuid/uuid_io.adoc | 41 ++++++++++++++++++++++++++++++++ 3 files changed, 79 insertions(+), 11 deletions(-) diff --git a/doc/uuid/changes.adoc b/doc/uuid/changes.adoc index 8181687..fb5fa36 100644 --- a/doc/uuid/changes.adoc +++ b/doc/uuid/changes.adoc @@ -3,6 +3,12 @@ :idprefix: changes_ +== Changes in Boost 1.91.0 + +* 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`. + == Changes in Boost 1.90.0 * `string_generator` is now `constexpr` on {cpp}14 and higher. diff --git a/doc/uuid/string_generator.adoc b/doc/uuid/string_generator.adoc index dda5a9d..6fa3ed6 100644 --- a/doc/uuid/string_generator.adoc +++ b/doc/uuid/string_generator.adoc @@ -15,13 +15,17 @@ struct string_generator using result_type = uuid; template - uuid operator()( std::basic_string const& s ) const; + constexpr uuid operator()( std::basic_string const& s ) const; - uuid operator()( char const* s ) const; - uuid operator()( wchar_t const* s ) const; + template + constexpr uuid operator()( Ch const* s ) const; template - uuid operator()( CharIterator begin, CharIterator end ) const; + constexpr uuid operator()( CharIterator first, CharIterator last ) const; + + template + constexpr uuid operator()( CharIterator first, CharIterator last, + int& pos, from_chars_error& err ) const noexcept; }; }} // namespace boost::uuids @@ -52,10 +56,10 @@ Invalid input will generate a `std::runtime_error` exception. ``` template - uuid operator()( std::basic_string const& s ) const; + constexpr uuid operator()( std::basic_string const& s ) const; ``` -Requires: :: The character type `Ch` of `s` must be either `char` or `wchar_t`. +Requires: :: The character type `Ch` of `s` must be one of `char`, `wchar_t`, `char8_t`, `char16_t`, `char32_t`. Effects: :: Parses the string `s` into a `uuid` and returns the result. @@ -71,10 +75,12 @@ uuid u2 = gen( std::wstring( L"01234567-89AB-CDEF-0123-456789ABCDEF" ) ); ``` ``` -uuid operator()( char const* s ) const; -uuid operator()( wchar_t const* s ) const; +template + constexpr uuid operator()( Ch const* s ) const; ``` +Requires: :: `Ch` must be a character type (one of `char`, `wchar_t`, `char8_t`, `char16_t`, `char32_t`). + Effects: :: Parses the string `s` into a `uuid` and returns the result. Example: :: @@ -90,12 +96,12 @@ uuid u2 = gen( L"01234567-89ab-cdef-0123-456789abcdef" ); ``` template - uuid operator()( CharIterator begin, CharIterator end ) const; + constexpr uuid operator()( CharIterator first, CharIterator last ) const; ``` -Requires: :: `CharIterator` must be an input iterator with a value type of either `char` or `wchar_t`. +Requires: :: `CharIterator` must be an input iterator with a character value type (one of `char`, `wchar_t`, `char8_t`, `char16_t`, `char32_t`). -Effects: :: Parses the character sequence `[begin, end)` into a `uuid` and returns the result. +Effects: :: Parses the character sequence `[first, last)` into a `uuid` and returns the result. Example: :: + @@ -110,3 +116,18 @@ uuid u1 = gen( s1.begin(), s1.end() ); std::wstring s2( L"01234567-89AB-CDEF-0123-456789ABCDEF" ); uuid u2 = gen( s2.begin(), s2.end() ); ``` + +``` +template + constexpr uuid operator()( CharIterator first, CharIterator last, + int& pos, from_chars_error& err ) const noexcept; +``` + +Requires: :: `CharIterator` must be an input iterator with a character value type (one of `char`, `wchar_t`, `char8_t`, `char16_t`, `char32_t`). + +Effects: :: + Parses the character sequence `[first, last)` into a `uuid` and returns the result. + On error, `pos` contains the position at which parsing failed, and `err` contains the error. + On success, `err` contains `from_chars_error::none`. + +NOTE: Unlike `from_chars`, this function does not allow extra input; if after a complete UUID is parsed, unconsumed characters remain, `err` is set to `from_chars_error::unexpected_extra_input`. diff --git a/doc/uuid/uuid_io.adoc b/doc/uuid/uuid_io.adoc index 429fc00..c3cf97f 100644 --- a/doc/uuid/uuid_io.adoc +++ b/doc/uuid/uuid_io.adoc @@ -38,6 +38,29 @@ template std::string to_string( uuid const& u ); std::wstring to_wstring( uuid const& u ); +// from_chars + +enum class from_chars_error +{ + none = 0, + + unexpected_end_of_input, + hex_digit_expected, + dash_expected, + closing_brace_expected, + unexpected_extra_input +}; + +template struct from_chars_result +{ + Ch const* ptr; + from_chars_error ec; +}; + +template + constexpr from_chars_result + from_chars( Ch const* first, Ch const* last, uuid& u ) noexcept; + }} // namespace boost::uuids ---- @@ -209,3 +232,21 @@ std::string s1 = to_string( u ); std::wstring s2 = to_wstring( u ); ``` + +=== from_chars + +``` +template + constexpr from_chars_result + from_chars( Ch const* first, Ch const* last, uuid& u ) noexcept; +``` + +Requires: :: `Ch` must be a character type (one of `char`, `wchar_t`, `char8_t`, `char16_t`, `char32_t`). + +Effects: :: + Parses a `uuid` string representation from the characters in the range `[first, last)` and stores the result in `u`. + On error, the returned `from_chars_result` struct contains the error code in `ec` and `ptr` points to the character at which parsing failed. + On success, `ec` contains `from_chars_error::none` and `ptr` points to the character immediately after the last `uuid` character. + +NOTE: The values `from_chars_error::closing_brace_expected` and `from_chars_error::unexpected_extra_input` are never returned by `from_chars`. + They can be returned from the nonthrowing `string_generator::operator()` overload.