diff options
Diffstat (limited to 'libs/optional/doc/20_reference.qbk')
| -rw-r--r-- | libs/optional/doc/20_reference.qbk | 1288 |
1 files changed, 0 insertions, 1288 deletions
diff --git a/libs/optional/doc/20_reference.qbk b/libs/optional/doc/20_reference.qbk deleted file mode 100644 index cba3bac90..000000000 --- a/libs/optional/doc/20_reference.qbk +++ /dev/null @@ -1,1288 +0,0 @@ -[/ - Boost.Optional - - Copyright (c) 2003-2007 Fernando Luis Cacciola Carballal - - Distributed under the Boost Software License, Version 1.0. - (See accompanying file LICENSE_1_0.txt or copy at - http://www.boost.org/LICENSE_1_0.txt) -] - - -[section Synopsis] - - ```// In Header: <`[@boost:/boost/optional/optional.hpp boost/optional/optional.hpp]'''<phrase role="comment">></phrase>'''`` - - namespace boost { - - template<class T> - class optional - { - public : - - // (If T is of reference type, the parameters and results by reference are by value) - - 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__]`` - - // [new in 1.34] - 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<class U> explicit optional ( optional<U> const& rhs ) ; ``[link reference_optional_constructor_other_optional __GO_TO__]`` - - template<class U> explicit optional ( optional<U>&& rhs ) ; ``[link reference_optional_move_constructor_other_optional __GO_TO__]`` - - template<class InPlaceFactory> explicit optional ( InPlaceFactory const& f ) ; ``[link reference_optional_constructor_factory __GO_TO__]`` - - template<class TypedInPlaceFactory> explicit optional ( TypedInPlaceFactory const& f ) ; ``[link reference_optional_constructor_factory __GO_TO__]`` - - 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<class U> optional& operator = ( optional<U> const& rhs ) ; ``[link reference_optional_operator_equal_other_optional __GO_TO__]`` - - template<class U> optional& operator = ( optional<U>&& rhs ) ; ``[link reference_optional_operator_move_equal_other_optional __GO_TO__]`` - - template<class... Args> void emplace ( Args...&& args ) ; ``[link reference_optional_emplace __GO_TO__]`` - - template<class InPlaceFactory> optional& operator = ( InPlaceFactory const& f ) ; ``[link reference_optional_operator_equal_factory __GO_TO__]`` - - template<class TypedInPlaceFactory> optional& operator = ( TypedInPlaceFactory const& f ) ; ``[link reference_optional_operator_equal_factory __GO_TO__]`` - - T const& get() const ; ``[link reference_optional_get __GO_TO__]`` - T& get() ; ``[link reference_optional_get __GO_TO__]`` - - T const* operator ->() const ; ``[link reference_optional_operator_arrow __GO_TO__]`` - T* operator ->() ; ``[link reference_optional_operator_arrow __GO_TO__]`` - - 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<class U> T value_or( U && v ) const& ; ``[link reference_optional_value_or __GO_TO__]`` - template<class U> T value_or( U && v ) && ; ``[link reference_optional_value_or_move __GO_TO__]`` - - template<class F> T value_or_eval( F f ) const& ; ``[link reference_optional_value_or_call __GO_TO__]`` - template<class F> T value_or_eval( F f ) && ; ``[link reference_optional_value_or_call_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__]`` - - explicit operator bool() const noexcept ; ``[link reference_optional_operator_bool __GO_TO__]`` - - bool operator!() const noexcept ; ``[link reference_optional_operator_not __GO_TO__]`` - - // deprecated methods - - // (deprecated) - void reset() noexcept ; ``[link reference_optional_reset __GO_TO__]`` - - // (deprecated) - void reset ( T const& ) ; ``[link reference_optional_reset_value __GO_TO__]`` - - // (deprecated) - 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__]`` - }; - - template<class T> inline bool operator == ( optional<T> const& x, optional<T> const& y ) ; ``[link reference_operator_compare_equal_optional_optional __GO_TO__]`` - - template<class T> inline bool operator != ( optional<T> const& x, optional<T> const& y ) ; ``[link reference_operator_compare_not_equal_optional_optional __GO_TO__]`` - - template<class T> inline bool operator < ( optional<T> const& x, optional<T> const& y ) ; ``[link reference_operator_compare_less_optional_optional __GO_TO__]`` - - template<class T> inline bool operator > ( optional<T> const& x, optional<T> const& y ) ; ``[link reference_operator_compare_greater_optional_optional __GO_TO__]`` - - template<class T> inline bool operator <= ( optional<T> const& x, optional<T> const& y ) ; ``[link reference_operator_compare_less_or_equal_optional_optional __GO_TO__]`` - - template<class T> inline bool operator >= ( optional<T> const& x, optional<T> const& y ) ; ``[link reference_operator_compare_greater_or_equal_optional_optional __GO_TO__]`` - - template<class T> inline bool operator == ( optional<T> const& x, none_t ) noexcept ; ``[link reference_operator_compare_equal_optional_none __GO_TO__]`` - - template<class T> inline bool operator != ( optional<T> const& x, none_t ) noexcept ; ``[link reference_operator_compare_not_equal_optional_none __GO_TO__]`` - - template<class T> inline optional<T> make_optional ( T const& v ) ; ``[link reference_make_optional_value __GO_TO__]`` - - template<class T> inline optional<T> make_optional ( bool condition, T const& v ) ; ``[link reference_make_optional_bool_value __GO_TO__]`` - - template<class T> inline T const& get_optional_value_or ( optional<T> const& opt, T const& default ) ; ``[link reference_optional_get_value_or_value __GO_TO__]`` - - template<class T> inline T const& get ( optional<T> const& opt ) ; ``[link reference_optional_get __GO_TO__]`` - - template<class T> inline T& get ( optional<T> & opt ) ; ``[link reference_optional_get __GO_TO__]`` - - template<class T> inline T const* get ( optional<T> const* opt ) ; ``[link reference_optional_get __GO_TO__]`` - - template<class T> inline T* get ( optional<T>* opt ) ; ``[link reference_optional_get __GO_TO__]`` - - template<class T> inline T const* get_pointer ( optional<T> const& opt ) ; ``[link reference_optional_get_ptr __GO_TO__]`` - - template<class T> inline T* get_pointer ( optional<T> & opt ) ; ``[link reference_optional_get_ptr __GO_TO__]`` - - template<class T> inline void swap( optional<T>& x, optional<T>& y ) ; ``[link reference_swap_optional_optional __GO_TO__]`` - - } // namespace boost - - -[endsect] - -[section Detailed Semantics] - -Because `T` might be of reference type, in the sequel, those entries whose -semantic depends on `T` being of reference type or not will be distinguished -using the following convention: - -* If the entry reads: `optional<T`['(not a ref)]`>`, the description -corresponds only to the case where `T` is not of reference type. -* If the entry reads: `optional<T&>`, the description corresponds only to -the case where `T` is of reference type. -* If the entry reads: `optional<T>`, the description is the same for both -cases. - -[note -The following section contains various `assert()` which are used only to show -the postconditions as sample code. It is not implied that the type `T` must -support each particular expression but that if the expression is supported, -the implied condition holds. -] - -__SPACE__ - -[heading optional class member functions] - -__SPACE__ - -[#reference_optional_constructor] - -[: `optional<T>::optional() noexcept;`] - -* [*Effect:] Default-Constructs an `optional`. -* [*Postconditions:] `*this` is [_uninitialized]. -* [*Notes:] T's default constructor [_is not] called. -* [*Example:] -`` -optional<T> def ; -assert ( !def ) ; -`` - -__SPACE__ - -[#reference_optional_constructor_none_t] - -[: `optional<T>::optional( none_t ) noexcept;`] - -* [*Effect:] Constructs an `optional` uninitialized. -* [*Postconditions:] `*this` is [_uninitialized]. -* [*Notes:] `T`'s default constructor [_is not] called. The expression -`boost::none` denotes an instance of `boost::none_t` that can be used as -the parameter. -* [*Example:] -`` -#include <boost/none.hpp> -optional<T> n(none) ; -assert ( !n ) ; -`` - -__SPACE__ - -[#reference_optional_constructor_value] - -[: `optional<T `['(not a ref)]`>::optional( T const& v )`] - -* [*Requires:] `is_copy_constructible<T>::value` is `true`. -* [*Effect:] Directly-Constructs an `optional`. -* [*Postconditions:] `*this` is [_initialized] and its value is a ['copy] -of `v`. -* [*Throws:] Whatever `T::T( T const& )` throws. -* [*Notes: ] `T::T( T const& )` is called. -* [*Exception Safety:] Exceptions can only be thrown during -`T::T( T const& );` in that case, this constructor has no effect. -* [*Example:] -`` -T v; -optional<T> opt(v); -assert ( *opt == v ) ; -`` - -__SPACE__ - -[: `optional<T&>::optional( T& ref )`] - -* [*Effect:] Directly-Constructs an `optional`. -* [*Postconditions:] `*this` is [_initialized] and its value is an instance -of an internal type wrapping the reference `ref`. -* [*Throws:] Nothing. -* [*Example:] -`` -T v; -T& vref = v ; -optional<T&> opt(vref); -assert ( *opt == v ) ; -++ v ; // mutate referee -assert (*opt == v); -`` - -__SPACE__ - -[#reference_optional_constructor_move_value] - -[: `optional<T `['(not a ref)]`>::optional( T&& v )`] - -* [*Requires:] `is_move_constructible<T>::value` is `true`. -* [*Effect:] Directly-Move-Constructs an `optional`. -* [*Postconditions:] `*this` is [_initialized] and its value is move-constructed from `v`. -* [*Throws:] Whatever `T::T( T&& )` throws. -* [*Notes: ] `T::T( T&& )` is called. -* [*Exception Safety:] Exceptions can only be thrown during -`T::T( T&& );` in that case, the state of `v` is determined by exception safety guarantees for `T::T(T&&)`. -* [*Example:] -`` -T v1, v2; -optional<T> opt(std::move(v1)); -assert ( *opt == v2 ) ; -`` - -__SPACE__ - -[: `optional<T&>::optional( T&& ref ) = delete`] - -* [*Notes:] This constructor is deleted - - -__SPACE__ - -[#reference_optional_constructor_bool_value] - -[: `optional<T` ['(not a ref)]`>::optional( bool condition, T const& v ) ;` ] -[: `optional<T&> ::optional( bool condition, T& v ) ;` ] - -* If condition is true, same as: - -[: `optional<T` ['(not a ref)]`>::optional( T const& v )`] -[: `optional<T&> ::optional( T& v )`] - -* otherwise, same as: - -[: `optional<T `['(not a ref)]`>::optional()`] -[: `optional<T&> ::optional()`] - -__SPACE__ - -[#reference_optional_constructor_optional] - -[: `optional<T `['(not a ref)]`>::optional( optional const& rhs );`] - -* [*Requires:] `is_copy_constructible<T>::value` is `true`. -* [*Effect:] Copy-Constructs an `optional`. -* [*Postconditions:] If rhs is initialized, `*this` is initialized and -its value is a ['copy] of the value of `rhs`; else `*this` is uninitialized. -* [*Throws:] Whatever `T::T( T const& )` throws. -* [*Notes:] If rhs is initialized, `T::T(T const& )` is called. -* [*Exception Safety:] Exceptions can only be thrown during -`T::T( T const& );` in that case, this constructor has no effect. -* [*Example:] -`` -optional<T> uninit ; -assert (!uninit); - -optional<T> uinit2 ( uninit ) ; -assert ( uninit2 == uninit ); - -optional<T> init( T(2) ); -assert ( *init == T(2) ) ; - -optional<T> init2 ( init ) ; -assert ( init2 == init ) ; -`` - -__SPACE__ - -[: `optional<T&>::optional( optional const& rhs );`] - -* [*Effect:] Copy-Constructs an `optional`. -* [*Postconditions:] If `rhs` is initialized, `*this` is initialized and its -value is another reference to the same object referenced by `*rhs`; else -`*this` is uninitialized. -* [*Throws:] Nothing. -* [*Notes:] If `rhs` is initialized, both `*this` and `*rhs` will refer to the -same object (they alias). -* [*Example:] -`` -optional<T&> uninit ; -assert (!uninit); - -optional<T&> uinit2 ( uninit ) ; -assert ( uninit2 == uninit ); - -T v = 2 ; T& ref = v ; -optional<T> init(ref); -assert ( *init == v ) ; - -optional<T> init2 ( init ) ; -assert ( *init2 == v ) ; - -v = 3 ; - -assert ( *init == 3 ) ; -assert ( *init2 == 3 ) ; -`` - -__SPACE__ - -[#reference_optional_move_constructor_optional] - -[: `optional<T `['(not a ref)]`>::optional( optional&& rhs ) noexcept(`['see below]`);`] - -* [*Requires:] `is_move_constructible<T>::value` is `true`. -* [*Effect:] Move-constructs an `optional`. -* [*Postconditions:] If `rhs` is initialized, `*this` is initialized and -its value is move constructed from `rhs`; else `*this` is uninitialized. -* [*Throws:] Whatever `T::T( T&& )` throws. -* [*Remarks:] The expression inside `noexcept` is equivalent to `is_nothrow_move_constructible<T>::value`. -* [*Notes:] If `rhs` is initialized, `T::T( T && )` is called. -* [*Exception Safety:] Exceptions can only be thrown during -`T::T( T&& );` in that case, `rhs` remains initialized and the value of `*rhs` is determined by exception safety of `T::T(T&&)`. -* [*Example:] -`` -optional<std::unique_ptr<T>> uninit ; -assert (!uninit); - -optional<std::unique_ptr<T>> uinit2 ( std::move(uninit) ) ; -assert ( uninit2 == uninit ); - -optional<std::unique_ptr<T>> init( std::uniqye_ptr<T>(new T(2)) ); -assert ( **init == T(2) ) ; - -optional<std::unique_ptr<T>> init2 ( std::move(init) ) ; -assert ( init ); -assert ( *init == nullptr ); -assert ( init2 ); -assert ( **init2 == T(2) ) ; -`` - -__SPACE__ - -[: `optional<T&>::optional( optional && rhs );`] - -* [*Effect:] Move-Constructs an `optional`. -* [*Postconditions:] If `rhs` is initialized, `*this` is initialized and its -value is another reference to the same object referenced by `*rhs`; else -`*this` is uninitialized. -* [*Throws:] Nothing. -* [*Notes:] If `rhs` is initialized, both `*this` and `*rhs` will refer to the -same object (they alias). -* [*Example:] -`` -optional<std::unique_ptr<T>&> uninit ; -assert (!uninit); - -optional<std::unique_ptr<T>&> uinit2 ( std::move(uninit) ) ; -assert ( uninit2 == uninit ); - -std::unique_ptr<T> v(new T(2)) ; -optional<std::unique_ptr<T>&> init(v); -assert ( *init == v ) ; - -optional<std::unique_ptr<T>&> init2 ( std::move(init) ) ; -assert ( *init2 == v ) ; - -*v = 3 ; - -assert ( **init == 3 ) ; -assert ( **init2 == 3 ) ; -`` - -__SPACE__ - -[#reference_optional_constructor_other_optional] - -[: `template<U> explicit optional<T` ['(not a ref)]`>::optional( optional<U> const& rhs );`] - -* [*Effect:] Copy-Constructs an `optional`. -* [*Postconditions:] If `rhs` is initialized, `*this` is initialized and its -value is a ['copy] of the value of rhs converted to type `T`; else `*this` is -uninitialized. -* [*Throws:] Whatever `T::T( U const& )` throws. -* [*Notes: ] `T::T( U const& )` is called if `rhs` is initialized, which requires a -valid conversion from `U` to `T`. -* [*Exception Safety:] Exceptions can only be thrown during `T::T( U const& );` -in that case, this constructor has no effect. -* [*Example:] -`` -optional<double> x(123.4); -assert ( *x == 123.4 ) ; - -optional<int> y(x) ; -assert( *y == 123 ) ; -`` - -__SPACE__ - -[#reference_optional_move_constructor_other_optional] - -[: `template<U> explicit optional<T` ['(not a ref)]`>::optional( optional<U>&& rhs );`] - -* [*Effect:] Move-constructs an `optional`. -* [*Postconditions:] If `rhs` is initialized, `*this` is initialized and its -value is move-constructed from `*rhs`; else `*this` is -uninitialized. -* [*Throws:] Whatever `T::T( U&& )` throws. -* [*Notes: ] `T::T( U&& )` is called if `rhs` is initialized, which requires a -valid conversion from `U` to `T`. -* [*Exception Safety:] Exceptions can only be thrown during `T::T( U&& );` -in that case, `rhs` remains initialized and the value of `*rhs` is determined by exception safety guarantee of `T::T( U&& )`. -* [*Example:] -`` -optional<double> x(123.4); -assert ( *x == 123.4 ) ; - -optional<int> y(std::move(x)) ; -assert( *y == 123 ) ; -`` - -__SPACE__ - -[#reference_optional_constructor_factory] - -[: `template<InPlaceFactory> explicit optional<T` ['(not a ref)]`>::optional( InPlaceFactory const& f );`] -[: `template<TypedInPlaceFactory> explicit optional<T` ['(not a ref)]`>::optional( TypedInPlaceFactory const& f );`] - -* [*Effect:] Constructs an `optional` with a value of `T` obtained from the -factory. -* [*Postconditions: ] `*this` is [_initialized] and its value is ['directly given] -from the factory `f` (i.e., the value [_is not copied]). -* [*Throws:] Whatever the `T` constructor called by the factory throws. -* [*Notes:] See [link boost_optional.tutorial.in_place_factories In-Place Factories] -* [*Exception Safety:] Exceptions can only be thrown during the call to -the `T` constructor used by the factory; in that case, this constructor has -no effect. -* [*Example:] -`` -class C { C ( char, double, std::string ) ; } ; - -C v('A',123.4,"hello"); - -optional<C> x( in_place ('A', 123.4, "hello") ); // InPlaceFactory used -optional<C> y( in_place<C>('A', 123.4, "hello") ); // TypedInPlaceFactory used - -assert ( *x == v ) ; -assert ( *y == v ) ; -`` - -__SPACE__ - -[#reference_optional_operator_equal_none_t] - -[: `optional& optional<T>::operator= ( none_t ) noexcept;`] - -* [*Effect:] If `*this` is initialized destroys its contained value. -* [*Postconditions: ] `*this` is uninitialized. - -__SPACE__ - -[#reference_optional_operator_equal_value] - -[: `optional& optional<T` ['(not a ref)]`>::operator= ( T const& rhs ) ;`] - -* [*Effect:] Assigns the value `rhs` to an `optional`. -* [*Postconditions: ] `*this` is initialized and its value is a ['copy] of `rhs`. -* [*Throws:] Whatever `T::operator=( T const& )` or `T::T(T const&)` throws. -* [*Notes:] If `*this` was initialized, `T`'s assignment operator is used, -otherwise, its copy-constructor is used. -* [*Exception Safety:] In the event of an exception, the initialization -state of `*this` is unchanged and its value unspecified as far as `optional` -is concerned (it is up to `T`'s `operator=()`). If `*this` is initially -uninitialized and `T`'s ['copy constructor] fails, `*this` is left properly -uninitialized. -* [*Example:] -`` -T x; -optional<T> def ; -optional<T> opt(x) ; - -T y; -def = y ; -assert ( *def == y ) ; -opt = y ; -assert ( *opt == y ) ; -`` - -__SPACE__ - -[: `optional<T&>& optional<T&>::operator= ( T& rhs ) ;`] - -* [*Effect:] (Re)binds the wrapped reference. -* [*Postconditions: ] `*this` is initialized and it references the same -object referenced by `rhs`. -* [*Notes:] If `*this` was initialized, it is ['rebound] to the new object. -See [link boost_optional.tutorial.rebinding_semantics_for_assignment_of_optional_references here] for details on this behavior. -* [*Example:] -`` -int a = 1 ; -int b = 2 ; -T& ra = a ; -T& rb = b ; -optional<int&> def ; -optional<int&> opt(ra) ; - -def = rb ; // binds 'def' to 'b' through 'rb' -assert ( *def == b ) ; -*def = a ; // changes the value of 'b' to a copy of the value of 'a' -assert ( b == a ) ; -int c = 3; -int& rc = c ; -opt = rc ; // REBINDS to 'c' through 'rc' -c = 4 ; -assert ( *opt == 4 ) ; -`` - -__SPACE__ - -[#reference_optional_operator_move_equal_value] - -[: `optional& optional<T` ['(not a ref)]`>::operator= ( T&& rhs ) ;`] - -* [*Effect:] Moves the value `rhs` to an `optional`. -* [*Postconditions: ] `*this` is initialized and its value is moved from `rhs`. -* [*Throws:] Whatever `T::operator=( T&& )` or `T::T(T &&)` throws. -* [*Notes:] If `*this` was initialized, `T`'s move-assignment operator is used, -otherwise, its move-constructor is used. -* [*Exception Safety:] In the event of an exception, the initialization -state of `*this` is unchanged and its value unspecified as far as `optional` -is concerned (it is up to `T`'s `operator=()`). If `*this` is initially -uninitialized and `T`'s ['move constructor] fails, `*this` is left properly -uninitialized. -* [*Example:] -`` -T x; -optional<T> def ; -optional<T> opt(x) ; - -T y1, y2, yR; -def = std::move(y1) ; -assert ( *def == yR ) ; -opt = std::move(y2) ; -assert ( *opt == yR ) ; -`` - -__SPACE__ - -[: `optional<T&>& optional<T&>::operator= ( T&& rhs ) = delete;`] - -* [*Notes:] This assignment operator is deleted. - - -__SPACE__ - -[#reference_optional_operator_equal_optional] - -[: `optional& optional<T` ['(not a ref)]`>::operator= ( optional const& rhs ) ;`] - -* [*Requires:] `T` is __COPY_CONSTRUCTIBLE__ and `CopyAssignable`. -* [*Effects:] - * If `!*this && !rhs` no effect, otherwise - * if `bool(*this) && !rhs`, destroys the contained value by calling `val->T::~T()`, otherwise - * if `!*this && bool(rhs)`, initializes the contained value as if direct-initializing an object of type `T` with `*rhs`, otherwise - * (if `bool(*this) && bool(rhs)`) assigns `*rhs` to the contained value. -* [*Returns:] `*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. -* [*Example:] -`` -T v; -optional<T> opt(v); -optional<T> def ; - -opt = def ; -assert ( !def ) ; -// previous value (copy of 'v') destroyed from within 'opt'. -`` - -__SPACE__ - -[: `optional<T&> & optional<T&>::operator= ( optional<T&> const& rhs ) ;`] - -* [*Effect:] (Re)binds thee wrapped reference. -* [*Postconditions:] If `*rhs` is initialized, `*this` is initialized and it -references the same object referenced by `*rhs`; otherwise, `*this` is -uninitialized (and references no object). -* [*Notes:] If `*this` was initialized and so is `*rhs`, `*this` is ['rebound] to -the new object. See [link boost_optional.tutorial.rebinding_semantics_for_assignment_of_optional_references here] for details on this behavior. -* [*Example:] -`` -int a = 1 ; -int b = 2 ; -T& ra = a ; -T& rb = b ; -optional<int&> def ; -optional<int&> ora(ra) ; -optional<int&> orb(rb) ; - -def = orb ; // binds 'def' to 'b' through 'rb' wrapped within 'orb' -assert ( *def == b ) ; -*def = ora ; // changes the value of 'b' to a copy of the value of 'a' -assert ( b == a ) ; -int c = 3; -int& rc = c ; -optional<int&> orc(rc) ; -ora = orc ; // REBINDS ora to 'c' through 'rc' -c = 4 ; -assert ( *ora == 4 ) ; -`` - -__SPACE__ - -[#reference_optional_operator_move_equal_optional] - -[: `optional& optional<T` ['(not a ref)]`>::operator= ( optional&& rhs ) noexcept(`['see below]`);`] - -* [*Requires:] `T` is __MOVE_CONSTRUCTIBLE__ and `MoveAssignable`. -* [*Effects:] - * If `!*this && !rhs` no effect, otherwise - * if `bool(*this) && !rhs`, destroys the contained value by calling `val->T::~T()`, otherwise - * if `!*this && bool(rhs)`, initializes the contained value as if direct-initializing an object of type `T` with `std::move(*rhs)`, otherwise - * (if `bool(*this) && bool(rhs)`) assigns `std::move(*rhs)` to the contained value. -* [*Returns:] `*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 -of `T`'s move constructor. If an exception is thrown during the call to T's move-assignment, the state of `**this` and `*rhs` is determined by the exception safety guarantee of T's move assignment. -* [*Example:] -`` -optional<T> opt(T(2)) ; -optional<T> def ; - -opt = def ; -assert ( def ) ; -assert ( opt ) ; -assert ( *opt == T(2) ) ; -`` - -__SPACE__ - -[: `optional<T&> & optional<T&>::operator= ( optional<T&>&& rhs ) ;`] - -* [*Effect:] Same as `optional<T&>::operator= ( optional<T&> const& rhs )`. - -__SPACE__ - - -[#reference_optional_operator_equal_other_optional] - -[: `template<U> optional& optional<T` ['(not a ref)]`>::operator= ( optional<U> const& rhs ) ;`] - -* [*Effect:] Assigns another convertible optional to an optional. -* [*Postconditions:] If `rhs` is initialized, `*this` is initialized and -its value is a ['copy] of the value of `rhs` ['converted] to type `T`; else -`*this` is uninitialized. -* [*Throws:] Whatever `T::operator=( U const& )` or `T::T( U const& )` throws. -* [*Notes:] If both `*this` and rhs are initially initialized, `T`'s -['assignment operator] (from `U`) is used. If `*this` is initially initialized -but `rhs` is uninitialized, `T`'s ['destructor] is called. If `*this` is -initially uninitialized but rhs is initialized, `T`'s ['converting constructor] -(from `U`) is called. -* [*Exception Safety:] In the event of an exception, the initialization state -of `*this` is unchanged and its value unspecified as far as optional is -concerned (it is up to `T`'s `operator=()`). If `*this` is initially -uninitialized and `T`'s converting constructor fails, `*this` is left properly -uninitialized. -* [*Example:] -`` -T v; -optional<T> opt0(v); -optional<U> opt1; - -opt1 = opt0 ; -assert ( *opt1 == static_cast<U>(v) ) ; -`` - -__SPACE__ - -[#reference_optional_operator_move_equal_other_optional] - -[: `template<U> optional& optional<T` ['(not a ref)]`>::operator= ( optional<U>&& rhs ) ;`] - -* [*Effect:] Move-assigns another convertible optional to an optional. -* [*Postconditions:] If `rhs` is initialized, `*this` is initialized and -its value is moved from the value of `rhs`; else -`*this` is uninitialized. -* [*Throws:] Whatever `T::operator=( U&& )` or `T::T( U&& )` throws. -* [*Notes:] If both `*this` and `rhs` are initially initialized, `T`'s -[' assignment operator] (from `U&&`) is used. If `*this` is initially initialized -but `rhs` is uninitialized, `T`'s ['destructor] is called. If `*this` is -initially uninitialized but `rhs` is initialized, `T`'s ['converting constructor] -(from `U&&`) is called. -* [*Exception Safety:] In the event of an exception, the initialization state -of `*this` is unchanged and its value unspecified as far as optional is -concerned (it is up to `T`'s `operator=()`). If `*this` is initially -uninitialized and `T`'s converting constructor fails, `*this` is left properly -uninitialized. -* [*Example:] -`` -T v; -optional<T> opt0(v); -optional<U> opt1; - -opt1 = std::move(opt0) ; -assert ( opt0 ); -assert ( opt1 ) -assert ( *opt1 == static_cast<U>(v) ) ; -`` - -__SPACE__ - -[#reference_optional_emplace] - -[: `template<class... Args> void optional<T` ['(not a ref)]`>::emplace( Args...&& args );`] - -* [*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)...`. -* [*Postconditions: ] `*this` is [_initialized]. -* [*Throws:] Whatever the selected `T`'s constructor throws. -* [*Notes:] `T` need not be __MOVE_CONSTRUCTIBLE__ or `MoveAssignable`. On compilers that do not support variadic templates, the signature falls back to single-argument: `template<class Arg> void emplace(Arg&& arg)`. On compilers that do not support rvalue references, the signature falls back to two overloads: taking `const` and non-`const` lvalue reference. -* [*Exception Safety:] If an exception is thrown during the initialization of `T`, `*this` is ['uninitialized]. -* [*Example:] -`` -T v; -optional<const T> opt; -opt.emplace(0); // create in-place using ctor T(int) -opt.emplace(); // destroy previous and default-construct another T -opt.emplace(v); // destroy and copy-construct in-place (no assignment called) -`` - -__SPACE__ - -[#reference_optional_operator_equal_factory] - -[: `template<InPlaceFactory> optional<T>& optional<T` ['(not a ref)]`>::operator=( InPlaceFactory const& f );`] -[: `template<TypedInPlaceFactory> optional<T>& optional<T` ['(not a ref)]`>::operator=( TypedInPlaceFactory const& f );`] - -* [*Effect:] Assigns an `optional` with a value of `T` obtained from the -factory. -* [*Postconditions: ] `*this` is [_initialized] and its value is ['directly given] -from the factory `f` (i.e., the value [_is not copied]). -* [*Throws:] Whatever the `T` constructor called by the factory throws. -* [*Notes:] See [link boost_optional.tutorial.in_place_factories In-Place Factories] -* [*Exception Safety:] Exceptions can only be thrown during the call to -the `T` constructor used by the factory; in that case, the `optional` object -will be reset to be ['uninitialized]. - -__SPACE__ - -[#reference_optional_reset_value] - -[: `void optional<T` ['(not a ref)]`>::reset( T const& v ) ;`] -* [*Deprecated:] same as `operator= ( T const& v) ;` - -__SPACE__ - -[#reference_optional_reset] - -[: `void optional<T>::reset() noexcept ;`] -* [*Deprecated:] Same as `operator=( none_t );` - -__SPACE__ - -[#reference_optional_get] - -[: `T const& optional<T` ['(not a ref)]`>::get() const ;`] -[: `T& optional<T` ['(not a ref)]`>::get() ;`] - -[: `inline T const& get ( optional<T` ['(not a ref)]`> const& ) ;`] -[: `inline T& get ( optional<T` ['(not a ref)]`> &) ;`] - -* [*Requires:] `*this` is initialized -* [*Returns:] A reference to the contained value -* [*Throws:] Nothing. -* [*Notes:] The requirement is asserted via `BOOST_ASSERT()`. - -__SPACE__ - -[: `T const& optional<T&>::get() const ;`] -[: `T& optional<T&>::get() ;`] - -[: `inline T const& get ( optional<T&> const& ) ;`] -[: `inline T& get ( optional<T&> &) ;`] - -* [*Requires: ] `*this` is initialized -* [*Returns:] [_The] reference contained. -* [*Throws:] Nothing. -* [*Notes:] The requirement is asserted via `BOOST_ASSERT()`. - -__SPACE__ - -[#reference_optional_operator_asterisk] - -[: `T const& optional<T` ['(not a ref)]`>::operator*() const& ;`] -[: `T& optional<T` ['(not a ref)]`>::operator*() &;`] - -* [*Requires:] `*this` is initialized -* [*Returns:] A reference to the contained value -* [*Throws:] Nothing. -* [*Notes:] The requirement is asserted via `BOOST_ASSERT()`. On compilers that do not support ref-qualifiers on member functions these two overloads are replaced with the classical two: a `const` and non-`const` member functions. -* [*Example:] -`` -T v ; -optional<T> opt ( v ); -T const& u = *opt; -assert ( u == v ) ; -T w ; -*opt = w ; -assert ( *opt == w ) ; -`` - -__SPACE__ - -[#reference_optional_operator_asterisk_move] - -[: `T&& optional<T` ['(not a ref)]`>::operator*() &&;`] - -* [*Requires:] `*this` contains a value. -* [*Effects:] Equivalent to `return std::move(*val);`. -* [*Notes:] The requirement is asserted via `BOOST_ASSERT()`. On compilers that do not support ref-qualifiers on member functions this overload is not present. - -__SPACE__ - -[: `T & optional<T&>::operator*() const& ;`] -[: `T & optional<T&>::operator*() & ;`] -[: `T & optional<T&>::operator*() && ;`] - -* [*Requires: ] `*this` is initialized -* [*Returns:] [_The] reference contained. -* [*Throws:] Nothing. -* [*Notes:] The requirement is asserted via `BOOST_ASSERT()`. On compilers that do not support ref-qualifiers on member functions these three overloads are replaced with the classical two: a `const` and non-`const` member functions. -* [*Example:] -`` -T v ; -T& vref = v ; -optional<T&> opt ( vref ); -T const& vref2 = *opt; -assert ( vref2 == v ) ; -++ v ; -assert ( *opt == v ) ; -`` - -__SPACE__ - -[#reference_optional_value] - -[: `T const& optional<T>::value() const& ;`] -[: `T& optional<T>::value() & ;`] - -* [*Effects:] Equivalent to `return bool(*this) ? *val : throw bad_optional_access();`. -* [*Notes:] On compilers that do not support ref-qualifiers on member functions these two overloads are replaced with the classical two: a `const` and non-`const` member functions. -* [*Example:] -`` -T v ; -optional<T> o0, o1 ( v ); -assert ( o1.value() == v ); - -try { - o0.value(); // throws - assert ( false ); -} -catch(bad_optional_access&) { - assert ( true ); -} -`` - -__SPACE__ - -[#reference_optional_value_move] - -[: `T&& optional<T>::value() && ;`] - -* [*Effects:] Equivalent to `return bool(*this) ? std::move(*val) : throw bad_optional_access();`. -* [*Notes:] On compilers that do not support ref-qualifiers on member functions this overload is not present. - -__SPACE__ - - -[#reference_optional_value_or] - -[: `template<class U> T optional<T>::value_or(U && v) const& ;`] - -* [*Effects:] Equivalent to `if (*this) return **this; else return std::forward<U>(v);`. -* [*Remarks:] If `T` is not __COPY_CONSTRUCTIBLE__ or `U &&` is not convertible to `T`, the program is ill-formed. -* [*Notes:] On compilers that do not support ref-qualifiers on member functions this overload is replaced with the `const`-qualified member function. On compilers without rvalue reference support the type of `v` becomes `U const&`. - -__SPACE__ - -[#reference_optional_value_or_move] - -[: `template<class U> T optional<T>::value_or(U && v) && ;`] - -* [*Effects:] Equivalent to `if (*this) return std::move(**this); else return std::forward<U>(v);`. -* [*Remarks:] If `T` is not __MOVE_CONSTRUCTIBLE__ or `U &&` is not convertible to `T`, the program is ill-formed. -* [*Notes:] On compilers that do not support ref-qualifiers on member functions this overload is not present. - -__SPACE__ - -[#reference_optional_value_or_call] - -[: `template<class F> T optional<T>::value_or_eval(F f) const& ;`] - -* [*Requires:] `T` is __COPY_CONSTRUCTIBLE__ and `F` models a __SGI_GENERATOR__ whose result type is convertible to `T`. -* [*Effects:] `if (*this) return **this; else return f();`. -* [*Notes:] On compilers that do not support ref-qualifiers on member functions this overload is replaced with the `const`-qualified member function. -* [*Example:] -`` -int complain_and_0() -{ - clog << "no value returned, using default" << endl; - return 0; -} - -optional<int> o1 = 1; -optional<int> oN = none; - -int i = o1.value_or_eval(complain_and_0); // fun not called -assert (i == 1); - -int j = oN.value_or_eval(complain_and_0); // fun called -assert (i == 0); -`` - -__SPACE__ - -[#reference_optional_value_or_call_move] - -[: `template<class F> T optional<T>::value_or_eval(F f) && ;`] - -* [*Requires:] `T` is __MOVE_CONSTRUCTIBLE__ and `F` models a __SGI_GENERATOR__ whose result type is convertible to `T`. -* [*Effects:] `if (*this) return std::move(**this); else return f();`. -* [*Notes:] On compilers that do not support ref-qualifiers on member functions this overload is not present. - -__SPACE__ - -[#reference_optional_get_value_or_value] - -[: `T const& optional<T` ['(not a ref)]`>::get_value_or( T const& default) const ;`] -[: `T& optional<T` ['(not a ref)]`>::get_value_or( T& default ) ;`] - -[: `inline T const& get_optional_value_or ( optional<T` ['(not a ref)]`> const& o, T const& default ) ;`] -[: `inline T& get_optional_value_or ( optional<T` ['(not a ref)]`>& o, T& default ) ;`] - -* [*Deprecated:] Use `value_or()` instead. -* [*Returns:] A reference to the contained value, if any, or `default`. -* [*Throws:] Nothing. -* [*Example:] -`` -T v, z ; -optional<T> def; -T const& y = def.get_value_or(z); -assert ( y == z ) ; - -optional<T> opt ( v ); -T const& u = get_optional_value_or(opt,z); -assert ( u == v ) ; -assert ( u != z ) ; -`` - - -__SPACE__ - -[#reference_optional_get_ptr] - -[: `T const* optional<T` ['(not a ref)]`>::get_ptr() const ;`] -[: `T* optional<T` ['(not a ref)]`>::get_ptr() ;`] - -[: `inline T const* get_pointer ( optional<T` ['(not a ref)]`> const& ) ;`] -[: `inline T* get_pointer ( optional<T` ['(not a ref)]`> &) ;`] - -* [*Returns:] If `*this` is initialized, a pointer to the contained value; -else `0` (['null]). -* [*Throws:] Nothing. -* [*Notes:] The contained value is permanently stored within `*this`, so you -should not hold nor delete this pointer -* [*Example:] -`` -T v; -optional<T> opt(v); -optional<T> const copt(v); -T* p = opt.get_ptr() ; -T const* cp = copt.get_ptr(); -assert ( p == get_pointer(opt) ); -assert ( cp == get_pointer(copt) ) ; -`` - -__SPACE__ - -[#reference_optional_operator_arrow] - -[: `T const* optional<T` ['(not a ref)]`>::operator ->() const ;`] -[: `T* optional<T` ['(not a ref)]`>::operator ->() ;`] - -* [*Requires: ] `*this` is initialized. -* [*Returns:] A pointer to the contained value. -* [*Throws:] Nothing. -* [*Notes:] The requirement is asserted via `BOOST_ASSERT()`. -* [*Example:] -`` -struct X { int mdata ; } ; -X x ; -optional<X> opt (x); -opt->mdata = 2 ; -`` - -__SPACE__ - -[#reference_optional_operator_bool] - -[: `explicit optional<T>::operator bool() const noexcept ;`] - -* [*Returns:] `get_ptr() != 0`. -* [*Notes:] On compilers that do not support explicit conversion operators this falls back to safe-bool idiom. -* [*Example:] -`` -optional<T> def ; -assert ( def == 0 ); -optional<T> opt ( v ) ; -assert ( opt ); -assert ( opt != 0 ); -`` - -__SPACE__ - -[#reference_optional_operator_not] - -[: `bool optional<T>::operator!() noexcept ;`] - -* [*Returns:] If `*this` is uninitialized, `true`; else `false`. -* [*Notes:] This operator is provided for those compilers which can't -use the ['unspecified-bool-type operator] in certain boolean contexts. -* [*Example:] -`` -optional<T> opt ; -assert ( !opt ); -*opt = some_T ; - -// Notice the "double-bang" idiom here. -assert ( !!opt ) ; -`` - -__SPACE__ - -[#reference_optional_is_initialized] - -[: `bool optional<T>::is_initialized() const ;`] - -* [*Deprecated:] Same as `explicit operator bool () ;` - -__SPACE__ - -[heading Free functions] - -__SPACE__ - -[#reference_make_optional_value] - -[: `optional<T` ['(not a ref)]`> make_optional( T const& v )`] - -* [*Returns: ] `optional<T>(v)` for the ['deduced] type `T` of `v`. -* [*Example:] -`` -template<class T> void foo ( optional<T> const& opt ) ; - -foo ( make_optional(1+1) ) ; // Creates an optional<int> -`` - -__SPACE__ - -[#reference_make_optional_bool_value] - -[: `optional<T` ['(not a ref)]`> make_optional( bool condition, T const& v )`] - -* [*Returns: ] `optional<T>(condition,v)` for the ['deduced] type `T` of `v`. -* [*Example:] -`` -optional<double> calculate_foo() -{ - double val = compute_foo(); - return make_optional(is_not_nan_and_finite(val),val); -} - -optional<double> v = calculate_foo(); -if ( !v ) - error("foo wasn't computed"); -`` - -__SPACE__ - -[#reference_operator_compare_equal_optional_optional] - -[: `bool operator == ( optional<T> const& x, optional<T> const& y );`] - -* [*Requires:] `T` shall meet requirements of __SGI_EQUALITY_COMPARABLE__. -* [*Returns:] If both `x` and `y` are initialized, `(*x == *y)`. If only -`x` or `y` is initialized, `false`. If both are uninitialized, `true`. -* [*Notes:] Pointers have shallow relational operators while `optional` has -deep relational operators. Do not use `operator==` directly in generic -code which expect to be given either an `optional<T>` or a pointer; use -__FUNCTION_EQUAL_POINTEES__ instead -* [*Example:] -`` -optional<T> oN, oN_; -optional<T> o1(T(1)), o1_(T(1)); -optional<T> o2(T(2)); - -assert ( oN == oN ); // Identity implies equality -assert ( o1 == o1 ); // - -assert ( oN == oN_ ); // Both uninitialized compare equal - -assert ( oN != o1 ); // Initialized unequal to initialized. - -assert ( o1 == o1_ ); // Both initialized compare as (*lhs == *rhs) -assert ( o1 != o2 ); // -`` - -__SPACE__ - -[#reference_operator_compare_less_optional_optional] - -[: `bool operator < ( optional<T> const& x, optional<T> const& y );`] - -* [*Requires:] Expression `*x < *y` shall be well-formed and its result shall be convertible to `bool`. -* [*Returns:] `(!y) ? false : (!x) ? true : *x < *y`. -* [*Notes:] Pointers have shallow relational operators while `optional` has -deep relational operators. Do not use `operator<` directly in generic code -which expect to be given either an `optional<T>` or a pointer; use __FUNCTION_LESS_POINTEES__ instead. `T` need not be __SGI_LESS_THAN_COMPARABLE__. Only single `operator<` is required. Other relational operations are defined in terms of this one. If `T`'s `operator<` satisfies the axioms of __SGI_LESS_THAN_COMPARABLE__ (transitivity, antisymmetry and irreflexivity), `optinal<T>` is __SGI_LESS_THAN_COMPARABLE__. -* [*Example:] -`` -optional<T> oN, oN_; -optional<T> o0(T(0)); -optional<T> o1(T(1)); - -assert ( !(oN < oN) ); // Identity implies equivalence -assert ( !(o1 < o1) ); - -assert ( !(oN < oN_) ); // Two uninitialized are equivalent -assert ( !(oN_ < oN) ); - -assert ( oN < o0 ); // Uninitialized is less than initialized -assert ( !(o0 < oN) ); - -assert ( o1 < o2 ) ; // Two initialized compare as (*lhs < *rhs) -assert ( !(o2 < o1) ) ; -assert ( !(o2 < o2) ) ; -`` - -__SPACE__ - -[#reference_operator_compare_not_equal_optional_optional] - -[: `bool operator != ( optional<T> const& x, optional<T> const& y );`] - -* [*Returns: ] `!( x == y );` - -__SPACE__ - -[#reference_operator_compare_greater_optional_optional] - -[: `bool operator > ( optional<T> const& x, optional<T> const& y );`] - -* [*Returns: ] `( y < x );` - -__SPACE__ - -[#reference_operator_compare_less_or_equal_optional_optional] - -[: `bool operator <= ( optional<T> const& x, optional<T> const& y );`] - -* [*Returns: ] `!( y < x );` - -__SPACE__ - -[#reference_operator_compare_greater_or_equal_optional_optional] - -[: `bool operator >= ( optional<T> const& x, optional<T> const& y );`] - -* [*Returns: ] `!( x < y );` - -__SPACE__ - -[#reference_operator_compare_equal_optional_none] - -[: `bool operator == ( optional<T> const& x, none_t ) noexcept;`] -[: `bool operator == ( none_t, optional<T> const& x ) noexcept;`] - -* [*Returns:] `!x`. -* [*Notes:] `T` need not meet requirements of __SGI_EQUALITY_COMPARABLE__. - - -__SPACE__ - -[#reference_operator_compare_not_equal_optional_none] - -[: `bool operator != ( optional<T> const& x, none_t ) noexcept;`] -[: `bool operator != ( none_t, optional<T> const& x ) noexcept;`] - -* [*Returns: ] `!( x == y );` - - -__SPACE__ - -[#reference_swap_optional_optional] - -[: `void swap ( optional<T>& x, optional<T>& y ) ;`] - -* [*Requires:] Lvalues of type `T` shall be swappable and `T` shall be __MOVE_CONSTRUCTIBLE__. -* [*Effects:] - * If `!*this && !rhs`, no effect, otherwise - * if `bool(*this) && !rhs`, initializes the contained value of `rhs` as if direct-initializing an object of type `T` with the expression `std::move(*(*this))`, followed by `val->T::~T()`, `*this` does not contain a value and `rhs` contains a value, otherwise - * if `!*this && bool(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, otherwise - * (if `bool(*this) && bool(rhs)`) calls `swap(*(*this), *rhs)`. -* [*Postconditions:] The states of `x` and `y` interchanged. -* [*Throws:] If both are initialized, whatever `swap(T&,T&)` throws. If only -one is initialized, whatever `T::T ( T&& )` throws. -* [*Example:] -`` -T x(12); -T y(21); -optional<T> def0 ; -optional<T> def1 ; -optional<T> optX(x); -optional<T> optY(y); - -boost::swap(def0,def1); // no-op - -boost::swap(def0,optX); -assert ( *def0 == x ); -assert ( !optX ); - -boost::swap(def0,optX); // Get back to original values - -boost::swap(optX,optY); -assert ( *optX == y ); -assert ( *optY == x ); -`` - -[endsect] |