[/ 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] namespace boost { template class optional { public : // (If T is of reference type, the parameters and results by reference are by value) optional () ; ``[link reference_optional_constructor __GO_TO__]`` optional ( none_t ) ; ``[link reference_optional_constructor_none_t __GO_TO__]`` optional ( T const& v ) ; ``[link reference_optional_constructor_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__]`` template explicit optional ( optional const& rhs ) ; ``[link reference_optional_constructor_other_optional __GO_TO__]`` template explicit optional ( InPlaceFactory const& f ) ; ``[link reference_optional_constructor_factory __GO_TO__]`` template explicit optional ( TypedInPlaceFactory const& f ) ; ``[link reference_optional_constructor_factory __GO_TO__]`` optional& operator = ( none_t ) ; ``[/[link reference_optional_operator_equal_none_t __GO_TO__]]`` optional& operator = ( T const& v ) ; ``[link reference_optional_operator_equal_value __GO_TO__]`` optional& operator = ( optional const& rhs ) ; ``[link reference_optional_operator_equal_optional __GO_TO__]`` template optional& operator = ( optional const& rhs ) ; ``[link reference_optional_operator_equal_other_optional __GO_TO__]`` template optional& operator = ( InPlaceFactory const& f ) ; ``[/[link reference_optional_operator_equal_factory __GO_TO__]]`` template 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__]`` // [new in 1.34] T const& get_value_or( T const& default ) const ; ``[link reference_optional_get_value_or_value __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_get __GO_TO__]`` T& operator *() ; ``[link reference_optional_get __GO_TO__]`` T const* get_ptr() const ; ``[link reference_optional_get_ptr __GO_TO__]`` T* get_ptr() ; ``[link reference_optional_get_ptr __GO_TO__]`` operator unspecified-bool-type() const ; ``[link reference_optional_operator_bool __GO_TO__]`` bool operator!() const ; ``[link reference_optional_operator_not __GO_TO__]`` // deprecated methods // (deprecated) void reset() ; ``[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__]`` }; 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__]`` template inline bool operator < ( optional const& x, optional const& y ) ; ``[link reference_operator_compare_less_optional_optional __GO_TO__]`` template inline bool operator > ( optional const& x, optional const& y ) ; ``[link reference_operator_compare_greater_optional_optional __GO_TO__]`` 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__]`` // [new in 1.34] template inline optional make_optional ( T const& v ) ; ``[link reference_make_optional_value __GO_TO__]`` // [new in 1.34] template inline optional make_optional ( bool condition, T const& v ) ; ``[link reference_make_optional_bool_value __GO_TO__]`` // [new in 1.34] template inline T const& get_optional_value_or ( optional const& opt, T const& default ) ; ``[link reference_optional_get_value_or_value __GO_TO__]`` template inline T const& get ( optional const& opt ) ; ``[link reference_optional_get __GO_TO__]`` template inline T& get ( optional & opt ) ; ``[link reference_optional_get __GO_TO__]`` template inline T const* get ( optional const* opt ) ; ``[link reference_optional_get __GO_TO__]`` template inline T* get ( optional* opt ) ; ``[link reference_optional_get __GO_TO__]`` template inline T const* get_pointer ( optional const& opt ) ; ``[link reference_optional_get_ptr __GO_TO__]`` template inline T* get_pointer ( optional & opt ) ; ``[link reference_optional_get_ptr __GO_TO__]`` template inline void swap( optional& x, optional& 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`, the description corresponds only to the case where `T` is not of reference type. * If the entry reads: `optional`, the description corresponds only to the case where `T` is of reference type. * If the entry reads: `optional`, 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::optional();`] * [*Effect:] Default-Constructs an `optional`. * [*Postconditions:] `*this` is [_uninitialized]. * [*Throws:] Nothing. * Notes: T's default constructor [_is not] called. * [*Example:] `` optional def ; assert ( !def ) ; `` __SPACE__ [#reference_optional_constructor_none_t] [: `optional::optional( none_t );`] * [*Effect:] Constructs an `optional` uninitialized. * [*Postconditions:] `*this` is [_uninitialized]. * [*Throws:] Nothing. * [*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 optional n(none) ; assert ( !n ) ; `` __SPACE__ [#reference_optional_constructor_value] [: `optional::optional( T const& v )`] * [*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 opt(v); assert ( *opt == v ) ; `` __SPACE__ [: `optional::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 opt(vref); assert ( *opt == v ) ; ++ v ; // mutate referee assert (*opt == v); `` __SPACE__ [#reference_optional_constructor_bool_value] [: `optional::optional( bool condition, T const& v ) ;` ] [: `optional ::optional( bool condition, T& v ) ;` ] * If condition is true, same as: [: `optional::optional( T const& v )`] [: `optional ::optional( T& v )`] * otherwise, same as: [: `optional::optional()`] [: `optional ::optional()`] __SPACE__ [#reference_optional_constructor_optional] [: `optional::optional( optional 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`; 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 uninit ; assert (!uninit); optional uinit2 ( uninit ) ; assert ( uninit2 == uninit ); optional init( T(2) ); assert ( *init == T(2) ) ; optional init2 ( init ) ; assert ( init2 == init ) ; `` __SPACE__ [: `optional::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 reefer to the same object (they alias). * [*Example:] `` optional uninit ; assert (!uninit); optional uinit2 ( uninit ) ; assert ( uninit2 == uninit ); T v = 2 ; T& ref = v ; optional init(ref); assert ( *init == v ) ; optional init2 ( init ) ; assert ( *init2 == v ) ; v = 3 ; assert ( *init == 3 ) ; assert ( *init2 == 3 ) ; `` __SPACE__ [#reference_optional_constructor_other_optional] [: `template explicit optional::optional( optional 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 x(123.4); assert ( *x == 123.4 ) ; optional y(x) ; assert( *y == 123 ) ; `` __SPACE__ [#reference_optional_constructor_factory] [: `template explicit optional::optional( InPlaceFactory const& f );`] [: `template explicit optional::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.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 x( in_place ('A', 123.4, "hello") ); // InPlaceFactory used optional y( in_place('A', 123.4, "hello") ); // TypedInPlaceFactory used assert ( *x == v ) ; assert ( *y == v ) ; `` __SPACE__ [#reference_optional_operator_equal_value] [: `optional& optional::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 def ; optional opt(x) ; T y; def = y ; assert ( *def == y ) ; opt = y ; assert ( *opt == y ) ; `` __SPACE__ [: `optional& optional::operator= ( T& const& rhs ) ;`] * [*Effect:] (Re)binds thee wrapped reference. * [*Postconditions: ] `*this` is initialized and it references the same object referenced by `rhs`. * [*Notes:] If `*this` was initialized, is is ['rebound] to the new object. See [link boost_optional.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 def ; optional 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_equal_optional] [: `optional& optional::operator= ( optional const& rhs ) ;`] * [*Effect:] Assigns another `optional` to 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::operator( T const&)` or `T::T( T const& )` throws. * [*Notes:] If both `*this` and `rhs` are initially initialized, `T`'s ['assignment operator] 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 ['copy constructor] 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 ['copy constructor] fails, `*this` is left properly uninitialized. * [*Example:] `` T v; optional opt(v); optional def ; opt = def ; assert ( !def ) ; // previous value (copy of 'v') destroyed from within 'opt'. `` __SPACE__ [: `optional & optional::operator= ( optional 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 is ['rebound] to the new object. See [link boost_optional.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 def ; optional ora(ra) ; optional 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 orc(rc) ; ora = orc ; // REBINDS ora to 'c' through 'rc' c = 4 ; assert ( *ora == 4 ) ; `` __SPACE__ [#reference_optional_operator_equal_other_optional] [: `template optional& optional::operator= ( optional 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 opt0(v); optional opt1; opt1 = opt0 ; assert ( *opt1 == static_cast(v) ) ; `` __SPACE__ [#reference_optional_reset_value] [: `void optional::reset( T const& v ) ;`] * [*Deprecated:] same as `operator= ( T const& v) ;` __SPACE__ [#reference_optional_reset] [: `void optional::reset() ;`] * [*Deprecated:] Same as `operator=( detail::none_t );` __SPACE__ [#reference_optional_get] [: `T const& optional::operator*() const ;`] [: `T& optional::operator*();`] [: `T const& optional::get() const ;`] [: `T& optional::get() ;`] [: `inline T const& get ( optional const& ) ;`] [: `inline T& get ( optional &) ;`] * [*Requirements:] `*this` is initialized * [*Returns:] A reference to the contained value * [*Throws:] Nothing. * [*Notes:] The requirement is asserted via `BOOST_ASSERT()`. * [*Example:] `` T v ; optional opt ( v ); T const& u = *opt; assert ( u == v ) ; T w ; *opt = w ; assert ( *opt == w ) ; `` __SPACE__ [#reference_optional_get_value_or_value] [: `T const& optional::get_value_or( T const& default) const ;`] [: `T& optional::get_value_or( T& default ) ;`] [: `inline T const& get_optional_value_or ( optional const& o, T const& default ) ;`] [: `inline T& get_optional_value_or ( optional& o, T& default ) ;`] * [*Returns:] A reference to the contained value, if any, or `default`. * [*Throws:] Nothing. * [*Example:] `` T v, z ; optional def; T const& y = def.get_value_or(z); assert ( y == z ) ; optional opt ( v ); T const& u = get_optional_value_or(opt,z); assert ( u == v ) ; assert ( u != z ) ; `` __SPACE__ [: `T const& optional::operator*() const ;`] [: `T & optional::operator*();`] [: `T const& optional::get() const ;`] [: `T& optional::get() ;`] [: `inline T const& get ( optional const& ) ;`] [: `inline T& get ( optional &) ;`] * [*Requirements: ] `*this` is initialized * [*Returns:] [_The] reference contained. * [*Throws:] Nothing. * [*Notes:] The requirement is asserted via `BOOST_ASSERT()`. * [*Example:] `` T v ; T& vref = v ; optional opt ( vref ); T const& vref2 = *opt; assert ( vref2 == v ) ; ++ v ; assert ( *opt == v ) ; `` __SPACE__ [#reference_optional_get_ptr] [: `T const* optional::get_ptr() const ;`] [: `T* optional::get_ptr() ;`] [: `inline T const* get_pointer ( optional const& ) ;`] [: `inline T* get_pointer ( optional &) ;`] * [*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 opt(v); optional 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::operator ->() const ;`] [: `T* optional::operator ->() ;`] * [*Requirements: ] `*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 opt (x); opt->mdata = 2 ; `` __SPACE__ [#reference_optional_operator_bool] [: `optional::operator `['unspecified-bool-type]`() const ;`] * [*Returns:] An unspecified value which if used on a boolean context is equivalent to (`get() != 0`) * [*Throws:] Nothing. * [*Example:] `` optional def ; assert ( def == 0 ); optional opt ( v ) ; assert ( opt ); assert ( opt != 0 ); `` __SPACE__ [#reference_optional_operator_not] [: `bool optional::operator!() ;`] * [*Returns:] If `*this` is uninitialized, `true`; else `false`. * [*Throws:] Nothing. * [*Notes:] This operator is provided for those compilers which can't use the ['unspecified-bool-type operator] in certain boolean contexts. * [*Example:] `` optional opt ; assert ( !opt ); *opt = some_T ; // Notice the "double-bang" idiom here. assert ( !!opt ) ; `` __SPACE__ [#reference_optional_is_initialized] [: `bool optional::is_initialized() const ;`] * [*Returns: ] `true` if the `optional` is initialized, `false` otherwise. * [*Throws:] Nothing. * [*Example:] `` optional def ; assert ( !def.is_initialized() ); optional opt ( v ) ; assert ( opt.is_initialized() ); `` __SPACE__ [heading Free functions] __SPACE__ [#reference_make_optional_value] [: `optional make_optional( T const& v )`] * [*Returns: ] `optional(v)` for the ['deduced] type `T` of `v`. * [*Example:] `` template void foo ( optional const& opt ) ; foo ( make_optional(1+1) ) ; // Creates an optional `` __SPACE__ [#reference_make_optional_bool_value] [: `optional make_optional( bool condition, T const& v )`] * [*Returns: ] `optional(condition,v)` for the ['deduced] type `T` of `v`. * [*Example:] `` optional calculate_foo() { double val = compute_foo(); return make_optional(is_not_nan_and_finite(val),val); } optional v = calculate_foo(); if ( !v ) error("foo wasn't computed"); `` __SPACE__ [#reference_operator_compare_equal_optional_optional] [: `bool operator == ( optional const& x, optional const& y );`] * [*Returns:] If both `x` and `y` are initialized, `(*x == *y)`. If only `x` or `y` is initialized, `false`. If both are uninitialized, `true`. * [*Throws:] Nothing. * [*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` or a pointer; use __FUNCTION_EQUAL_POINTEES__ instead * [*Example:] `` T x(12); T y(12); T z(21); optional def0 ; optional def1 ; optional optX(x); optional optY(y); optional optZ(z); // Identity always hold assert ( def0 == def0 ); assert ( optX == optX ); // Both uninitialized compare equal assert ( def0 == def1 ); // Only one initialized compare unequal. assert ( def0 != optX ); // Both initialized compare as (*lhs == *rhs) assert ( optX == optY ) ; assert ( optX != optZ ) ; `` __SPACE__ [#reference_operator_compare_less_optional_optional] [: `bool operator < ( optional const& x, optional const& y );`] * [*Returns:] If `y` is not initialized, `false`. If `y` is initialized and `x` is not initialized, `true`. If both `x` and `y` are initialized, `(*x < *y)`. * [*Throws:] Nothing. * [*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` or a pointer; use __FUNCTION_LESS_POINTEES__ instead. * [*Example:] `` T x(12); T y(34); optional def ; optional optX(x); optional optY(y); // Identity always hold assert ( !(def < def) ); assert ( optX == optX ); // Both uninitialized compare equal assert ( def0 == def1 ); // Only one initialized compare unequal. assert ( def0 != optX ); // Both initialized compare as (*lhs == *rhs) assert ( optX == optY ) ; assert ( optX != optZ ) ; `` __SPACE__ [#reference_operator_compare_not_equal_optional_optional] [: `bool operator != ( optional const& x, optional const& y );`] * [*Returns: ] `!( x == y );` * [*Throws:] Nothing. __SPACE__ [#reference_operator_compare_greater_optional_optional] [: `bool operator > ( optional const& x, optional const& y );`] * [*Returns: ] `( y < x );` * [*Throws:] Nothing. __SPACE__ [#reference_operator_compare_less_or_equal_optional_optional] [: `bool operator <= ( optional const& x, optional const& y );`] * [*Returns: ] `!( y= ( optional const& x, optional const& y );`] * [*Returns: ] `!( x& x, optional& y );`] * [*Effect:] If both `x` and `y` are initialized, calls `swap(*x,*y)` using `std::swap`. If only one is initialized, say `x`, calls: `y.reset(*x); x.reset();` If none is initialized, does nothing. * [*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 const& )` throws. * [*Notes:] If both are initialized, `swap(T&,T&)` is used unqualified but with `std::swap` introduced in scope. If only one is initialized, `T::~T()` and `T::T( T const& )` is called. * [*Exception Safety:] If both are initialized, this operation has the exception safety guarantees of `swap(T&,T&)`. If only one is initialized, it has the same basic guarantee as `optional::reset( T const& )`. * [*Example:] `` T x(12); T y(21); optional def0 ; optional def1 ; optional optX(x); optional 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]