Home | Libraries | People | FAQ | More |
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:
optional<T
(not
a ref)>
, the
description corresponds only to the case where T
is not of reference type.
optional<T&>
, the description corresponds only
to the case where T
is
of reference type.
optional<T>
, the description is the same for both
cases.
Note | |
---|---|
The following section contains various |
optional<T>::optional() noexcept;
optional
.
*this
is uninitialized.
optional<T> def ; assert ( !def ) ;
optional<T>::optional( none_t ) noexcept;
optional
uninitialized.
*this
is uninitialized.
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.
#include <boost/none.hpp> optional<T> n(none) ; assert ( !n ) ;
optional<T
(not a ref)>::optional( T const& v )
is_copy_constructible<T>::value
is true
.
optional
.
*this
is initialized
and its value is a copy of v
.
T::T(
T const& )
throws.
T::T(
T const& )
is called.
T::T( T
const&
);
in that case, this constructor
has no effect.
T v; optional<T> opt(v); assert ( *opt == v ) ;
optional<T&>::optional( T& ref )
optional
.
*this
is initialized
and its value is an instance of an internal type wrapping the reference
ref
.
T v; T& vref = v ; optional<T&> opt(vref); assert ( *opt == v ) ; ++ v ; // mutate referee assert (*opt == v);
optional<T
(not a ref)>::optional( T&& v )
is_move_constructible<T>::value
is true
.
optional
.
*this
is initialized
and its value is move-constructed from v
.
T::T(
T&&
)
throws.
T::T(
T&&
)
is called.
T::T( T&& );
in that case, the state of v
is determined by exception safety guarantees for T::T(T&&)
.
T v1, v2; optional<T> opt(std::move(v1)); assert ( *opt == v2 ) ;
optional<T&>::optional( T&& ref ) = delete
optional<T
(not a ref)>::optional( bool condition, T const& v ) ;
optional<T&> ::optional( bool condition, T& v ) ;
optional<T
(not a ref)>::optional( T const& v )
optional<T&> ::optional( T& v )
optional<T
(not a ref)>::optional()
optional<T&> ::optional()
optional<T
(not a ref)>::optional( optional const& rhs );
is_copy_constructible<T>::value
is true
.
optional
.
*this
is initialized and its value is a copy of the value
of rhs
; else *this
is
uninitialized.
T::T(
T const& )
throws.
T::T(T const& )
is called.
T::T( T
const&
);
in that case, this constructor
has no effect.
optional<T> uninit ; assert (!uninit); optional<T> uinit2 ( uninit ) ; assert ( uninit2 == uninit ); optional<T> init( T(2) ); assert ( *init == T(2) ) ; optional<T> init2 ( init ) ; assert ( init2 == init ) ;
optional<T&>::optional( optional const& rhs );
optional
.
rhs
is initialized, *this
is initialized and its value is another reference to the same object referenced
by *rhs
;
else *this
is uninitialized.
rhs
is initialized, both *this
and *rhs
will reefer to the same object (they alias).
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 ) ;
optional<T
(not a ref)>::optional( optional&& rhs ) noexcept(
see below);
is_move_constructible<T>::value
is true
.
optional
.
rhs
is initialized, *this
is initialized and its value is move constructed from rhs
;
else *this
is uninitialized.
T::T(
T&&
)
throws.
rhs
is initialized, T::T( T
&& )
is called. The expression inside noexcept
is equivalent to is_nothrow_move_constructible<T>::value
.
T::T( T&& );
in that case, rhs
remains
initialized and the value of *rhs
is determined by exception safety
of T::T(T&&)
.
optional<std::unique_ptr<T>> uninit ; assert (!uninit); optional<std::unique_ptr<T>> uinit2 ( std::move(uninit) ) ; assert ( uninit2 == uninit ); optional<std::unique_ptr<T>> init( std::uniqye_ptr<T>(new T(2)) ); assert ( **init == T(2) ) ; optional<std::unique_ptr<T>> init2 ( std::move(init) ) ; assert ( init ); assert ( *init == nullptr ); assert ( init2 ); assert ( **init2 == T(2) ) ;
optional<T&>::optional( optional && rhs );
optional
.
rhs
is initialized, *this
is initialized and its value is another reference to the same object referenced
by *rhs
;
else *this
is uninitialized.
rhs
is initialized, both *this
and *rhs
will reefer to the same object (they alias).
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 ) ;
template<U> explicit optional<T
(not a ref)>::optional( optional<U> const& rhs );
optional
.
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.
T::T(
U const& )
throws.
T::T(
U const& )
is called if rhs
is initialized,
which requires a valid conversion from U
to T
.
T::T( U
const&
);
in that case, this constructor
has no effect.
optional<double> x(123.4); assert ( *x == 123.4 ) ; optional<int> y(x) ; assert( *y == 123 ) ;
template<U> explicit optional<T
(not a ref)>::optional( optional<U>&& rhs );
optional
.
rhs
is initialized, *this
is initialized and its value is move constructed from *rhs
; else *this
is uninitialized.
T::T(
U&&
)
throws.
T::T(
U&&
)
is called if rhs
is initialized, which requires a valid conversion from U
to T
.
T::T( U&& );
in that case, rhs
remains
initialized and the value of *rhs
is determined by exception safety
guarantee of T::T( U&& )
.
optional<double> x(123.4); assert ( *x == 123.4 ) ; optional<int> y(std::move(x)) ; assert( *y == 123 ) ;
template<InPlaceFactory> explicit optional<T
(not a ref)>::optional( InPlaceFactory const& f );
template<TypedInPlaceFactory> explicit optional<T
(not a ref)>::optional( TypedInPlaceFactory const& f );
optional
with a value of T
obtained
from the factory.
*this
is initialized
and its value is directly given from the factory
f
(i.e., the value is not copied).
T
constructor called by the factory throws.
T
constructor used by the factory; in that case, this constructor has no
effect.
class C { C ( char, double, std::string ) ; } ; C v('A',123.4,"hello"); optional<C> x( in_place ('A', 123.4, "hello") ); // InPlaceFactory used optional<C> y( in_place<C>('A', 123.4, "hello") ); // TypedInPlaceFactory used assert ( *x == v ) ; assert ( *y == v ) ;
optional& optional<T>::operator= ( none_t ) noexcept;
*this
is initialized destroys its contained
value.
*this
is uninitialized.
optional& optional<T
(not a ref)>::operator= ( T const& rhs ) ;
rhs
to an optional
.
*this
is initialized and its value is a
copy of rhs
.
T::operator=( T const& )
or T::T(T const&)
throws.
*this
was initialized, T
's
assignment operator is used, otherwise, its copy-constructor is used.
*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.
T x; optional<T> def ; optional<T> opt(x) ; T y; def = y ; assert ( *def == y ) ; opt = y ; assert ( *opt == y ) ;
optional<T&>& optional<T&>::operator= ( T& rhs ) ;
*this
is initialized and it references the
same object referenced by rhs
.
*this
was initialized, it is rebound
to the new object. See here
for details on this behavior.
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 ) ;
optional& optional<T
(not a ref)>::operator= ( T&& rhs ) ;
rhs
to an optional
.
*this
is initialized and its value is moved
from rhs
.
T::operator=( T&& )
or T::T(T
&&)
throws.
*this
was initialized, T
's
move-assignment operator is used, otherwise, its move-constructor is used.
*this
is unchanged and its value unspecified
as far as optional
is concerned
(it is up to T
's operator=()
).
If *this
is initially uninitialized and T
's
move constructor fails, *this
is left properly uninitialized.
T x; optional<T> def ; optional<T> opt(x) ; T y1, y2, yR; def = std::move(y1) ; assert ( *def == yR ) ; opt = std::move(y2) ; assert ( *opt == yR ) ;
optional<T&>& optional<T&>::operator= ( T&& rhs ) = delete;
optional& optional<T
(not a ref)>::operator= ( optional const& rhs ) ;
optional
to an optional
.
rhs
is initialized, *this
is initialized and its value is a copy of the value
of rhs
; else *this
is
uninitialized.
T::operator( T const&)
or T::T( T
const&
)
throws.
*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.
*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.
T v; optional<T> opt(v); optional<T> def ; opt = def ; assert ( !def ) ; // previous value (copy of 'v') destroyed from within 'opt'.
optional<T&> & optional<T&>::operator= ( optional<T&> const& rhs ) ;
*rhs
is initialized, *this
is initialized and it references the
same object referenced by *rhs
; otherwise, *this
is uninitialized (and references no
object).
*this
was initialized and so is *rhs
,
*this
is rebound to the new object. See here
for details on this behavior.
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 ) ;
optional& optional<T
(not a ref)>::operator= ( optional&& rhs ) noexcept(
see below);
optional
to an optional
.
rhs
is initialized, *this
is initialized and its value is moved from *rhs
, rhs
remains initialized; else *this
is uninitialized.
T::operator( T&&
)
or T::T(
T &&
)
throws.
*this
and rhs
are initially initialized, T
's
move 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 move
constructor is called. The expression inside noexcept
is equivalent to is_nothrow_move_constructible<T>::value
&& is_nothrow_move_assignable<T>::value
.
*this
is unchanged and its value unspecified
as far as optional is concerned (it is up to T
's
operator=()
).
If *this
is initially uninitialized and T
's
move constructor fails, *this
is left properly uninitialized.
optional<T> opt(T(2)) ; optional<T> def ; opt = def ; assert ( def ) ; assert ( opt ) ; assert ( *opt == T(2) ) ;
optional<T&> & optional<T&>::operator= ( optional<T&>&& rhs ) ;
optional<T&>::operator= ( optional<T&> const& rhs )
.
template<U> optional& optional<T
(not a ref)>::operator= ( optional<U> const& rhs ) ;
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.
T::operator=( U const& )
or T::T(
U const& )
throws.
*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.
*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.
T v; optional<T> opt0(v); optional<U> opt1; opt1 = opt0 ; assert ( *opt1 == static_cast<U>(v) ) ;
template<U> optional& optional<T
(not a ref)>::operator= ( optional<U>&& rhs ) ;
rhs
is initialized, *this
is initialized and its value is moved from the value of rhs
;
else *this
is uninitialized.
T::operator=( U&& )
or T::T( U&& )
throws.
*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.
*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.
T v; optional<T> opt0(v); optional<U> opt1; opt1 = std::move(opt0) ; assert ( *opt1 == static_cast<U>(v) ) ;
template<class... Args> void optional<T
(not a ref)>::emplace( Args...&& args );
*this
is initialized calls *this =
none
. Then initializes in-place
the contained value as if direct-initializing an object of type T
with std::forward<Args>(args)...
.
*this
is initialized.
T
's constructor throws.
T
need not be MoveConstructible
or MoveAssignable
.
T
,
*this
is uninitialized.
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 );
optional
with a value of T
obtained
from the factory.
*this
is initialized
and its value is directly given from the factory
f
(i.e., the value is not copied).
T
constructor called by the factory throws.
T
constructor used by the factory; in that case, the optional
object will be reset to be uninitialized.
void optional<T
(not a ref)>::reset( T const& v ) ;
operator= ( T
const&
v)
;
void optional<T>::reset() noexcept ;
operator=( none_t );
T const& optional<T
(not a ref)>::get() const ;
T& optional<T
(not a ref)>::get() ;
inline T const& get ( optional<T
(not a ref)> const& ) ;
inline T& get ( optional<T
(not a ref)> &) ;
*this
is initialized
BOOST_ASSERT()
.
T const& optional<T&>::get() const ;
T& optional<T&>::get() ;
inline T const& get ( optional<T&> const& ) ;
inline T& get ( optional<T&> &) ;
*this
is initialized
BOOST_ASSERT()
.
T const& optional<T
(not a ref)>::operator*() const& ;
T& optional<T
(not a ref)>::operator*() &;
T&& optional<T
(not a ref)>::operator*() &&;
*this
is initialized
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.
T v ; optional<T> opt ( v ); T const& u = *opt; assert ( u == v ) ; T w ; *opt = w ; assert ( *opt == w ) ;
T const& optional<T&>::operator*() const& ;
T & optional<T&>::operator*() & ;
T & optional<T&>::operator*() && ;
*this
is initialized
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.
T v ; T& vref = v ; optional<T&> opt ( vref ); T const& vref2 = *opt; assert ( vref2 == v ) ; ++ v ; assert ( *opt == v ) ;
T const& optional<T>::value() const& ;
T& optional<T>::value() & ;
T&& optional<T>::value() && ;
*this
is initialized.
bad_optional_access
,
if *this
is not initialized.
const
and non-const
member functions.
T v ; optional<T> o0, o1 ( v ); assert ( o1.value() == v ); try { o0.value(); // throws assert ( false ); } catch(bad_optional_access&) { assert ( true ); }
template<class U> T optional<T>::value_or(U && v) const& ;
template<class U> T optional<T>::value_or(U && v) && ;
T
is CopyConstructible.
bool(*this) ? **this : static_cast<T>(forward<U>(v))
.
second overload: bool(*this) ?
std::move(**this) :
static_cast<T>(forward<U>(v))
.
T
.
const
and non-const
member functions.
On compilers without rvalue reference support the type of v
becomes U
const&
.
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 ) ;
value_or()
instead.
default
.
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
(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)> &) ;
*this
is initialized, a pointer to the contained
value; else 0
(null).
*this
,
so you should not hold nor delete this pointer
T v; optional<T> opt(v); optional<T> const copt(v); T* p = opt.get_ptr() ; T const* cp = copt.get_ptr(); assert ( p == get_pointer(opt) ); assert ( cp == get_pointer(copt) ) ;
T const* optional<T
(not a ref)>::operator ->() const ;
T* optional<T
(not a ref)>::operator ->() ;
*this
is initialized.
BOOST_ASSERT()
.
struct X { int mdata ; } ; X x ; optional<X> opt (x); opt->mdata = 2 ;
explicit optional<T>::operator bool() const ;
get_ptr() != 0
.
optional<T> def ; assert ( def == 0 ); optional<T> opt ( v ) ; assert ( opt ); assert ( opt != 0 );
bool optional<T>::operator!() noexcept ;
*this
is uninitialized, true
;
else false
.
optional<T> opt ; assert ( !opt ); *opt = some_T ; // Notice the "double-bang" idiom here. assert ( !!opt ) ;
bool optional<T>::is_initialized() const ;
explicit
operator bool
() ;
optional<T
(not a ref)> make_optional( T const& v )
optional<T>(v)
for the deduced type
T
of v
.
template<class T> void foo ( optional<T> const& opt ) ; foo ( make_optional(1+1) ) ; // Creates an optional<int>
optional<T
(not a ref)> make_optional( bool condition, T const& v )
optional<T>(condition,v)
for the deduced type T
of v
.
optional<double> calculate_foo() { double val = compute_foo(); return make_optional(is_not_nan_and_finite(val),val); } optional<double> v = calculate_foo(); if ( !v ) error("foo wasn't computed");
bool operator == ( optional<T> const& x, optional<T> const& y );
T
shall meet requirements of EqualityComparable
.
x
and y
are initialized,
(*x
== *y)
. If
only x
or y
is initialized, false
.
If both are uninitialized, true
.
optional
has deep relational operators. Do not use operator
==
directly in generic code which
expect to be given either an optional<T>
or a pointer; use equal_pointees()
instead
T x(12); T y(12); T z(21); optional<T> def0 ; optional<T> def1 ; optional<T> optX(x); optional<T> optY(y); optional<T> 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 ) ;
bool operator < ( optional<T> const& x, optional<T> const& y );
T
shall meet requirements of LessThanComparable
.
y
is not initialized, false
.
If y
is initialized and
x
is not initialized,
true
. If both x
and y
are initialized, (*x
< *y)
.
optional
has deep relational operators. Do not use operator
<
directly in generic code which
expect to be given either an optional<T>
or a pointer; use less_pointees()
instead.
T x(12); T y(34); optional<T> def ; optional<T> optX(x); optional<T> 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 ) ;
bool operator != ( optional<T> const& x, optional<T> const& y );
!(
x ==
y );
bool operator > ( optional<T> const& x, optional<T> const& y );
(
y <
x );
bool operator <= ( optional<T> const& x, optional<T> const& y );
!(
y <
x );
bool operator >= ( optional<T> const& x, optional<T> const& y );
!(
x<y );
bool operator == ( optional<T> const& x, none_t ) noexcept;
!x
.
T
need not meet requirements of EqualityComparable
.
bool operator != ( optional<T> const& x, none_t ) noexcept;
!(
x ==
y );
void swap ( optional<T>& x, optional<T>& y ) ;
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.
x
and y
interchanged.
swap(T&,T&)
throws. If only one is initialized, whatever T::T ( T&&
)
throws.
swap(T&,T&)
is used unqualified but with std::swap
introduced in scope. If only one is initialized, T::~T()
and T::T(
T&&
)
is called.
swap(T&,T&)
.
If only one is initialized, it has the same basic guarantee as optional<T>::operator= ( T&&
)
.
T x(12); T y(21); optional<T> def0 ; optional<T> def1 ; optional<T> optX(x); optional<T> optY(y); boost::swap(def0,def1); // no-op boost::swap(def0,optX); assert ( *def0 == x ); assert ( !optX ); boost::swap(def0,optX); // Get back to original values boost::swap(optX,optY); assert ( *optX == y ); assert ( *optY == x );