From f4bcc0fd2af832378a98c09b18dcdce691c0c075 Mon Sep 17 00:00:00 2001
From: Peter Dimov <pdimov@gmail.com>
Date: Thu, 15 Jan 2026 15:38:40 +0200
Subject: [PATCH] Update documentation

---
 doc/uuid/changes.adoc          |  1 +
 doc/uuid/invalid_uuid.adoc     | 47 ++++++++++++++++++++++++++++++++++
 doc/uuid/reference.adoc        |  1 +
 doc/uuid/string_generator.adoc |  2 +-
 doc/uuid/uuid_io.adoc          |  4 +--
 5 files changed, 52 insertions(+), 3 deletions(-)
 create mode 100644 doc/uuid/invalid_uuid.adoc

diff --git a/doc/uuid/changes.adoc b/doc/uuid/changes.adoc
index 8604082..beab210 100644
--- a/doc/uuid/changes.adoc
+++ b/doc/uuid/changes.adoc
@@ -12,6 +12,7 @@
 * Added SIMD implementation of `to_chars`, which can offer up to 5.5x performance improvement in UUID formatting. (Andrey Semashev)
 * Added SIMD implementation of `from_chars`, which can offer up to 13x performance improvement in UUID parsing. (Andrey Semashev)
 * Added `uuid_from_string` to `boost/uuid/uuid_io.hpp`.
+* Added a dedicated `invalid_uuid` exception class, derived from `std::runtime_error` for backward compatibility.
 
 == Changes in Boost 1.90.0
 
diff --git a/doc/uuid/invalid_uuid.adoc b/doc/uuid/invalid_uuid.adoc
new file mode 100644
index 0000000..007aaa9
--- /dev/null
+++ b/doc/uuid/invalid_uuid.adoc
@@ -0,0 +1,47 @@
+[#invalid_uuid]
+== <boost/uuid/invalid_uuid.hpp>
+
+:idprefix: invalid_uuid_
+
+=== Synopsis
+
+[source,c++]
+----
+namespace boost {
+namespace uuids {
+
+class invalid_uuid: public std::runtime_error
+{
+public:
+
+    invalid_uuid( std::ptrdiff_t pos, from_chars_error err );
+
+    std::ptrdiff_t position() const noexcept;
+    from_chars_error error() const noexcept;
+};
+
+}} // namespace boost::uuids
+----
+
+=== invalid_uuid
+
+Functions that parse a string UUID representation throw an exception of type `invalid_uuid` to indicate failure.
+
+```
+invalid_uuid( std::ptrdiff_t pos, from_chars_error err );
+```
+
+Effects: :: Constructs an `invalid_uuid` object, initializing its internal members to `pos` and `err` and the `runtime_error` base class with an appropriate error message.
+Postconditions: :: `this\->position() == pos && this\->error() == err`.
+
+```
+std::ptrdiff_t position() const noexcept;
+```
+
+Returns: :: The zero-based position in the input string at which parsing failed.
+
+```
+from_chars_error error() const noexcept;
+```
+
+Returns: :: The error code describing the reason parsing failed.
diff --git a/doc/uuid/reference.adoc b/doc/uuid/reference.adoc
index 0df1706..9a4f150 100644
--- a/doc/uuid/reference.adoc
+++ b/doc/uuid/reference.adoc
@@ -4,6 +4,7 @@
 include::uuid_all.adoc[]
 include::uuid.adoc[]
 include::uuid_io.adoc[]
+include::invalid_uuid.adoc[]
 include::generators.adoc[]
 include::nil_generator.adoc[]
 include::string_generator.adoc[]
diff --git a/doc/uuid/string_generator.adoc b/doc/uuid/string_generator.adoc
index 19e7f9d..2f10ff1 100644
--- a/doc/uuid/string_generator.adoc
+++ b/doc/uuid/string_generator.adoc
@@ -52,7 +52,7 @@ hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh
 {hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh}
 ```
 
-Invalid input will generate a `std::runtime_error` exception.
+Invalid input will throw an `invalid_uuid` exception.
 
 ```
 template<class Str>
diff --git a/doc/uuid/uuid_io.adoc b/doc/uuid/uuid_io.adoc
index dea4ba0..8ca75da 100644
--- a/doc/uuid/uuid_io.adoc
+++ b/doc/uuid/uuid_io.adoc
@@ -285,7 +285,7 @@ Requires: :: `Ch` must be a character type (one of `char`, `wchar_t`, `char8_t`,
 
 Effects: ::
   Parses a `uuid` string representation from the characters in the range `[str, str + std::char_traits<Ch>::length(str))` and stores the result in `u`.
-  On error, throws `std::runtime_error`.
+  On error, throws `invalid_uuid`.
 
 NOTE:  Unlike `from_chars`, this function does not allow extra input; if after a complete UUID is parsed, unconsumed characters remain, an exception is thrown.
 
@@ -300,6 +300,6 @@ Requires: ::
 
 Effects: ::
   Parses a `uuid` string representation from the characters in the range `[str.data(), str.data() + str.size())` and stores the result in `u`.
-  On error, throws `std::runtime_error`.
+  On error, throws `invalid_uuid`.
 
 NOTE:  Unlike `from_chars`, this function does not allow extra input; if after a complete UUID is parsed, unconsumed characters remain, an exception is thrown.