@ -3,6 +3,7 @@
< HTML > < HTML >
< HEAD > < HEAD >
< meta http-equiv = "Content-Language" content = "en-us" >
< meta name = "GENERATOR" content = "Microsoft FrontPage 5.0" > < meta name = "GENERATOR" content = "Microsoft FrontPage 5.0" >
< meta name = "ProgId" content = "FrontPage.Editor.Document" > < meta name = "ProgId" content = "FrontPage.Editor.Document" >
< META HTTP-EQUIV = "Content-Type" CONTENT = "text/html; charset=windows-1252" > < META HTTP-EQUIV = "Content-Type" CONTENT = "text/html; charset=windows-1252" >
@ -23,6 +24,7 @@ HREF="../../../boost/optional/optional.hpp">boost/optional/optional.hpp</A>>
< DT > < A HREF = "#examples" > Examples< / A > < / DT >
< DT > < A HREF = "#examples" > Examples< / A > < / DT >
< DT > < A HREF = "#ref" > Optional references< / A > < / DT >
< DT > < A HREF = "#ref" > Optional references< / A > < / DT >
< DT > < A HREF = "#refassign" > Rebinding semantics for assignment of optional references< / A > < / DT >
< DT > < A HREF = "#refassign" > Rebinding semantics for assignment of optional references< / A > < / DT >
< DT > < A HREF = "#none" > none_t and none< / A > < / DT >
< DT > < A HREF = "#inplace" > In-Place Factories< / A > < / DT >
< DT > < A HREF = "#inplace" > In-Place Factories< / A > < / DT >
< DT > < A HREF = "#bool" > A note about optional< bool> < / A > < / DT >
< DT > < A HREF = "#bool" > A note about optional< bool> < / A > < / DT >
< DT > < A HREF = "#exsafety" > Exception Safety Guarantees< / A > < / DT >
< DT > < A HREF = "#exsafety" > Exception Safety Guarantees< / A > < / DT >
@ -138,7 +140,7 @@ necessary in order to do so.</p>
< u > purpose< / u > of optional< T> suggests< u > purpose< / u > of optional< T> suggests
an alternative model: a < i > container< / i > that either has a value of T or nothing.
an alternative model: a < i > container< / i > that either has a value of T or nothing.
< / p > < / p >
< p > As of this writing I don't know of any precedence for a variable-size fixed-capacity (of 1)< p > As of this writing I don't know of any precedent for a variable-size fixed-capacity (of 1)
stack-based container model for optional values, yet I believe this is the consequence of
stack-based container model for optional values, yet I believe this is the consequence of
the lack of practical implementations of such a container rather than an inherent shortcoming
the lack of practical implementations of such a container rather than an inherent shortcoming
of the container model.< / p >
of the container model.< / p >
@ -329,9 +331,9 @@ class optional
template< class U> explicit optional ( optional< U> const& rhs ) ;
template< class U> explicit optional ( optional< U> const& rhs ) ;
template< class InPlaceFactory> explicit optional ( InPlaceFactory const& f ) ;
template< InPlaceFactory> explicit optional ( InPlaceFactory const& f ) ;
template< class TypedInPlaceFactory> explicit optional ( TypedInPlaceFactory const& f ) ;
template< TypedInPlaceFactory> explicit optional ( TypedInPlaceFactory const& f ) ;
optional& operator = ( none_t ) ;
optional& operator = ( none_t ) ;
@ -341,14 +343,14 @@ class optional
template< class U> optional& operator = ( optional< U> const& amp rhs ) ;
template< class U> optional& operator = ( optional< U> const& amp rhs ) ;
template< class InPlaceFactory> optional& operator = ( InPlaceFactory const& amp f ) ;
template< InPlaceFactory> optional& operator = ( InPlaceFactory const& amp f ) ;
template< class TypedInPlaceFactory> optional& operator = ( TypedInPlaceFactory const& amp f ) ;
template< TypedInPlaceFactory> optional& operator = ( TypedInPlaceFactory const& amp f ) ;
T const& get() const ;
T const& get() const ;
T& get() ;
T& get() ;
T< span lang = "es" > const& < / span > & default ) const ; < u > < i > [new in 1.34]< / u > < / i >
T const& get_value_or( T const& default ) const ; < u > < i > [new in 1.34]< / u > < / i >
T const* operator -> () const ;
T const* operator -> () const ;
T* operator -> () ;
T* operator -> () ;
@ -383,11 +385,59 @@ template<class T> inline bool operator <= ( optional<T> const& x, op
template< class T> inline bool operator >= ( optional< T> const& x, optional< T> const& y ) ;
template< class T> inline bool operator >= ( optional< T> const& x, optional< T> const& y ) ;
template< class T> inline bool operator == ( optional< T> const& x, T const& n ) ; < u > < i > [new in 1.34]< / u > < / i >
template< class T> inline bool operator != ( optional< T> const& x, T const& n ) ; < u > < i > [new in 1.34]< / u > < / i >
template< class T> inline bool operator < ( optional< T> const& x, T const& n ) ; < u > < i > [new in 1.34]< / u > < / i >
template< class T> inline bool operator > ( optional< T> const& x, T const& n ) ; < u > < i > [new in 1.34]< / u > < / i >
template< class T> inline bool operator < = ( optional< T> const& x, T const& n ) ; < u > < i > [new in 1.34]< / u > < / i >
template< class T> inline bool operator >= ( optional< T> const& x, T const& n ) ; < u > < i > [new in 1.34]< / u > < / i >
template< class T> inline bool operator == ( T const& n, optional< T> const& y ) ; < u > < i > [new in 1.34]< / u > < / i >
template< class T> inline bool operator != ( T const& n, optional< T> const& y ) ; < u > < i > [new in 1.34]< / u > < / i >
template< class T> inline bool operator < ( T const& n, optional< T> const& y ) ; < u > < i > [new in 1.34]< / u > < / i >
template< class T> inline bool operator > ( T const& n, optional< T> const& y ) ; < u > < i > [new in 1.34]< / u > < / i >
template< class T> inline bool operator < = ( T const& n, optional< T> const& y ) ; < u > < i > [new in 1.34]< / u > < / i >
template< class T> inline bool operator >= ( T const& n, optional< T> const& y ) ; < u > < i > [new in 1.34]< / u > < / i >
template< class T> inline bool operator == ( optional< T> const& x, none_t n ) ; < u > < i > [new in 1.34]< / u > < / i >
template< class T> inline bool operator != ( optional< T> const& x, none_t n ) ; < u > < i > [new in 1.34]< / u > < / i >
template< class T> inline bool operator < ( optional< T> const& x, none_t n ) ; < u > < i > [new in 1.34]< / u > < / i >
template< class T> inline bool operator > ( optional< T> const& x, none_t n ) ; < u > < i > [new in 1.34]< / u > < / i >
template< class T> inline bool operator < = ( optional< T> const& x, none_t n ) ; < u > < i > [new in 1.34]< / u > < / i >
template< class T> inline bool operator >= ( optional< T> const& x, none_t n ) ; < u > < i > [new in 1.34]< / u > < / i >
template< class T> inline bool operator == ( none_t n, optional< T> const& y ) ; < u > < i > [new in 1.34]< / u > < / i >
template< class T> inline bool operator != ( none_t n, optional< T> const& y ) ; < u > < i > [new in 1.34]< / u > < / i >
template< class T> inline bool operator < ( none_t n, optional< T> const& y ) ; < u > < i > [new in 1.34]< / u > < / i >
template< class T> inline bool operator > ( none_t n, optional< T> const& y ) ; < u > < i > [new in 1.34]< / u > < / i >
template< class T> inline bool operator < = ( none_t n, optional< T> const& y ) ; < u > < i > [new in 1.34]< / u > < / i >
template< class T> inline bool operator >= ( none_t n, optional< T> const& y ) ; < u > < i > [new in 1.34]< / u > < / i >
template< class T> inline optional< T> make_optional ( T const& v ) ; < u > < i > [new in 1.34]< / u > < / i >
template< class T> inline optional< T> make_optional ( T const& v ) ; < u > < i > [new in 1.34]< / u > < / i >
template< class T> inline optional< T> make_optional ( bool condition, T const& v ) ; < u > < i > [new in 1.34]< / u > < / i >
template< class T> inline optional< T> make_optional ( bool condition, T const& v ) ; < u > < i > [new in 1.34]< / u > < / i >
template< class T> inline T < span lang = "es" > const& < / span > get_< span lang = "es" > optional_< / span > < T> const& opt, T const& default ) ; < u > < i > [new in 1.34]< / u > < / i >
template< class T> inline T const& get_optional_ value_or ( optional< T> const& opt, T const& default ) ; < u > < i > [new in 1.34]< / u > < / i >
template< class T> inline T const& get ( optional< T> const& opt ) ;
template< class T> inline T const& get ( optional< T> const& opt ) ;
@ -457,9 +507,11 @@ used as the parameter.</p>
< / blockquote > < / blockquote >
< p > < b > Example:< / b > < / p > < p > < b > Example:< / b > < / p >
< blockquote >
< blockquote >
< pre > #include < boost/none.hpp> < / pre > < pre >
< pre > optional< T> n(none) ; #include < boost/none.hpp>
assert ( !n ) ;< / pre > optional< int> n(boost::none) ;
assert ( !n ) ;
< / pre >
< / blockquote > < / blockquote >
< / blockquote > < / blockquote >
@ -476,9 +528,11 @@ in that case, this constructor has no effect.
< / p > < / p >
< p > < b > Example:< / b > < / p > < p > < b > Example:< / b > < / p >
< blockquote > < blockquote >
< pre > T v; < pre >
T v;
optional< T> opt(v);
optional< T> opt(v);
assert ( *opt == v ) ;< / pre >
assert ( *opt == v ) ;
< / pre >
< / blockquote > < / blockquote >
< / blockquote > < / blockquote >
@ -492,29 +546,32 @@ instance of an internal type wrapping the reference 'ref'.</p>
< p > < b > Throws:< / b > Nothing.< / p > < p > < b > Throws:< / b > Nothing.< / p >
< p > < b > Example:< / b > < / p > < p > < b > Example:< / b > < / p >
< blockquote > < blockquote >
< pre > T v; < pre >
T v;
T& vref = v ;
T& vref = v ;
optional< T& > opt(vref);
optional< T& > opt(vref);
assert ( *opt == v ) ;
assert ( *opt == v ) ;
++ v ; // mutate referee
++ v ; // mutate referee
assert (*opt == v); < / pre >
assert (*opt == v);
< / pre >
< / blockquote > < / blockquote >
< / blockquote > < / blockquote >
< HR > < HR >
< pre > optional< T < i > (not a ref)< / i > > ::optional( bool condition, T const& v ) ;< pre > optional< T < i > (not a ref)< / i > > ::optional( bool condition, T const& v ) ;
optional< T& > < span lang = "es" > < / span > ::optional( bool condition, T& < span lang = "es" > < / span >
optional< T& > ::optional( bool condition, T& v ) ;
< / pre > < / pre >
< blockquote > < blockquote >
< p > If < i > condition< / i > is < code > true< / code > , same as:< / p > < p > If < i > condition< / i > is < code > true< / code > , same as:< / p >
< pre > optional< T < i > (not a ref)< / i > > ::optional( T const& v )< pre > optional< T < i > (not a ref)< / i > > ::optional( T const& v )
optional< T& > < span lang = "es" > < / span > ::optional( T& < span lang = "es" > < / span >
optional< T& > ::optional( T& v )
< / pre > < / pre >
< p > otherwise, same as:< / p > < p > otherwise, same as:< / p >
< pre > optional< T < i > (not a ref)< / i > > ::optional() < pre >
optional< T& > < span lang = "es" > < / span >
optional< T < i > (not a ref)< / i > > ::optional()
optional< T& > ::optional()
< / pre > < / pre >
< / blockquote > < / blockquote >
@ -533,7 +590,8 @@ in that case, this constructor has no effect.
< / p > < / p >
< p > < b > Example:< / b > < / p > < p > < b > Example:< / b > < / p >
< blockquote > < blockquote >
< pre > optional< T> uninit ; < pre >
optional< T> uninit ;
assert (!uninit);
assert (!uninit);
optional< T> uinit2 ( uninit ) ;
optional< T> uinit2 ( uninit ) ;
@ -562,7 +620,8 @@ is uninitialized.</p>
reefer to the same object< b > < / b > (they alias).< / p >
reefer to the same object< b > < / b > (they alias).< / p >
< p > < b > Example:< / b > < / p > < p > < b > Example:< / b > < / p >
< blockquote > < blockquote >
< pre > optional< T& > uninit ; < pre >
optional< T& > uninit ;
assert (!uninit);
assert (!uninit);
optional< T& > uinit2 ( uninit ) ;
optional< T& > uinit2 ( uninit ) ;
@ -605,7 +664,8 @@ in that case, this constructor has no effect.
< p > < b > Example:< / b > < / p > < p > < b > Example:< / b > < / p >
< blockquote > < blockquote >
< pre > optional< double> x(123.4); < pre >
optional< double> x(123.4);
assert ( *x == 123.4 ) ;
assert ( *x == 123.4 ) ;
optional< int> y(x) ;
optional< int> y(x) ;
@ -633,7 +693,8 @@ in that case, this constructor has no effect.
< p > < b > Example:< / b > < / p > < p > < b > Example:< / b > < / p >
< blockquote > < blockquote >
< pre > class C { C ( char, double, std::string ) ; } ; < pre >
class C { C ( char, double, std::string ) ; } ;
C v('A',123.4," hello" );
C v('A',123.4," hello" );
@ -649,6 +710,27 @@ assert ( *y == v ) ;
< HR > < HR >
< pre > optional& optional< T< / i > > ::operator= ( none_t n ) ;< / pre >
< blockquote >
< p > < b > Effect:< / b > Same as opeator=(optional const& rhs), when rhs is default-constructed (uninitialized).< / p >
< p > < b > Postconditions:< / b > < b > *this< / b > is uninitialized< / p >
< p > < b > Example:< / b > < / p >
< blockquote >
< pre >
#include < boost/none.hpp>
optional< int> def ;
optional< int> opt(123) ;
opt = boost::none ;
assert ( opt == def ) ;
< / pre >
< / blockquote >
< / blockquote >
< HR >
< pre > optional& optional< T < i > (not a ref)< / i > > ::operator= ( T const& rhs ) ;< / pre > < pre > optional& optional< T < i > (not a ref)< / i > > ::operator= ( T const& rhs ) ;< / pre >
< blockquote > < blockquote >
< p > < b > Effect:< / b > Assigns the value 'rhs' to an < b > optional< / b > .< / p > < p > < b > Effect:< / b > Assigns the value 'rhs' to an < b > optional< / b > .< / p >
@ -664,7 +746,8 @@ uninitialized and T's <i>copy constructor</i> fails, <b>*this</b> is left
properly uninitialized]< / p >
properly uninitialized]< / p >
< p > < b > Example:< / b > < / p > < p > < b > Example:< / b > < / p >
< blockquote > < blockquote >
< pre > T x; < pre >
T x;
optional< T> def ;
optional< T> def ;
optional< T> opt(x) ;
optional< T> opt(x) ;
@ -687,7 +770,8 @@ and it references the same object referenced by <b>rhs.</b></p>
new object. See < A HREF = "#refassign" > here< / a > for details on this behavior.< / p >
new object. See < A HREF = "#refassign" > here< / a > for details on this behavior.< / p >
< p > < b > Example:< / b > < / p > < p > < b > Example:< / b > < / p >
< blockquote > < blockquote >
< pre > int a = 1 ; < pre >
int a = 1 ;
int b = 2 ;
int b = 2 ;
T& ra = a ;
T& ra = a ;
T& rb = b ;
T& rb = b ;
@ -817,7 +901,7 @@ assert ( *opt1 == static_cast<U>(v) ) ;
< HR > < HR >
< pre > void optional< T> ::reset() ;< / pre > < pre > void optional< T> ::reset() ;< / pre >
< blockquote > < blockquote >
< p > < b > Deprecated: < / b > Same as operator=( detail:: none_t );< / p > < p > < b > Deprecated: < / b > Same as operator=( none_t n );< / p >
< / blockquote > < / blockquote >
< HR > < HR >
@ -852,32 +936,6 @@ assert ( *opt == w ) ;
< HR > < HR >
< pre > T const& optional< T < i > (not a ref)< / i > > ::get_value_or( T const& default) const ;
T& optional< T < i > (not a ref)< / i > > ::get_value_or( T& default ) ;
inline T const& get_optional_value_or ( optional< T< i > (not a ref)< / i > > const& o, T const& default ) ;
inline T& get_optional_value_or ( optional< T < i > (not a ref)< / i > > & o, T& default ) ;
< / pre >
< blockquote >
< p > < b > Returns:< / b > A reference to the contained value, if any, or < code > default< / code > < / p >
< p > < b > Throws:< / b > Nothing.< / p >
< p > < b > Example:< / b > < / p >
< blockquote >
< pre > 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 ) ;
< / pre >
< / blockquote >
< pre > < / pre >
< / blockquote >
< HR >
< pre > T const& optional< T& > ::operator*() const ;< pre > T const& optional< T& > ::operator*() const ;
T & optional< T< i > & < / i > > ::operator*();< / pre >
T & optional< T< i > & < / i > > ::operator*();< / pre >
@ -907,29 +965,66 @@ assert ( *opt == v ) ;</pre>
< HR > < HR >
< pre > T const* optional< T < i > (not a ref)< / i > > ::get_ptr( ) const ;< pre > T const& < T> ::get_value_or( T const& default
T* optional< T < i > (not a ref)< / i > > ::get_ptr( ) ;
T& < T> ::get_value_or( T& default
inline T const* get_pointer ( optional< T < i > (not a ref)< / i > > const& ) ;
inline T const& get_optional_value_or ( optional< T> const& o, T& default ) ;
inline T* get_pointe r ( optional< T < i > (not a ref)< / i > > & ) ;
inline T& optional_value_o r ( optional< T> & o, T& default
< / pre >
< blockquote >
< p > < b > Returns:< / b > A reference to the contained value (which can be itself a reference), if any, or < code > default< / code > < / p >
< p > < b > Throws:< / b > Nothing.< / p >
< p > < b > Example:< / b > < / p >
< blockquote >
< pre > 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 ) ;
< / pre >
< / blockquote >
< pre > < / pre >
< / blockquote >
< HR >
< pre > T const* optional< T> ::get_ptr() const ;
T* optional< T> ::get_ptr() ;
inline T const* get_pointer ( optional< T> const& ) ;
inline T* get_pointer ( optional< T> & ) ;
< / pre > < / pre >
< blockquote > < blockquote >
< p > < b > Returns:< / b > If < b > *this< / b > is initialized, a pointer to the contained< p > < b > Returns:< / b > If < b > *this< / b > is initialized, a pointer to the contained
value; else 0 (< i > null< / i > ).
value; else 0 (< i > null< / i > ).
< / p > < / p >
< p > < b > Throws:< / b > Nothing.< / p > < p > < b > Throws:< / b > Nothing.< / p >
< p > < b > Notes:< / b > If T is a reference type, the pointer is to the referenced object< / p >
< p > < b > Notes:< / b > The contained value is permanently stored within *this, so< p > < b > Notes:< / b > The contained value is permanently stored within *this, so
you should not hold nor delete this pointer
you should not hold nor delete this pointer.
< / p > < / p >
< p > < b > Example:< / b > < / p > < p > < b > Example:< / b > < / p >
< blockquote > < blockquote >
< pre > T v ;
< pre > int v=123 ;
optional< T > opt(v);
optional< int > opt(v);
optional< T > const copt(v);
optional< int > const copt(v);
T * p = opt.get_ptr() ;int * p = opt.get_ptr() ;
T const* cp = copt.get_ptr();int const* cp = copt.get_ptr();
assert ( p == get_pointer(opt) );
assert ( p == get_pointer(opt) );
assert ( cp == get_pointer(copt) ) ;
assert ( cp == get_pointer(copt) ) ;
int& rv = v ;
optional< int& > optr(rv);
*(optr.get_ptr()) = 456 ;
assert ( v == 456 );
< / pre > < / pre >
< / blockquote > < / blockquote >
< / blockquote > < / blockquote >
@ -938,13 +1033,14 @@ assert ( cp == get_pointer(copt) ) ;
< HR > < HR >
< pre > T const* optional< T < i > (not a ref)< / i > > ::operator -> () const ;< pre > T const* optional< T> ::operator -> () const ;
T* optional< T < i > (not a ref)< / i > > ::operator -> () ;
T* optional< T> ::operator -> () ;
< / pre > < / pre >
< blockquote > < blockquote >
< p > < b > Requirements: *this< / b > is initialized.< / p > < p > < b > Requirements: *this< / b > is initialized.< / p >
< p > < b > Returns:< / b > A pointer to the contained value.< / p > < p > < b > Returns:< / b > A pointer to the contained value.< / p >
< p > < b > Throws:< / b > Nothing.< / p > < p > < b > Throws:< / b > Nothing.< / p >
< p > < b > Notes:< / b > If T is a reference type, the pointer is to the referenced object< / p >
< p > < b > Notes:< / b > The requirement is asserted via BOOST_ASSERT().< / p > < p > < b > Notes:< / b > The requirement is asserted via BOOST_ASSERT().< / p >
< p > < b > Example:< / b > < / p > < p > < b > Example:< / b > < / p >
< blockquote > < blockquote >
@ -952,6 +1048,14 @@ T* optional<T <i>(not a ref)</i>>::operator ->() ;
X x ;
X x ;
optional< X> opt (x);
optional< X> opt (x);
opt-> mdata = 2 ;
opt-> mdata = 2 ;
X& rx = x ;
optional< X& > optr (rx);
optr-> mdata = 4 ;
assert ( x.mdata = 4 )
< / pre > < / pre >
< / blockquote > < / blockquote >
< / blockquote > < / blockquote >
@ -1154,13 +1258,50 @@ assert ( optX != optZ ) ;
< p > < b > Throws:< / b > Nothing.< / p >
< p > < b > Throws:< / b > Nothing.< / p >
< / blockquote > < / blockquote >
< HR >
< pre >
bool operator == ( optional< T> const& x, T const& n );
bool operator != ( optional< T> const& x, T const& n );
bool operator < ( optional< T> const& x, T const& n );
bool operator > ( optional< T> const& x, T const& n );
bool operator < = ( optional< T> const& x, T const& n );
bool operator > = ( optional< T> const& x, T const& n );
bool operator == ( T const& n, optional< T> const& y );
bool operator != ( T const& n, optional< T> const& y );
bool operator < ( T const& n, optional< T> const& y );
bool operator > ( T const& n, optional< T> const& y );
bool operator < = ( T const& n, optional< T> const& y );
bool operator > = ( T const& n, optional< T> const& y );
< / pre >
< blockquote >
< p > < b > Returns:< / b > The result obtained by replacing the argument 'n' by optional< T> (n).< / p >
< / blockquote >
< HR >
< pre >
bool operator == ( optional< T> const& x, none_t n );
bool operator != ( optional< T> const& x, none_t n );
bool operator < ( optional< T> const& x, none_t n );
bool operator > ( optional< T> const& x, none_t n );
bool operator < = ( optional< T> const& x, none_t n );
bool operator > = ( optional< T> const& x, none_t n );
bool operator == ( none_t n, optional< T> const& y );
bool operator != ( none_t n, optional< T> const& y );
bool operator < ( none_t n, optional< T> const& y );
bool operator > ( none_t n, optional< T> const& y );
bool operator < = ( none_t n, optional< T> const& y );
bool operator > = ( none_t n, optional< T> const& y );
< / pre >
< blockquote >
< p > < b > Returns:< / b > The result obtained by replacing the argument 'n' by optional< T> ().< / p >
< / blockquote >
< HR > < HR >
< pre > void swap ( optional< T> & amp x, optional< T& gt& amp y );< / pre > < pre > void swap ( optional< T> & amp x, optional< T& gt& amp y );< / pre >
< blockquote > < blockquote >
< p > < b > Effect:< / b > If both < b > x< / b > and < b > y< / b > are initialized, calls < code > swap(*x,*y)< / code > using std::swap.< br > < p > < b > Effect:< / b > If both < b > x< / b > and < b > y< / b > are initialized, calls < code > swap(*x,*y)< / code > using std::swap.< br >
If only one is initialized, say x, calls: < code > y.reset( *x) ; x.reset() ;< / code > < br >
If only one is initialized, say x, calls: < code > y = *x; x = boost:none ;< / code > < br >
If none is initialized, does nothing. < / p >
If none is initialized, does nothing. < / p >
< p > < b > Postconditions:< / b > The states of x and y interchanged.< / p > < p > < b > Postconditions:< / b > The states of x and y interchanged.< / p >
< p > < b > Throws:< / b > If both are initialized, whatever swap(T& ,T& ) throws.< p > < b > Throws:< / b > If both are initialized, whatever swap(T& ,T& ) throws.
@ -1169,7 +1310,7 @@ If only one is initialized, whatever T::T ( T const& ) throws. </p>
If only one is initialized, T::~T() and T::T( T const& ) is called. < / p >
If only one is initialized, T::~T() and T::T( T const& ) is called. < / p >
< p > < b > Exception Safety:< / b > If both are initialized, this operation has the exception< p > < b > Exception Safety:< / b > If both are initialized, this operation has the exception
safety guarantees of swap(T& ,T& ).< br >
safety guarantees of swap(T& ,T& ).< br >
If only one is initialized, it has the same < b > basic< / b > guarantee as optional< T> ::reset ( T const& ). < / p >
If only one is initialized, it has the same < b > basic< / b > guarantee as optional< T> ::operator= ( T const& ). < / p >
< p > < b > Example:< / b > < / p > < p > < b > Example:< / b > < / p >
< blockquote > < blockquote >
< pre > T x(12);
< pre > T x(12);
@ -1219,12 +1360,12 @@ void receive_async_message()
< pre > optional< string> name ;< pre > optional< string> name ;
if ( database.open() )
if ( database.open() )
{
{
name.reset ( database.lookup(employer_name) ) ; name = database.lookup(employer_name) ;
}
}
else
else
{
{
if ( can_ask_user ) if ( can_ask_user )
name.reset ( user.ask(employer_name) ) ; name = user.ask(employer_name) ;
}
}
if ( name )
if ( name )
@ -1245,7 +1386,7 @@ else print("employer's name not found!");
void clip_in_rect ( rect const& rect ) void clip_in_rect ( rect const& rect )
{ {
.... ....
m_clipping_rect.reset ( rect ) ; // initialized here. m_clipping_rect = rect ; // initialized here.
} }
void draw ( canvas& cvs ) void draw ( canvas& cvs )
@ -1289,16 +1430,17 @@ some operations are not available in this case:</p>
< li > Converting assignment< / li >
< li > Converting assignment< / li >
< li > InPlace construction< / li >
< li > InPlace construction< / li >
< li > InPlace assignment< / li >
< li > InPlace assignment< / li >
< li > Value-access via pointer< / li >
< / ul > < / ul >
< p > Also, even though optional< T& > treats it wrapped pseudo-object much as a real< p > Also, even though optional< T& > treats it wrapped pseudo-object much as a real
value, a true real reference is stored so aliasing will ocurr: < / p >
value, a true real reference is stored, thus aliasing can ocurr: < / p >
< ul > < ul >
< li > Copies of optional< T& > will copy the references but all these references
< li > Copies of optional< T& > copies the reference, but all copied references
will nonetheless reefer to the same object.< / li >
will nonetheless reefer to the same object.< / li >
< li > Value-access will actually provide access to the referenced object rather
< li > Value-access provides access to the referenced object rather
than the reference itself.< / li >
than the reference itself.< / li >
< li > Pointer-access provides a pointer to the referenced object rather
than a pointer to the reference itself.< / li >
< / ul > < / ul >
< HR > < HR >
@ -1309,7 +1451,7 @@ Clearly, there is no other choice.</p>
< pre > int x = 1 ;< pre > int x = 1 ;
int& rx = x ;
int& rx = x ;
optional< int& > ora ;
optional< int& > ora ;
optional< int& > orb(x) ;
optional< int& > orb(r x) ;
ora = orb ; // now 'ora' is bound to 'x' through 'rx'
ora = orb ; // now 'ora' is bound to 'x' through 'rx'
*ora = 2 ; // Changes value of 'x' through 'ora'
*ora = 2 ; // Changes value of 'x' through 'ora'
assert(x==2);
assert(x==2);
@ -1320,7 +1462,7 @@ referenced object; it's value changes but the reference is never rebound.</p>
int& ra = a ;
int& ra = a ;
int b = 2 ;
int b = 2 ;
int& rb = b ;
int& rb = b ;
ra = rb ; // Changes the value of 'a' to 'b'
ra = rb ; // Changes the VALUE of 'a' to that of 'b'
assert(a==b);
assert(a==b);
b = 3 ;
b = 3 ;
assert(ra!=b); // 'ra' is not rebound to 'b'
assert(ra!=b); // 'ra' is not rebound to 'b'
@ -1346,38 +1488,68 @@ C++ references.<br>
It is true that optional< U> strives to behave as much as possible as U does
It is true that optional< U> strives to behave as much as possible as U does
whenever it is initialized; but in the case when U is T& , doing so would result
whenever it is initialized; but in the case when U is T& , doing so would result
in inconsistent behavior w.r.t to the lvalue initialization state.< / p >
in inconsistent behavior w.r.t to the lvalue initialization state.< / p >
< p > Imagine optional< T& > forwarding assignment to the referenced object (thus < p > Consider the following code :< / p >
changing the referenced object value but not rebinding), and consider the < pre >
following code :< / p > int x = 1 ;
< pre > optional< int& > a = get()int& rx = x ;
int x = 1 ;void foo ( optional< int& > & outer )
int& rx = x ;{
< int& > b(rx); optional< int& > b(rx);
a outer = b ;
}
< / pre >
< p > What should the assignment to 'outer' do?< br >
If 'outer' is < i > uninitialized< / i > , the answer is clear: it should bind to 'x' (so we now have
a second reference to 'x').< br >
But what if 'outer' is already < i > initialized?< / i > < br >
The assignment could change the value of the
referenced object (whatever that is), but doing that would be inconsistent with the uninitialized case
and then you wouldn't be able to reason at compile time about all the references to x since
the appearance of a new reference to it would depend on wheter the lvalue ('outer')
is initialized or not.< / p >
< p > Arguably, if rebinding the reference to another object is wrong for your code, then is
likely that binding it for the fist time via assignment instead of intialization is also wrong.
In that case, you can always just assign the value to the referenced object directly via
the access operator < code > *opt=value< / code > .< / p >
< p > If rebinding is wrong but first-time binding
isn't (via assignment), you can always work around the rebinding semantics using a discriminator:< / p >
< pre >
if ( !opt )
opt = value ; // first-time binding
else *opt = value ; // assign to referee without rebinding
< / pre >
< HR >
< H2 > < A NAME = "none" > none_t and none< / A > < / H2 >
< p > optional< T> supports uninitialized states with a convenient syntax via a constant of
the < i > implementation-defined< / i > type < code > boost::none_t< / code > , identified as < code > boost::none< / code > .< / p >
< p > Starting with Boost version 1.34.0, both < code > boost::none_t< / code > and < code > boost::none< / code > are
included in < code > boost/none.hpp< / code > , which is automatically included by < code > boost/optional/optional.hpp< / code >
< / p >
< p > This contant is similar in purpose to NULL, except that is not a < i > null pointer value< / i > . You can use it to initialize
an optional< T> instance, which has the same effect of a default constructor, and you can assign it which has the
effect of reseting the optional< T> instance. You can also use it in relational operators to make the predicate expression
more clear.< / p >
< p > Here are some typical examples:< / p >
< pre >
#include "boost/optional/optional.hpp" // boost/none.hpp is included automatically
boost::optional< int> foo ( int a )
{
return some_condition(a) ? boost::make_optional(a) : boost::none ;
// NOTE: in real code you can just use this: make_optional(some_condition(a), a )
}
boost::optional< int> opt = boost::none ;
if ( opt == boost::none )
opt = foo(123);
opt = boost::none ;
< / pre > < / pre >
< p > What does the assignment do?< br >
If 'a' is < i > uninitialized< / i > , the answer is clear: it binds to 'x' (we now have
another reference to 'x').< br >
But what if 'a' is already < i > initialized? < / i > it would change the value of the
referenced object (whatever that is); which is inconsistent with the other
possible case.< / p >
< p > If optional< T& > would assign just like T& does, you would never be able to
use Optional's assignment without explicitly handling the previous
initialization state unless your code is capable of functioning whether after
the assignment, 'a'
aliases the same object as 'b' or not.< / p >
< p > That is, you would have to discriminate in order to be consistency.< br >
< br >
If in your code rebinding to another object is not an option, then is very
likely that binding for the fist time isn't either. In such case, assignment to
an < i > uninitialized< / i > optional< T& > shall be prohibited. It is quite
possible that in such scenario the precondition that the lvalue must be already
initialized exist. If it doesn't, then binding for the first time is OK while
rebinding is not which is IMO
very unlikely.< br >
In such scenario, you can assign the value itself directly, as in:< / p >
< pre > assert(!!opt);
*opt=value; < / pre >
< HR > < HR >
@ -1506,9 +1678,8 @@ public:
the < i > maybe< / i > state < u > represents a valid value< / u > , unlike the corresponding state
the < i > maybe< / i > state < u > represents a valid value< / u > , unlike the corresponding state
of an uninitialized optional< bool> .< br >
of an uninitialized optional< bool> .< br >
It should be carefully considered if an optional< bool> instead of a tribool is really needed< / p >
It should be carefully considered if an optional< bool> instead of a tribool is really needed< / p >
< p > Second, optional< > provides an implicit conversion to bool. This conversion < p > Second, optional< > provides a simple way to test initialization state: an implicit conversion to a type that evaluates as a 'bool' in a boolean context.< br >
refers to the initialization state and not to the contained value.< br > Using optional< bool> can lead to subtle errors due to this implicit conversion:< / p >
Using optional< bool> can lead to subtle errors due to the implicit bool conversion:< / p >
< pre > void foo ( bool v ) ;< pre > void foo ( bool v ) ;
void bar()
void bar()
{
{
@ -1524,7 +1695,9 @@ void bar()
integral promotions don't apply (i.e. if foo() takes an 'int' instead, it won't compile). < HR >
integral promotions don't apply (i.e. if foo() takes an 'int' instead, it won't compile). < HR >
< H2 > < A NAME = "exsafety" > Exception Safety Guarantees< / A > < / H2 > < H2 > < A NAME = "exsafety" > Exception Safety Guarantees< / A > < / H2 >
< H3 > < u > Assignment and Reset:< / u > < / H3 >
< H3 > < u > Assignment:< / u > < / H3 >
< p > < i > IMPORTANT NOTE: This changed in 1.33.1 with respect to previous versions< / i > < / p >
< p > Because of the current implementation (see < A HREF = "#impl" > Implementation Notes< / A > ), all< p > Because of the current implementation (see < A HREF = "#impl" > Implementation Notes< / A > ), all
of the assignment methods:< / p >
of the assignment methods:< / p >
< ul > < ul >
@ -1537,60 +1710,17 @@ of the assignment methods:</p>
InPlaceFactory const& ) < / code > < / li >
InPlaceFactory const& ) < / code > < / li >
< li > < code > template< class TypedInPlaceFactory> optional< T> ::operator= (
< li > < code > template< class TypedInPlaceFactory> optional< T> ::operator= (
TypedInPlaceFactory const& ) < / code > < / li >
TypedInPlaceFactory const& ) < / code > < / li >
< li > < code > optional< T> :::reset ( T const& )< / code > < / li >
< / ul > < / ul >
< p > C an onl y < i > guarantee< / i > the < u > basic exception safety< / u > : The lvalue optional is left < u > uninitialized < / u > if an exception is thrown (any previous value is < i > first< / i > destroyed using T::~T()) < / p > < p > c annot offer an y < i > exception safety guarantee < / i > beyond that provided by < code > T::operator=( T const& )< / code > < / p >
< p > On the other hand, the < i > uninitializing< / i > methods:< / p > < p > On the other hand, the < i > uninitializing< / i > methods:< / p >
< ul > < ul >
< li > < code > optional< T> ::operator= ( detail::none_t ) < / code > < / li >
< li > < code > optional< T> ::operator= ( detail::none_t ) < / code > < / li >
< li > < code > optional< T> ::reset()< / code > < / li >
< / ul > < / ul >
< p > Provide the no-throw guarantee (assuming a no-throw T::~T())< / p > < p > Provides the no-throw guarantee (assuming a no-throw T::~T()) becuse it only destroys the stored object. < / p >
< p > However, since < code > optional& lt& gt< / code > itself doesn't throw any exceptions,
the only source for exceptions here are T's constructor, so if you know the exception guarantees
for T::T ( T const& ), you know that optional's assignment and reset has the same guarantees.< / p >
< pre > //
// Case 1: Exception thrown during assignment.
//
T v0(123);
optional& ltT& gt opt0(v0);
try
{
T v1(456);
optional& ltT& gt opt1(v1);
opt0 = opt1 ;
// If no exception was thrown, assignment succeeded.
assert( *opt0 == v1 ) ;
}
catch(...)
{
// If any exception was thrown, 'opt0' is reset to uninitialized.
assert( !opt0 ) ;
}
//
// Case 2: Exception thrown during reset(v)
//
T v0(123);
optional& ltT& gt opt(v0);
try
{
T v1(456);
opt.reset ( v1 ) ;
// If no exception was thrown, reset succeeded.
assert( *opt == v1 ) ;
}
catch(...)
{
// If any exception was thrown, 'opt' is reset to uninitialized.
assert( !opt ) ;
}
< / pre >
< H3 > < u > Swap:< / u > < / H3 > < H3 > < u > Swap:< / u > < / H3 >
< p > < code > void swap( optional< T> & , optional< T> & )< / code > has the same exception guarantee as < code > swap(T& ,T& )< / code > when both optionals are initialized.< br > < p > < code > void swap( optional< T> & , optional< T> & )< / code > has the same exception guarantee as < code > swap(T& ,T& )< / code > when both optionals are initialized.< br >
If only one of the optionals is initialized, it gives the same < i > basic< / i > exception guarantee as < code > optional< T> ::reset ( T const& )< / code > (since < code > optional< T> ::reset( )< / code > doesn't throw).< br >
If only one of the optionals is initialized, it gives the same exception guarantee as < code > T::operator= ( T const& )< / code > (since < code > optional< T> ::operator=( none_t )< / code > doesn't throw).< br >
If none of the optionals is initialized, it has no-throw guarantee since it is a no-op. < / p >
If none of the optionals is initialized, it has no-throw guarantee since it is a no-op. < / p >
< HR > < HR >
@ -1604,14 +1734,11 @@ T <u>is not</u> required to be <a href="http://www.sgi.com/tech/stl/DefaultConst
< H2 > < A NAME = "impl" > Implementation Notes< / A > < / H2 > < H2 > < A NAME = "impl" > Implementation Notes< / A > < / H2 >
< p > optional< T> is currently implemented< p > optional< T> is currently implemented
using a custom aligned storage facility built from < code > alignment_of< / code > and < code > type_with_alignment< / code > (both from Type Traits).
using a custom aligned storage facility built from < code > alignment_of< / code > and < code > type_with_alignment< / code > (both from Type Traits).
It uses a separate boolean flag to indicate the initialization state.< br >
It uses a separate boolean flag to indicate the initialization state.< / p >
Placement new with T's copy constructor and T's destructor< p >
are explicitly used to initialize,copy and destroy optional values.< br >
is explicitly used to initialize and destroy optional values. This allows T's default constructor to be effectively by-passed.< / p >
As a result, T's default constructor is effectively by-passed, but the exception < p > If assignment is used and the lvalue optional is uninitialized, T's copy constructor is used. However, if it is already initialized, T's assignment operator is used. This prevents optional from offering any exception guarantee stronger than the one offered by the type T itself< / p >
guarantees are basic.< br >
It is planned to replace the current implementation with another with
stronger exception safety, such as a future boost::variant< T , nil_t > . < / p >
< HR > < HR >
@ -1665,12 +1792,12 @@ T <u>is not</u> required to be <a href="http://www.sgi.com/tech/stl/DefaultConst
< / blockquote > < / blockquote >
< HR > < HR >
< P > Revised April 21 , 2005 < / P > < P > Revised March 27 , 2007 < / P >
< p > <EFBFBD> Copyright Fernando Luis Cacciola Carballal, 2003, 2004,2005 < / p > < p > <EFBFBD> Copyright Fernando Luis Cacciola Carballal, 2003- 2007 < / p >
< p > Use, modification, and distribution are subject to the Boost Software< p > Use, modification, and distribution are subject to the Boost Software
License, Version 1.0. (See accompanying file < a href = "../../../LICENSE_1_0.txt" > LICENSE_1_0.txt< / a > or copy at < a href = "http://www.boost.org/LICENSE_1_0.txt" > www.boost.org/LICENSE_1_0.txt< / a > )< / p >
License, Version 1.0. (See accompanying file < a href = "../../../LICENSE_1_0.txt" > LICENSE_1_0.txt< / a > or copy at < a href = "http://www.boost.org/LICENSE_1_0.txt" > www.boost.org/LICENSE_1_0.txt< / a > )< / p >
< P > Developed by < A HREF = "mailto:fernando_cacciola@hotmail.com" > Fernando Cacciola< / A > ,< P > Developed by < A HREF = "mailto:fernando_cacciola@hotmail.com" > Fernando Cacciola< / A > ,
the latest version of this file can be found at < A
the latest version of this file can be found at < A
HREF = "http://www.boost.org" > www.boost.org< / A > , and the boost < A HREF = "http://www.boost.org/more/mailing_lists.htm#main" > discussion lists< / A > < / P > HREF = "http://www.boost.org" > www.boost.org< / A > , and the boost < A HREF = "http://www.boost.org/more/mailing_lists.htm#main" > discussion lists< / A > < / P >
< / pre > < / BODY > < / pre > < / BODY >
< / HTML > < / HTML >
