As of this writing I don't know of any precedence for a variable-size fixed-capacity (of 1)
+
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
the lack of practical implementations of such a container rather than an inherent shortcoming
of the container model.
@@ -348,7 +350,7 @@ class optional
T const& get() const ;
T& get() ;
- T
- optional<T> uninit ;
+
+optional<T> uninit ;
assert (!uninit);
optional<T> uinit2 ( uninit ) ;
@@ -562,7 +620,8 @@ is uninitialized.
reefer to the same object (they alias).
Example:
- optional<T&> uninit ;
+
+optional<T&> uninit ;
assert (!uninit);
optional<T&> uinit2 ( uninit ) ;
@@ -605,7 +664,8 @@ in that case, this constructor has no effect.
Example:
-optional<double> x(123.4);
+
+optional<double> x(123.4);
assert ( *x == 123.4 ) ;
optional<int> y(x) ;
@@ -633,7 +693,8 @@ in that case, this constructor has no effect.
Example:
-class C { C ( char, double, std::string ) ; } ;
+
+class C { C ( char, double, std::string ) ; } ;
C v('A',123.4,"hello");
@@ -649,6 +710,27 @@ assert ( *y == v ) ;
+optional& optional<T>::operator= ( none_t n ) ;
+
+Effect: Same as opeator=(optional const& rhs), when rhs is default-constructed (uninitialized).
+Postconditions: *this is uninitialized
+Example:
+
+
+#include <boost/none.hpp>
+
+optional<int> def ;
+optional<int> opt(123) ;
+
+opt = boost::none ;
+
+assert ( opt == def ) ;
+
+
+
+
+
+
optional& optional<T (not a ref)>::operator= ( T const& rhs ) ;
Effect: Assigns the value 'rhs' to an optional.
@@ -664,7 +746,8 @@ uninitialized and T's copy constructor fails, *this is left
properly uninitialized]
Example:
- T x;
+
+T x;
optional<T> def ;
optional<T> opt(x) ;
@@ -687,7 +770,8 @@ and it references the same object referenced by rhs.
new object. See here for details on this behavior.
Example:
- int a = 1 ;
+
+int a = 1 ;
int b = 2 ;
T& ra = a ;
T& rb = b ;
@@ -817,7 +901,7 @@ assert ( *opt1 == static_cast<U>(v) ) ;
void optional<T>::reset() ;
-Deprecated: Same as operator=( detail::none_t );
+Deprecated: Same as operator=( none_t n);
@@ -852,32 +936,6 @@ assert ( *opt == w ) ;
-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 ) ;
-
-
-Returns: A reference to the contained value, if any, or default
-Throws: Nothing.
-Example:
-
- T v, z ;
-optional<T> def;
-T const& y = def.get_value_or(z);
-assert ( y == z ) ;
-
-optional<T> opt ( v );
-T const& u = get_optional_value_or(opt,z);
-assert ( u == v ) ;
-assert ( u != z ) ;
-
-
-
-
-
-
T const& optional<T&>::operator*() const ;
T & optional<T&>::operator*();
@@ -907,29 +965,66 @@ assert ( *opt == v ) ;
-T const* optional<T (not a ref)>::get_ptr() const ;
-T* optional<T (not a ref)>::get_ptr() ;
+T const& optional<T>::get_value_or( T const& default) const ;
+T& optional<T>::get_value_or( T& default ) ;
-inline T const* get_pointer ( optional<T (not a ref)> const& ) ;
-inline T* get_pointer ( optional<T (not a ref)> &) ;
+inline T const& get_optional_value_or ( optional<T> const& o, T const& default ) ;
+inline T& get_optional_value_or ( optional<T>& o, T& default ) ;
+
+
+Returns: A reference to the contained value (which can be itself a reference), if any, or default
+Throws: Nothing.
+Example:
+
+ T v, z ;
+optional<T> def;
+T const& y = def.get_value_or(z);
+assert ( y == z ) ;
+
+optional<T> opt ( v );
+T const& u = get_optional_value_or(opt,z);
+assert ( u == v ) ;
+assert ( u != z ) ;
+
+
+
+
+
+
+
+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> &) ;
Returns: If *this is initialized, a pointer to the contained
value; else 0 (null).
Throws: Nothing.
+Notes: If T is a reference type, the pointer is to the referenced object
Notes: 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.
Example:
- T v;
-optional<T> opt(v);
-optional<T> const copt(v);
-T* p = opt.get_ptr() ;
-T const* cp = copt.get_ptr();
+ int v=123;
+optional<int> opt(v);
+optional<int> const copt(v);
+int* p = opt.get_ptr() ;
+int const* cp = copt.get_ptr();
assert ( p == get_pointer(opt) );
assert ( cp == get_pointer(copt) ) ;
+
+int& rv = v ;
+optional<int&> optr(rv);
+
+*(optr.get_ptr()) = 456 ;
+
+assert ( v == 456 );
+
+
@@ -938,13 +1033,14 @@ assert ( cp == get_pointer(copt) ) ;
-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 ->() ;
Requirements: *this is initialized.
Returns: A pointer to the contained value.
Throws: Nothing.
+Notes: If T is a reference type, the pointer is to the referenced object
Notes: The requirement is asserted via BOOST_ASSERT().
Example:
@@ -952,6 +1048,14 @@ T* optional<T (not a ref)>::operator ->() ;
X x ;
optional<X> opt (x);
opt->mdata = 2 ;
+
+X& rx = x ;
+
+optional<X&> optr (rx);
+optr->mdata = 4 ;
+
+assert ( x.mdata = 4 )
+
@@ -1154,13 +1258,50 @@ assert ( optX != optZ ) ;
Throws: Nothing.
+
+
+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 );
+
+
+ Returns: The result obtained by replacing the argument 'n' by optional<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 >= ( 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 );
+
+
+ Returns: The result obtained by replacing the argument 'n' by optional<T>().
+
void swap ( optional<T>& x, optional<T>& 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 only one is initialized, say x, calls: y = *x; x = boost:none;
If none is initialized, does nothing.
Postconditions: The states of x and y interchanged.
Throws: If both are initialized, whatever swap(T&,T&) throws.
@@ -1169,7 +1310,7 @@ If only one is initialized, whatever T::T ( T const& ) throws.
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<T>::reset( T const& ).
+If only one is initialized, it has the same basic guarantee as optional<T>::operator=( T const& ).
Example:
T x(12);
@@ -1219,12 +1360,12 @@ void receive_async_message()
optional<string> name ;
if ( database.open() )
{
- name.reset ( database.lookup(employer_name) ) ;
+ name = database.lookup(employer_name) ;
}
else
{
if ( can_ask_user )
- name.reset ( user.ask(employer_name) ) ;
+ name = user.ask(employer_name) ;
}
if ( name )
@@ -1245,7 +1386,7 @@ else print("employer's name not found!");
void clip_in_rect ( rect const& rect )
{
....
- m_clipping_rect.reset ( rect ) ; // initialized here.
+ m_clipping_rect = rect ; // initialized here.
}
void draw ( canvas& cvs )
@@ -1289,16 +1430,17 @@ some operations are not available in this case:
Converting assignment
InPlace construction
InPlace assignment
- Value-access via pointer
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:
+value, a true real reference is stored, thus aliasing can ocurr:
- - Copies of optional<T&> will copy the references but all these references
+
- Copies of optional<T&> copies the reference, but all copied references
will nonetheless reefer to the same object.
- - Value-access will actually provide access to the referenced object rather
+
- Value-access provides access to the referenced object rather
than the reference itself.
+ - Pointer-access provides a pointer to the referenced object rather
+ than a pointer to the reference itself.
@@ -1309,7 +1451,7 @@ Clearly, there is no other choice.
int x = 1 ;
int& rx = x ;
optional<int&> ora ;
-optional<int&> orb(x) ;
+optional<int&> orb(rx) ;
ora = orb ; // now 'ora' is bound to 'x' through 'rx'
*ora = 2 ; // Changes value of 'x' through 'ora'
assert(x==2);
@@ -1320,7 +1462,7 @@ referenced object; it's value changes but the reference is never rebound.
int& ra = a ;
int b = 2 ;
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);
b = 3 ;
assert(ra!=b); // 'ra' is not rebound to 'b'
@@ -1346,38 +1488,68 @@ C++ references.
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
in inconsistent behavior w.r.t to the lvalue initialization state.
-Imagine optional<T&> forwarding assignment to the referenced object (thus
-changing the referenced object value but not rebinding), and consider the
-following code :
- optional<int&> a = get();
- int x = 1 ;
- int& rx = x ;
- optional<int&> b(rx);
- a = b ;
+Consider the following code :
+
+int x = 1 ;
+int& rx = x ;
+void foo ( optional<int&> & outer )
+{
+ optional<int&> b(rx);
+ outer = b ;
+}
+
+What should the assignment to 'outer' do?
+If 'outer' is uninitialized, the answer is clear: it should bind to 'x' (so we now have
+a second reference to 'x').
+But what if 'outer' is already initialized?
+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.
+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 *opt=value.
+If rebinding is wrong but first-time binding
+isn't (via assignment), you can always work around the rebinding semantics using a discriminator:
+
+if ( !opt )
+ opt = value ; // first-time binding
+else *opt = value ; // assign to referee without rebinding
+
+
+
+
+
+optional<T> supports uninitialized states with a convenient syntax via a constant of
+the implementation-defined type boost::none_t, identified as boost::none.
+Starting with Boost version 1.34.0, both boost::none_t and boost::none are
+included in boost/none.hpp, which is automatically included by boost/optional/optional.hpp
+
+This contant is similar in purpose to NULL, except that is not a null pointer value. 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.
+Here are some typical examples:
+
+#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 ;
+
-What does the assignment do?
-If 'a' is uninitialized, the answer is clear: it binds to 'x' (we now have
-another reference to 'x').
-But what if 'a' is already initialized? it would change the value of the
-referenced object (whatever that is); which is inconsistent with the other
-possible case.
-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.
-That is, you would have to discriminate in order to be consistency.
-
-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 uninitialized 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.
-In such scenario, you can assign the value itself directly, as in:
-assert(!!opt);
-*opt=value;
@@ -1506,9 +1678,8 @@ public:
the maybe state represents a valid value, unlike the corresponding state
of an uninitialized optional<bool>.
It should be carefully considered if an optional<bool> instead of a tribool is really needed
-Second, optional<> provides an implicit conversion to bool. This conversion
- refers to the initialization state and not to the contained value.
-Using optional<bool> can lead to subtle errors due to the implicit bool conversion:
+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.
+Using optional<bool> can lead to subtle errors due to this implicit conversion:
void foo ( bool v ) ;
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).
-Assignment and Reset:
+
+Assignment:
+IMPORTANT NOTE: This changed in 1.33.1 with respect to previous versions
Because of the current implementation (see Implementation Notes), all
of the assignment methods:
@@ -1537,60 +1710,17 @@ of the assignment methods:
InPlaceFactory const& )
-
template<class TypedInPlaceFactory> optional<T>::operator= (
TypedInPlaceFactory const& )
- -
optional<T>:::reset ( T const&)
-Can only guarantee the basic exception safety: The lvalue optional is left uninitialized if an exception is thrown (any previous value is first destroyed using T::~T())
+cannot offer any exception safety guarantee beyond that provided by T::operator=( T const& )
On the other hand, the uninitializing methods:
optional<T>::operator= ( detail::none_t ) optional<T>::reset()
-Provide the no-throw guarantee (assuming a no-throw T::~T())
-However, since optional<> 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.
-//
-// Case 1: Exception thrown during assignment.
-//
-T v0(123);
-optional<T> opt0(v0);
-try
-{
- T v1(456);
- optional<T> opt1(v1);
- opt0 = opt1 ;
+Provides the no-throw guarantee (assuming a no-throw T::~T()) becuse it only destroys the stored object.
- // 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<T> 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 ) ;
-}
-
Swap:
void swap( optional<T>&, optional<T>& ) has the same exception guarantee as swap(T&,T&) when both optionals are initialized.
-If only one of the optionals is initialized, it gives the same basic exception guarantee as optional<T>::reset( T const& ) (since optional<T>::reset() doesn't throw).
+If only one of the optionals is initialized, it gives the same exception guarantee as T::operator=( T const& ) (since optional<T>::operator=( none_t ) doesn't throw).
If none of the optionals is initialized, it has no-throw guarantee since it is a no-op.
@@ -1604,14 +1734,11 @@ T is not required to be Implementation Notes
optional<T> is currently implemented
- using a custom aligned storage facility built from alignment_of and type_with_alignment (both from Type Traits).
- It uses a separate boolean flag to indicate the initialization state.
- Placement new with T's copy constructor and T's destructor
- are explicitly used to initialize,copy and destroy optional values.
- As a result, T's default constructor is effectively by-passed, but the exception
- guarantees are basic.
- It is planned to replace the current implementation with another with
- stronger exception safety, such as a future boost::variant.
+ using a custom aligned storage facility built from alignment_of and type_with_alignment (both from Type Traits).
+ It uses a separate boolean flag to indicate the initialization state.
+Placement new with T's copy constructor and T's destructor
+ is explicitly used to initialize and destroy optional values. This allows T's default constructor to be effectively by-passed.
+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
@@ -1665,12 +1792,12 @@ T is not required to be LICENSE_1_0.txt or copy at www.boost.org/LICENSE_1_0.txt)
Developed by Fernando Cacciola,
the latest version of this file can be found at www.boost.org, and the boost discussion lists
-
+