From d0b87d2f359f8fa4fa31c84ca03e0e18576a7c11 Mon Sep 17 00:00:00 2001 From: Andrzej Krzemienski Date: Mon, 2 Jul 2018 23:07:47 +0200 Subject: [PATCH] documented flat_map --- doc/27_ref_optional_synopsis.qbk | 89 ++++++++-------- doc/28_ref_optional_semantics.qbk | 100 +++++++++++++----- doc/91_relnotes.qbk | 7 +- ...ailed_semantics___optional_references.html | 24 +++++ .../detailed_semantics___optional_values.html | 76 +++++++++++++ .../header_optional_optional_refs.html | 3 +- .../header_optional_optional_values.html | 4 + doc/html/boost_optional/relnotes.html | 5 +- doc/html/index.html | 2 +- 9 files changed, 236 insertions(+), 74 deletions(-) diff --git a/doc/27_ref_optional_synopsis.qbk b/doc/27_ref_optional_synopsis.qbk index 5d4c2e4..7114b43 100644 --- a/doc/27_ref_optional_synopsis.qbk +++ b/doc/27_ref_optional_synopsis.qbk @@ -17,16 +17,16 @@ class in_place_init_t { /* see below */ } ; ``[link reference_in_place_init __GO_TO__]`` const in_place_init_t in_place_init ( /* see below */ ) ; - + class in_place_init_if_t { /*see below*/ } ; ``[link reference_in_place_init_if __GO_TO__]`` const in_place_init_if_t in_place_init_if ( /*see below*/ ) ; - + template class optional ; ``[link reference_operator_template __GO_TO__]`` - + template class optional ; ``[link reference_operator_template_spec __GO_TO__]`` - + template inline bool operator == ( optional const& x, optional const& y ) ; ``[link reference_operator_compare_equal_optional_optional __GO_TO__]`` template inline bool operator != ( optional const& x, optional const& y ) ; ``[link reference_operator_compare_not_equal_optional_optional __GO_TO__]`` @@ -38,21 +38,21 @@ template inline bool operator <= ( optional const& x, optional const& y ) ; ``[link reference_operator_compare_less_or_equal_optional_optional __GO_TO__]`` template inline bool operator >= ( optional const& x, optional const& y ) ; ``[link reference_operator_compare_greater_or_equal_optional_optional __GO_TO__]`` - + template inline bool operator == ( optional const& x, none_t ) noexcept ; ``[link reference_operator_compare_equal_optional_none __GO_TO__]`` template inline bool operator != ( optional const& x, none_t ) noexcept ; ``[link reference_operator_compare_not_equal_optional_none __GO_TO__]`` template inline optional make_optional ( T const& v ) ; ``[link reference_make_optional_value __GO_TO__]`` - + template inline optional> make_optional ( T && v ) ; ``[link reference_make_optional_rvalue __GO_TO__]`` template inline optional make_optional ( bool condition, T const& v ) ; ``[link reference_make_optional_bool_value __GO_TO__]`` - + template inline optional> make_optional ( bool condition, T && v ) ; ``[link reference_make_optional_bool_rvalue __GO_TO__]`` - template inline auto get_optional_value_or ( optional const& opt, typename optional::reference_const_type def ) -> typename optional::reference_const_type; ``[link reference_free_get_value_or __GO_TO__]`` - + template inline auto get_optional_value_or ( optional const& opt, typename optional::reference_const_type def ) -> typename optional::reference_const_type; ``[link reference_free_get_value_or __GO_TO__]`` + template inline auto get_optional_value_or ( optional const& opt, typename optional::reference_type def ) -> typename optional::reference_type ; ``[link reference_free_get_value_or __GO_TO__]`` template inline T const& get ( optional const& opt ) ; ``[link reference_optional_get __GO_TO__]`` @@ -68,7 +68,7 @@ template inline auto get_pointer ( optional & opt ) -> ``['see below]``; ``[link reference_free_get_pointer __GO_TO__]`` template inline void swap( optional& x, optional& y ) ; ``[link reference_swap_optional_optional __GO_TO__]`` - + template inline void swap( optional& x, optional& y ) ; ``[link reference_swap_optional_reference __GO_TO__]`` } // namespace boost @@ -86,21 +86,21 @@ class in_place_init_t { /* see below */ } ; const in_place_init_t in_place_init ( /* see below */ ) ; - + class in_place_init_if_t { /*see below*/ } ; const in_place_init_if_t in_place_init_if ( /*see below*/ ) ; - + } -Classes `in_place_init_t` and `in_place_init_if_t` are empty clsses. Their purpose is to control overload resolution in the initialization of optional objects. -They are empty, trivially copyable classes with disabled default constructor. +Classes `in_place_init_t` and `in_place_init_if_t` are empty clsses. Their purpose is to control overload resolution in the initialization of optional objects. +They are empty, trivially copyable classes with disabled default constructor. [endsect] [section:header_optional_optional_values Optional Values] [#reference_operator_template] - + template class optional { @@ -112,27 +112,27 @@ They are empty, trivially copyable classes with disabled default constructor. typedef T && rval_reference_type ; typedef T * pointer_type ; typedef T const* pointer_const_type ; - + optional () noexcept ; ``[link reference_optional_constructor __GO_TO__]`` optional ( none_t ) noexcept ; ``[link reference_optional_constructor_none_t __GO_TO__]`` optional ( T const& v ) ; ``[link reference_optional_constructor_value __GO_TO__]`` - + optional ( T&& v ) ; ``[link reference_optional_constructor_move_value __GO_TO__]`` - optional ( bool condition, T const& v ) ; ``[link reference_optional_constructor_bool_value __GO_TO__]`` + optional ( bool condition, T const& v ) ; ``[link reference_optional_constructor_bool_value __GO_TO__]`` optional ( optional const& rhs ) ; ``[link reference_optional_constructor_optional __GO_TO__]`` - + optional ( optional&& rhs ) noexcept(``['see below]``) ; ``[link reference_optional_move_constructor_optional __GO_TO__]`` template explicit optional ( optional const& rhs ) ; ``[link reference_optional_constructor_other_optional __GO_TO__]`` - + template explicit optional ( optional&& rhs ) ; ``[link reference_optional_move_constructor_other_optional __GO_TO__]`` - + template explicit optional ( in_place_init_t, Args&&... args ) ; ``[link reference_optional_in_place_init __GO_TO__]`` - + template explicit optional ( in_place_init_if_t, bool condition, Args&&... args ) ; ``[link reference_optional_in_place_init_if __GO_TO__]`` template explicit optional ( InPlaceFactory const& f ) ; ``[link reference_optional_constructor_factory __GO_TO__]`` @@ -142,17 +142,17 @@ They are empty, trivially copyable classes with disabled default constructor. optional& operator = ( none_t ) noexcept ; ``[link reference_optional_operator_equal_none_t __GO_TO__]`` optional& operator = ( T const& v ) ; ``[link reference_optional_operator_equal_value __GO_TO__]`` - + optional& operator = ( T&& v ) ; ``[link reference_optional_operator_move_equal_value __GO_TO__]`` optional& operator = ( optional const& rhs ) ; ``[link reference_optional_operator_equal_optional __GO_TO__]`` - + optional& operator = ( optional&& rhs ) noexcept(``['see below]``) ; ``[link reference_optional_operator_move_equal_optional __GO_TO__]`` template optional& operator = ( optional const& rhs ) ; ``[link reference_optional_operator_equal_other_optional __GO_TO__]`` - + template optional& operator = ( optional&& rhs ) ; ``[link reference_optional_operator_move_equal_other_optional __GO_TO__]`` - + template void emplace ( Args&&... args ) ; ``[link reference_optional_emplace __GO_TO__]`` template optional& operator = ( InPlaceFactory const& f ) ; ``[link reference_optional_operator_equal_factory __GO_TO__]`` @@ -168,14 +168,14 @@ They are empty, trivially copyable classes with disabled default constructor. T const& operator *() const& ; ``[link reference_optional_operator_asterisk __GO_TO__]`` T& operator *() & ; ``[link reference_optional_operator_asterisk __GO_TO__]`` T&& operator *() && ; ``[link reference_optional_operator_asterisk_move __GO_TO__]`` - + T const& value() const& ; ``[link reference_optional_value __GO_TO__]`` T& value() & ; ``[link reference_optional_value __GO_TO__]`` T&& value() && ; ``[link reference_optional_value_move __GO_TO__]`` - + template T value_or( U && v ) const& ; ``[link reference_optional_value_or __GO_TO__]`` template T value_or( U && v ) && ; ``[link reference_optional_value_or_move __GO_TO__]`` - + template T value_or_eval( F f ) const& ; ``[link reference_optional_value_or_call __GO_TO__]`` template T value_or_eval( F f ) && ; ``[link reference_optional_value_or_call_move __GO_TO__]`` @@ -183,11 +183,15 @@ They are empty, trivially copyable classes with disabled default constructor. template auto map( F f ) & -> ``['see below]``; ``[link reference_optional_map __GO_TO__]`` template auto map( F f ) && -> ``['see below]``; ``[link reference_optional_map_move __GO_TO__]`` + template auto flat_map( F f ) const& -> ``['see below]``; ``[link reference_optional_flat_map __GO_TO__]`` + template auto flat_map( F f ) & -> ``['see below]``; ``[link reference_optional_flat_map __GO_TO__]`` + template auto flat_map( F f ) && -> ``['see below]``; ``[link reference_optional_flat_map_move __GO_TO__]`` + T const* get_ptr() const ; ``[link reference_optional_get_ptr __GO_TO__]`` T* get_ptr() ; ``[link reference_optional_get_ptr __GO_TO__]`` bool has_value() const noexcept ; ``[link reference_optional_operator_bool __GO_TO__]`` - + explicit operator bool() const noexcept ; ``[link reference_optional_operator_bool __GO_TO__]`` bool operator!() const noexcept ; ``[link reference_optional_operator_not __GO_TO__]`` @@ -204,7 +208,7 @@ They are empty, trivially copyable classes with disabled default constructor. bool is_initialized() const ; ``[link reference_optional_is_initialized __GO_TO__]`` // (deprecated) - T const& get_value_or( T const& default ) const ; ``[link reference_optional_get_value_or_value __GO_TO__]`` + T const& get_value_or( T const& default ) const ; ``[link reference_optional_get_value_or_value __GO_TO__]`` }; @@ -231,22 +235,21 @@ They are empty, trivially copyable classes with disabled default constructor. optional ( none_t ) noexcept ; ``[link reference_optional_ref_default_ctor __GO_TO__]`` template optional(R&& r) noexcept ; ``[link reference_optional_ref_value_ctor __GO_TO__]`` - + template optional(bool cond, R&& r) noexcept ; ``[link reference_optional_ref_cond_value_ctor __GO_TO__]`` - + optional ( optional const& rhs ) noexcept ; ``[link reference_optional_ref_copy_ctor __GO_TO__]`` template explicit optional ( optional const& rhs ) noexcept ; ``[link reference_optional_ref_ctor_from_opt_U __GO_TO__]`` optional& operator = ( none_t ) noexcept ; ``[link reference_optional_ref_assign_none_t __GO_TO__]`` - optional& operator = ( optional const& rhs ) noexcept; ``[link reference_optional_ref_copy_assign __GO_TO__]`` template optional& operator = ( optional const& rhs ) noexcept ; ``[link reference_optional_ref_assign_optional_U __GO_TO__]`` - - template optional& operator = (R&& r) noexcept ; ``[link reference_optional_ref_assign_R __GO_TO__]`` - + + template optional& operator = (R&& r) noexcept ; ``[link reference_optional_ref_assign_R __GO_TO__]`` + template void emplace ( R&& r ) noexcept ; ``[link reference_optional_ref_emplace_R __GO_TO__]`` T& get() const ; ``[link reference_optional_ref_get __GO_TO__]`` @@ -255,17 +258,19 @@ They are empty, trivially copyable classes with disabled default constructor. T* operator ->() const ; ``[link reference_optional_ref_arrow __GO_TO__]`` T& value() const& ; ``[link reference_optional_ref_value __GO_TO__]`` - + template T& value_or( R && r ) const noexcept ; ``[link reference_optional_ref_value_or __GO_TO__]`` - + template T& value_or_eval( F f ) const ; ``[link reference_optional_ref_value_or_eval __GO_TO__]`` template auto map( F f ) const -> ``['see below]``; ``[link reference_optional_ref_map __GO_TO__]`` + template auto flat_map( F f ) const -> ``['see below]``; ``[link reference_optional_ref_flat_map __GO_TO__]`` + T* get_ptr() const noexcept ; ``[link reference_optional_ref_get_ptr __GO_TO__]`` bool has_value() const noexcept ; ``[link reference_optional_ref_operator_bool __GO_TO__]`` - + explicit operator bool() const noexcept ; ``[link reference_optional_ref_operator_bool __GO_TO__]`` bool operator!() const noexcept ; ``[link reference_optional_ref_operator_not __GO_TO__]`` @@ -282,8 +287,8 @@ They are empty, trivially copyable classes with disabled default constructor. bool is_initialized() const noexcept ; ``[link reference_optional_ref_is_initialized __GO_TO__]`` // (deprecated) - template T& get_value_or( R && r ) constnoexcept; ``[link reference_optional_ref_get_value_or_value __GO_TO__]`` - + template T& get_value_or( R && r ) constnoexcept; ``[link reference_optional_ref_get_value_or_value __GO_TO__]`` + private: T* ref; // exposition only }; diff --git a/doc/28_ref_optional_semantics.qbk b/doc/28_ref_optional_semantics.qbk index b615e35..6ce0d2e 100644 --- a/doc/28_ref_optional_semantics.qbk +++ b/doc/28_ref_optional_semantics.qbk @@ -233,7 +233,7 @@ __SPACE__ arguments `std::forward(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)...`. * [*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::value && is_nothrow_move_assignable::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 optional& optional::operator= ( optional 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 opt1; opt1 = std::move(opt0) ; assert ( opt0 ); -assert ( opt1 ) +assert ( opt1 ) assert ( *opt1 == static_cast(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)...`. + of type `T` with `std::forward(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 auto optional::map(F f) & -> `['see below]` ;`] * [*Effects:] `if (*this) return f(**this); else return none;` -* [*Notes:] The return type of these overloads is `optional`. 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`. 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 o1 {}, o2 {"cat"}; +optional 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 auto optional::flat_map(F f) const& -> `['see below]` ;`] +[: `template auto optional::flat_map(F f) & -> `['see below]` ;`] + +* [*Requires:] The return type of expression `f(**this)` is `optional` 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`. 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 first_char(const string& s) { + return s.empty() ? none : optional(s[0]); +}; +optional o1 {}, o2 {"cat"}; +optional 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 auto optional::flat_map(F f) && -> `['see below]` ;`] + +* [*Requires:] The return type of expression `f(std::move(**this))` is `optional` 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`. + +__SPACE__ + [#reference_optional_get_value_or_value] [: `T const& optional::get_value_or( T const& default) const ;`] @@ -835,7 +875,7 @@ __SPACE__ [: `template optional::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` 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::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::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` is an instance of `boost::optional`. @@ -1035,13 +1075,13 @@ __SPACE__ [#reference_optional_ref_value] [: `T& optional::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 T& optional::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 auto optional::flat_map( F f ) const -> `['see below]`;`] +* [*Requires:] The return type of expression `f(**this)` is `optional` 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`. + +__SPACE__ + [#reference_optional_ref_get_ptr] [: `T* optional::get_ptr () const noexcept;`] * [*Returns:] `ref`. @@ -1102,9 +1150,9 @@ __SPACE__ [#reference_optional_ref_get_value_or_value] [: `template T& optional::get_value_or( R&& r ) const noexcept;`] -* [*Effects:] Equivalent to `return value_or(std::forward(r);`. +* [*Effects:] Equivalent to `return value_or(std::forward(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]] diff --git a/doc/91_relnotes.qbk b/doc/91_relnotes.qbk index 79bb200..b7d410f 100644 --- a/doc/91_relnotes.qbk +++ b/doc/91_relnotes.qbk @@ -14,7 +14,8 @@ [heading Boost Release 1.68] * Added member function `has_value()` for compatibility with `std::optional` ([@https://github.com/boostorg/optional/issues/52 issue #52]). -* Added member function `map()` for transforming `optional` into `optional` using a function of type `U(T)`. +* Added member function `map()` for transforming `optional` into `optional` using a function of type `T -> U`. +* Added member function `flat_map()` for transforming `optional` into `optional` using a function of type `T -> optonal`. [heading Boost Release 1.67] @@ -26,7 +27,7 @@ [heading Boost Release 1.66] * On newer compilers `optional` is now trivially-copyable for scalar `T`s. This uses a different storage (just `T` rather than `aligned_storage`). We require the compiler to support defaulted functions. -* Changed the implementation of `operator==` to get rid of the `-Wmaybe-uninitialized` false-positive warning from GCC. +* Changed the implementation of `operator==` to get rid of the `-Wmaybe-uninitialized` false-positive warning from GCC. [heading Boost Release 1.63] * Added two new in-place constructors. They work similarly to `emplace()` functions: they initialize the contained value by perfect-forwarding the obtained arguments. One constructor always initializes the contained value, the other based on a boolean condition. @@ -70,7 +71,7 @@ * IOStream operators are now mentioned in documentation. * Added a way to manually disable move semantics: just define macro `BOOST_OPTIONAL_CONFIG_NO_RVALUE_REFERENCES`. This can be used to work around [@https://svn.boost.org/trac/boost/ticket/10399 Trac #10399]. * It is no longer possible to assign `optional` to `optional` when `U` is not assignable or convertible to `T` ([@https://svn.boost.org/trac/boost/ticket/11087 Trac #11087]). -* Value accessors now work correctly on rvalues of `optional` ([@https://svn.boost.org/trac/boost/ticket/10839 Trac #10839]). +* Value accessors now work correctly on rvalues of `optional` ([@https://svn.boost.org/trac/boost/ticket/10839 Trac #10839]). [heading Boost Release 1.57] diff --git a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics___optional_references.html b/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics___optional_references.html index acb6775..99b8cb8 100644 --- a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics___optional_references.html +++ b/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics___optional_references.html @@ -422,6 +422,30 @@ is optional<decltype(f(**this))>. +

+ space +

+

+ 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

diff --git a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics___optional_values.html b/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics___optional_values.html index 127df4c..42af248 100644 --- a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics___optional_values.html +++ b/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics___optional_values.html @@ -1495,6 +1495,16 @@ 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 @@ -1515,6 +1525,72 @@ is optional<decltype(f(istd::move(**this)))>. +

    + space +

    +

    + 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 +
      • +
    +

    + 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

    diff --git a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/header_optional_optional_refs.html b/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/header_optional_optional_refs.html index 77906eb..43b0c0a 100644 --- a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/header_optional_optional_refs.html +++ b/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/header_optional_optional_refs.html @@ -53,7 +53,6 @@ optional& operator = ( none_t ) noexcept ; R - optional& operator = ( optional const& rhs ) noexcept; R template<class U> optional& operator = ( optional<U&> const& rhs ) noexcept ; R @@ -75,6 +74,8 @@ template<class F> auto map( F f ) const -> see below; R + template<class F> auto flat_map( F f ) const -> see below; R + T* get_ptr() const noexcept ; R bool has_value() const noexcept ; R diff --git a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/header_optional_optional_values.html b/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/header_optional_optional_values.html index 5e960f1..5e1edff 100644 --- a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/header_optional_optional_values.html +++ b/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/header_optional_optional_values.html @@ -109,6 +109,10 @@ template<class F> auto map( F f ) & -> see below; R template<class F> auto map( F f ) && -> see below; R + template<class F> auto flat_map( F f ) const& -> see below; R + template<class F> auto flat_map( F f ) & -> see below; R + template<class F> auto flat_map( F f ) && -> see below; R + T const* get_ptr() const ; R T* get_ptr() ; R diff --git a/doc/html/boost_optional/relnotes.html b/doc/html/boost_optional/relnotes.html index b596e38..f074211 100644 --- a/doc/html/boost_optional/relnotes.html +++ b/doc/html/boost_optional/relnotes.html @@ -37,7 +37,10 @@ #52).
  • - Added member function map() for transforming optional<T> into optional<U> using a function of type U(T). + Added member function map() for transforming optional<T> into optional<U> using a function of type T -> U. +
    • +
  • + Added member function flat_map() for transforming optional<T> into optional<U> using a function of type T -> optonal<U>.

    • diff --git a/doc/html/index.html b/doc/html/index.html index 44e9bc0..c563c86 100644 --- a/doc/html/index.html +++ b/doc/html/index.html @@ -145,7 +145,7 @@ - +

    Last revised: June 23, 2018 at 18:49:36 GMT

    Last revised: July 02, 2018 at 21:10:01 GMT