From d37876102c97a7ec7910edf48f7df45f87e6ccb1 Mon Sep 17 00:00:00 2001 From: Simon Brand Date: Mon, 27 Nov 2017 15:11:47 +0000 Subject: [PATCH] Update docs --- docs/index.md | 278 ++++++++++++++++++++++++++------------------- standardese.config | 1 + 2 files changed, 161 insertions(+), 118 deletions(-) diff --git a/docs/index.md b/docs/index.md index 4075734..aeaf9a2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,144 +1,152 @@ # Header file `expected.hpp` -
#define TL_EXPECTED_HPP
+
#define TL_EXPECTED_HPP
 
-#define TL_EXPECTED_GCC49
+#define TL_EXPECTED_GCC49
 
-#define TL_EXPECTED_NO_CONSTRR
+#define IS_TRIVIALLY_COPY_CONSTRUCTIBLE(T)
 
-#define TL_EXPECTED_CXX14
+#define IS_TRIVIALLY_COPY_ASSIGNABLE(T)
 
-#define TL_IN_PLACE_MONOSTATE_DEFINED
+#define IS_TRIVIALLY_DESTRUCTIBLE(T)
 
-namespace tl
+#define TL_EXPECTED_CXX14
+
+#define TL_MONOSTATE_INPLACE_MUTEX
+
+#define TL_TRAITS_MUTEX
+
+#define TL_OPTIONAL_EXPECTED_MUTEX
+
+namespace tl
 {
-    class monostate;
+    class monostate;
     
-    struct in_place_t;
+    struct in_place_t;
     
-    constexpr in_place_t{} in_place;
+    constexpr in_place_t{} in_place;
     
     template <class E>
-    class unexpected;
+    class unexpected;
     
     template <class E>
-    constexpr bool operator==(const unexpected<E>& lhs, const unexpected<E>& rhs);
+    constexpr bool operator==(const unexpected<E>& lhs, const unexpected<E>& rhs);
     template <class E>
-    constexpr bool operator!=(const unexpected<E>& lhs, const unexpected<E>& rhs);
+    constexpr bool operator!=(const unexpected<E>& lhs, const unexpected<E>& rhs);
     template <class E>
-    constexpr bool operator<(const unexpected<E>& lhs, const unexpected<E>& rhs);
+    constexpr bool operator<(const unexpected<E>& lhs, const unexpected<E>& rhs);
     template <class E>
-    constexpr bool operator<=(const unexpected<E>& lhs, const unexpected<E>& rhs);
+    constexpr bool operator<=(const unexpected<E>& lhs, const unexpected<E>& rhs);
     template <class E>
-    constexpr bool operator>(const unexpected<E>& lhs, const unexpected<E>& rhs);
+    constexpr bool operator>(const unexpected<E>& lhs, const unexpected<E>& rhs);
     template <class E>
-    constexpr bool operator>=(const unexpected<E>& lhs, const unexpected<E>& rhs);
+    constexpr bool operator>=(const unexpected<E>& lhs, const unexpected<E>& rhs);
     
     template <class E>
-    unexpected<E> make_unexpected(E&& e);
+    unexpected<E> make_unexpected(E&& e);
     
-    struct unexpect_t;
+    struct unexpect_t;
     
-    constexpr unexpect_t{} unexpect;
+    constexpr unexpect_t{} unexpect;
     
     template <class E>
-    class bad_expected_access;
+    class bad_expected_access;
     
     template <class T, class E>
-    class expected;
+    class expected;
     
     template <class T, class E, class U, class F>
-    constexpr bool operator==(const expected<T, E>& lhs, const expected<U, F>& rhs);
+    constexpr bool operator==(const expected<T, E>& lhs, const expected<U, F>& rhs);
     
     template <class T, class E, class U, class F>
-    constexpr bool operator!=(const expected<T, E>& lhs, const expected<U, F>& rhs);
+    constexpr bool operator!=(const expected<T, E>& lhs, const expected<U, F>& rhs);
     
     template <class T, class E, class U, class F>
-    constexpr bool operator<(const expected<T, E>& lhs, const expected<U, F>& rhs);
+    constexpr bool operator<(const expected<T, E>& lhs, const expected<U, F>& rhs);
     
     template <class T, class E, class U, class F>
-    constexpr bool operator>(const expected<T, E>& lhs, const expected<U, F>& rhs);
+    constexpr bool operator>(const expected<T, E>& lhs, const expected<U, F>& rhs);
     
     template <class T, class E, class U, class F>
-    constexpr bool operator<=(const expected<T, E>& lhs, const expected<U, F>& rhs);
+    constexpr bool operator<=(const expected<T, E>& lhs, const expected<U, F>& rhs);
     
     template <class T, class E, class U, class F>
-    constexpr bool operator>=(const expected<T, E>& lhs, const expected<U, F>& rhs);
+    constexpr bool operator>=(const expected<T, E>& lhs, const expected<U, F>& rhs);
     
     template <class T, class E, class U>
-    constexpr bool operator==(const expected<T, E>& x, const U& v);
+    constexpr bool operator==(const expected<T, E>& x, const U& v);
     
     template <class T, class E, class U>
-    constexpr bool operator==(const U& v, const expected<T, E>& x);
+    constexpr bool operator==(const U& v, const expected<T, E>& x);
     
     template <class T, class E, class U>
-    constexpr bool operator!=(const expected<T, E>& x, const U& v);
+    constexpr bool operator!=(const expected<T, E>& x, const U& v);
     
     template <class T, class E, class U>
-    constexpr bool operator!=(const U& v, const expected<T, E>& x);
+    constexpr bool operator!=(const U& v, const expected<T, E>& x);
     
     template <class T, class E, class U>
-    constexpr bool operator<(const expected<T, E>& x, const U& v);
+    constexpr bool operator<(const expected<T, E>& x, const U& v);
     
     template <class T, class E, class U>
-    constexpr bool operator<(const U& v, const expected<T, E>& x);
+    constexpr bool operator<(const U& v, const expected<T, E>& x);
     
     template <class T, class E, class U>
-    constexpr bool operator<=(const expected<T, E>& x, const U& v);
+    constexpr bool operator<=(const expected<T, E>& x, const U& v);
     
     template <class T, class E, class U>
-    constexpr bool operator<=(const U& v, const expected<T, E>& x);
+    constexpr bool operator<=(const U& v, const expected<T, E>& x);
     
     template <class T, class E, class U>
-    constexpr bool operator>(const expected<T, E>& x, const U& v);
+    constexpr bool operator>(const expected<T, E>& x, const U& v);
     
     template <class T, class E, class U>
-    constexpr bool operator>(const U& v, const expected<T, E>& x);
+    constexpr bool operator>(const U& v, const expected<T, E>& x);
     
     template <class T, class E, class U>
-    constexpr bool operator>=(const expected<T, E>& x, const U& v);
+    constexpr bool operator>=(const expected<T, E>& x, const U& v);
     
     template <class T, class E, class U>
-    constexpr bool operator>=(const U& v, const expected<T, E>& x);
+    constexpr bool operator>=(const U& v, const expected<T, E>& x);
     
     template <class T, class E>
-    constexpr bool operator==(const expected<T, E>& x, const unexpected<E>& e);
+    constexpr bool operator==(const expected<T, E>& x, const unexpected<E>& e);
     
     template <class T, class E>
-    constexpr bool operator==(const unexpected<E>& e, const expected<T, E>& x);
+    constexpr bool operator==(const unexpected<E>& e, const expected<T, E>& x);
     
     template <class T, class E>
-    constexpr bool operator!=(const expected<T, E>& x, const unexpected<E>& e);
+    constexpr bool operator!=(const expected<T, E>& x, const unexpected<E>& e);
     
     template <class T, class E>
-    constexpr bool operator!=(const unexpected<E>& e, const expected<T, E>& x);
+    constexpr bool operator!=(const unexpected<E>& e, const expected<T, E>& x);
     
     template <class T, class E>
-    constexpr bool operator<(const expected<T, E>& x, const unexpected<E>& e);
+    constexpr bool operator<(const expected<T, E>& x, const unexpected<E>& e);
     
     template <class T, class E>
-    constexpr bool operator<(const unexpected<E>& e, const expected<T, E>& x);
+    constexpr bool operator<(const unexpected<E>& e, const expected<T, E>& x);
     
     template <class T, class E>
-    constexpr bool operator<=(const expected<T, E>& x, const unexpected<E>& e);
+    constexpr bool operator<=(const expected<T, E>& x, const unexpected<E>& e);
     
     template <class T, class E>
-    constexpr bool operator<=(const unexpected<E>& e, const expected<T, E>& x);
+    constexpr bool operator<=(const unexpected<E>& e, const expected<T, E>& x);
     
     template <class T, class E>
-    constexpr bool operator>(const expected<T, E>& x, const unexpected<E>& e);
+    constexpr bool operator>(const expected<T, E>& x, const unexpected<E>& e);
     
     template <class T, class E>
-    constexpr bool operator>(const unexpected<E>& e, const expected<T, E>& x);
+    constexpr bool operator>(const unexpected<E>& e, const expected<T, E>& x);
     
     template <class T, class E>
-    constexpr bool operator>=(const expected<T, E>& x, const unexpected<E>& e);
+    constexpr bool operator>=(const expected<T, E>& x, const unexpected<E>& e);
     
     template <class T, class E>
-    constexpr bool operator>=(const unexpected<E>& e, const expected<T, E>& x);
+    constexpr bool operator>=(const unexpected<E>& e, const expected<T, E>& x);
     
     template <class T, class E, 'hidden'>
-    void swap(expected<T, E>& lhs, expected<T, E>& rhs) noexcept(noexcept(lhs.swap(rhs)));
+    void swap(expected<T, E>& lhs, expected<T, E>& rhs) noexcept(noexcept(lhs.swap(rhs)));
 }

 
 ## Class `tl::monostate`
@@ -153,14 +161,14 @@ Used to represent an expected with no data
 
 
struct in_place_t
 {
-    in_place_t() = default;
+    in_place_t() = default;
 };

 
 A tag type to tell expected to construct its value in-place
 
 ## Variable `tl::in_place`
 
-
constexpr in_place_t{} in_place;

+
constexpr in_place_t{} in_place;

 
 A tag to tell expected to construct its value in-place
 
@@ -170,15 +178,15 @@ A tag to tell expected to construct its value in-place
 class unexpected
 {
 public:
-    unexpected() = delete;
+    unexpected() = delete;
     
-    constexpr unexpected(const E& e);
+    constexpr unexpected(const E& e);
     
-    constexpr unexpected(E&& e);
+    constexpr unexpected(E&& e);
     
-    constexpr const E& value() const &;
-    constexpr E& value() &;
-    constexpr E&& value() &&;
+    constexpr const E& value() const &;
+    E& value() &;
+    E&& value() &&;
 };
Used as a wrapper to store the unexpected value @@ -187,9 +195,9 @@ Used as a wrapper to store the unexpected value 
(1)  constexpr const E& value() const &;
 
-(2)  constexpr E& value() &;
+(2)  E& value() &;
 
-(3)  constexpr E&& value() &&;
+(3) E&& value() &&; *Returns*: the contained value @@ -198,22 +206,22 @@ Used as a wrapper to store the unexpected value ## Comparison operator `tl::operator==` 
(1)  template <class E>
-     constexpr bool operator==(const unexpected<E>& lhs, const unexpected<E>& rhs);
+     constexpr bool operator==(const unexpected<E>& lhs, const unexpected<E>& rhs);
 
 (2)  template <class E>
-     constexpr bool operator!=(const unexpected<E>& lhs, const unexpected<E>& rhs);
+     constexpr bool operator!=(const unexpected<E>& lhs, const unexpected<E>& rhs);
 
 (3)  template <class E>
-     constexpr bool operator<(const unexpected<E>& lhs, const unexpected<E>& rhs);
+     constexpr bool operator<(const unexpected<E>& lhs, const unexpected<E>& rhs);
 
 (4)  template <class E>
-     constexpr bool operator<=(const unexpected<E>& lhs, const unexpected<E>& rhs);
+     constexpr bool operator<=(const unexpected<E>& lhs, const unexpected<E>& rhs);
 
 (5)  template <class E>
-     constexpr bool operator>(const unexpected<E>& lhs, const unexpected<E>& rhs);
+     constexpr bool operator>(const unexpected<E>& lhs, const unexpected<E>& rhs);
 
 (6)  template <class E>
-     constexpr bool operator>=(const unexpected<E>& lhs, const unexpected<E>& rhs);
+ constexpr bool operator>=(const unexpected<E>& lhs, const unexpected<E>& rhs); Compares two unexpected objects @@ -222,7 +230,7 @@ Simply compares lhs.value() to rhs.value() ## Function template `tl::make_unexpected` 
template <class E>
-unexpected<E> make_unexpected(E&& e);
+unexpected<E> make_unexpected(E&& e); Create an `unexpected` from `e`, deducing the return type @@ -232,14 +240,14 @@ Create an `unexpected` from `e`, deducing the return type 
struct unexpect_t
 {
-    unexpect_t() = default;
+    unexpect_t() = default;
 };
A tag type to tell expected to construct the unexpected value ## Variable `tl::unexpect` -
constexpr unexpect_t{} unexpect;
+
constexpr unexpect_t{} unexpect;
A tag to tell expected to construct the unexpected value @@ -249,112 +257,128 @@ A tag to tell expected to construct the unexpected value class expected { public: - using value_type = T; + using value_type = T; - using error_type = E; + using error_type = E; - using unexpected_type = unexpected<E>; + using unexpected_type = unexpected<E>; template <class F> - 'hidden' and_then(F&& f) &; + 'hidden' and_then(F&& f) &; template <class F> constexpr auto and_then(F &&f) &&; template <class F> constexpr auto and_then(F &&f) const &; + template <class F> + constexpr auto and_then(F &&f) const &&; template <class F> constexpr auto map(F &&f) &; template <class F> constexpr auto map(F &&f) &&; template <class F> constexpr auto map(F &&f) const &; + template <class F> constexpr auto map(F &&f) const &&; template <class F> constexpr auto map_error(F &&f) &; template <class F> constexpr auto map_error(F &&f) &&; template <class F> constexpr auto map_error(F &&f) const &; + template <class F> constexpr auto map_error(F &&f) const &&; - constexpr expected() = default; + template <class F> + expected or_else(F&& f) &; - constexpr expected(const expected& rhs) = default; + template <class F> + expected or_else(F&& f) &&; - constexpr expected(expected&& rhs) = default; + template <class F> + constexpr expected or_else(F&& f) const &; - constexpr expected& operator=(const expected& rhs) = default; + template <class F> + constexpr expected or_else(F&& f) const &&; - constexpr expected& operator=(expected&& rhs) = default; + constexpr expected() = default; + + constexpr expected(const expected& rhs) = default; + + constexpr expected(expected&& rhs) = default; + + expected& operator=(const expected& rhs) = default; + + expected& operator=(expected&& rhs) = default; template <class ... Args, 'hidden' ... = nullptr> - constexpr expected(in_place_t, Args&&... args); + constexpr expected(in_place_t, Args&&... args); template <class U, class ... Args, 'hidden' ... = nullptr> - constexpr expected(in_place_t, std::initializer_list<U> il, Args&&... args); + constexpr expected(in_place_t, std::initializer_list<U> il, Args&&... args); EXPLICIT constexpr expected(const unexpected<G> &e); EXPLICIT constexpr expected(unexpected<G> &&e); template <class ... Args, 'hidden' ... = nullptr> - constexpr expected(unexpect_t, Args&&... args); + constexpr expected(unexpect_t, Args&&... args); - template <class U, class G, 'hidden'> - constexpr expected(const expected<U, G>& rhs); + template <class U, class G, 'hidden', 'hidden'> + expected(const expected<U, G>& rhs); - template <class U, class G, 'hidden'> - constexpr expected(expected<U, G>&& rhs); - - template <class U = T, 'hidden'> - constexpr expected(U&& v); + template <class U, class G, 'hidden', 'hidden'> + expected(expected<U, G>&& rhs); template <class U = T, 'hidden', 'hidden'> - expected& operator=(U&& v); + constexpr expected(U&& v); + + template <class U = T, 'hidden', 'hidden'> + expected& operator=(U&& v); template <class G = E, 'hidden'> - expected& operator=(const unexpected<G>& rhs); + expected& operator=(const unexpected<G>& rhs); template <class G = E, 'hidden'> - expected& operator=(unexpected<G>&& rhs) noexcept; + expected& operator=(unexpected<G>&& rhs) noexcept; template <class ... Args, 'hidden' ... = nullptr> - void emplace(Args&&... args); + void emplace(Args&&... args); template <class U, class ... Args, 'hidden' ... = nullptr> - void emplace(std::initializer_list<U> il, Args&&... args); + void emplace(std::initializer_list<U> il, Args&&... args); - void swap(expected& rhs) noexcept(std::is_nothrow_move_constructible<T>::value&&noexcept(swap(std::declval<T&>(), std::declval<T&>()))&&std::is_nothrow_move_constructible<E>::value&&noexcept(swap(std::declval<E&>(), std::declval<E&>()))); + void swap(expected& rhs) noexcept(std::is_nothrow_move_constructible<T>::value&&noexcept(swap(std::declval<T&>(), std::declval<T&>()))&&std::is_nothrow_move_constructible<E>::value&&noexcept(swap(std::declval<E&>(), std::declval<E&>()))); - constexpr const T* operator->() const; + constexpr const T* operator->() const; - constexpr T* operator->(); + T* operator->(); - constexpr const T& operator*() const &; + constexpr const T& operator*() const &; - constexpr T& operator*() &; + T& operator*() &; - constexpr const T&& operator*() const &&; + constexpr const T&& operator*() const &&; - constexpr T&& operator*() &&; + T&& operator*() &&; - constexpr operator bool() const noexcept; + constexpr operator bool() const noexcept; - constexpr bool has_value() const noexcept; + constexpr bool has_value() const noexcept; - constexpr const T& value() const &; + constexpr const T& value() const &; - constexpr T& value() &; + T& value() &; - constexpr const T&& value() const &&; + constexpr const T&& value() const &&; - constexpr T&& value() &&; + T&& value() &&; - constexpr const E& error() const &; + constexpr const E& error() const &; - constexpr E& error() &; + E& error() &; - constexpr const E&& error() const &&; + constexpr const E&& error() const &&; - constexpr E&& error() &&; + E&& error() &&; template <class U> - constexpr T value_or(U&& v) const &; + constexpr T value_or(U&& v) const &; template <class U> - T value_or(U&& v) &&; + T value_or(U&& v) &&; }; An `expected` object is an object that contains the storage for another object and manages the lifetime of this contained object `T`. Alternatively it could contain the storage for another unexpected object `E`. The contained object may not be initialized after the expected object has been initialized, and may not be destroyed before the expected object has been destroyed. The initialization state of the contained object is tracked by the expected object. @@ -368,9 +392,12 @@ An `expected` object is an object that contains the storage for another ob constexpr auto and_then(F &&f) &&; (3) template <class F> - constexpr auto and_then(F &&f) const &; + constexpr auto and_then(F &&f) const &; -Carries out some operation which returns an optional on the stored object if there is one. \\requires `std::invoke(std::forward(f), value())` returns a `std::optional` for some `U`. \\returns Let `U` be the result of `std::invoke(std::forward(f), value())`. Returns a `std::optional`. The return value is empty if `*this` is empty, otherwise the return value of `std::invoke(std::forward(f), value())` is returned. \\group and\_then \\synopsis template \\\nconstexpr auto and\_then(F &\&f) &; +(4) template <class F> + constexpr auto and_then(F &&f) const &&; + +Carries out some operation which returns an expected on the stored object if there is one. \\requires `std::invoke(std::forward(f), value())` returns a `std::expected` for some `U`. \\returns Let `U` be the result of `std::invoke(std::forward(f), value())`. Returns a `std::expected`. The return value is empty if `*this` is empty, otherwise the return value of `std::invoke(std::forward(f), value())` is returned. \\group and\_then \\synopsis template \\\nconstexpr auto and\_then(F &\&f) &; ### Function template `tl::expected::map` @@ -378,7 +405,9 @@ Carries out some operation which returns an optional on the stored object if the (2) template <class F> constexpr auto map(F &&f) &&; -(3) template <class F> constexpr auto map(F &&f) const &; +(3) template <class F> constexpr auto map(F &&f) const &; + +(4) template <class F> constexpr auto map(F &&f) const &&; Carries out some operation on the stored object if there is one. @@ -390,12 +419,25 @@ Carries out some operation on the stored object if there is one. (2) template <class F> constexpr auto map_error(F &&f) &&; -(3) template <class F> constexpr auto map_error(F &&f) const &; +(3) template <class F> constexpr auto map_error(F &&f) const &; + +(4) template <class F> constexpr auto map_error(F &&f) const &&; Carries out some operation on the stored unexpected object if there is one. *Returns*: Let `U` be the result of `std::invoke(std::forward(f), value())`. Returns a `std::expected`. If `*this` has an expected value, the result is `*this`, otherwise an `expected` is constructed from `make_unexpected(std::invoke(std::forward(f), value()))` and is returned. +### Function template `tl::expected::or_else` + +
(1)  template <class F>
+     expected or_else(F&& f) &;
+ +Calls `f` if the expectd is in the unexpected state + +*Requires*: `std::invoke_result_t` must be void or convertible to `expcted`. + +*Effects*: If `*this` has a value, returns `*this`. Otherwise, if `f` returns `void`, calls `std::forward(f)` and returns `std::nullopt`. Otherwise, returns `std::forward(f)()`. + ### Function template `tl::expected::expected` 
(1)  EXPLICIT constexpr expected(const unexpected<G> &e);
diff --git a/standardese.config b/standardese.config
index bdd6d9b..643fd3b 100644
--- a/standardese.config
+++ b/standardese.config
@@ -1,2 +1,3 @@
 [output]
 format=commonmark
+link_extension=html