Add missing examples

doc/modules/ROOT/nav.adoc

@@ -8,14 +8,18 @@
 ** xref:examples.adoc#examples_wrapping[Wrapping Arithmetic]
 ** xref:examples.adoc#examples_strict[Strict Arithmetic]
 ** xref:examples.adoc#examples_generic[Generic Policy-Parameterized Arithmetic]
+** xref:examples.adoc#examples_literals[Literals]
 ** xref:examples.adoc#examples_charconv[Character Conversion]
 ** xref:examples.adoc#examples_fmt_format[Formatting]
+** xref:examples.adoc#examples_iostream[Stream I/O]
 * xref:api_reference.adoc[]
 ** xref:api_reference.adoc#api_types[Types]
 ** xref:api_reference.adoc#api_functions[Functions]
 ** xref:api_reference.adoc#api_headers[Headers]
 * xref:unsigned_integers.adoc[]
 * xref:policies.adoc[]
+* xref:literals.adoc[]
 * xref:limits.adoc[]
 * xref:format.adoc[]
+* xref:iostream.adoc[]
 * xref:charconv.adoc[]

doc/modules/ROOT/pages/api_reference.adoc

@@ -59,6 +59,26 @@ https://www.boost.org/LICENSE_1_0.txt
 | Parses a character string into a safe integer
 |===
 
+=== Literals
+
+[cols="1,2", options="header"]
+|===
+| Literal | Description
+
+| xref:literals.adoc[`_u8`, `_u16`, `_u32`, `_u64`, `_u128`]
+| User-defined literal suffixes for constructing safe integer types
+|===
+
+=== Stream I/O
+
+[cols="1,2", options="header"]
+|===
+| Function | Description
+
+| xref:iostream.adoc[`operator<<`, `operator>>`]
+| Stream insertion and extraction for all safe integer types
+|===
+
 === Arithmetic
 
 [cols="1,2", options="header"]
@@ -97,6 +117,12 @@ https://www.boost.org/LICENSE_1_0.txt
 | `<boost/safe_numbers/overflow_policy.hpp>`
 | The `overflow_policy` enum class
 
+| `<boost/safe_numbers/literals.hpp>`
+| User-defined literal suffixes (`_u8`, `_u16`, `_u32`, `_u64`, `_u128`)
+
+| `<boost/safe_numbers/iostream.hpp>`
+| Stream I/O operators (`operator<<`, `operator>>`) for safe integer types
+
 | `<boost/safe_numbers/charconv.hpp>`
 | Character conversion functions (`to_chars`, `from_chars`)
 

doc/modules/ROOT/pages/examples.adoc

@@ -203,6 +203,32 @@ add<wrapping>(max, 1)          = 0
 ----
 ====
 
+[#examples_literals]
+== Literals
+
+User-defined literal suffixes (`_u8`, `_u16`, `_u32`, `_u64`, `_u128`) provide concise construction of safe integer types.
+Values are range-checked at construction, producing a compile error in `constexpr` contexts or throwing `std::overflow_error` at runtime for out-of-range values.
+
+.This https://github.com/boostorg/safe_numbers/blob/develop/examples/literals.cpp[example] demonstrates how to use user-defined literals with safe integer types.
+====
+[source, c++]
+----
+include::example$literals.cpp[]
+----
+
+Output:
+----
+42_u8   = 42
+1000_u16 = 1000
+100000_u32 = 100000
+9999999999_u64 = 9999999999
+max_u128 = 340282366920938463463374607431768211455
+100_u32 + 50_u32 = 150
+6_u32 * 7_u32    = 42
+constexpr 255_u8 = 255
+----
+====
+
 [#examples_charconv]
 == Character Conversion
 
@@ -272,6 +298,35 @@ Fill Character:
 ----
 ====
 
+[#examples_iostream]
+== Stream I/O
+
+The library provides `operator<<` and `operator>>` overloads for all safe integer types.
+The `u8` type is handled specially: it displays as a numeric value rather than as a character.
+
+.This https://github.com/boostorg/safe_numbers/blob/develop/examples/iostream.cpp[example] demonstrates stream I/O with safe integer types.
+====
+[source, c++]
+----
+include::example$iostream.cpp[]
+----
+
+Output:
+----
+u8:  42
+u16: 1000
+u32: 100000
+u64: 9999999999
+u8(10) = 10 (not a newline character)
+u8(32) = 32 (not a space character)
+Read from stream: 12345
+Decimal:     255
+Hexadecimal: ff
+Octal:       377
+Roundtrip: 18446744073709551615 -> "18446744073709551615" -> 18446744073709551615
+----
+====
+
 [#examples_policy_comparison]
 == Policy Comparison
 

doc/modules/ROOT/pages/iostream.adoc

@@ -0,0 +1,98 @@
+////
+Copyright 2026 Matt Borland
+Distributed under the Boost Software License, Version 1.0.
+https://www.boost.org/LICENSE_1_0.txt
+////
+
+[#iostream]
+
+= Stream I/O Support
+
+== Description
+
+The library provides `operator<<` and `operator>>` overloads for all safe integer types, enabling use with standard C++ streams (`std::cout`, `std::cin`, `std::stringstream`, etc.).
+
+The `u8` type is handled specially: it displays as a numeric value rather than as a character, unlike `std::uint8_t` which most implementations treat as `unsigned char`.
+
+Attempting to read a negative value into an unsigned safe integer throws `std::domain_error`.
+
+[source,c++]
+----
+#include <boost/safe_numbers/iostream.hpp>
+
+namespace boost::safe_numbers::detail {
+
+// Output: writes the numeric value to the stream
+template <typename charT, typename traits, library_type LibType>
+auto operator<<(std::basic_ostream<charT, traits>& os, const LibType& v)
+    -> std::basic_ostream<charT, traits>&;
+
+// Input: reads a numeric value from the stream
+// Throws std::domain_error if the input begins with '-'
+template <typename charT, typename traits, library_type LibType>
+auto operator>>(std::basic_istream<charT, traits>& is, LibType& v)
+    -> std::basic_istream<charT, traits>&;
+
+} // namespace boost::safe_numbers::detail
+----
+
+== Behavior
+
+=== Output (`operator<<`)
+
+|===
+| Type | Behavior
+
+| `u8`
+| Promoted to `std::uint32_t` before output so the value displays as a number, not a character
+
+| `u16`, `u32`, `u64`
+| Converted to the underlying type and written directly
+
+| `u128`
+| Converted to the underlying `uint128_t` and written using its stream support
+|===
+
+Standard stream manipulators (`std::hex`, `std::oct`, `std::dec`, `std::setw`, etc.) work as expected.
+
+=== Input (`operator>>`)
+
+|===
+| Input | Behavior
+
+| Valid non-negative number
+| Parsed and stored in the safe integer
+
+| Negative number (starts with `-`)
+| Throws `std::domain_error`
+
+| Invalid input
+| Sets the stream's fail bit as with any standard stream extraction
+|===
+
+For `u8`, the input is read as a `std::uint32_t` to avoid character interpretation, then narrowed to `std::uint8_t`.
+
+== Examples
+
+.This https://github.com/boostorg/safe_numbers/blob/develop/examples/iostream.cpp[example] demonstrates stream I/O with safe integer types.
+====
+[source, c++]
+----
+include::example$iostream.cpp[]
+----
+
+Output:
+----
+u8:  42
+u16: 1000
+u32: 100000
+u64: 9999999999
+u8(10) = 10 (not a newline character)
+u8(32) = 32 (not a space character)
+Read from stream: 12345
+Decimal:     255
+Hexadecimal: ff
+Octal:       377
+Roundtrip: 18446744073709551615 -> "18446744073709551615" -> 18446744073709551615
+----
+====

doc/modules/ROOT/pages/literals.adoc

@@ -0,0 +1,98 @@
+////
+Copyright 2026 Matt Borland
+Distributed under the Boost Software License, Version 1.0.
+https://www.boost.org/LICENSE_1_0.txt
+////
+
+[#literals]
+
+= User-Defined Literals
+
+== Description
+
+The library provides user-defined literal suffixes for concise construction of safe integer types.
+The literals are defined in the `boost::safe_numbers::literals` namespace.
+For `_u8`, `_u16`, and `_u32`, the literal value is range-checked and throws `std::overflow_error` if the value exceeds the target type's maximum.
+The `_u64` literal performs no range check since `unsigned long long` maps directly to `std::uint64_t`.
+The `_u128` literal parses a string representation and throws `std::overflow_error` on overflow or `std::invalid_argument` on invalid input.
+
+[source,c++]
+----
+#include <boost/safe_numbers/literals.hpp>
+
+namespace boost::safe_numbers::literals {
+
+constexpr auto operator ""_u8(unsigned long long int val) -> u8;
+constexpr auto operator ""_u16(unsigned long long int val) -> u16;
+constexpr auto operator ""_u32(unsigned long long int val) -> u32;
+constexpr auto operator ""_u64(unsigned long long int val) -> u64;
+constexpr auto operator ""_u128(const char* str) -> u128;
+
+} // namespace boost::safe_numbers::literals
+----
+
+== Literal Suffixes
+
+|===
+| Suffix | Result Type | Range Check
+
+| `_u8`
+| `u8`
+| Throws `std::overflow_error` if value > 255
+
+| `_u16`
+| `u16`
+| Throws `std::overflow_error` if value > 65,535
+
+| `_u32`
+| `u32`
+| Throws `std::overflow_error` if value > 4,294,967,295
+
+| `_u64`
+| `u64`
+| No range check (direct conversion from `unsigned long long`)
+
+| `_u128`
+| `u128`
+| Parses string; throws `std::overflow_error` on overflow, `std::invalid_argument` on invalid input
+|===
+
+== Usage
+
+To use the literals, bring the `boost::safe_numbers::literals` namespace into scope:
+
+[source,c++]
+----
+using namespace boost::safe_numbers::literals;
+
+constexpr auto a {42_u8};
+constexpr auto b {1000_u16};
+constexpr auto c {100000_u32};
+constexpr auto d {9999999999_u64};
+constexpr auto e {340282366920938463463374607431768211455_u128};
+----
+
+Literals are `constexpr` and can be used in compile-time contexts.
+When used in a `constexpr` context, an out-of-range value produces a compile error rather than a runtime exception.
+
+== Examples
+
+.This https://github.com/boostorg/safe_numbers/blob/develop/examples/literals.cpp[example] demonstrates how to use user-defined literals with safe integer types.
+====
+[source, c++]
+----
+include::example$literals.cpp[]
+----
+
+Output:
+----
+42_u8   = 42
+1000_u16 = 1000
+100000_u32 = 100000
+9999999999_u64 = 9999999999
+max_u128 = 340282366920938463463374607431768211455
+100_u32 + 50_u32 = 150
+6_u32 * 7_u32    = 42
+constexpr 255_u8 = 255
+----
+====