From 7878dec8427cf078cb47916e999821b40ecfa794 Mon Sep 17 00:00:00 2001
From: Andrzej Krzemienski <akrzemi1@gmail.com>
Date: Sun, 1 Oct 2023 23:34:38 +0200
Subject: [PATCH] document monadic interface

---
 doc/00_optional.qbk                           |  2 +-
 doc/14_monadic_interface.qbk                  | 45 +++++++++++++++++++
 doc/{14_io.qbk => 15_io.qbk}                  |  0
 ...erences.qbk => 16_optional_references.qbk} |  0
 ...actories.qbk => 17_in_place_factories.qbk} |  0
 doc/{17_gotchas.qbk => 18_gotchas.qbk}        |  0
 ...ion_safety.qbk => 19_exception_safety.qbk} |  0
 ...uirements.qbk => 1A_type_requirements.qbk} |  0
 ..._performance.qbk => 1B_on_performance.qbk} |  0
 9 files changed, 46 insertions(+), 1 deletion(-)
 create mode 100644 doc/14_monadic_interface.qbk
 rename doc/{14_io.qbk => 15_io.qbk} (100%)
 rename doc/{15_optional_references.qbk => 16_optional_references.qbk} (100%)
 rename doc/{16_in_place_factories.qbk => 17_in_place_factories.qbk} (100%)
 rename doc/{17_gotchas.qbk => 18_gotchas.qbk} (100%)
 rename doc/{18_exception_safety.qbk => 19_exception_safety.qbk} (100%)
 rename doc/{19_type_requirements.qbk => 1A_type_requirements.qbk} (100%)
 rename doc/{1A_on_performance.qbk => 1B_on_performance.qbk} (100%)

diff --git a/doc/00_optional.qbk b/doc/00_optional.qbk
index 473212f..f03e0ef 100644
--- a/doc/00_optional.qbk
+++ b/doc/00_optional.qbk
@@ -2,7 +2,7 @@
     [quickbook 1.4]
     [authors [Cacciola Carballal, Fernando Luis]]
     [copyright 2003-2007 Fernando Luis Cacciola Carballal]
-    [copyright 2014-2022 Andrzej Krzemie&#324;ski]
+    [copyright 2014-2023 Andrzej Krzemie&#324;ski]
     [category miscellaneous]
     [id optional]
     [dirname optional]
diff --git a/doc/14_monadic_interface.qbk b/doc/14_monadic_interface.qbk
new file mode 100644
index 0000000..21731e4
--- /dev/null
+++ b/doc/14_monadic_interface.qbk
@@ -0,0 +1,45 @@
+[section Monadic interface]
+
+The monadic interface of `optional` allows the application of functions
+to optional values without resorting to the usage of explicit `if`-statements.
+
+Function `map` takes a function mapping type `T` onto type `U` and maps an `optional<T>`
+onto an `optional<U>` using the provided function.
+
+    int length(const string& s){ return s.size(); };
+
+    optional<string> null{}, thin{""}, word{"word"};
+    assert (null.map(length) == none);
+    assert (thin.map(length) == 0);
+    assert (word.map(length) == 4);
+
+Function `flat_map` is similar, but it requires the function to return an
+`optional<V>` for some type `V`. This `optional<V>` becomes the return type of
+`flat_map`.
+
+    optional<char> first_char(const string& s) {
+      if (s.empty()) return none;
+      else           return s[0];
+    };
+
+    optional<string> null{}, thin{""}, word{"word"};
+    assert (null.flat_map(first_char) == none);
+    assert (thin.flat_map(first_char) == none);
+    assert (word.flat_map(first_char) == 'w');
+
+These functions can be combined in one expression reflecting a chain of computations:
+
+    auto get_contents(path p) -> optional<string>;
+    auto trim(string) -> string;
+    auto length(string) -> int;
+
+    auto trimmed_size_of(optional<path> p) -> int
+    {
+      return p.flat_map(get_contents)
+              .map(trim)
+              .map(length)
+              .value_or(0);
+    }
+ 
+
+[endsect]
diff --git a/doc/14_io.qbk b/doc/15_io.qbk
similarity index 100%
rename from doc/14_io.qbk
rename to doc/15_io.qbk
diff --git a/doc/15_optional_references.qbk b/doc/16_optional_references.qbk
similarity index 100%
rename from doc/15_optional_references.qbk
rename to doc/16_optional_references.qbk
diff --git a/doc/16_in_place_factories.qbk b/doc/17_in_place_factories.qbk
similarity index 100%
rename from doc/16_in_place_factories.qbk
rename to doc/17_in_place_factories.qbk
diff --git a/doc/17_gotchas.qbk b/doc/18_gotchas.qbk
similarity index 100%
rename from doc/17_gotchas.qbk
rename to doc/18_gotchas.qbk
diff --git a/doc/18_exception_safety.qbk b/doc/19_exception_safety.qbk
similarity index 100%
rename from doc/18_exception_safety.qbk
rename to doc/19_exception_safety.qbk
diff --git a/doc/19_type_requirements.qbk b/doc/1A_type_requirements.qbk
similarity index 100%
rename from doc/19_type_requirements.qbk
rename to doc/1A_type_requirements.qbk
diff --git a/doc/1A_on_performance.qbk b/doc/1B_on_performance.qbk
similarity index 100%
rename from doc/1A_on_performance.qbk
rename to doc/1B_on_performance.qbk