From 1bc08296de02e693d695c49b63a93e79d78012ab Mon Sep 17 00:00:00 2001
From: Peter Dimov <pdimov@gmail.com>
Date: Mon, 30 Oct 2023 21:03:39 +0200
Subject: [PATCH] Update documentation

---
 doc/system/changes.adoc   |  1 +
 doc/system/reference.adoc | 94 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 95 insertions(+)

diff --git a/doc/system/changes.adoc b/doc/system/changes.adoc
index 427cefd..1799005 100644
--- a/doc/system/changes.adoc
+++ b/doc/system/changes.adoc
@@ -12,6 +12,7 @@ https://www.boost.org/LICENSE_1_0.txt
 
 * Added support for `result<U&, E>`.
 * Added `operator|` for `result`.
+* Added `operator&` for `result`.
 
 ## Changes in Boost 1.81
 
diff --git a/doc/system/reference.adoc b/doc/system/reference.adoc
index 1d703ef..65c5a47 100644
--- a/doc/system/reference.adoc
+++ b/doc/system/reference.adoc
@@ -1532,6 +1532,16 @@ template<class T, class E, class F, class R = ...> R operator|( result<T, E>&& r
 template<class E, class F, class R = ...> R operator|( result<void, E> const& r, F&& f );
 template<class E, class F, class R = ...> R operator|( result<void, E>&& r, F&& f );
 
+// operator&
+
+template<class T, class E, class F, class U = ...>
+  result<U, E> operator&( result<T, E> const& r, F&& f );
+template<class T, class E, class F, class U = ...>
+  result<U, E> operator&( result<T, E>&& r, F&& f );
+
+template<class T, class E, class F, class R = ...> R operator&( result<T, E> const& r, F&& f );
+template<class T, class E, class F, class R = ...> R operator&( result<T, E>&& r, F&& f );
+
 } // namespace system
 } // namespace boost
 ```
@@ -2607,6 +2617,90 @@ int get_port()
 }
 ```
 
+#### operator&
+
+```
+template<class T, class E, class F, class U = ...>
+  result<U, E> operator&( result<T, E> const& r, F&& f );
+
+template<class T, class E, class F, class U = ...>
+  result<U, E> operator&( result<T, E>&& r, F&& f );
+```
+[none]
+* {blank}
++
+Returns the error in `r`, or if `r` contains a value, transforms the value by calling `f` on it.
++
+Let `U` be the type of `f(*r)`.
++
+Effects: ::
+  - If `r.has_value()` is `true`, returns `f(*r)`.
+  - Otherwise, returns `r.error()`.
+Remarks: ::
+  Only enabled when `U` is not an instance of `result`.
+Example: ::
++
+```
+struct currency_type
+{
+    char code_[ 4 ] = {};
+};
+
+result<double> get_exchange_rate( currency_type from, currency_type to );
+
+result<double> convert( double amount, currency_type from, currency_type to )
+{
+    return get_exchange_rate( from, to ) & [&](double rate){ return rate * amount; };
+}
+```
+
+```
+template<class T, class E, class F, class R = ...> R operator&( result<T, E> const& r, F&& f );
+template<class T, class E, class F, class R = ...> R operator&( result<T, E>&& r, F&& f );
+```
+[none]
+* {blank}
++
+Returns the error in `r`, or if `r` contains a value, another `result` obtained
+by invoking the function `f` on the value in `r`.
++
+Let `R` be the type of `f(*r)`.
++
+Effects: ::
+  - If `r.has_value()` is `true`, returns `f(*r)`.
+  - Otherwise, returns `r.error()`.
+Remarks: ::
+  Only enabled when `R` is an instance of `result` and `E` is convertible to `R::error_type`.
+Example: ::
++
+```
+struct JsonValue
+{
+    result<JsonValue const&> at( std::size_t i ) const noexcept;
+    result<JsonValue const&> at( std::string_view key ) const noexcept;
+    template<class T> result<T> to_number() const noexcept;
+};
+
+namespace helpers
+{
+    inline auto at( std::size_t i ) {
+        return [=](JsonValue const& jv){ return jv.at( i ); }; }
+
+    inline auto at( std::string_view key ) {
+        return [=](JsonValue const& jv){ return jv.at( key ); }; }
+
+    template<class T> inline auto to_number() {
+        return [](JsonValue const& jv){ return jv.to_number<T>(); }; }
+
+} // namespace helpers
+
+int get_port( JsonValue const& config, int def )
+{
+    using namespace helpers;
+    return config.at( "servers" ) & at( 0 ) & at( "port" ) & to_number<int>() | def;
+}
+```
+
 ## <boost/system.hpp>
 
 This convenience header includes all the headers previously described.