forked from boostorg/optional
doc update about optional references
This commit is contained in:
Andrzej Krzemienski
@ -9,18 +9,7 @@
|
||||
]
|
||||
|
||||
|
||||
[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.
|
||||
[section Detailed Semantics - Optional Values]
|
||||
|
||||
[note
|
||||
The following section contains various `assert()` which are used only to show
|
||||
@ -29,9 +18,6 @@ support each particular expression but that if the expression is supported,
|
||||
the implied condition holds.
|
||||
]
|
||||
|
||||
__SPACE__
|
||||
|
||||
[heading optional class member functions]
|
||||
|
||||
__SPACE__
|
||||
|
||||
@ -70,7 +56,7 @@ __SPACE__
|
||||
|
||||
[#reference_optional_constructor_value]
|
||||
|
||||
[: `optional<T `['(not a ref)]`>::optional( T const& v )`]
|
||||
[: `optional<T>::optional( T const& v )`]
|
||||
|
||||
* [*Requires:] `is_copy_constructible<T>::value` is `true`.
|
||||
* [*Effect:] Directly-Constructs an `optional`.
|
||||
@ -87,29 +73,12 @@ 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 )`]
|
||||
[: `optional<T>::optional( T&& v )`]
|
||||
|
||||
* [*Requires:] `is_move_constructible<T>::value` is `true`.
|
||||
* [*Effect:] Directly-Move-Constructs an `optional`.
|
||||
@ -125,35 +94,27 @@ 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 ) ;` ]
|
||||
[: `optional<T>::optional( bool condition, T const& v ) ;` ]
|
||||
|
||||
* If condition is true, same as:
|
||||
|
||||
[: `optional<T` ['(not a ref)]`>::optional( T const& v )`]
|
||||
[: `optional<T&> ::optional( T& v )`]
|
||||
[: `optional<T>::optional( T const& v )`]
|
||||
|
||||
* otherwise, same as:
|
||||
|
||||
[: `optional<T `['(not a ref)]`>::optional()`]
|
||||
[: `optional<T&> ::optional()`]
|
||||
[: `optional<T>::optional()`]
|
||||
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_constructor_optional]
|
||||
|
||||
[: `optional<T `['(not a ref)]`>::optional( optional const& rhs );`]
|
||||
[: `optional<T>::optional( optional const& rhs );`]
|
||||
|
||||
* [*Requires:] `is_copy_constructible<T>::value` is `true`.
|
||||
* [*Effect:] Copy-Constructs an `optional`.
|
||||
@ -178,43 +139,12 @@ 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]`);`]
|
||||
[: `optional<T>::optional( optional&& rhs ) noexcept(`['see below]`);`]
|
||||
|
||||
* [*Requires:] `is_move_constructible<T>::value` is `true`.
|
||||
* [*Effect:] Move-constructs an `optional`.
|
||||
@ -243,43 +173,12 @@ 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 );`]
|
||||
[: `template<U> explicit optional<T>::optional( optional<U> const& rhs );`]
|
||||
|
||||
* [*Effect:] Copy-Constructs an `optional`.
|
||||
* [*Postconditions:] If `rhs` is initialized, `*this` is initialized and its
|
||||
@ -303,7 +202,7 @@ __SPACE__
|
||||
|
||||
[#reference_optional_move_constructor_other_optional]
|
||||
|
||||
[: `template<U> explicit optional<T` ['(not a ref)]`>::optional( optional<U>&& rhs );`]
|
||||
[: `template<U> explicit optional<T>::optional( optional<U>&& rhs );`]
|
||||
|
||||
* [*Effect:] Move-constructs an `optional`.
|
||||
* [*Postconditions:] If `rhs` is initialized, `*this` is initialized and its
|
||||
@ -327,8 +226,8 @@ __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 );`]
|
||||
[: `template<InPlaceFactory> explicit optional<T>::optional( InPlaceFactory const& f );`]
|
||||
[: `template<TypedInPlaceFactory> explicit optional<T>::optional( TypedInPlaceFactory const& f );`]
|
||||
|
||||
* [*Effect:] Constructs an `optional` with a value of `T` obtained from the
|
||||
factory.
|
||||
@ -365,7 +264,7 @@ __SPACE__
|
||||
|
||||
[#reference_optional_operator_equal_value]
|
||||
|
||||
[: `optional& optional<T` ['(not a ref)]`>::operator= ( T const& rhs ) ;`]
|
||||
[: `optional& optional<T>::operator= ( T const& rhs ) ;`]
|
||||
|
||||
* [*Effect:] Assigns the value `rhs` to an `optional`.
|
||||
* [*Postconditions: ] `*this` is initialized and its value is a ['copy] of `rhs`.
|
||||
@ -390,40 +289,12 @@ 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 ) ;`]
|
||||
[: `optional& optional<T>::operator= ( T&& rhs ) ;`]
|
||||
|
||||
* [*Effect:] Moves the value `rhs` to an `optional`.
|
||||
* [*Postconditions: ] `*this` is initialized and its value is moved from `rhs`.
|
||||
@ -448,18 +319,12 @@ 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 ) ;`]
|
||||
[: `optional& optional<T>::operator= ( optional const& rhs ) ;`]
|
||||
|
||||
* [*Requires:] `T` is __COPY_CONSTRUCTIBLE__ and `CopyAssignable`.
|
||||
* [*Effects:]
|
||||
@ -485,43 +350,12 @@ 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]`);`]
|
||||
[: `optional& optional<T>::operator= ( optional&& rhs ) noexcept(`['see below]`);`]
|
||||
|
||||
* [*Requires:] `T` is __MOVE_CONSTRUCTIBLE__ and `MoveAssignable`.
|
||||
* [*Effects:]
|
||||
@ -548,18 +382,13 @@ 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 ) ;`]
|
||||
[: `template<U> optional& optional<T>::operator= ( optional<U> const& rhs ) ;`]
|
||||
|
||||
* [*Effect:]
|
||||
[table
|
||||
@ -587,7 +416,7 @@ __SPACE__
|
||||
|
||||
[#reference_optional_operator_move_equal_other_optional]
|
||||
|
||||
[: `template<U> optional& optional<T` ['(not a ref)]`>::operator= ( optional<U>&& rhs ) ;`]
|
||||
[: `template<U> optional& optional<T>::operator= ( optional<U>&& rhs ) ;`]
|
||||
|
||||
* [*Effect:]
|
||||
[table
|
||||
@ -617,7 +446,7 @@ __SPACE__
|
||||
|
||||
[#reference_optional_emplace]
|
||||
|
||||
[: `template<class... Args> void optional<T` ['(not a ref)]`>::emplace( Args...&& args );`]
|
||||
[: `template<class... Args> void optional<T>::emplace( Args...&& args );`]
|
||||
|
||||
* [*Requires:] The compiler supports rvalue references and variadic templates.
|
||||
* [*Effect:] If `*this` is initialized calls `*this = none`.
|
||||
@ -642,8 +471,8 @@ __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 );`]
|
||||
[: `template<InPlaceFactory> optional<T>& optional<T>::operator=( InPlaceFactory const& f );`]
|
||||
[: `template<TypedInPlaceFactory> optional<T>& optional<T>::operator=( TypedInPlaceFactory const& f );`]
|
||||
|
||||
* [*Effect:] Assigns an `optional` with a value of `T` obtained from the
|
||||
factory.
|
||||
@ -659,7 +488,7 @@ __SPACE__
|
||||
|
||||
[#reference_optional_reset_value]
|
||||
|
||||
[: `void optional<T` ['(not a ref)]`>::reset( T const& v ) ;`]
|
||||
[: `void optional<T>::reset( T const& v ) ;`]
|
||||
* [*Deprecated:] same as `operator= ( T const& v) ;`
|
||||
|
||||
__SPACE__
|
||||
@ -673,36 +502,24 @@ __SPACE__
|
||||
|
||||
[#reference_optional_get]
|
||||
|
||||
[: `T const& optional<T` ['(not a ref)]`>::get() const ;`]
|
||||
[: `T& optional<T` ['(not a ref)]`>::get() ;`]
|
||||
[: `T const& optional<T>::get() const ;`]
|
||||
[: `T& optional<T>::get() ;`]
|
||||
|
||||
[: `inline T const& get ( optional<T` ['(not a ref)]`> const& ) ;`]
|
||||
[: `inline T& get ( optional<T` ['(not a ref)]`> &) ;`]
|
||||
[: `inline T const& get ( optional<T> const& ) ;`]
|
||||
[: `inline T& get ( optional<T> &) ;`]
|
||||
|
||||
* [*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*() &;`]
|
||||
[: `T const& optional<T>::operator*() const& ;`]
|
||||
[: `T& optional<T>::operator*() &;`]
|
||||
|
||||
* [*Requires:] `*this` is initialized
|
||||
* [*Returns:] A reference to the contained value
|
||||
@ -723,32 +540,12 @@ __SPACE__
|
||||
|
||||
[#reference_optional_operator_asterisk_move]
|
||||
|
||||
[: `T&& optional<T` ['(not a ref)]`>::operator*() &&;`]
|
||||
[: `T&& optional<T>::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__
|
||||
|
||||
@ -845,11 +642,8 @@ __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 ) ;`]
|
||||
[: `T const& optional<T>::get_value_or( T const& default) const ;`]
|
||||
[: `T& optional<T>::get_value_or( T& default ) ;`]
|
||||
|
||||
* [*Deprecated:] Use `value_or()` instead.
|
||||
* [*Returns:] A reference to the contained value, if any, or `default`.
|
||||
@ -862,7 +656,7 @@ T const& y = def.get_value_or(z);
|
||||
assert ( y == z ) ;
|
||||
|
||||
optional<T> opt ( v );
|
||||
T const& u = get_optional_value_or(opt,z);
|
||||
T const& u = opt.get_value_or(z);
|
||||
assert ( u == v ) ;
|
||||
assert ( u != z ) ;
|
||||
``
|
||||
@ -872,11 +666,8 @@ __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)]`> &) ;`]
|
||||
[: `T const* optional<T>::get_ptr() const ;`]
|
||||
[: `T* optional<T>::get_ptr() ;`]
|
||||
|
||||
* [*Returns:] If `*this` is initialized, a pointer to the contained value;
|
||||
else `0` (['null]).
|
||||
@ -898,8 +689,8 @@ __SPACE__
|
||||
|
||||
[#reference_optional_operator_arrow]
|
||||
|
||||
[: `T const* optional<T` ['(not a ref)]`>::operator ->() const ;`]
|
||||
[: `T* optional<T` ['(not a ref)]`>::operator ->() ;`]
|
||||
[: `T const* optional<T>::operator ->() const ;`]
|
||||
[: `T* optional<T>::operator ->() ;`]
|
||||
|
||||
* [*Requires: ] `*this` is initialized.
|
||||
* [*Returns:] A pointer to the contained value.
|
||||
@ -957,15 +748,300 @@ __SPACE__
|
||||
|
||||
* [*Deprecated:] Same as `explicit operator bool () ;`
|
||||
|
||||
|
||||
[endsect]
|
||||
|
||||
[section Detailed Semantics - Optional References]
|
||||
|
||||
__SPACE__
|
||||
|
||||
[heading Free functions]
|
||||
[#reference_optional_ref_default_ctor]
|
||||
|
||||
[: `optional<T&>::optional() noexcept;`]
|
||||
[: `optional<T&>::optional(none_t) noexcept;`]
|
||||
|
||||
* [*Postconditions:] `bool(*this) == false`; `*this` refers to nothing.
|
||||
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_ref_value_ctor]
|
||||
|
||||
[: `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`.
|
||||
* [*Example:]
|
||||
``
|
||||
T v;
|
||||
T& vref = v ;
|
||||
optional<T&> opt(vref);
|
||||
assert ( *opt == v ) ;
|
||||
++ v ; // mutate referee
|
||||
assert (*opt == v);
|
||||
``
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_ref_cond_value_ctor]
|
||||
|
||||
[: `template<class R> optional<T&>::optional(bool cond, R&& r) noexcept;`]
|
||||
* [*Effects: ] Initializes `ref` with expression `cond ? addressof(r) : nullptr`.
|
||||
* [*Postconditions:] `bool(*this) == cond`; If `bool(*this)`, `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`.
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_ref_copy_ctor]
|
||||
|
||||
[: `optional<T&>::optional ( optional const& rhs ) noexcept ;`]
|
||||
|
||||
* [*Effects: ] Initializes `ref` with expression `rhs.ref`.
|
||||
|
||||
* [*Postconditions:] `bool(*this) == bool(rhs)`.
|
||||
|
||||
* [*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_ref_ctor_from_opt_U]
|
||||
|
||||
[: `template<class U> explicit optional<T&>::optional ( optional<U&> const& rhs ) noexcept ;`]
|
||||
|
||||
* [*Requires:] `is_convertible<U&, T&>::value` is `true`.
|
||||
|
||||
* [*Effects: ] Initializes `ref` with expression `rhs.ref`.
|
||||
|
||||
* [*Postconditions:] `bool(*this) == bool(rhs)`.
|
||||
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_ref_assign_none_t]
|
||||
|
||||
[: `optional<T&>::operator= ( none_t ) noexcept ;`]
|
||||
|
||||
* [*Effects: ] Assigns `ref` with expression `nullptr`.
|
||||
|
||||
* [*returns:] `*this`.
|
||||
|
||||
* [*Postconditions:] `bool(*this) == false`.
|
||||
|
||||
|
||||
|
||||
[#reference_optional_ref_copy_assign]
|
||||
|
||||
[: `optional& optional<T&>::operator= ( optional const& rhs ) noexcept ;`]
|
||||
|
||||
* [*Effects: ] Assigns `ref` with expression `rhs.ref`.
|
||||
|
||||
* [*returns:] `*this`.
|
||||
|
||||
* [*Postconditions:] `bool(*this) == bool(rhs)`.
|
||||
|
||||
* [*Notes:] This behaviour is called ['rebinding semantics]. See [link boost_optional.tutorial.rebinding_semantics_for_assignment_of_optional_references here] for details.
|
||||
|
||||
* [*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 ) ;
|
||||
``
|
||||
|
||||
|
||||
[#reference_optional_ref_assign_optional_U]
|
||||
|
||||
[: `template<class U> optional& optional<T&>::operator= ( optional<U&> const& rhs ) noexcept ;`]
|
||||
|
||||
* [*Requires:] `is_convertible<U&, T&>::value` is `true`.
|
||||
|
||||
* [*Effects: ] Assigns `ref` with expression `rhs.ref`.
|
||||
|
||||
* [*returns:] `*this`.
|
||||
|
||||
* [*Postconditions:] `bool(*this) == bool(rhs)`.
|
||||
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_ref_assign_R]
|
||||
|
||||
[: `template<class R> optional& optional<T&>::operator= ( R&& r ) noexcept ;`]
|
||||
|
||||
* [*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`.
|
||||
|
||||
* [*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_ref_emplace_R]
|
||||
|
||||
[: `void optional<T&>::emplace( R&& r ) noexcept ;`]
|
||||
* [*Effects: ] Assigns `ref` with expression `r`.
|
||||
* [*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`.
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_ref_get]
|
||||
[: `T& optional<T&>::get() const ;`]
|
||||
[: `T& optional<T&>::operator *() const ;`]
|
||||
* [*Requires:] `bool(*this) == true`.
|
||||
* [*Effects: ] Returns `*ref`.
|
||||
* [*Throws: ] Nothing.
|
||||
* [*Example:]
|
||||
``
|
||||
T v ;
|
||||
T& vref = v ;
|
||||
optional<T&> opt ( vref );
|
||||
T const& vref2 = *opt;
|
||||
assert ( vref2 == v ) ;
|
||||
++ v ;
|
||||
assert ( *opt == v ) ;
|
||||
``
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_ref_arrow]
|
||||
[: `T* optional<T&>::operator -> () const ;`]
|
||||
* [*Requires:] `bool(*this) == true`.
|
||||
* [*Effects: ] Returns `ref`.
|
||||
* [*Throws: ] Nothing.
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_ref_value]
|
||||
[: `T& optional<T&>::value() const ;`]
|
||||
* [*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;`.
|
||||
* [*Remarks:] Unless `R` is an lvalue reference, the program is ill-formed.
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_ref_value_or_eval]
|
||||
[: `template<class F> T& optional<T&>::value_or( F f ) const ;`]
|
||||
* [*Effects:] Equivalent to `if (*this) return **this; else return f();`.
|
||||
* [*Remarks:] Unless `decltype(f())` is an lvalue reference, the program is ill-formed.
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_ref_get_ptr]
|
||||
[: `T* optional<T&>::get_ptr () const noexcept;`]
|
||||
* [*Returns:] `ref`.
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_ref_operator_bool]
|
||||
[: `optional<T&>::operator bool () const noexcept;`]
|
||||
* [*Returns:] `bool(ref)`.
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_ref_operator_not]
|
||||
[: `optional<T&>::operator ! () const noexcept;`]
|
||||
* [*Returns:] `!bool(ref)`.
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_ref_reset]
|
||||
[: `void optional<T&>::reset() noexcept;`]
|
||||
* [*Effects:] Use `*this = none` instead.
|
||||
* [*Remarks:] This function is depprecated.
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_ref_reset_value]
|
||||
[: `template<class R> void optional<T&>::reset ( R&& r) noexcept;`]
|
||||
* [*Effects:] Equivalent to `*this = std::forward<R>(r)`.
|
||||
* [*Remarks:] This function is depprecated.
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_optional_ref_is_initialized]
|
||||
[: `bool optional<T&>::is_initialized() const noexcept;`]
|
||||
* [*Effects:] Equivalent to `return bool(*this)`.
|
||||
* [*Remarks:] This function is depprecated.
|
||||
|
||||
__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);`.
|
||||
* [*Remarks:] This function is depprecated.
|
||||
|
||||
[endsect]
|
||||
|
||||
|
||||
[section Detailed Semantics - Free Functions]
|
||||
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_make_optional_value]
|
||||
|
||||
[: `optional<T` ['(not a ref)]`> make_optional( T const& v )`]
|
||||
[: `optional<T> make_optional( T const& v )`]
|
||||
|
||||
* [*Returns: ] `optional<T>(v)` for the ['deduced] type `T` of `v`.
|
||||
* [*Example:]
|
||||
@ -979,9 +1055,9 @@ __SPACE__
|
||||
|
||||
[#reference_make_optional_bool_value]
|
||||
|
||||
[: `optional<T` ['(not a ref)]`> make_optional( bool condition, T const& v )`]
|
||||
[: `optional<T> make_optional( bool condition, T const& v )`]
|
||||
|
||||
* [*Returns: ] `optional<T>(condition,v)` for the ['deduced] type `T` of `v`.
|
||||
* [*Returns: ] `optional<T>(condition, v)` for the ['deduced] type `T` of `v`.
|
||||
* [*Example:]
|
||||
``
|
||||
optional<double> calculate_foo()
|
||||
@ -1108,6 +1184,25 @@ __SPACE__
|
||||
* [*Returns: ] `!( x == y );`
|
||||
|
||||
|
||||
__SPACE__
|
||||
|
||||
|
||||
[#reference_free_get_pointer]
|
||||
[: `auto get_pointer ( optional<T>& o ) -> typename optional<T>::pointer_type ;`]
|
||||
[: `auto get_pointer ( optional<T> const& o ) -> typename optional<T>::pointer_const_type ;`]
|
||||
* [*Returns:] `o.get_ptr()`.
|
||||
* [*Throws:] Nothing.
|
||||
|
||||
__SPACE__
|
||||
|
||||
|
||||
[#reference_free_get_value_or]
|
||||
[: `auto get_optional_value_or ( optional<T>& o, typename optional<T>::reference_type def ) -> typename optional<T>::reference_type ;`]
|
||||
[: `auto get_optional_value_or ( optional<T> const& o, typename optional<T>::reference_const_type def ) -> typename optional<T>::reference_const_type ;`]
|
||||
* [*Returns:] `o.get_value_or(def)`.
|
||||
* [*Throws:] Nothing.
|
||||
* [*Remarks:] This function is deprecated.
|
||||
|
||||
__SPACE__
|
||||
|
||||
[#reference_swap_optional_optional]
|
||||
@ -1147,4 +1242,30 @@ assert ( *optX == y );
|
||||
assert ( *optY == x );
|
||||
``
|
||||
|
||||
[endsect]
|
||||
__SPACE__
|
||||
|
||||
[#reference_swap_optional_reference]
|
||||
[: `void swap ( optional<T&>& x, optional<T&>& y ) noexcept ;`]
|
||||
|
||||
* [*Postconditions:] `x` refers to what `y` refererred to before the swap (if anything). `y` refers to whatever `x` referred to before the swap.
|
||||
|
||||
* [*Example:]
|
||||
``
|
||||
T x(12);
|
||||
T y(21);
|
||||
|
||||
optional<T&> opt0;
|
||||
optional<T&> optX (x);
|
||||
optional<T&> optY (y);
|
||||
|
||||
boost::swap(optX, optY);
|
||||
assert (addressof(*optX) == addressof(y));
|
||||
assert (addressof(*optY) == addressof(x));
|
||||
|
||||
boost::swap(opt0, optX);
|
||||
assert ( opt0 );
|
||||
assert ( !optX );
|
||||
assert (addressof(*opt0) == addressof(y));
|
||||
``
|
||||
|
||||
[endsect]
|
||||
Reference in New Issue
Block a user