feedc0de/boost_optional
1
0
Fork 0
forked from boostorg/optional
Code Pull Requests Activity

documented flat_map

Browse Source
This commit is contained in:
Andrzej Krzemienski
2018-07-02 23:07:47 +02:00
parent 71d797b9ee
commit d0b87d2f35
9 changed files with 236 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files

100
doc/28_ref_optional_semantics.qbk
View File

@ -233,7 +233,7 @@ __SPACE__
arguments `std::forward<Args>(args)...`.
* [*Postconditions:] `*this` is initialized.
* [*Throws:] Any exception thrown by the selected constructor of `T`.
* [*Notes: ] `T` need not be __MOVE_CONSTRUCTIBLE__. On compilers that do not suppor variadic templates or rvalue references, this constuctor is available in limited functionality. For details [link optional_emplace_workaround see here].
* [*Notes: ] `T` need not be __MOVE_CONSTRUCTIBLE__. On compilers that do not suppor variadic templates or rvalue references, this constuctor is available in limited functionality. For details [link optional_emplace_workaround see here].
* [*Example:]
``
@ -257,7 +257,7 @@ __SPACE__
* [*Effect:] If `condition` is `true`, initializes the contained value as if direct-non-list-initializing an object of type `T` with the arguments `std::forward<Args>(args)...`.
* [*Postconditions:] `bool(*this) == condition`.
* [*Throws:] Any exception thrown by the selected constructor of `T`.
* [*Notes: ] `T` need not be __MOVE_CONSTRUCTIBLE__. On compilers that do not suppor variadic templates or rvalue references, this constuctor is available in limited functionality. For details [link optional_emplace_workaround see here].
* [*Notes: ] `T` need not be __MOVE_CONSTRUCTIBLE__. On compilers that do not suppor variadic templates or rvalue references, this constuctor is available in limited functionality. For details [link optional_emplace_workaround see here].
* [*Example:]
``
@ -376,13 +376,13 @@ __SPACE__
* [*Requires:] `T` is __COPY_CONSTRUCTIBLE__ and `CopyAssignable`.
* [*Effects:]
[table
[]
[]
[[][[*`*this` contains a value]][[*`*this` does not contain a value]]]
[[[*`rhs` contains a value]][assigns `*rhs` to the contained value][initializes the contained value as if direct-initializing an object of type `T` with `*rhs`]]
[[[*`rhs` does not contain a value]][destroys the contained value by calling `val->T::~T()`][no effect]]
]
* [*Returns:] `*this`;
* [*Postconditions:] `bool(rhs) == bool(*this)`.
* [*Postconditions:] `bool(rhs) == bool(*this)`.
* [*Exception Safety:] If any exception is thrown, the initialization state of `*this` and `rhs` remains unchanged.
If an exception is thrown during the call to `T`'s copy constructor, no effect.
If an exception is thrown during the call to `T`'s copy assignment, the state of its contained value is as defined by the exception safety guarantee of `T`'s copy assignment.
@ -406,14 +406,14 @@ __SPACE__
* [*Requires:] `T` is __MOVE_CONSTRUCTIBLE__ and `MoveAssignable`.
* [*Effects:]
[table
[table
[]
[[][[*`*this` contains a value]][[*`*this` does not contain a value]]]
[[[*`rhs` contains a value]][assigns `std::move(*rhs)` to the contained value][initializes the contained value as if direct-initializing an object of type `T` with `std::move(*rhs)`]]
[[[*`rhs` does not contain a value]][destroys the contained value by calling `val->T::~T()`][no effect]]
]
* [*Returns:] `*this`;
* [*Postconditions:] `bool(rhs) == bool(*this)`.
* [*Postconditions:] `bool(rhs) == bool(*this)`.
* [*Remarks:] The expression inside `noexcept` is equivalent to `is_nothrow_move_constructible<T>::value && is_nothrow_move_assignable<T>::value`.
* [*Exception Safety:] If any exception is thrown, the initialization state of `*this` and `rhs` remains unchanged. If an exception is
thrown during the call to `T`'s move constructor, the state of `*rhs` is determined by the exception safety guarantee
@ -437,15 +437,15 @@ __SPACE__
[: `template<U> optional& optional<T>::operator= ( optional<U> const& rhs ) ;`]
* [*Effect:]
[table
* [*Effect:]
[table
[]
[[][[*`*this` contains a value]][[*`*this` does not contain a value]]]
[[[*`rhs` contains a value]][assigns `*rhs` to the contained value][initializes the contained value as if direct-initializing an object of type `T` with `*rhs`]]
[[[*`rhs` does not contain a value]][destroys the contained value by calling `val->T::~T()`][no effect]]
]
* [*Returns:] `*this`.
* [*Postconditions:] `bool(rhs) == bool(*this)`.
* [*Postconditions:] `bool(rhs) == bool(*this)`.
* [*Exception Safety:] If any exception is thrown, the result of the expression `bool(*this)` remains unchanged.
If an exception is thrown during the call to `T`'s constructor, no effect.
If an exception is thrown during the call to `T`'s assignment, the state of its contained value is as defined by the exception safety guarantee of `T`'s copy assignment.
@ -467,13 +467,13 @@ __SPACE__
* [*Effect:]
[table
[]
[]
[[][[*`*this` contains a value]][[*`*this` does not contain a value]]]
[[[*`rhs` contains a value]][assigns `std::move(*rhs)` to the contained value][initializes the contained value as if direct-initializing an object of type `T` with `std::move(*rhs)`]]
[[[*`rhs` does not contain a value]][destroys the contained value by calling `val->T::~T()`][no effect]]
]
* [*Returns:] `*this`.
* [*Postconditions:] `bool(rhs) == bool(*this)`.
* [*Postconditions:] `bool(rhs) == bool(*this)`.
* [*Exception Safety:] If any exception is thrown, the result of the expression `bool(*this)` remains unchanged.
If an exception is thrown during the call to `T`'s constructor, no effect.
If an exception is thrown during the call to `T`'s assignment, the state of its contained value is as defined by the exception safety guarantee of `T`'s copy assignment.
@ -485,7 +485,7 @@ optional<U> opt1;
opt1 = std::move(opt0) ;
assert ( opt0 );
assert ( opt1 )
assert ( opt1 )
assert ( *opt1 == static_cast<U>(v) ) ;
``
@ -498,11 +498,11 @@ __SPACE__
* [*Requires:] The compiler supports rvalue references and variadic templates.
* [*Effect:] If `*this` is initialized calls `*this = none`.
Then initializes in-place the contained value as if direct-initializing an object
of type `T` with `std::forward<Args>(args)...`.
of type `T` with `std::forward<Args>(args)...`.
* [*Postconditions: ] `*this` is [_initialized].
* [*Throws:] Whatever the selected `T`'s constructor throws.
* [*Exception Safety:] If an exception is thrown during the initialization of `T`, `*this` is ['uninitialized].
* [*Notes:] `T` need not be __MOVE_CONSTRUCTIBLE__ or `MoveAssignable`. On compilers that do not suppor variadic templates or rvalue references, this function is available in limited functionality. For details [link optional_emplace_workaround see here].
* [*Notes:] `T` need not be __MOVE_CONSTRUCTIBLE__ or `MoveAssignable`. On compilers that do not suppor variadic templates or rvalue references, this function is available in limited functionality. For details [link optional_emplace_workaround see here].
* [*Example:]
``
T v;
@ -691,7 +691,16 @@ __SPACE__
[: `template<class F> auto optional<T>::map(F f) & -> `['see below]` ;`]
* [*Effects:] `if (*this) return f(**this); else return none;`
* [*Notes:] The return type of these overloads is `optional<decltype(f(**this))>`. On compilers that do not support ref-qualifiers on member functions, these two (as well as the next one) overloads are replaced with good old const and non-const overloads.
* [*Notes:] The return type of these overloads is `optional<decltype(f(**this))>`. On compilers that do not support ref-qualifiers on member functions, these two (as well as the next one) overloads are replaced with good old const and non-const overloads.
* [*Example:]
``
auto length = [](const string& s){ return s.size(); };
optional<string> o1 {}, o2 {"cat"};
optional<size_t> os1 = o1.map(length), os2 = o2.map(length);
assert ( !os1 ) ;
assert ( os2 ) ;
assert ( *os2 == 3 ) ;
``
__SPACE__
@ -704,6 +713,37 @@ __SPACE__
__SPACE__
[#reference_optional_flat_map]
[: `template<class F> auto optional<T>::flat_map(F f) const& -> `['see below]` ;`]
[: `template<class F> auto optional<T>::flat_map(F f) & -> `['see below]` ;`]
* [*Requires:] The return type of expression `f(**this)` is `optional<U>` for some object or reference type `U`.
* [*Effects:] `if (*this) return f(**this); else return none;`
* [*Notes:] The return type of these overloads is `optional<U>`. On compilers that do not support ref-qualifiers on member functions, these two (as well as the next one) overloads are replaced with good old const and non-const overloads.
* [*Example:]
``
optional<char> first_char(const string& s) {
return s.empty() ? none : optional<char>(s[0]);
};
optional<string> o1 {}, o2 {"cat"};
optional<char> os1 = o1.flat_map(first_char), os2 = o2.flat_map(first_char);
assert ( !os1 ) ;
assert ( os2 ) ;
assert ( *os2 == 'c' ) ;
``
__SPACE__
[#reference_optional_flat_map_move]
[: `template<class F> auto optional<T>::flat_map(F f) && -> `['see below]` ;`]
* [*Requires:] The return type of expression `f(std::move(**this))` is `optional<U>` for some object or reference type `U`.
* [*Effects:] `if (*this) return f(std::move(**this)); else return none;`
* [*Notes:] The return type of this overload is `optional<U>`.
__SPACE__
[#reference_optional_get_value_or_value]
[: `T const& optional<T>::get_value_or( T const& default) const ;`]
@ -835,7 +875,7 @@ __SPACE__
[: `template<class R> optional<T&>::optional(R&& r) noexcept;`]
* [*Postconditions:] `bool(*this) == true`; `addressof(**this) == addressof(r)`.
* [*Remarks:] Unless `R` is an lvalue reference, the program is ill-formed. This constructor does not participate in overload resolution if `decay<R>` is an instance of `boost::optional`.
* [*Notes:] This constructor is declared `explicit` on compilers that do not correctly suport binding to const lvalues of integral types. For more details [link optional_reference_binding see here].
* [*Notes:] This constructor is declared `explicit` on compilers that do not correctly suport binding to const lvalues of integral types. For more details [link optional_reference_binding see here].
* [*Example:]
``
T v;
@ -862,7 +902,7 @@ __SPACE__
[: `optional<T&>::optional ( optional const& rhs ) noexcept ;`]
* [*Effects: ] Initializes `ref` with expression `rhs.ref`.
* [*Postconditions:] `bool(*this) == bool(rhs)`.
* [*Example:]
@ -895,7 +935,7 @@ __SPACE__
* [*Requires:] `is_convertible<U&, T&>::value` is `true`.
* [*Effects: ] Initializes `ref` with expression `rhs.ref`.
* [*Postconditions:] `bool(*this) == bool(rhs)`.
@ -911,7 +951,7 @@ __SPACE__
* [*Postconditions:] `bool(*this) == false`.
[#reference_optional_ref_copy_assign]
@ -959,7 +999,7 @@ assert ( *ora == 4 ) ;
* [*returns:] `*this`.
* [*Postconditions:] `bool(*this) == bool(rhs)`.
__SPACE__
@ -970,7 +1010,7 @@ __SPACE__
* [*Effects: ] Assigns `ref` with expression `r`.
* [*returns:] `*this`.
* [*Postconditions:] `bool(*this) == true`.
* [*Remarks:] Unless `R` is an lvalue reference, the program is ill-formed. This function does not participate in overload resolution if `decay<R>` is an instance of `boost::optional`.
@ -1035,13 +1075,13 @@ __SPACE__
[#reference_optional_ref_value]
[: `T& optional<T&>::value() const ;`]
* [*Effects:] Equivalent to `return bool(*this) ? *val : throw bad_optional_access();`.
* [*Effects:] Equivalent to `return bool(*this) ? *val : throw bad_optional_access();`.
__SPACE__
[#reference_optional_ref_value_or]
[: `template<class R> T& optional<T&>::value_or( R&& r ) const noexcept;`]
* [*Effects:] Equivalent to `if (*this) return **this; else return r;`.
* [*Effects:] Equivalent to `if (*this) return **this; else return r;`.
* [*Remarks:] Unless `R` is an lvalue reference, the program is ill-formed.
__SPACE__
@ -1060,6 +1100,14 @@ __SPACE__
__SPACE__
[#reference_optional_ref_flat_map]
[: `template<class F> auto optional<T&>::flat_map( F f ) const -> `['see below]`;`]
* [*Requires:] The return type of expression `f(**this)` is `optional<U>` for some object or reference type `U`.
* [*Effects:] Equivalent to `if (*this) return f(**this); else return none;`.
* [*Remarks:] The return type of this function is `optional<U>`.
__SPACE__
[#reference_optional_ref_get_ptr]
[: `T* optional<T&>::get_ptr () const noexcept;`]
* [*Returns:] `ref`.
@ -1102,9 +1150,9 @@ __SPACE__
[#reference_optional_ref_get_value_or_value]
[: `template<class R> T& optional<T&>::get_value_or( R&& r ) const noexcept;`]
* [*Effects:] Equivalent to `return value_or(std::forward<R>(r);`.
* [*Effects:] Equivalent to `return value_or(std::forward<R>(r);`.
* [*Remarks:] This function is depprecated.
[endsect]
@ -1303,7 +1351,7 @@ __SPACE__
* [*Requires:] Lvalues of type `T` shall be swappable and `T` shall be __MOVE_CONSTRUCTIBLE__.
* [*Effects:]
[table
[table
[]
[[][[*`*this` contains a value]][[*`*this` does not contain a value]]]
[[[*`rhs` contains a value]][calls `swap(*(*this), *rhs)`][initializes the contained value of `*this` as if direct-initializing an object of type `T` with the expression `std::move(*rhs)`, followed by `rhs.val->T::~T()`, `*this` contains a value and `rhs` does not contain a value]]