4 Copyright (c) 2003-2007 Fernando Luis Cacciola Carballal
6 Distributed under the Boost Software License, Version 1.0.
7 (See accompanying file LICENSE_1_0.txt or copy at
8 http://www.boost.org/LICENSE_1_0.txt)
12 [section Detailed Semantics - Optional Values]
15 The following section contains various `assert()` which are used only to show
16 the postconditions as sample code. It is not implied that the type `T` must
17 support each particular expression but that if the expression is supported,
18 the implied condition holds.
24 [#reference_optional_constructor]
26 [: `optional<T>::optional() noexcept;`]
28 * [*Effect:] Default-Constructs an `optional`.
29 * [*Postconditions:] `*this` is [_uninitialized].
30 * [*Notes:] T's default constructor [_is not] called.
39 [#reference_optional_constructor_none_t]
41 [: `optional<T>::optional( none_t ) noexcept;`]
43 * [*Effect:] Constructs an `optional` uninitialized.
44 * [*Postconditions:] `*this` is [_uninitialized].
45 * [*Notes:] `T`'s default constructor [_is not] called. The expression
46 `boost::none` denotes an instance of `boost::none_t` that can be used as
50 #include <boost/none.hpp>
57 [#reference_optional_constructor_value]
59 [: `optional<T>::optional( T const& v )`]
61 * [*Requires:] `is_copy_constructible<T>::value` is `true`.
62 * [*Effect:] Directly-Constructs an `optional`.
63 * [*Postconditions:] `*this` is [_initialized] and its value is a ['copy]
65 * [*Throws:] Whatever `T::T( T const& )` throws.
66 * [*Notes: ] `T::T( T const& )` is called.
67 * [*Exception Safety:] Exceptions can only be thrown during
68 `T::T( T const& );` in that case, this constructor has no effect.
73 assert ( *opt == v ) ;
79 [#reference_optional_constructor_move_value]
81 [: `optional<T>::optional( T&& v )`]
83 * [*Requires:] `is_move_constructible<T>::value` is `true`.
84 * [*Effect:] Directly-Move-Constructs an `optional`.
85 * [*Postconditions:] `*this` is [_initialized] and its value is move-constructed from `v`.
86 * [*Throws:] Whatever `T::T( T&& )` throws.
87 * [*Notes: ] `T::T( T&& )` is called.
88 * [*Exception Safety:] Exceptions can only be thrown during
89 `T::T( T&& );` in that case, the state of `v` is determined by exception safety guarantees for `T::T(T&&)`.
93 optional<T> opt(std::move(v1));
94 assert ( *opt == v2 ) ;
100 [#reference_optional_constructor_bool_value]
102 [: `optional<T>::optional( bool condition, T const& v ) ;` ]
104 * If condition is true, same as:
106 [: `optional<T>::optional( T const& v )`]
108 * otherwise, same as:
110 [: `optional<T>::optional()`]
115 [#reference_optional_constructor_optional]
117 [: `optional<T>::optional( optional const& rhs );`]
119 * [*Requires:] `is_copy_constructible<T>::value` is `true`.
120 * [*Effect:] Copy-Constructs an `optional`.
121 * [*Postconditions:] If rhs is initialized, `*this` is initialized and
122 its value is a ['copy] of the value of `rhs`; else `*this` is uninitialized.
123 * [*Throws:] Whatever `T::T( T const& )` throws.
124 * [*Notes:] If rhs is initialized, `T::T(T const& )` is called.
125 * [*Exception Safety:] Exceptions can only be thrown during
126 `T::T( T const& );` in that case, this constructor has no effect.
132 optional<T> uinit2 ( uninit ) ;
133 assert ( uninit2 == uninit );
135 optional<T> init( T(2) );
136 assert ( *init == T(2) ) ;
138 optional<T> init2 ( init ) ;
139 assert ( init2 == init ) ;
145 [#reference_optional_move_constructor_optional]
147 [: `optional<T>::optional( optional&& rhs ) noexcept(`['see below]`);`]
149 * [*Requires:] `is_move_constructible<T>::value` is `true`.
150 * [*Effect:] Move-constructs an `optional`.
151 * [*Postconditions:] If `rhs` is initialized, `*this` is initialized and
152 its value is move constructed from `rhs`; else `*this` is uninitialized.
153 * [*Throws:] Whatever `T::T( T&& )` throws.
154 * [*Remarks:] The expression inside `noexcept` is equivalent to `is_nothrow_move_constructible<T>::value`.
155 * [*Notes:] If `rhs` is initialized, `T::T( T && )` is called.
156 * [*Exception Safety:] Exceptions can only be thrown during
157 `T::T( T&& );` in that case, `rhs` remains initialized and the value of `*rhs` is determined by exception safety of `T::T(T&&)`.
160 optional<std::unique_ptr<T>> uninit ;
163 optional<std::unique_ptr<T>> uinit2 ( std::move(uninit) ) ;
164 assert ( uninit2 == uninit );
166 optional<std::unique_ptr<T>> init( std::uniqye_ptr<T>(new T(2)) );
167 assert ( **init == T(2) ) ;
169 optional<std::unique_ptr<T>> init2 ( std::move(init) ) ;
171 assert ( *init == nullptr );
173 assert ( **init2 == T(2) ) ;
179 [#reference_optional_constructor_other_optional]
181 [: `template<U> explicit optional<T>::optional( optional<U> const& rhs );`]
183 * [*Effect:] Copy-Constructs an `optional`.
184 * [*Postconditions:] If `rhs` is initialized, `*this` is initialized and its
185 value is a ['copy] of the value of rhs converted to type `T`; else `*this` is
187 * [*Throws:] Whatever `T::T( U const& )` throws.
188 * [*Notes: ] `T::T( U const& )` is called if `rhs` is initialized, which requires a
189 valid conversion from `U` to `T`.
190 * [*Exception Safety:] Exceptions can only be thrown during `T::T( U const& );`
191 in that case, this constructor has no effect.
194 optional<double> x(123.4);
195 assert ( *x == 123.4 ) ;
198 assert( *y == 123 ) ;
203 [#reference_optional_move_constructor_other_optional]
205 [: `template<U> explicit optional<T>::optional( optional<U>&& rhs );`]
207 * [*Effect:] Move-constructs an `optional`.
208 * [*Postconditions:] If `rhs` is initialized, `*this` is initialized and its
209 value is move-constructed from `*rhs`; else `*this` is
211 * [*Throws:] Whatever `T::T( U&& )` throws.
212 * [*Notes: ] `T::T( U&& )` is called if `rhs` is initialized, which requires a
213 valid conversion from `U` to `T`.
214 * [*Exception Safety:] Exceptions can only be thrown during `T::T( U&& );`
215 in that case, `rhs` remains initialized and the value of `*rhs` is determined by exception safety guarantee of `T::T( U&& )`.
218 optional<double> x(123.4);
219 assert ( *x == 123.4 ) ;
221 optional<int> y(std::move(x)) ;
222 assert( *y == 123 ) ;
227 [#reference_optional_in_place_init]
229 [: `template<class... Args> explicit optional<T>::optional( in_place_init_t, Args&&... ars );`]
231 * [*Requires:] `is_constructible_v<T, Args&&...>` is `true`.
232 * [*Effect:] Initializes the contained value as if direct-non-list-initializing an object of type `T` with the
233 arguments `std::forward<Args>(args)...`.
234 * [*Postconditions:] `*this` is initialized.
235 * [*Throws:] Any exception thrown by the selected constructor of `T`.
236 * [*Notes: ] `T` need not be __MOVE_CONSTRUCTIBLE__. On compilers that do not suppor variadic templates or rvalue references, this constuctor is available in limited functionality. For details [link optional_emplace_workaround see here].
240 // creates an std::mutex using its default constructor
241 optional<std::mutex> om {in_place_init};
244 // creates a unique_lock by calling unique_lock(*om, std::defer_lock)
245 optional<std::unique_lock<std::mutex>> ol {in_place_init, *om, std::defer_lock};
247 assert (!ol->owns_lock());
252 [#reference_optional_in_place_init_if]
254 [: `template<class... Args> explicit optional<T>::optional( in_place_init_if_t, bool condition, Args&&... ars );`]
256 * [*Requires:] `is_constructible_v<T, Args&&...>` is `true`.
257 * [*Effect:] If `condition` is `true`, initializes the contained value as if direct-non-list-initializing an object of type `T` with the arguments `std::forward<Args>(args)...`.
258 * [*Postconditions:] `bool(*this) == condition`.
259 * [*Throws:] Any exception thrown by the selected constructor of `T`.
260 * [*Notes: ] `T` need not be __MOVE_CONSTRUCTIBLE__. On compilers that do not suppor variadic templates or rvalue references, this constuctor is available in limited functionality. For details [link optional_emplace_workaround see here].
264 optional<std::vector<std::string>> ov1 {in_place_init_if, false, 3, "A"};
267 optional<std::vector<std::string>> ov2 {in_place_init_if, true, 3, "A"};
269 assert (ov2->size() == 3);
274 [#reference_optional_constructor_factory]
276 [: `template<InPlaceFactory> explicit optional<T>::optional( InPlaceFactory const& f );`]
277 [: `template<TypedInPlaceFactory> explicit optional<T>::optional( TypedInPlaceFactory const& f );`]
279 * [*Effect:] Constructs an `optional` with a value of `T` obtained from the
281 * [*Postconditions: ] `*this` is [_initialized] and its value is ['directly given]
282 from the factory `f` (i.e., the value [_is not copied]).
283 * [*Throws:] Whatever the `T` constructor called by the factory throws.
284 * [*Notes:] See [link boost_optional.tutorial.in_place_factories In-Place Factories]
285 * [*Exception Safety:] Exceptions can only be thrown during the call to
286 the `T` constructor used by the factory; in that case, this constructor has
290 class C { C ( char, double, std::string ) ; } ;
292 C v('A',123.4,"hello");
294 optional<C> x( in_place ('A', 123.4, "hello") ); // InPlaceFactory used
295 optional<C> y( in_place<C>('A', 123.4, "hello") ); // TypedInPlaceFactory used
303 [#reference_optional_operator_equal_none_t]
305 [: `optional& optional<T>::operator= ( none_t ) noexcept;`]
307 * [*Effect:] If `*this` is initialized destroys its contained value.
308 * [*Postconditions: ] `*this` is uninitialized.
312 [#reference_optional_operator_equal_value]
314 [: `optional& optional<T>::operator= ( T const& rhs ) ;`]
316 * [*Effect:] Assigns the value `rhs` to an `optional`.
317 * [*Postconditions: ] `*this` is initialized and its value is a ['copy] of `rhs`.
318 * [*Throws:] Whatever `T::operator=( T const& )` or `T::T(T const&)` throws.
319 * [*Notes:] If `*this` was initialized, `T`'s assignment operator is used,
320 otherwise, its copy-constructor is used.
321 * [*Exception Safety:] In the event of an exception, the initialization
322 state of `*this` is unchanged and its value unspecified as far as `optional`
323 is concerned (it is up to `T`'s `operator=()`). If `*this` is initially
324 uninitialized and `T`'s ['copy constructor] fails, `*this` is left properly
334 assert ( *def == y ) ;
336 assert ( *opt == y ) ;
342 [#reference_optional_operator_move_equal_value]
344 [: `optional& optional<T>::operator= ( T&& rhs ) ;`]
346 * [*Effect:] Moves the value `rhs` to an `optional`.
347 * [*Postconditions: ] `*this` is initialized and its value is moved from `rhs`.
348 * [*Throws:] Whatever `T::operator=( T&& )` or `T::T(T &&)` throws.
349 * [*Notes:] If `*this` was initialized, `T`'s move-assignment operator is used,
350 otherwise, its move-constructor is used.
351 * [*Exception Safety:] In the event of an exception, the initialization
352 state of `*this` is unchanged and its value unspecified as far as `optional`
353 is concerned (it is up to `T`'s `operator=()`). If `*this` is initially
354 uninitialized and `T`'s ['move constructor] fails, `*this` is left properly
363 def = std::move(y1) ;
364 assert ( *def == yR ) ;
365 opt = std::move(y2) ;
366 assert ( *opt == yR ) ;
372 [#reference_optional_operator_equal_optional]
374 [: `optional& optional<T>::operator= ( optional const& rhs ) ;`]
376 * [*Requires:] `T` is __COPY_CONSTRUCTIBLE__ and `CopyAssignable`.
380 [[][[*`*this` contains a value]][[*`*this` does not contain a value]]]
381 [[[*`rhs` contains a value]][assigns `*rhs` to the contained value][initializes the contained value as if direct-initializing an object of type `T` with `*rhs`]]
382 [[[*`rhs` does not contain a value]][destroys the contained value by calling `val->T::~T()`][no effect]]
384 * [*Returns:] `*this`;
385 * [*Postconditions:] `bool(rhs) == bool(*this)`.
386 * [*Exception Safety:] If any exception is thrown, the initialization state of `*this` and `rhs` remains unchanged.
387 If an exception is thrown during the call to `T`'s copy constructor, no effect.
388 If an exception is thrown during the call to `T`'s copy assignment, the state of its contained value is as defined by the exception safety guarantee of `T`'s copy assignment.
397 // previous value (copy of 'v') destroyed from within 'opt'.
403 [#reference_optional_operator_move_equal_optional]
405 [: `optional& optional<T>::operator= ( optional&& rhs ) noexcept(`['see below]`);`]
407 * [*Requires:] `T` is __MOVE_CONSTRUCTIBLE__ and `MoveAssignable`.
411 [[][[*`*this` contains a value]][[*`*this` does not contain a value]]]
412 [[[*`rhs` contains a value]][assigns `std::move(*rhs)` to the contained value][initializes the contained value as if direct-initializing an object of type `T` with `std::move(*rhs)`]]
413 [[[*`rhs` does not contain a value]][destroys the contained value by calling `val->T::~T()`][no effect]]
415 * [*Returns:] `*this`;
416 * [*Postconditions:] `bool(rhs) == bool(*this)`.
417 * [*Remarks:] The expression inside `noexcept` is equivalent to `is_nothrow_move_constructible<T>::value && is_nothrow_move_assignable<T>::value`.
418 * [*Exception Safety:] If any exception is thrown, the initialization state of `*this` and `rhs` remains unchanged. If an exception is
419 thrown during the call to `T`'s move constructor, the state of `*rhs` is determined by the exception safety guarantee
420 of `T`'s move constructor. If an exception is thrown during the call to T's move-assignment, the state of `**this` and `*rhs` is determined by the exception safety guarantee of T's move assignment.
423 optional<T> opt(T(2)) ;
429 assert ( *opt == T(2) ) ;
436 [#reference_optional_operator_equal_other_optional]
438 [: `template<U> optional& optional<T>::operator= ( optional<U> const& rhs ) ;`]
443 [[][[*`*this` contains a value]][[*`*this` does not contain a value]]]
444 [[[*`rhs` contains a value]][assigns `*rhs` to the contained value][initializes the contained value as if direct-initializing an object of type `T` with `*rhs`]]
445 [[[*`rhs` does not contain a value]][destroys the contained value by calling `val->T::~T()`][no effect]]
447 * [*Returns:] `*this`.
448 * [*Postconditions:] `bool(rhs) == bool(*this)`.
449 * [*Exception Safety:] If any exception is thrown, the result of the expression `bool(*this)` remains unchanged.
450 If an exception is thrown during the call to `T`'s constructor, no effect.
451 If an exception is thrown during the call to `T`'s assignment, the state of its contained value is as defined by the exception safety guarantee of `T`'s copy assignment.
459 assert ( *opt1 == static_cast<U>(v) ) ;
464 [#reference_optional_operator_move_equal_other_optional]
466 [: `template<U> optional& optional<T>::operator= ( optional<U>&& rhs ) ;`]
471 [[][[*`*this` contains a value]][[*`*this` does not contain a value]]]
472 [[[*`rhs` contains a value]][assigns `std::move(*rhs)` to the contained value][initializes the contained value as if direct-initializing an object of type `T` with `std::move(*rhs)`]]
473 [[[*`rhs` does not contain a value]][destroys the contained value by calling `val->T::~T()`][no effect]]
475 * [*Returns:] `*this`.
476 * [*Postconditions:] `bool(rhs) == bool(*this)`.
477 * [*Exception Safety:] If any exception is thrown, the result of the expression `bool(*this)` remains unchanged.
478 If an exception is thrown during the call to `T`'s constructor, no effect.
479 If an exception is thrown during the call to `T`'s assignment, the state of its contained value is as defined by the exception safety guarantee of `T`'s copy assignment.
486 opt1 = std::move(opt0) ;
489 assert ( *opt1 == static_cast<U>(v) ) ;
494 [#reference_optional_emplace]
496 [: `template<class... Args> void optional<T>::emplace( Args&&... args );`]
498 * [*Requires:] The compiler supports rvalue references and variadic templates.
499 * [*Effect:] If `*this` is initialized calls `*this = none`.
500 Then initializes in-place the contained value as if direct-initializing an object
501 of type `T` with `std::forward<Args>(args)...`.
502 * [*Postconditions: ] `*this` is [_initialized].
503 * [*Throws:] Whatever the selected `T`'s constructor throws.
504 * [*Exception Safety:] If an exception is thrown during the initialization of `T`, `*this` is ['uninitialized].
505 * [*Notes:] `T` need not be __MOVE_CONSTRUCTIBLE__ or `MoveAssignable`. On compilers that do not suppor variadic templates or rvalue references, this function is available in limited functionality. For details [link optional_emplace_workaround see here].
509 optional<const T> opt;
510 opt.emplace(0); // create in-place using ctor T(int)
511 opt.emplace(); // destroy previous and default-construct another T
512 opt.emplace(v); // destroy and copy-construct in-place (no assignment called)
517 [#reference_optional_operator_equal_factory]
519 [: `template<InPlaceFactory> optional<T>& optional<T>::operator=( InPlaceFactory const& f );`]
520 [: `template<TypedInPlaceFactory> optional<T>& optional<T>::operator=( TypedInPlaceFactory const& f );`]
522 * [*Effect:] Assigns an `optional` with a value of `T` obtained from the
524 * [*Postconditions: ] `*this` is [_initialized] and its value is ['directly given]
525 from the factory `f` (i.e., the value [_is not copied]).
526 * [*Throws:] Whatever the `T` constructor called by the factory throws.
527 * [*Notes:] See [link boost_optional.tutorial.in_place_factories In-Place Factories]
528 * [*Exception Safety:] Exceptions can only be thrown during the call to
529 the `T` constructor used by the factory; in that case, the `optional` object
530 will be reset to be ['uninitialized].
534 [#reference_optional_reset_value]
536 [: `void optional<T>::reset( T const& v ) ;`]
537 * [*Deprecated:] same as `operator= ( T const& v) ;`
541 [#reference_optional_reset]
543 [: `void optional<T>::reset() noexcept ;`]
544 * [*Deprecated:] Same as `operator=( none_t );`
548 [#reference_optional_get]
550 [: `T const& optional<T>::get() const ;`]
551 [: `T& optional<T>::get() ;`]
553 [: `inline T const& get ( optional<T> const& ) ;`]
554 [: `inline T& get ( optional<T> &) ;`]
556 * [*Requires:] `*this` is initialized
557 * [*Returns:] A reference to the contained value
558 * [*Throws:] Nothing.
559 * [*Notes:] The requirement is asserted via `BOOST_ASSERT()`.
564 [#reference_optional_operator_asterisk]
566 [: `T const& optional<T>::operator*() const& ;`]
567 [: `T& optional<T>::operator*() &;`]
569 * [*Requires:] `*this` is initialized
570 * [*Returns:] A reference to the contained value
571 * [*Throws:] Nothing.
572 * [*Notes:] The requirement is asserted via `BOOST_ASSERT()`. On compilers that do not support ref-qualifiers on member functions these two overloads are replaced with the classical two: a `const` and non-`const` member functions.
576 optional<T> opt ( v );
581 assert ( *opt == w ) ;
586 [#reference_optional_operator_asterisk_move]
588 [: `T&& optional<T>::operator*() &&;`]
590 * [*Requires:] `*this` contains a value.
591 * [*Effects:] Equivalent to `return std::move(*val);`.
592 * [*Notes:] The requirement is asserted via `BOOST_ASSERT()`. On compilers that do not support ref-qualifiers on member functions this overload is not present.
597 [#reference_optional_value]
599 [: `T const& optional<T>::value() const& ;`]
600 [: `T& optional<T>::value() & ;`]
602 * [*Effects:] Equivalent to `return bool(*this) ? *val : throw bad_optional_access();`.
603 * [*Notes:] On compilers that do not support ref-qualifiers on member functions these two overloads are replaced with the classical two: a `const` and non-`const` member functions.
607 optional<T> o0, o1 ( v );
608 assert ( o1.value() == v );
611 o0.value(); // throws
614 catch(bad_optional_access&) {
621 [#reference_optional_value_move]
623 [: `T&& optional<T>::value() && ;`]
625 * [*Effects:] Equivalent to `return bool(*this) ? std::move(*val) : throw bad_optional_access();`.
626 * [*Notes:] On compilers that do not support ref-qualifiers on member functions this overload is not present.
631 [#reference_optional_value_or]
633 [: `template<class U> T optional<T>::value_or(U && v) const& ;`]
635 * [*Effects:] Equivalent to `if (*this) return **this; else return std::forward<U>(v);`.
636 * [*Remarks:] If `T` is not __COPY_CONSTRUCTIBLE__ or `U &&` is not convertible to `T`, the program is ill-formed.
637 * [*Notes:] On compilers that do not support ref-qualifiers on member functions this overload is replaced with the `const`-qualified member function. On compilers without rvalue reference support the type of `v` becomes `U const&`.
641 [#reference_optional_value_or_move]
643 [: `template<class U> T optional<T>::value_or(U && v) && ;`]
645 * [*Effects:] Equivalent to `if (*this) return std::move(**this); else return std::forward<U>(v);`.
646 * [*Remarks:] If `T` is not __MOVE_CONSTRUCTIBLE__ or `U &&` is not convertible to `T`, the program is ill-formed.
647 * [*Notes:] On compilers that do not support ref-qualifiers on member functions this overload is not present.
651 [#reference_optional_value_or_call]
653 [: `template<class F> T optional<T>::value_or_eval(F f) const& ;`]
655 * [*Requires:] `T` is __COPY_CONSTRUCTIBLE__ and `F` models a __SGI_GENERATOR__ whose result type is convertible to `T`.
656 * [*Effects:] `if (*this) return **this; else return f();`.
657 * [*Notes:] On compilers that do not support ref-qualifiers on member functions this overload is replaced with the `const`-qualified member function.
662 clog << "no value returned, using default" << endl;
666 optional<int> o1 = 1;
667 optional<int> oN = none;
669 int i = o1.value_or_eval(complain_and_0); // fun not called
672 int j = oN.value_or_eval(complain_and_0); // fun called
678 [#reference_optional_value_or_call_move]
680 [: `template<class F> T optional<T>::value_or_eval(F f) && ;`]
682 * [*Requires:] `T` is __MOVE_CONSTRUCTIBLE__ and `F` models a __SGI_GENERATOR__ whose result type is convertible to `T`.
683 * [*Effects:] `if (*this) return std::move(**this); else return f();`.
684 * [*Notes:] On compilers that do not support ref-qualifiers on member functions this overload is not present.
688 [#reference_optional_get_value_or_value]
690 [: `T const& optional<T>::get_value_or( T const& default) const ;`]
691 [: `T& optional<T>::get_value_or( T& default ) ;`]
693 * [*Deprecated:] Use `value_or()` instead.
694 * [*Returns:] A reference to the contained value, if any, or `default`.
695 * [*Throws:] Nothing.
700 T const& y = def.get_value_or(z);
703 optional<T> opt ( v );
704 T const& u = opt.get_value_or(z);
712 [#reference_optional_get_ptr]
714 [: `T const* optional<T>::get_ptr() const ;`]
715 [: `T* optional<T>::get_ptr() ;`]
717 * [*Returns:] If `*this` is initialized, a pointer to the contained value;
719 * [*Throws:] Nothing.
720 * [*Notes:] The contained value is permanently stored within `*this`, so you
721 should not hold nor delete this pointer
726 optional<T> const copt(v);
727 T* p = opt.get_ptr() ;
728 T const* cp = copt.get_ptr();
729 assert ( p == get_pointer(opt) );
730 assert ( cp == get_pointer(copt) ) ;
735 [#reference_optional_operator_arrow]
737 [: `T const* optional<T>::operator ->() const ;`]
738 [: `T* optional<T>::operator ->() ;`]
740 * [*Requires: ] `*this` is initialized.
741 * [*Returns:] A pointer to the contained value.
742 * [*Throws:] Nothing.
743 * [*Notes:] The requirement is asserted via `BOOST_ASSERT()`.
746 struct X { int mdata ; } ;
754 [#reference_optional_operator_bool]
756 [: `explicit optional<T>::operator bool() const noexcept ;`]
758 * [*Returns:] `get_ptr() != 0`.
759 * [*Notes:] On compilers that do not support explicit conversion operators this falls back to safe-bool idiom.
764 optional<T> opt ( v ) ;
771 [#reference_optional_operator_not]
773 [: `bool optional<T>::operator!() noexcept ;`]
775 * [*Returns:] If `*this` is uninitialized, `true`; else `false`.
776 * [*Notes:] This operator is provided for those compilers which can't
777 use the ['unspecified-bool-type operator] in certain boolean contexts.
784 // Notice the "double-bang" idiom here.
790 [#reference_optional_is_initialized]
792 [: `bool optional<T>::is_initialized() const ;`]
794 * [*Deprecated:] Same as `explicit operator bool () ;`
799 [section Detailed Semantics - Optional References]
803 [#reference_optional_ref_default_ctor]
805 [: `optional<T&>::optional() noexcept;`]
806 [: `optional<T&>::optional(none_t) noexcept;`]
808 * [*Postconditions:] `bool(*this) == false`; `*this` refers to nothing.
813 [#reference_optional_ref_value_ctor]
815 [: `template<class R> optional<T&>::optional(R&& r) noexcept;`]
816 * [*Postconditions:] `bool(*this) == true`; `addressof(**this) == addressof(r)`.
817 * [*Remarks:] Unless `R` is an lvalue reference, the program is ill-formed. This constructor does not participate in overload resolution if `decay<R>` is an instance of `boost::optional`.
818 * [*Notes:] This constructor is declared `explicit` on compilers that do not correctly suport binding to const lvalues of integral types. For more details [link optional_reference_binding see here].
823 optional<T&> opt(vref);
824 assert ( *opt == v ) ;
825 ++ v ; // mutate referee
831 [#reference_optional_ref_cond_value_ctor]
833 [: `template<class R> optional<T&>::optional(bool cond, R&& r) noexcept;`]
834 * [*Effects: ] Initializes `ref` with expression `cond ? addressof(r) : nullptr`.
835 * [*Postconditions:] `bool(*this) == cond`; If `bool(*this)`, `addressof(**this) == addressof(r)`.
836 * [*Remarks:] Unless `R` is an lvalue reference, the program is ill-formed. This constructor does not participate in overload resolution if `decay<R>` is an instance of `boost::optional`.
840 [#reference_optional_ref_copy_ctor]
842 [: `optional<T&>::optional ( optional const& rhs ) noexcept ;`]
844 * [*Effects: ] Initializes `ref` with expression `rhs.ref`.
846 * [*Postconditions:] `bool(*this) == bool(rhs)`.
850 optional<T&> uninit ;
853 optional<T&> uinit2 ( uninit ) ;
854 assert ( uninit2 == uninit );
856 T v = 2 ; T& ref = v ;
857 optional<T> init(ref);
858 assert ( *init == v ) ;
860 optional<T> init2 ( init ) ;
861 assert ( *init2 == v ) ;
865 assert ( *init == 3 ) ;
866 assert ( *init2 == 3 ) ;
871 [#reference_optional_ref_ctor_from_opt_U]
873 [: `template<class U> explicit optional<T&>::optional ( optional<U&> const& rhs ) noexcept ;`]
875 * [*Requires:] `is_convertible<U&, T&>::value` is `true`.
877 * [*Effects: ] Initializes `ref` with expression `rhs.ref`.
879 * [*Postconditions:] `bool(*this) == bool(rhs)`.
884 [#reference_optional_ref_assign_none_t]
886 [: `optional<T&>::operator= ( none_t ) noexcept ;`]
888 * [*Effects: ] Assigns `ref` with expression `nullptr`.
890 * [*returns:] `*this`.
892 * [*Postconditions:] `bool(*this) == false`.
896 [#reference_optional_ref_copy_assign]
898 [: `optional& optional<T&>::operator= ( optional const& rhs ) noexcept ;`]
900 * [*Effects: ] Assigns `ref` with expression `rhs.ref`.
902 * [*returns:] `*this`.
904 * [*Postconditions:] `bool(*this) == bool(rhs)`.
906 * [*Notes:] This behaviour is called ['rebinding semantics]. See [link boost_optional.tutorial.optional_references.rebinding_semantics_for_assignment_of_optional_references here] for details.
915 optional<int&> ora(ra) ;
916 optional<int&> orb(rb) ;
918 def = orb ; // binds 'def' to 'b' through 'rb' wrapped within 'orb'
919 assert ( *def == b ) ;
920 *def = ora ; // changes the value of 'b' to a copy of the value of 'a'
924 optional<int&> orc(rc) ;
925 ora = orc ; // REBINDS ora to 'c' through 'rc'
927 assert ( *ora == 4 ) ;
931 [#reference_optional_ref_assign_optional_U]
933 [: `template<class U> optional& optional<T&>::operator= ( optional<U&> const& rhs ) noexcept ;`]
935 * [*Requires:] `is_convertible<U&, T&>::value` is `true`.
937 * [*Effects: ] Assigns `ref` with expression `rhs.ref`.
939 * [*returns:] `*this`.
941 * [*Postconditions:] `bool(*this) == bool(rhs)`.
946 [#reference_optional_ref_assign_R]
948 [: `template<class R> optional& optional<T&>::operator= ( R&& r ) noexcept ;`]
950 * [*Effects: ] Assigns `ref` with expression `r`.
952 * [*returns:] `*this`.
954 * [*Postconditions:] `bool(*this) == true`.
956 * [*Remarks:] Unless `R` is an lvalue reference, the program is ill-formed. This function does not participate in overload resolution if `decay<R>` is an instance of `boost::optional`.
965 optional<int&> opt(ra) ;
967 def = rb ; // binds 'def' to 'b' through 'rb'
968 assert ( *def == b ) ;
969 *def = a ; // changes the value of 'b' to a copy of the value of 'a'
973 opt = rc ; // REBINDS to 'c' through 'rc'
975 assert ( *opt == 4 ) ;
980 [#reference_optional_ref_emplace_R]
982 [: `void optional<T&>::emplace( R&& r ) noexcept ;`]
983 * [*Effects: ] Assigns `ref` with expression `r`.
984 * [*Postconditions:] `bool(*this) == true`.
985 * [*Remarks:] Unless `R` is an lvalue reference, the program is ill-formed. This function does not participate in overload resolution if `decay<R>` is an instance of `boost::optional`.
989 [#reference_optional_ref_get]
990 [: `T& optional<T&>::get() const ;`]
991 [: `T& optional<T&>::operator *() const ;`]
992 * [*Requires:] `bool(*this) == true`.
993 * [*Effects: ] Returns `*ref`.
994 * [*Throws: ] Nothing.
999 optional<T&> opt ( vref );
1000 T const& vref2 = *opt;
1001 assert ( vref2 == v ) ;
1003 assert ( *opt == v ) ;
1008 [#reference_optional_ref_arrow]
1009 [: `T* optional<T&>::operator -> () const ;`]
1010 * [*Requires:] `bool(*this) == true`.
1011 * [*Effects: ] Returns `ref`.
1012 * [*Throws: ] Nothing.
1016 [#reference_optional_ref_value]
1017 [: `T& optional<T&>::value() const ;`]
1018 * [*Effects:] Equivalent to `return bool(*this) ? *val : throw bad_optional_access();`.
1022 [#reference_optional_ref_value_or]
1023 [: `template<class R> T& optional<T&>::value_or( R&& r ) const noexcept;`]
1024 * [*Effects:] Equivalent to `if (*this) return **this; else return r;`.
1025 * [*Remarks:] Unless `R` is an lvalue reference, the program is ill-formed.
1029 [#reference_optional_ref_value_or_eval]
1030 [: `template<class F> T& optional<T&>::value_or( F f ) const ;`]
1031 * [*Effects:] Equivalent to `if (*this) return **this; else return f();`.
1032 * [*Remarks:] Unless `decltype(f())` is an lvalue reference, the program is ill-formed.
1036 [#reference_optional_ref_get_ptr]
1037 [: `T* optional<T&>::get_ptr () const noexcept;`]
1038 * [*Returns:] `ref`.
1042 [#reference_optional_ref_operator_bool]
1043 [: `optional<T&>::operator bool () const noexcept;`]
1044 * [*Returns:] `bool(ref)`.
1048 [#reference_optional_ref_operator_not]
1049 [: `optional<T&>::operator ! () const noexcept;`]
1050 * [*Returns:] `!bool(ref)`.
1054 [#reference_optional_ref_reset]
1055 [: `void optional<T&>::reset() noexcept;`]
1056 * [*Effects:] Use `*this = none` instead.
1057 * [*Remarks:] This function is depprecated.
1061 [#reference_optional_ref_reset_value]
1062 [: `template<class R> void optional<T&>::reset ( R&& r) noexcept;`]
1063 * [*Effects:] Equivalent to `*this = std::forward<R>(r)`.
1064 * [*Remarks:] This function is depprecated.
1068 [#reference_optional_ref_is_initialized]
1069 [: `bool optional<T&>::is_initialized() const noexcept;`]
1070 * [*Effects:] Equivalent to `return bool(*this)`.
1071 * [*Remarks:] This function is depprecated.
1075 [#reference_optional_ref_get_value_or_value]
1076 [: `template<class R> T& optional<T&>::get_value_or( R&& r ) const noexcept;`]
1077 * [*Effects:] Equivalent to `return value_or(std::forward<R>(r);`.
1078 * [*Remarks:] This function is depprecated.
1083 [section Detailed Semantics - Free Functions]
1088 [#reference_make_optional_value]
1090 [: `optional<T> make_optional( T const& v )`]
1092 * [*Returns: ] `optional<T>(v)` for the ['deduced] type `T` of `v`.
1095 template<class T> void foo ( optional<T> const& opt ) ;
1097 foo ( make_optional(1+1) ) ; // Creates an optional<int>
1102 [#reference_make_optional_bool_value]
1104 [: `optional<T> make_optional( bool condition, T const& v )`]
1106 * [*Returns: ] `optional<T>(condition, v)` for the ['deduced] type `T` of `v`.
1109 optional<double> calculate_foo()
1111 double val = compute_foo();
1112 return make_optional(is_not_nan_and_finite(val),val);
1115 optional<double> v = calculate_foo();
1117 error("foo wasn't computed");
1122 [#reference_operator_compare_equal_optional_optional]
1124 [: `bool operator == ( optional<T> const& x, optional<T> const& y );`]
1126 * [*Requires:] `T` shall meet requirements of __SGI_EQUALITY_COMPARABLE__.
1127 * [*Returns:] If both `x` and `y` are initialized, `(*x == *y)`. If only
1128 `x` or `y` is initialized, `false`. If both are uninitialized, `true`.
1129 * [*Notes:] This definition guarantees that `optional<T>` not containing a value is compared unequal to any `optional<T>` containing any value, and equal to any other `optional<T>` not containing a value.
1130 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<T>` or a pointer; use
1131 __FUNCTION_EQUAL_POINTEES__ instead
1134 optional<T> oN, oN_;
1135 optional<T> o1(T(1)), o1_(T(1));
1136 optional<T> o2(T(2));
1138 assert ( oN == oN ); // Identity implies equality
1139 assert ( o1 == o1 ); //
1141 assert ( oN == oN_ ); // Both uninitialized compare equal
1143 assert ( oN != o1 ); // Initialized unequal to initialized.
1145 assert ( o1 == o1_ ); // Both initialized compare as (*lhs == *rhs)
1146 assert ( o1 != o2 ); //
1151 [#reference_operator_compare_less_optional_optional]
1153 [: `bool operator < ( optional<T> const& x, optional<T> const& y );`]
1155 * [*Requires:] Expression `*x < *y` shall be well-formed and its result shall be convertible to `bool`.
1156 * [*Returns:] `(!y) ? false : (!x) ? true : *x < *y`.
1157 * [*Notes:] This definition guarantees that `optional<T>` not containing a value is ordered as less than any `optional<T>` containing any value, and equivalent to any other `optional<T>` not containing a value.
1158 Pointers have shallow relational operators while `optional` has deep relational operators. Do not use `operator<` directly in generic code
1159 which expect to be given either an `optional<T>` or a pointer; use __FUNCTION_LESS_POINTEES__ instead. `T` need not be __SGI_LESS_THAN_COMPARABLE__. Only single `operator<` is required. Other relational operations are defined in terms of this one. If `T`'s `operator<` satisfies the axioms of __SGI_LESS_THAN_COMPARABLE__ (transitivity, antisymmetry and irreflexivity), `optinal<T>` is __SGI_LESS_THAN_COMPARABLE__.
1162 optional<T> oN, oN_;
1163 optional<T> o0(T(0));
1164 optional<T> o1(T(1));
1166 assert ( !(oN < oN) ); // Identity implies equivalence
1167 assert ( !(o1 < o1) );
1169 assert ( !(oN < oN_) ); // Two uninitialized are equivalent
1170 assert ( !(oN_ < oN) );
1172 assert ( oN < o0 ); // Uninitialized is less than initialized
1173 assert ( !(o0 < oN) );
1175 assert ( o1 < o2 ) ; // Two initialized compare as (*lhs < *rhs)
1176 assert ( !(o2 < o1) ) ;
1177 assert ( !(o2 < o2) ) ;
1182 [#reference_operator_compare_not_equal_optional_optional]
1184 [: `bool operator != ( optional<T> const& x, optional<T> const& y );`]
1186 * [*Returns: ] `!( x == y );`
1190 [#reference_operator_compare_greater_optional_optional]
1192 [: `bool operator > ( optional<T> const& x, optional<T> const& y );`]
1194 * [*Returns: ] `( y < x );`
1198 [#reference_operator_compare_less_or_equal_optional_optional]
1200 [: `bool operator <= ( optional<T> const& x, optional<T> const& y );`]
1202 * [*Returns: ] `!( y < x );`
1206 [#reference_operator_compare_greater_or_equal_optional_optional]
1208 [: `bool operator >= ( optional<T> const& x, optional<T> const& y );`]
1210 * [*Returns: ] `!( x < y );`
1214 [#reference_operator_compare_equal_optional_none]
1216 [: `bool operator == ( optional<T> const& x, none_t ) noexcept;`]
1217 [: `bool operator == ( none_t, optional<T> const& x ) noexcept;`]
1220 * [*Notes:] `T` need not meet requirements of __SGI_EQUALITY_COMPARABLE__.
1225 [#reference_operator_compare_not_equal_optional_none]
1227 [: `bool operator != ( optional<T> const& x, none_t ) noexcept;`]
1228 [: `bool operator != ( none_t, optional<T> const& x ) noexcept;`]
1230 * [*Returns: ] `bool(x);`
1236 [#reference_free_get_pointer]
1237 [: `auto get_pointer ( optional<T>& o ) -> typename optional<T>::pointer_type ;`]
1238 [: `auto get_pointer ( optional<T> const& o ) -> typename optional<T>::pointer_const_type ;`]
1239 * [*Returns:] `o.get_ptr()`.
1240 * [*Throws:] Nothing.
1245 [#reference_free_get_value_or]
1246 [: `auto get_optional_value_or ( optional<T>& o, typename optional<T>::reference_type def ) -> typename optional<T>::reference_type ;`]
1247 [: `auto get_optional_value_or ( optional<T> const& o, typename optional<T>::reference_const_type def ) -> typename optional<T>::reference_const_type ;`]
1248 * [*Returns:] `o.get_value_or(def)`.
1249 * [*Throws:] Nothing.
1250 * [*Remarks:] This function is deprecated.
1254 [#reference_swap_optional_optional]
1256 [: `void swap ( optional<T>& x, optional<T>& y ) ;`]
1258 * [*Requires:] Lvalues of type `T` shall be swappable and `T` shall be __MOVE_CONSTRUCTIBLE__.
1262 [[][[*`*this` contains a value]][[*`*this` does not contain a value]]]
1263 [[[*`rhs` contains a value]][calls `swap(*(*this), *rhs)`][initializes the contained value of `*this` as if direct-initializing an object of type `T` with the expression `std::move(*rhs)`, followed by `rhs.val->T::~T()`, `*this` contains a value and `rhs` does not contain a value]]
1264 [[[*`rhs` does not contain a value]][initializes the contained value of `rhs` as if direct-initializing an object of type `T` with the expression `std::move(*(*this))`, followed by `val->T::~T()`, `*this` does not contain a value and `rhs` contains a value][no effect]]
1266 * [*Postconditions:] The states of `x` and `y` interchanged.
1267 * [*Throws:] If both are initialized, whatever `swap(T&,T&)` throws. If only
1268 one is initialized, whatever `T::T ( T&& )` throws.
1275 optional<T> optX(x);
1276 optional<T> optY(y);
1278 boost::swap(def0,def1); // no-op
1280 boost::swap(def0,optX);
1281 assert ( *def0 == x );
1284 boost::swap(def0,optX); // Get back to original values
1286 boost::swap(optX,optY);
1287 assert ( *optX == y );
1288 assert ( *optY == x );
1293 [#reference_swap_optional_reference]
1294 [: `void swap ( optional<T&>& x, optional<T&>& y ) noexcept ;`]
1296 * [*Postconditions:] `x` refers to what `y` refererred to before the swap (if anything). `y` refers to whatever `x` referred to before the swap.
1304 optional<T&> optX (x);
1305 optional<T&> optY (y);
1307 boost::swap(optX, optY);
1308 assert (addressof(*optX) == addressof(y));
1309 assert (addressof(*optY) == addressof(x));
1311 boost::swap(opt0, optX);
1314 assert (addressof(*opt0) == addressof(y));