diff --git a/doc/00_optional.qbk b/doc/00_optional.qbk index b99f8dc5..2381794e 100644 --- a/doc/00_optional.qbk +++ b/doc/00_optional.qbk @@ -2,7 +2,7 @@ [quickbook 1.4] [authors [Cacciola Carballal, Fernando Luis]] [copyright 2003-2007 Fernando Luis Cacciola Carballal] - [copyright 2014-2023 Andrzej Krzemieński] + [copyright 2014-2024 Andrzej Krzemieński] [category miscellaneous] [id optional] [dirname optional] @@ -47,7 +47,7 @@ Distributed under the Boost Software License, Version 1.0. [/ Icons ] [def __SPACE__ [$images/space.png]] -[def __GO_TO__ [$images/callouts/R.png]] +[def __GO_TO__ [$images/R.png]] [section Introduction] diff --git a/doc/Jamfile.v2 b/doc/Jamfile.v2 index 91af84f3..c33abf8f 100644 --- a/doc/Jamfile.v2 +++ b/doc/Jamfile.v2 @@ -26,6 +26,8 @@ install images images/opt_align2.png images/opt_align3.png images/opt_align4.png + images/R.png + images/space.png : html/images ; @@ -38,7 +40,7 @@ boostbook standalone html:"boost.libraries=../../../../libs/libraries.htm" "chapter.autolabel=0" "chunk.section.depth=8" - "toc.section.depth=2" + "toc.section.depth=1" "toc.max.depth=2" "generate.section.toc.level=1" pdf:"img.src.path=$(images)/" diff --git a/doc/html/boost_optional/a_note_about_optional_bool_.html b/doc/html/boost_optional/a_note_about_optional_bool_.html deleted file mode 100644 index 64f37f68..00000000 --- a/doc/html/boost_optional/a_note_about_optional_bool_.html +++ /dev/null @@ -1,108 +0,0 @@ - - - -A note about optional<bool> - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- optional<bool> should - be used with special caution and consideration. -

-

- First, it is functionally similar to a tristate boolean (false, maybe, true) - —such as boost::tribool— - except that in a tristate boolean, 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, although optional<> - provides a contextual conversion to bool - in C++11, this falls back to an implicit conversion on older compilers. 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: -

-
void foo ( bool v ) ;
-void bar()
-{
-    optional<bool> v = try();
-
-    // The following intended to pass the value of 'v' to foo():
-    foo(v);
-    // But instead, the initialization state is passed
-    // due to a typo: it should have been foo(*v).
-}
-
-

- The only implicit conversion is to bool, - and it is safe in the sense that typical integral promotions don't apply (i.e. - if foo() - takes an int instead, it won't - compile). -

-

- Third, mixed comparisons with bool - work differently than similar mixed comparisons between pointers and bool, so the results might surprise you: -

-
optional<bool> oEmpty(none), oTrue(true), oFalse(false);
-
-if (oEmpty == none);  // renders true
-if (oEmpty == false); // renders false!
-if (oEmpty == true);  // renders false!
-
-if (oFalse == none);  // renders false
-if (oFalse == false); // renders true!
-if (oFalse == true);  // renders false
-
-if (oTrue == none);   // renders false
-if (oTrue == false);  // renders false
-if (oTrue == true);   // renders true
-
-

- In other words, for optional<>, the following assertion does not hold: -

-
assert((opt == false) == (!opt));
-
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/acknowledgements.html b/doc/html/boost_optional/acknowledgements.html deleted file mode 100644 index 54195804..00000000 --- a/doc/html/boost_optional/acknowledgements.html +++ /dev/null @@ -1,130 +0,0 @@ - - - -Acknowledgements - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHome -
-
-
-

- - Pre-formal - review -

-
    -
  • - Peter Dimov suggested the name 'optional', and was the first to point out - the need for aligned storage. -
    • -
  • - Douglas Gregor developed 'type_with_alignment', and later Eric Friedman - coded 'aligned_storage', which are the core of the optional class implementation. -
    • -
  • - Andrei Alexandrescu and Brian Parker also worked with aligned storage techniques - and their work influenced the current implementation. -
    • -
  • - Gennadiy Rozental made extensive and important comments which shaped the - design. -
    • -
  • - Vesa Karvonen and Douglas Gregor made quite useful comparisons between - optional, variant and any; and made other relevant comments. -
    • -
  • - Douglas Gregor and Peter Dimov commented on comparisons and evaluation - in boolean contexts. -
    • -
  • - Eric Friedman helped understand the issues involved with aligned storage, - move/copy operations and exception safety. -
    • -
  • - Many others have participated with useful comments: Aleksey Gurotov, Kevlin - Henney, David Abrahams, and others I can't recall. -
    • -
-

- - Post-formal - review -

-
    -
  • - William Kempf carefully considered the originally proposed interface and - suggested the new interface which is currently used. He also started and - fueled the discussion about the analogy optional<>/smart pointer - and about relational operators. -
    • -
  • - Peter Dimov, Joel de Guzman, David Abrahams, Tanton Gibbs and Ian Hanson - focused on the relational semantics of optional (originally undefined); - concluding with the fact that the pointer-like interface doesn't make it - a pointer so it shall have deep relational operators. -
    • -
  • - Augustus Saunders also explored the different relational semantics between - optional<> and a pointer and developed the OptionalPointee concept - as an aid against potential conflicts on generic code. -
    • -
  • - Joel de Guzman noticed that optional<> can be seen as an API on top - of variant<T,nil_t>. -
    • -
  • - Dave Gomboc explained the meaning and usage of the Haskell analog to optional<>: - the Maybe type constructor (analogy originally pointed out by David Sankel). -
    • -
  • - Other comments were posted by Vincent Finn, Anthony Williams, Ed Brey, - Rob Stewart, and others. -
    • -
  • - Joel de Guzman made the case for the support of references and helped with - the proper semantics. -
    • -
  • - Mat Marcus shown the virtues of a value-oriented interface, influencing - the current design, and contributed the idea of "none". -
    • -
  • - Vladimir Batov's design of Boost.Convert library motivated the development - of value accessors for optional: - functions value, value_or, value_or_eval. -
    • -
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHome -
- - diff --git a/doc/html/boost_optional/acknowledgments.html b/doc/html/boost_optional/acknowledgments.html deleted file mode 100644 index b09cf6e1..00000000 --- a/doc/html/boost_optional/acknowledgments.html +++ /dev/null @@ -1,125 +0,0 @@ - - - -Acknowledgments - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHome -
-
-
-

- - Pre-formal - review -

-
    -
  • - Peter Dimov suggested the name 'optional', and was the first to point out - the need for aligned storage. -
    • -
  • - Douglas Gregor developed 'type_with_alignment', and later Eric Friedman - coded 'aligned_storage', which are the core of the optional class implementation. -
    • -
  • - Andrei Alexandrescu and Brian Parker also worked with aligned storage techniques - and their work influenced the current implementation. -
    • -
  • - Gennadiy Rozental made extensive and important comments which shaped the - design. -
    • -
  • - Vesa Karvonen and Douglas Gregor made quite useful comparisons between - optional, variant and any; and made other relevant comments. -
    • -
  • - Douglas Gregor and Peter Dimov commented on comparisons and evaluation - in boolean contexts. -
    • -
  • - Eric Friedman helped understand the issues involved with aligned storage, - move/copy operations and exception safety. -
    • -
  • - Many others have participated with useful comments: Aleksey Gurotov, Kevlin - Henney, David Abrahams, and others I can't recall. -
    • -
-

- - Post-formal - review -

-
    -
  • - William Kempf carefully considered the originally proposed interface and - suggested the new interface which is currently used. He also started and - fueled the discussion about the analogy optional<>/smart pointer - and about relational operators. -
    • -
  • - Peter Dimov, Joel de Guzman, David Abrahams, Tanton Gibbs and Ian Hanson - focused on the relational semantics of optional (originally undefined); - concluding with the fact that the pointer-like interface doesn't make it - a pointer so it shall have deep relational operators. -
    • -
  • - Augustus Saunders also explored the different relational semantics between - optional<> and a pointer and developed the OptionalPointee concept - as an aid against potential conflicts on generic code. -
    • -
  • - Joel de Guzman noticed that optional<> can be seen as an API on top - of variant<T,nil_t>. -
    • -
  • - Dave Gomboc explained the meaning and usage of the Haskell analog to optional<>: - the Maybe type constructor (analogy originally pointed out by David Sankel). -
    • -
  • - Other comments were posted by Vincent Finn, Anthony Williams, Ed Brey, - Rob Stewart, and others. -
    • -
  • - Joel de Guzman made the case for the support of references and helped with - the proper semantics. -
    • -
  • - Mat Marcus shown the virtues of a value-oriented interface, influencing - the current design, and contributed the idea of "none". -
    • -
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHome -
- - diff --git a/doc/html/boost_optional/dependencies_and_portability.html b/doc/html/boost_optional/dependencies_and_portability.html deleted file mode 100644 index 2b4f7c43..00000000 --- a/doc/html/boost_optional/dependencies_and_portability.html +++ /dev/null @@ -1,91 +0,0 @@ - - - -Dependencies and Portability - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-
-
Dependencies
-
Emplace - operations in older compilers
-
Optional - Reference Binding
-
-
-
-

- The implementation uses the following other Boost modules: -

-
    -
  1. - assert -
    2. -
  2. - config -
    3. -
  3. - core -
    4. -
  4. - detail -
    5. -
  5. - move -
    6. -
  6. - mpl -
    7. -
  7. - static_assert -
    8. -
  8. - throw_exception -
    9. -
  9. - type_traits -
    10. -
  10. - utility -
    11. -
-
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/dependencies_and_portability/emplace_operations_in_older_compilers.html b/doc/html/boost_optional/dependencies_and_portability/emplace_operations_in_older_compilers.html deleted file mode 100644 index e4c08bcb..00000000 --- a/doc/html/boost_optional/dependencies_and_portability/emplace_operations_in_older_compilers.html +++ /dev/null @@ -1,90 +0,0 @@ - - - -Emplace operations in older compilers - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- Certain constructors and functions - in the interface of optional - perform a 'perfect forwarding' of arguments: -

-
template<class... Args> optional(in_place_init_t, Args&&... args);
-template<class... Args> optional(in_place_init_if_t, bool condition, Args&&... args);
-template<class... Args> void emplace(Args&&... args);
-
-

- On compilers that do not support variadic templates, each of these functions - is substituted with two overloads, one forwarding a single argument, the - other forwarding zero arguments. This forms the following set: -

-
template<class Arg> optional(in_place_init_t, Arg&& arg);
-optional(in_place_init_t);
-
-template<class Arg> optional(in_place_init_if_t, bool condition, Arg&& arg);
-optional(in_place_init_if_t, bool condition);
-
-template<class Arg> void emplace(Arg&& arg);
-void emplace();
-
-

- On compilers that do not support rvalue references, each of these functions - is substituted with three overloads: taking const - and non-const lvalue reference, - and third forwarding zero arguments. This forms the following set: -

-
template<class Arg> optional(in_place_init_t, const Arg& arg);
-template<class Arg> optional(in_place_init_t, Arg& arg);
-optional(in_place_init_t);
-
-template<class Arg> optional(in_place_init_if_t, bool condition, const Arg& arg);
-template<class Arg> optional(in_place_init_if_t, bool condition, Arg& arg);
-optional(in_place_init_if_t, bool condition);
-
-template<class Arg> void emplace(const Arg& arg);
-template<class Arg> void emplace(Arg& arg);
-void emplace();
-
-

- This workaround addresses about 40% of all use cases. If this is insufficient, - you need to resort to using In-Place - Factories. -

-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/dependencies_and_portability/optional_reference_binding.html b/doc/html/boost_optional/dependencies_and_portability/optional_reference_binding.html deleted file mode 100644 index 9bd61868..00000000 --- a/doc/html/boost_optional/dependencies_and_portability/optional_reference_binding.html +++ /dev/null @@ -1,107 +0,0 @@ - - - -Optional Reference Binding - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- A number of compilers incorrectly - treat const lvalues of integral type as rvalues, and create an illegal temporary - when binding to an lvalue reference to const in some expressions. This could - result in creating an optional lvalue reference that is in fact bound to - an unexpected temporary rather than to the intended object. In order to prevent - hard to find run-time bugs, this library performs compile-time checks to - prevent expressions that would otherwise bind an optional reference to an - unexpected temporary. As a consequence, on certain compilers certain pieces - of functionality in optional references are missing. In order to maintain - a portability of your code across different compilers, it is recommended that - you only stick to the minimum portable interface of optional references: - prefer direct-initialization and copy assignment of optional references to - copy-initialization and assignment from T&: -

-
const int i = 0;
-optional<const int&> or1;
-optional<const int&> or2 = i;  // caution: not portable
-or1 = i;                       // caution: not portable
-
-optional<const int&> or3(i);   // portable
-or1 = optional<const int&>(i); // portable
-
-

- Compilers known to have these deficiencies include GCC versions 4.2, 4.3, - 4.4, 4.5, 5.1, 5.2; QCC 4.4.2; MSVC versions 8.0, 9.0, 10.0, 11.0, 12.0. - In order to check if your compiler correctly implements reference binding - use this test program. -

-
#include <cassert>
-
-const int global_i = 0;
-
-struct TestingReferenceBinding
-{
-  TestingReferenceBinding(const int& ii)
-  {
-    assert(&ii == &global_i);
-  }
-
-  void operator=(const int& ii)
-  {
-    assert(&ii == &global_i);
-  }
-
-  void operator=(int&&) // remove this if your compiler doesn't have rvalue refs
-  {
-    assert(false);
-  }
-};
-
-int main()
-{
-  const int& iref = global_i;
-  assert(&iref == &global_i);
-
-  TestingReferenceBinding ttt = global_i;
-  ttt = global_i;
-
-  TestingReferenceBinding ttt2 = iref;
-  ttt2 = iref;
-}
-
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/detailed_semantics.html b/doc/html/boost_optional/detailed_semantics.html deleted file mode 100644 index 28aa8150..00000000 --- a/doc/html/boost_optional/detailed_semantics.html +++ /dev/null @@ -1,1975 +0,0 @@ - - - -Detailed Semantics - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- Because T might be of reference - type, in the sequel, those entries whose semantic depends on T being of reference type or not will be - distinguished using the following convention: -

-
    -
  • - If the entry reads: optional<T(not - a ref)>, the - description corresponds only to the case where T - is not of reference type. -
    • -
  • - If the entry reads: optional<T&>, the description corresponds only - to the case where T is - of reference type. -
    • -
  • - If the entry reads: optional<T>, the description is the same for both - cases. -
    • -
-
- - - - - -
[Note]Note

- The following section contains various assert() which are used only to show the postconditions - as sample code. It is not implied that the type T - must support each particular expression but that if the expression is supported, - the implied condition holds. -

-

- space -

-

- - optional - class member functions -

-

- space -

-

- optional<T>::optional() noexcept; -

-
    -
  • - Effect: Default-Constructs an optional. -
    • -
  • - Postconditions: *this is uninitialized. -
    • -
  • - Notes: T's default constructor is not called. -
    • -
  • - Example: -
    optional<T> def ;
-assert ( !def ) ;
-
    -
    • -
-

- space -

-

- optional<T>::optional( none_t ) noexcept; -

-
    -
  • - Effect: Constructs an optional - uninitialized. -
    • -
  • - Postconditions: *this is uninitialized. -
    • -
  • - Notes: T's - default constructor is not called. - The expression boost::none denotes an instance of boost::none_t that can be used as the parameter. -
    • -
  • - Example: -
    #include <boost/none.hpp>
-optional<T> n(none) ;
-assert ( !n ) ;
-
    -
    • -
-

- space -

-

- optional<T (not a ref)>::optional( T const& v ) -

-
    -
  • - Requires: is_copy_constructible<T>::value - is true. -
    • -
  • - Effect: Directly-Constructs an optional. -
    • -
  • - Postconditions: *this is initialized - and its value is a copy of v. -
    • -
  • - Throws: Whatever T::T( - T const& ) - throws. -
    • -
  • - Notes: T::T( - T const& ) - is called. -
    • -
  • - Exception Safety: Exceptions can only - be thrown during T::T( T - const& - ); in that case, this constructor - has no effect. -
    • -
  • - Example: -
    T v;
-optional<T> opt(v);
-assert ( *opt == v ) ;
-
    -
    • -
-

- space -

-

- optional<T&>::optional( T& ref ) -

-
    -
  • - Effect: Directly-Constructs an optional. -
    • -
  • - Postconditions: *this is initialized - and its value is an instance of an internal type wrapping the reference - ref. -
    • -
  • - Throws: Nothing. -
    • -
  • - Example: -
    T v;
-T& vref = v ;
-optional<T&> opt(vref);
-assert ( *opt == v ) ;
-++ v ; // mutate referee
-assert (*opt == v);
-
    -
    • -
-

- space -

-

- optional<T (not a ref)>::optional( T&& - v ) -

-
    -
  • - Requires: is_move_constructible<T>::value - is true. -
    • -
  • - Effect: Directly-Move-Constructs an optional. -
    • -
  • - Postconditions: *this is initialized - and its value is move-constructed from v. -
    • -
  • - Throws: Whatever T::T( - T&& - ) throws. -
    • -
  • - Notes: T::T( - T&& - ) is called. -
    • -
  • - Exception Safety: Exceptions can only - be thrown during T::T( T&& ); - in that case, the state of v - is determined by exception safety guarantees for T::T(T&&). -
    • -
  • - Example: -
    T v1, v2;
-optional<T> opt(std::move(v1));
-assert ( *opt == v2 ) ;
-
    -
    • -
-

- space -

-

- optional<T&>::optional( T&& ref ) = delete -

-
  • - Notes: This constructor is deleted -
-

- space -

-

- optional<T (not a ref)>::optional( bool condition, T const& v ) ; -

-

- optional<T&> ::optional( bool condition, T& - v ) ; -

-
  • - If condition is true, same as: -
-

- optional<T (not a ref)>::optional( T const& v ) -

-

- optional<T&> ::optional( T& - v ) -

-
  • - otherwise, same as: -
-

- optional<T (not a ref)>::optional() -

-

- optional<T&> ::optional() -

-

- space -

-

- optional<T (not a ref)>::optional( optional const& rhs ); -

-
    -
  • - Requires: is_copy_constructible<T>::value - is true. -
    • -
  • - Effect: Copy-Constructs an optional. -
    • -
  • - Postconditions: If rhs is initialized, - *this - is initialized and its value is a copy of the value - of rhs; else *this is - uninitialized. -
    • -
  • - Throws: Whatever T::T( - T const& ) - throws. -
    • -
  • - Notes: If rhs is initialized, T::T(T const& ) - is called. -
    • -
  • - Exception Safety: Exceptions can only - be thrown during T::T( T - const& - ); in that case, this constructor - has no effect. -
    • -
  • - Example: -
    optional<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 ) ;
-
    -
    • -
-

- space -

-

- optional<T&>::optional( optional const& rhs ); -

-
    -
  • - Effect: Copy-Constructs an optional. -
    • -
  • - Postconditions: If rhs - is initialized, *this - is initialized and its value is another reference to the same object referenced - by *rhs; - else *this - is uninitialized. -
    • -
  • - Throws: Nothing. -
    • -
  • - Notes: If rhs - is initialized, both *this - and *rhs - will reefer to the same object (they alias). -
    • -
  • - Example: -
    optional<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 ) ;
-
    -
    • -
-

- space -

-

- optional<T (not a ref)>::optional( optional&& rhs - ) noexcept(see below); -

-
    -
  • - Requires: is_move_constructible<T>::value - is true. -
    • -
  • - Effect: Move-constructs an optional. -
    • -
  • - Postconditions: If rhs - is initialized, *this - is initialized and its value is move constructed from rhs; - else *this - is uninitialized. -
    • -
  • - Throws: Whatever T::T( - T&& - ) throws. -
    • -
  • - Notes: If rhs - is initialized, T::T( T - && ) - is called. The expression inside noexcept - is equivalent to is_nothrow_move_constructible<T>::value. -
    • -
  • - Exception Safety: Exceptions can only - be thrown during T::T( T&& ); - in that case, rhs remains - initialized and the value of *rhs is determined by exception safety - of T::T(T&&). -
    • -
  • - Example: -
    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::unique_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) ) ;
-
    -
    • -
-

- space -

-

- optional<T&>::optional( optional && - rhs ); -

-
    -
  • - Effect: Move-Constructs an optional. -
    • -
  • - Postconditions: If rhs - is initialized, *this - is initialized and its value is another reference to the same object referenced - by *rhs; - else *this - is uninitialized. -
    • -
  • - Throws: Nothing. -
    • -
  • - Notes: If rhs - is initialized, both *this - and *rhs - will reefer to the same object (they alias). -
    • -
  • - Example: -
    optional<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 ) ;
-
    -
    • -
-

- space -

-

- template<U> explicit optional<T - (not a ref)>::optional( optional<U> const& rhs ); -

-
    -
  • - Effect: Copy-Constructs an optional. -
    • -
  • - Postconditions: If rhs - is initialized, *this - is initialized and its value is a copy of the value - of rhs converted to type T; - else *this - is uninitialized. -
    • -
  • - Throws: Whatever T::T( - U const& ) - throws. -
    • -
  • - Notes: T::T( - U const& ) - is called if rhs is initialized, - which requires a valid conversion from U - to T. -
    • -
  • - Exception Safety: Exceptions can only - be thrown during T::T( U - const& - ); in that case, this constructor - has no effect. -
    • -
  • - Example: -
    optional<double> x(123.4);
-assert ( *x == 123.4 ) ;
-
-optional<int> y(x) ;
-assert( *y == 123 ) ;
-
    -
    • -
-

- space -

-

- template<U> explicit optional<T - (not a ref)>::optional( optional<U>&& - rhs ); -

-
    -
  • - Effect: Move-constructs an optional. -
    • -
  • - Postconditions: If rhs - is initialized, *this - is initialized and its value is move constructed from *rhs; else *this is uninitialized. -
    • -
  • - Throws: Whatever T::T( - U&& - ) throws. -
    • -
  • - Notes: T::T( - U&& - ) is called if rhs - is initialized, which requires a valid conversion from U - to T. -
    • -
  • - Exception Safety: Exceptions can only - be thrown during T::T( U&& ); - in that case, rhs remains - initialized and the value of *rhs is determined by exception safety - guarantee of T::T( U&& ). -
    • -
  • - Example: -
    optional<double> x(123.4);
-assert ( *x == 123.4 ) ;
-
-optional<int> y(std::move(x)) ;
-assert( *y == 123 ) ;
-
    -
    • -
-

- space -

-

- template<InPlaceFactory> - explicit optional<T - (not a ref)>::optional( InPlaceFactory const& f ); -

-

- template<TypedInPlaceFactory> - explicit optional<T - (not a ref)>::optional( TypedInPlaceFactory const& f ); -

-
    -
  • - Effect: Constructs an optional - with a value of T obtained - from the factory. -
    • -
  • - Postconditions: *this is initialized - and its value is directly given from the factory - f (i.e., the value is not copied). -
    • -
  • - Throws: Whatever the T - constructor called by the factory throws. -
    • -
  • - Notes: See In-Place - Factories -
    • -
  • - Exception Safety: Exceptions can only - be thrown during the call to the T - constructor used by the factory; in that case, this constructor has no - effect. -
    • -
  • - Example: -
    class C { C ( char, double, std::string ) ; } ;
-
-C v('A',123.4,"hello");
-
-optional<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 ) ;
-
    -
    • -
-

- space -

-

- optional& - optional<T>::operator= ( none_t ) noexcept; -

-
    -
  • - Effect: If *this is initialized destroys its contained - value. -
    • -
  • - Postconditions: *this is uninitialized. -
    • -
-

- space -

-

- optional& - optional<T (not a ref)>::operator= ( T - const& - rhs ) - ; -

-
    -
  • - Effect: Assigns the value rhs to an optional. -
    • -
  • - Postconditions: *this is initialized and its value is a - copy of rhs. -
    • -
  • - Throws: Whatever T::operator=( T const& ) or T::T(T const&) throws. -
    • -
  • - Notes: If *this was initialized, T's - assignment operator is used, otherwise, its copy-constructor is used. -
    • -
  • - Exception Safety: In the event of an exception, - the initialization state of *this is unchanged and its value unspecified - as far as optional is concerned - (it is up to T's operator=()). - If *this - is initially uninitialized and T's - copy constructor fails, *this is left properly uninitialized. -
    • -
  • - Example: -
    T x;
-optional<T> def ;
-optional<T> opt(x) ;
-
-T y;
-def = y ;
-assert ( *def == y ) ;
-opt = y ;
-assert ( *opt == y ) ;
-
    -
    • -
-

- space -

-

- optional<T&>& - optional<T&>::operator= ( T& - rhs ) - ; -

-
    -
  • - Effect: (Re)binds the wrapped reference. -
    • -
  • - Postconditions: *this is initialized and it references the - same object referenced by rhs. -
    • -
  • - Notes: If *this was initialized, it is rebound - to the new object. See here - for details on this behavior. -
    • -
  • - Example: -
    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 ) ;
-
    -
    • -
-

- space -

-

- optional& - optional<T (not a ref)>::operator= ( T&& rhs - ) ; -

-
    -
  • - Effect: Moves the value rhs to an optional. -
    • -
  • - Postconditions: *this is initialized and its value is moved - from rhs. -
    • -
  • - Throws: Whatever T::operator=( T&& ) - or T::T(T - &&) throws. -
    • -
  • - Notes: If *this was initialized, T's - move-assignment operator is used, otherwise, its move-constructor is used. -
    • -
  • - Exception Safety: In the event of an exception, - the initialization state of *this is unchanged and its value unspecified - as far as optional is concerned - (it is up to T's operator=()). - If *this - is initially uninitialized and T's - move constructor fails, *this is left properly uninitialized. -
    • -
  • - Example: -
    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 ) ;
-
    -
    • -
-

- space -

-

- optional<T&>& - optional<T&>::operator= ( T&& - rhs ) - = delete; -

-
  • - Notes: This assignment operator is deleted. -
-

- space -

-

- optional& - optional<T (not a ref)>::operator= ( optional - const& - rhs ) - ; -

-
    -
  • - Effect: Assigns another optional to an optional. -
    • -
  • - Postconditions: If rhs - is initialized, *this - is initialized and its value is a copy of the value - of rhs; else *this is - uninitialized. -
    • -
  • - Throws: Whatever T::operator( T const&) - or T::T( T - const& - ) throws. -
    • -
  • - Notes: If both *this and rhs - are initially initialized, T's - assignment operator is used. If *this is initially initialized but rhs is uninitialized, T's - [destructor] is called. If *this is initially uninitialized but rhs is initialized, T's - copy constructor is called. -
    • -
  • - Exception Safety: In the event of an exception, - the initialization state of *this is unchanged and its value unspecified - as far as optional is concerned (it is up to T's - operator=()). - If *this - is initially uninitialized and T's - copy constructor fails, *this is left properly uninitialized. -
    • -
  • - Example: -
    T v;
-optional<T> opt(v);
-optional<T> def ;
-
-opt = def ;
-assert ( !def ) ;
-// previous value (copy of 'v') destroyed from within 'opt'.
-
    -
    • -
-

- space -

-

- optional<T&> & optional<T&>::operator= ( optional<T&> - const& - rhs ) - ; -

-
    -
  • - Effect: (Re)binds thee wrapped reference. -
    • -
  • - Postconditions: If *rhs is initialized, *this is initialized and it references the - same object referenced by *rhs; otherwise, *this is uninitialized (and references no - object). -
    • -
  • - Notes: If *this was initialized and so is *rhs, - *this - is rebound to the new object. See here - for details on this behavior. -
    • -
  • - Example: -
    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 ) ;
-
    -
    • -
-

- space -

-

- optional& - optional<T (not a ref)>::operator= ( optional&& rhs - ) noexcept(see below); -

-
    -
  • - Effect: Move-assigns another optional to an optional. -
    • -
  • - Postconditions: If rhs - is initialized, *this - is initialized and its value is moved from *rhs, rhs - remains initialized; else *this is uninitialized. -
    • -
  • - Throws: Whatever T::operator( T&& - ) or T::T( - T && - ) throws. -
    • -
  • - Notes: If both *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. -
    • -
  • - Exception Safety: In the event of an exception, - the initialization state of *this is unchanged and its value unspecified - as far as optional is concerned (it is up to T's - operator=()). - If *this - is initially uninitialized and T's - move constructor fails, *this is left properly uninitialized. -
    • -
  • - Example: -
    optional<T> opt(T(2)) ;
-optional<T> def ;
-
-opt = def ;
-assert ( def ) ;
-assert ( opt ) ;
-assert ( *opt == T(2) ) ;
-
    -
    • -
-

- space -

-

- optional<T&> & optional<T&>::operator= ( optional<T&>&& - rhs ) - ; -

-
  • - Effect: Same as optional<T&>::operator= ( optional<T&> const& rhs ). -
-

- space -

-

- template<U> optional& - optional<T (not a ref)>::operator= ( optional<U> - const& - rhs ) - ; -

-
    -
  • - Effect: Assigns another convertible optional - to an optional. -
    • -
  • - Postconditions: If rhs - is initialized, *this - is initialized and its value is a copy of the value - of rhs converted - to type T; else *this is - uninitialized. -
    • -
  • - Throws: Whatever T::operator=( U const& ) or T::T( - U const& ) - throws. -
    • -
  • - Notes: If both *this and rhs are initially initialized, - T's assignment - operator (from U) - is used. If *this - is initially initialized but rhs - is uninitialized, T's - destructor is called. If *this is initially uninitialized but rhs - is initialized, T's converting - constructor (from U) - is called. -
    • -
  • - Exception Safety: In the event of an exception, - the initialization state of *this is unchanged and its value unspecified - as far as optional is concerned (it is up to T's - operator=()). - If *this - is initially uninitialized and T's - converting constructor fails, *this is left properly uninitialized. -
    • -
  • - Example: -
    T v;
-optional<T> opt0(v);
-optional<U> opt1;
-
-opt1 = opt0 ;
-assert ( *opt1 == static_cast<U>(v) ) ;
-
    -
    • -
-

- space -

-

- template<U> optional& - optional<T (not a ref)>::operator= ( optional<U>&& - rhs ) - ; -

-
    -
  • - Effect: Move-assigns another convertible - optional to an optional. -
    • -
  • - Postconditions: If rhs - is initialized, *this - is initialized and its value is moved from the value of rhs; - else *this - is uninitialized. -
    • -
  • - Throws: Whatever T::operator=( U&& ) - or T::T( U&& ) - throws. -
    • -
  • - Notes: If both *this and rhs - are initially initialized, T's - assignment operator (from U&&) is used. If *this is initially initialized but rhs is uninitialized, T's - destructor is called. If *this is initially uninitialized but rhs is initialized, T's - converting constructor (from U&&) is called. -
    • -
  • - Exception Safety: In the event of an exception, - the initialization state of *this is unchanged and its value unspecified - as far as optional is concerned (it is up to T's - operator=()). - If *this - is initially uninitialized and T's - converting constructor fails, *this is left properly uninitialized. -
    • -
  • - Example: -
    T v;
-optional<T> opt0(v);
-optional<U> opt1;
-
-opt1 = std::move(opt0) ;
-assert ( *opt1 == static_cast<U>(v) ) ;
-
    -
    • -
-

- space -

-

- template<class... Args> void optional<T - (not a ref)>::emplace( Args...&& - args ); -

-
    -
  • - Requires: The compiler supports rvalue - references and variadic templates. -
    • -
  • - Effect: If *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).... -
    • -
  • - Postconditions: *this is initialized. -
    • -
  • - Throws: Whatever the selected T's constructor throws. -
    • -
  • - Notes: T - need not be MoveConstructible - or MoveAssignable. -
    • -
  • - Exception Safety: If an exception is thrown - during the initialization of T, - *this - is uninitialized. -
    • -
-

- space -

-

- 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 ); -

-
    -
  • - Effect: Assigns an optional - with a value of T obtained - from the factory. -
    • -
  • - Postconditions: *this is initialized - and its value is directly given from the factory - f (i.e., the value is not copied). -
    • -
  • - Throws: Whatever the T - constructor called by the factory throws. -
    • -
  • - Notes: See In-Place - Factories -
    • -
  • - Exception Safety: Exceptions can only - be thrown during the call to the T - constructor used by the factory; in that case, the optional - object will be reset to be uninitialized. -
    • -
-

- space -

-

- void optional<T - (not a ref)>::reset( T const& v ) ; -

-
  • - Deprecated: same as operator= ( T - const& - v) - ; -
-

- space -

-

- void optional<T>::reset() noexcept ; -

-
  • - Deprecated: Same as operator=( none_t ); -
-

- space -

-

- 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)> - &) ; -

-
    -
  • - Requires: *this is initialized -
    • -
  • - Returns: A reference to the contained - value -
    • -
  • - Throws: Nothing. -
    • -
  • - Notes: The requirement is asserted via - BOOST_ASSERT(). -
    • -
-

- space -

-

- T const& optional<T&>::get() const ; -

-

- T& - optional<T&>::get() ; -

-

- inline T - const& - get ( - optional<T&> const& ) ; -

-

- inline T& get ( optional<T&> - &) ; -

-
    -
  • - Requires: *this is initialized -
    • -
  • - Returns: The - reference contained. -
    • -
  • - Throws: Nothing. -
    • -
  • - Notes: The requirement is asserted via - BOOST_ASSERT(). -
    • -
-

- space -

-

- T const& optional<T - (not a ref)>::operator*() const& ; -

-

- T& - optional<T (not a ref)>::operator*() &; -

-

- T&& - optional<T (not a ref)>::operator*() &&; -

-
    -
  • - Requires: *this is initialized -
    • -
  • - Returns: A reference to the contained - value -
    • -
  • - Throws: Nothing. -
    • -
  • - Notes: The requirement is asserted via - 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. -
    • -
  • - Example: -
    T v ;
-optional<T> opt ( v );
-T const& u = *opt;
-assert ( u == v ) ;
-T w ;
-*opt = w ;
-assert ( *opt == w ) ;
-
    -
    • -
-

- space -

-

- T const& optional<T&>::operator*() const& ; -

-

- T & - optional<T&>::operator*() & ; -

-

- T & - optional<T&>::operator*() && ; -

-
    -
  • - Requires: *this is initialized -
    • -
  • - Returns: The - reference contained. -
    • -
  • - Throws: Nothing. -
    • -
  • - Notes: The requirement is asserted via - 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. -
    • -
  • - Example: -
    T v ;
-T& vref = v ;
-optional<T&> opt ( vref );
-T const& vref2 = *opt;
-assert ( vref2 == v ) ;
-++ v ;
-assert ( *opt == v ) ;
-
    -
    • -
-

- space -

-

- T const& optional<T>::value() const& ; -

-

- T& - optional<T>::value() & ; -

-

- T&& - optional<T>::value() && ; -

-
    -
  • - Returns: A reference to the contained - value, if *this - is initialized. -
    • -
  • - Throws: An instance of bad_optional_access, - if *this - is not initialized. -
    • -
  • - Notes: 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. -
    • -
  • - Example: -
    T v ;
-optional<T> o0, o1 ( v );
-assert ( o1.value() == v );
-
-try {
-  o0.value(); // throws
-  assert ( false );
-}
-catch(bad_optional_access&) {
-  assert ( true );
-}
-
    - space -
    • -
-

- template<class U> T optional<T>::value_or(U && - v) const& ; -

-

- template<class U> T optional<T>::value_or(U && - v) && ; -

-
    -
  • - Requires: T - is CopyConstructible. -
    • -
  • - Returns: First overload: bool(*this) ? **this : static_cast<T>(forward<U>(v)). - second overload: bool(*this) ? - std::move(**this) : - static_cast<T>(forward<U>(v)). -
    • -
  • - Throws: Any exception thrown by the selected - constructor of T. -
    • -
  • - Notes: 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. - On compilers without rvalue reference support the type of v becomes U - const&. -
    • -
-

- space -

-

- 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 ) ; -

-
    -
  • - Deprecated: Use value_or() instead. -
    • -
  • - 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 ) ;
-
    -
    • -
-

- space -

-

- 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)> - &) ; -

-
    -
  • - Returns: If *this is initialized, a pointer to the contained - value; else 0 (null). -
    • -
  • - Throws: Nothing. -
    • -
  • - Notes: The contained value is permanently - stored within *this, - so you should not hold nor delete this pointer -
    • -
  • - Example: -
    T v;
-optional<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) ) ;
-
    -
    • -
-

- space -

-

- T const* optional<T - (not a ref)>::operator ->() - const ; -

-

- T* - optional<T (not a ref)>::operator ->() ; -

-
    -
  • - Requires: *this is initialized. -
    • -
  • - Returns: A pointer to the contained value. -
    • -
  • - Throws: Nothing. -
    • -
  • - Notes: The requirement is asserted via - BOOST_ASSERT(). -
    • -
  • - Example: -
    struct X { int mdata ; } ;
-X x ;
-optional<X> opt (x);
-opt->mdata = 2 ;
-
    -
    • -
-

- space -

-

- explicit optional<T>::operator bool() const ; -

-
    -
  • - Returns: get_ptr() != 0. -
    • -
  • - Throws: Nothing. -
    • -
  • - Notes: On compilers that do not support - explicit conversion operators this falls back to safe-bool idiom. -
    • -
  • - Example: -
    optional<T> def ;
-assert ( def == 0 );
-optional<T> opt ( v ) ;
-assert ( opt );
-assert ( opt != 0 );
-
    -
    • -
-

- space -

-

- bool optional<T>::operator!() noexcept ; -

-
    -
  • - Returns: If *this is uninitialized, true; - else false. -
    • -
  • - Notes: This operator is provided for those - compilers which can't use the unspecified-bool-type operator - in certain boolean contexts. -
    • -
  • - Example: -
    optional<T> opt ;
-assert ( !opt );
-*opt = some_T ;
-
-// Notice the "double-bang" idiom here.
-assert ( !!opt ) ;
-
    -
    • -
-

- space -

-

- bool optional<T>::is_initialized() - const ; -

-
  • - Deprecated: Same as explicit - operator bool - () ; -
-

- space -

-

- - Free - functions -

-

- space -

-

- optional<T (not a ref)> make_optional( T const& v ) -

-
    -
  • - Returns: optional<T>(v) for the deduced type - T of v. -
    • -
  • - Example: -
    template<class T> void foo ( optional<T> const& opt ) ;
-
-foo ( make_optional(1+1) ) ; // Creates an optional<int>
-
    -
    • -
-

- space -

-

- optional<T (not a ref)> make_optional( bool condition, T const& v ) -

-
    -
  • - Returns: optional<T>(condition,v) - for the deduced type T - of v. -
    • -
  • - Example: -
    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");
-
    -
    • -
-

- space -

-

- bool operator - == ( optional<T> const& x, optional<T> - const& - y ); -

-
    -
  • - Requires: T - shall meet requirements of EqualityComparable. -
    • -
  • - Returns: If both x - and y are initialized, - (*x - == *y). If - only x or y is initialized, false. - If both are uninitialized, true. -
    • -
  • - Throws: Nothing. -
    • -
  • - Notes: Pointers have shallow relational - operators while optional - has deep relational operators. Do not use operator - == directly in generic code which - expect to be given either an optional<T> or a pointer; use equal_pointees() - instead -
    • -
  • - Example: -
    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 ) ;
-
    -
    • -
-

- space -

-

- bool operator - < ( optional<T> const& x, optional<T> - const& - y ); -

-
    -
  • - Requires: T - shall meet requirements of LessThanComparable. -
    • -
  • - Returns: If y - is not initialized, false. - If y is initialized and - x is not initialized, - true. If both x and y - are initialized, (*x - < *y). -
    • -
  • - Throws: Nothing. -
    • -
  • - Notes: Pointers have shallow relational - operators while optional - has deep relational operators. Do not use operator - < directly in generic code which - expect to be given either an optional<T> or a pointer; use less_pointees() - instead. -
    • -
  • - Example: -
    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 ) ;
-
    -
    • -
-

- space -

-

- bool operator - != ( optional<T> const& x, optional<T> - const& - y ); -

-
    -
  • - Returns: !( - x == - y ); -
    • -
  • - Throws: Nothing. -
    • -
-

- space -

-

- bool operator - > ( optional<T> const& x, optional<T> - const& - y ); -

-
    -
  • - Returns: ( - y < - x ); -
    • -
  • - Throws: Nothing. -
    • -
-

- space -

-

- bool operator - <= ( - optional<T> const& x, optional<T> - const& - y ); -

-
    -
  • - Returns: !( - y < - x ); -
    • -
  • - Throws: Nothing. -
    • -
-

- space -

-

- bool operator - >= ( - optional<T> const& x, optional<T> - const& - y ); -

-
    -
  • - Returns: !( - x<y ); -
    • -
  • - Throws: Nothing. -
    • -
-

- bool operator - == ( optional<T> const& x, none_t - ) noexcept; -

-
    -
  • - Returns: !x. -
    • -
  • - Notes: T - need not meet requirements of EqualityComparable. -
    • -
-

- space -

-

- bool operator - != ( optional<T> const& x, none_t - ) noexcept; -

-
  • - Returns: !( - x == - y ); -
-

- space -

-

- 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 none is initialized, does nothing. -
    • -
  • - Postconditions: The states of x and y - interchanged. -
    • -
  • - Throws: If both are initialized, whatever - swap(T&,T&) - throws. If only one is initialized, whatever T::T ( T&& - ) throws. -
    • -
  • - Notes: If both are initialized, swap(T&,T&) - is used unqualified but with std::swap - introduced in scope. If only one is initialized, T::~T() and T::T( - T&& - ) 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>::operator= ( T&& - ). -
    • -
  • - Example: -
    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 );
-
    -
    • -
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/development.html b/doc/html/boost_optional/development.html deleted file mode 100644 index 21e6db44..00000000 --- a/doc/html/boost_optional/development.html +++ /dev/null @@ -1,412 +0,0 @@ - - - -Development - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-
-
The models
-
The semantics
-
The Interface
-
-
-
-

- In C++, we can declare an object (a variable) of type - T, and we can give this variable - an initial value (through an initializer. - (cf. 8.5)). When a declaration includes a non-empty initializer (an initial - value is given), it is said that the object has been initialized. If the - declaration uses an empty initializer (no initial value is given), and neither - default nor value initialization applies, it is said that the object is - uninitialized. Its actual value exist but - has an indeterminate initial value (cf. 8.5/11). optional<T> intends - to formalize the notion of initialization (or lack of it) allowing a program - to test whether an object has been initialized and stating that access to - the value of an uninitialized object is undefined behavior. That is, when - a variable is declared as optional<T> - and no initial value is given, the variable is formally - uninitialized. A formally uninitialized optional object has conceptually - no value at all and this situation can be tested at runtime. It is formally - undefined behavior to try to access the value of an - uninitialized optional. An uninitialized optional can be assigned a value, - in which case its initialization state changes to initialized. Furthermore, - given the formal treatment of initialization states in optional objects, - it is even possible to reset an optional to uninitialized. -

-

- In C++ there is no formal notion of uninitialized objects, which means that - objects always have an initial value even if indeterminate. As discussed - on the previous section, this has a drawback because you need additional - information to tell if an object has been effectively initialized. One of - the typical ways in which this has been historically dealt with is via a - special value: EOF, npos, -1, etc... This is equivalent to - adding the special value to the set of possible values of a given type. This - super set of T plus some - nil_t—where nil_t - is some stateless POD—can be modeled in modern languages as a discriminated union of T and nil_t. Discriminated - unions are often called variants. A variant has a current - type, which in our case is either T - or nil_t. Using the Boost.Variant library, this model - can be implemented in terms of boost::variant<T,nil_t>. - There is precedent for a discriminated union as a model for an optional value: - the Haskell Maybe - built-in type constructor. Thus, a discriminated union T+nil_t - serves as a conceptual foundation. -

-

- A variant<T,nil_t> follows naturally from the traditional - idiom of extending the range of possible values adding an additional sentinel - value with the special meaning of Nothing. However, - this additional Nothing value is largely irrelevant - for our purpose since our goal is to formalize the notion of uninitialized - objects and, while a special extended value can be used to convey that meaning, - it is not strictly necessary in order to do so. -

-

- The observation made in the last paragraph about the irrelevant nature of - the additional nil_t with - respect to purpose of optional<T> suggests - an alternative model: a container that either has a - value of T or nothing. -

-

- 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. -

-

- In any event, both the discriminated-union or the single-element container - models serve as a conceptual ground for a class representing optional—i.e. - possibly uninitialized—objects. For instance, these models show the exact - semantics required for a wrapper of optional values: -

-

- Discriminated-union: -

-
    -
  • - deep-copy semantics: copies of the variant - implies copies of the value. -
    • -
  • - deep-relational semantics: comparisons - between variants matches both current types and values -
    • -
  • - If the variant's current type is T, - it is modeling an initialized optional. -
    • -
  • - If the variant's current type is not T, - it is modeling an uninitialized optional. -
    • -
  • - Testing if the variant's current type is T - models testing if the optional is initialized -
    • -
  • - Trying to extract a T - from a variant when its current type is not T, - models the undefined behavior of trying to access the value of an uninitialized - optional -
    • -
-

- Single-element container: -

-
    -
  • - deep-copy semantics: copies of the container - implies copies of the value. -
    • -
  • - deep-relational semantics: comparisons - between containers compare container size and if match, contained value -
    • -
  • - If the container is not empty (contains an object of type T), it is modeling an initialized - optional. -
    • -
  • - If the container is empty, it is modeling an uninitialized - optional. -
    • -
  • - Testing if the container is empty models testing if the optional is initialized -
    • -
  • - Trying to extract a T - from an empty container models the undefined behavior of trying to access - the value of an uninitialized optional -
    • -
-
-
-
-

- Objects of type optional<T> - are intended to be used in places where objects of type T - would but which might be uninitialized. Hence, optional<T>'s - purpose is to formalize the additional possibly uninitialized state. From - the perspective of this role, optional<T> - can have the same operational semantics of T - plus the additional semantics corresponding to this special state. As such, - optional<T> could - be thought of as a supertype of T. - Of course, we can't do that in C++, so we need to compose the desired semantics - using a different mechanism. Doing it the other way around, that is, making - optional<T> a - subtype of T - is not only conceptually wrong but also impractical: it is not allowed to - derive from a non-class type, such as a built-in type. -

-

- We can draw from the purpose of optional<T> - the required basic semantics: -

-
    -
  • - Default Construction: To introduce a - formally uninitialized wrapped object. -
    • -
  • - Direct Value Construction via copy: - To introduce a formally initialized wrapped object whose value is obtained - as a copy of some object. -
    • -
  • - Deep Copy Construction: To obtain a - new yet equivalent wrapped object. -
    • -
  • - Direct Value Assignment (upon initialized): - To assign a value to the wrapped object. -
    • -
  • - Direct Value Assignment (upon uninitialized): - To initialize the wrapped object with a value obtained as a copy of some - object. -
    • -
  • - Assignment (upon initialized): To assign - to the wrapped object the value of another wrapped object. -
    • -
  • - Assignment (upon uninitialized): To - initialize the wrapped object with value of another wrapped object. -
    • -
  • - Deep Relational Operations (when supported by the - type T): To compare wrapped object values taking into account - the presence of uninitialized states. -
    • -
  • - Value access: To unwrap the wrapped - object. -
    • -
  • - Initialization state query: To determine - if the object is formally initialized or not. -
    • -
  • - Swap: To exchange wrapped objects. (with - whatever exception safety guarantees are provided by T's - swap). -
    • -
  • - De-initialization: To release the wrapped - object (if any) and leave the wrapper in the uninitialized state. -
    • -
-

- Additional operations are useful, such as converting constructors and converting - assignments, in-place construction and assignment, and safe value access - via a pointer to the wrapped object or null. -

-
-
-
-

- Since the purpose of optional is to allow us to use objects with a formal - uninitialized additional state, the interface could try to follow the interface - of the underlying T type - as much as possible. In order to choose the proper degree of adoption of - the native T interface, the - following must be noted: Even if all the operations supported by an instance - of type T are defined for - the entire range of values for such a type, an optional<T> - extends such a set of values with a new value for which most (otherwise valid) - operations are not defined in terms of T. -

-

- Furthermore, since optional<T> - itself is merely a T wrapper - (modeling a T supertype), - any attempt to define such operations upon uninitialized optionals will be - totally artificial w.r.t. T. -

-

- This library chooses an interface which follows from T's - interface only for those operations which are well defined (w.r.t the type - T) even if any of the operands - are uninitialized. These operations include: construction, copy-construction, - assignment, swap and relational operations. -

-

- For the value access operations, which are undefined (w.r.t the type T) when the operand is uninitialized, a - different interface is chosen (which will be explained next). -

-

- Also, the presence of the possibly uninitialized state requires additional - operations not provided by T - itself which are supported by a special interface. -

-
- - Lexically-hinted - Value Access in the presence of possibly uninitialized optional objects: The - operators * and -> -
-

- A relevant feature of a pointer is that it can have a null - pointer value. This is a special value which - is used to indicate that the pointer is not referring to any object at all. - In other words, null pointer values convey the notion of nonexistent objects. -

-

- This meaning of the null pointer value allowed pointers to became a de - facto standard for handling optional objects because all you have - to do to refer to a value which you don't really have is to use a null pointer - value of the appropriate type. Pointers have been used for decades—from - the days of C APIs to modern C++ libraries—to refer - to optional (that is, possibly nonexistent) objects; particularly as optional - arguments to a function, but also quite often as optional data members. -

-

- The possible presence of a null pointer value makes the operations that access - the pointee's value possibly undefined, therefore, expressions which use - dereference and access operators, such as: ( - *p = 2 ) - and ( p->foo() ), implicitly - convey the notion of optionality, and this information is tied to the syntax - of the expressions. That is, the presence of operators * - and -> tell by themselves - —without any additional context— that the expression will be undefined - unless the implied pointee actually exist. -

-

- Such a de facto idiom for referring to optional objects - can be formalized in the form of a concept: the OptionalPointee - concept. This concept captures the syntactic usage of operators *, -> - and contextual conversion to bool - to convey the notion of optionality. -

-

- However, pointers are good to refer - to optional objects, but not particularly good to handle the optional objects - in all other respects, such as initializing or moving/copying them. The problem - resides in the shallow-copy of pointer semantics: if you need to effectively - move or copy the object, pointers alone are not enough. The problem is that - copies of pointers do not imply copies of pointees. For example, as was discussed - in the motivation, pointers alone cannot be used to return optional objects - from a function because the object must move outside from the function and - into the caller's context. -

-

- A solution to the shallow-copy problem that is often used is to resort to - dynamic allocation and use a smart pointer to automatically handle the details - of this. For example, if a function is to optionally return an object X, it can use shared_ptr<X> - as the return value. However, this requires dynamic allocation of X. If X - is a built-in or small POD, this technique is very poor in terms of required - resources. Optional objects are essentially values so it is very convenient - to be able to use automatic storage and deep-copy semantics to manipulate - optional values just as we do with ordinary values. Pointers do not have - this semantics, so are inappropriate for the initialization and transport - of optional values, yet are quite convenient for handling the access to the - possible undefined value because of the idiomatic aid present in the OptionalPointee concept - incarnated by pointers. -

-
- - Optional<T> - as a model of OptionalPointee -
-

- For value access operations optional<> uses operators * - and -> to lexically warn - about the possibly uninitialized state appealing to the familiar pointer - semantics w.r.t. to null pointers. -

-
- - - - - -
[Warning]Warning

- However, it is particularly important to note that optional<> objects are not pointers. optional<> is not, and does not model, a pointer. -

-

- For instance, optional<> - does not have shallow-copy so does not alias: two different optionals never - refer to the same value unless T - itself is a reference (but may have equivalent values). - The difference between an optional<T> - and a pointer must be kept in mind, particularly because the semantics of - relational operators are different: since optional<T> - is a value-wrapper, relational operators are deep: they compare optional - values; but relational operators for pointers are shallow: they do not compare - pointee values. As a result, you might be able to replace optional<T> - by T* - on some situations but not always. Specifically, on generic code written - for both, you cannot use relational operators directly, and must use the - template functions equal_pointees() - and less_pointees() - instead. -

-
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/discussion.html b/doc/html/boost_optional/discussion.html deleted file mode 100644 index d17a70e8..00000000 --- a/doc/html/boost_optional/discussion.html +++ /dev/null @@ -1,128 +0,0 @@ - - - -Discussion - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- Consider these functions which should return a value but which might not have - a value to return: -

-
    -
  • - (A) double sqrt(double n ); -
    • -
  • - (B) char get_async_input(); -
    • -
  • - (C) point polygon::get_any_point_effectively_inside(); -
    • -
-

- There are different approaches to the issue of not having a value to return. -

-

- A typical approach is to consider the existence of a valid return value as - a postcondition, so that if the function cannot compute the value to return, - it has either undefined behavior (and can use assert in a debug build) or uses - a runtime check and throws an exception if the postcondition is violated. This - is a reasonable choice for example, for function (A), because the lack of a - proper return value is directly related to an invalid parameter (out of domain - argument), so it is appropriate to require the callee to supply only parameters - in a valid domain for execution to continue normally. -

-

- However, function (B), because of its asynchronous nature, does not fail just - because it can't find a value to return; so it is incorrect to consider such - a situation an error and assert or throw an exception. This function must return, - and somehow, must tell the callee that it is not returning a meaningful value. -

-

- A similar situation occurs with function (C): it is conceptually an error to - ask a null-area polygon to return a point inside itself, - but in many applications, it is just impractical for performance reasons to - treat this as an error (because detecting that the polygon has no area might - be too expensive to be required to be tested previously), and either an arbitrary - point (typically at infinity) is returned, or some efficient way to tell the - callee that there is no such point is used. -

-

- There are various mechanisms to let functions communicate that the returned - value is not valid. One such mechanism, which is quite common since it has - zero or negligible overhead, is to use a special value which is reserved to - communicate this. Classical examples of such special values are EOF, string::npos, points - at infinity, etc... -

-

- When those values exist, i.e. the return type can hold all meaningful values - plus the signal value, this mechanism - is quite appropriate and well known. Unfortunately, there are cases when such - values do not exist. In these cases, the usual alternative is either to use - a wider type, such as int in place - of char; or a compound type, such - as std::pair<point,bool>. -

-

- Returning a std::pair<T,bool>, thus attaching a boolean flag to the result - which indicates if the result is meaningful, has the advantage that can be - turned into a consistent idiom since the first element of the pair can be whatever - the function would conceptually return. For example, the last two functions - could have the following interface: -

-
std::pair<char,bool> get_async_input();
-std::pair<point,bool> polygon::get_any_point_effectively_inside();
-
-

- These functions use a consistent interface for dealing with possibly nonexistent - results: -

-
std::pair<point,bool> p = poly.get_any_point_effectively_inside();
-if ( p.second )
-    flood_fill(p.first);
-
-

- However, not only is this quite a burden syntactically, it is also error prone - since the user can easily use the function result (first element of the pair) - without ever checking if it has a valid value. -

-

- Clearly, we need a better idiom. -

-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/examples.html b/doc/html/boost_optional/examples.html deleted file mode 100644 index 64a95a97..00000000 --- a/doc/html/boost_optional/examples.html +++ /dev/null @@ -1,147 +0,0 @@ - - - -Examples - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-
-
Optional - return values
-
Optional - local variables
-
Optional - data members
-
Bypassing - expensive unnecessary default construction
-
-
-
-
optional<char> get_async_input()
-{
-    if ( !queue.empty() )
-        return optional<char>(queue.top());
-    else return optional<char>(); // uninitialized
-}
-
-void receive_async_message()
-{
-    optional<char> rcv ;
-    // The safe boolean conversion from 'rcv' is used here.
-    while ( (rcv = get_async_input()) && !timeout() )
-        output(*rcv);
-}
-
-
-
-
-
optional<string> name ;
-if ( database.open() )
-{
-    name = database.lookup(employer_name) ;
-}
-else
-{
-    if ( can_ask_user )
-        name = user.ask(employer_name) ;
-}
-
-if ( name )
-    print(*name);
-else print("employer's name not found!");
-
-
-
-
-
class figure
-{
-    public:
-
-    figure()
-    {
-        // data member 'm_clipping_rect' is uninitialized at this point.
-    }
-
-    void clip_in_rect ( rect const& rect )
-    {
-        ....
-        m_clipping_rect = rect ; // initialized here.
-    }
-
-    void draw ( canvas& cvs )
-    {
-        if ( m_clipping_rect )
-            do_clipping(*m_clipping_rect);
-
-        cvs.drawXXX(..);
-    }
-
-    // this can return NULL.
-    rect const* get_clipping_rect() { return get_pointer(m_clipping_rect); }
-
-    private :
-
-    optional<rect> m_clipping_rect ;
-
-};
-
-
-
-
-
class ExpensiveCtor { ... } ;
-class Fred
-{
-    Fred() : mLargeVector(10000) {}
-
-    std::vector< optional<ExpensiveCtor> > mLargeVector ;
-} ;
-
-
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/exception_safety_guarantees.html b/doc/html/boost_optional/exception_safety_guarantees.html deleted file mode 100644 index 3cb8b153..00000000 --- a/doc/html/boost_optional/exception_safety_guarantees.html +++ /dev/null @@ -1,170 +0,0 @@ - - - -Exception Safety Guarantees - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- This library assumes that T's - destructor does not throw exceptions. If it does, the behaviour of many operations - on optional<T> is - undefined. -

-

- The following mutating operations never throw exceptions: -

-
    -
  • - optional<T>::operator= ( none_t ) noexcept -
    • -
  • - optional<T>::reset() noexcept -
    • -
-

- In addition, the following constructors and the destructor never throw exceptions: -

-
    -
  • - optional<T>::optional() - noexcept -
    • -
  • - optional<T>::optional( none_t ) noexcept -
    • -
-

- Regarding the following assignment functions: -

-
    -
  • - optional<T>::operator= ( optional<T> const& ) -
    • -
  • - optional<T>::operator= ( T const& ) -
    • -
  • - template<class U> optional<T>::operator= ( optional<U> const& ) -
    • -
  • - template<class InPlaceFactory> optional<T>::operator= ( InPlaceFactory - const& - ) -
    • -
  • - template<class TypedInPlaceFactory> optional<T>::operator= ( TypedInPlaceFactory - const& - ) -
    • -
  • - optional<T>::reset( T const& ) -
    • -
-

- They forward calls to the corresponding T's - constructors or assignments (depending on whether the optional object is initialized - or not); so if both T's constructor - and the assignment provide strong exception safety guarantee, optional<T>'s assignment - also provides strong exception safety guarantee; otherwise we only get the - basic guarantee. Additionally, if both involved T's - constructor and the assignment never throw, optional<T>'s - assignment also never throws. -

-

- Unless T's constructor or assignment - throws, assignments to optional<T> - do not throw anything else on its own. A throw during assignment never changes - the initialization state of any optional object involved: -

-
optional<T> opt1(val1);
-optional<T> opt2(val2);
-assert(opt1);
-assert(opt2);
-
-try
-{
-  opt1 = opt2; // throws
-}
-catch(...)
-{
-  assert(opt1);
-  assert(opt2);
-}
-
-

- This also applies to move assignments/constructors. However, move operations - are made no-throw more often. -

-

- Operation emplace provides - basic exception safety guarantee. If it throws, the optional object becomes - uninitialized regardless of its initial state, and its previous contained value - (if any) is destroyed. It doesn't call any assignment or move/copy constructor - on T. -

-

- - Swap -

-

- Unless swap on optional is - customized, its primary implementation forwards calls to T's - swap or move constructor (depending - on the initialization state of the optional objects). Thus, if both T's swap - and move constructor never throw, swap - on optional<T> never - throws. similarly, if both T's - swap and move constructor offer - strong guarantee, swap on - optional<T> also - offers a strong guarantee. -

-

- In case swap on optional is - customized, the call to T's - move constructor are replaced with the calls to T's - default constructor followed by swap. - (This is more useful on older compilers that do not support move semantics, - when one wants to achieve stronger exception safety guarantees.) In this case - the exception safety guarantees for swap - are reliant on the guarantees of T's - swap and default constructor -

-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/implementation_notes.html b/doc/html/boost_optional/implementation_notes.html deleted file mode 100644 index 48d476cd..00000000 --- a/doc/html/boost_optional/implementation_notes.html +++ /dev/null @@ -1,55 +0,0 @@ - - - -Implementation Notes - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- 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/move constructor and T's - destructor are explicitly used to initialize, copy, move 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. -

-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/in_place_factories.html b/doc/html/boost_optional/in_place_factories.html deleted file mode 100644 index 1cc1e05f..00000000 --- a/doc/html/boost_optional/in_place_factories.html +++ /dev/null @@ -1,196 +0,0 @@ - - - -In-Place Factories - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- One of the typical problems with wrappers and containers is that their interfaces - usually provide an operation to initialize or assign the contained object as - a copy of some other object. This not only requires the underlying type to - be Copy Constructible, - but also requires the existence of a fully constructed object, often temporary, - just to follow the copy from: -

-
struct X
-{
-    X ( int, std::string ) ;
-} ;
-
-class W
-{
-    X wrapped_ ;
-
-    public:
-
-    W ( X const& x ) : wrapped_(x) {}
-} ;
-
-void foo()
-{
-    // Temporary object created.
-    W ( X(123,"hello") ) ;
-}
-
-

- A solution to this problem is to support direct construction of the contained - object right in the container's storage. In this scheme, the user only needs - to supply the arguments to the constructor to use in the wrapped object construction. -

-
class W
-{
-    X wrapped_ ;
-
-    public:
-
-    W ( X const& x ) : wrapped_(x) {}
-    W ( int a0, std::string a1) : wrapped_(a0,a1) {}
-} ;
-
-void foo()
-{
-    // Wrapped object constructed in-place
-    // No temporary created.
-    W (123,"hello") ;
-}
-
-

- A limitation of this method is that it doesn't scale well to wrapped objects - with multiple constructors nor to generic code were the constructor overloads - are unknown. -

-

- The solution presented in this library is the family of InPlaceFactories - and TypedInPlaceFactories. These factories - are a family of classes which encapsulate an increasing number of arbitrary - constructor parameters and supply a method to construct an object of a given - type using those parameters at an address specified by the user via placement - new. -

-

- For example, one member of this family looks like: -

-
template<class T,class A0, class A1>
-class TypedInPlaceFactory2
-{
-    A0 m_a0 ; A1 m_a1 ;
-
-    public:
-
-    TypedInPlaceFactory2( A0 const& a0, A1 const& a1 ) : m_a0(a0), m_a1(a1) {}
-
-    void construct ( void* p ) { new (p) T(m_a0,m_a1) ; }
- } ;
-
-

- A wrapper class aware of this can use it as: -

-
class W
-{
-    X wrapped_ ;
-
-    public:
-
-    W ( X const& x ) : wrapped_(x) {}
-    W ( TypedInPlaceFactory2 const& fac ) { fac.construct(&wrapped_) ; }
-} ;
-
-void foo()
-{
-    // Wrapped object constructed in-place via a TypedInPlaceFactory.
-    // No temporary created.
-    W ( TypedInPlaceFactory2<X,int,std::string>(123,"hello")) ;
-}
-
-

- The factories are divided in two groups: -

-
    -
  • - TypedInPlaceFactories: those which - take the target type as a primary template parameter. -
    • -
  • - InPlaceFactories: those with a template - construct(void*) member - function taking the target type. -
    • -
-

- Within each group, all the family members differ only in the number of parameters - allowed. -

-

- This library provides an overloaded set of helper template functions to construct - these factories without requiring unnecessary template parameters: -

-
template<class A0,...,class AN>
-InPlaceFactoryN <A0,...,AN> in_place ( A0 const& a0, ..., AN const& aN) ;
-
-template<class T,class A0,...,class AN>
-TypedInPlaceFactoryN <T,A0,...,AN> in_place ( T const& a0, A0 const& a0, ..., AN const& aN) ;
-
-

- In-place factories can be used generically by the wrapper and user as follows: -

-
class W
-{
-    X wrapped_ ;
-
-    public:
-
-    W ( X const& x ) : wrapped_(x) {}
-
-    template< class InPlaceFactory >
-    W ( InPlaceFactory const& fac ) { fac.template <X>construct(&wrapped_) ; }
-
-} ;
-
-void foo()
-{
-    // Wrapped object constructed in-place via a InPlaceFactory.
-    // No temporary created.
-    W ( in_place(123,"hello") ) ;
-}
-
-

- The factories are implemented in the headers: in_place_factory.hpp - and typed_in_place_factory.hpp -

-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/motivation.html b/doc/html/boost_optional/motivation.html deleted file mode 100644 index ee00899c..00000000 --- a/doc/html/boost_optional/motivation.html +++ /dev/null @@ -1,128 +0,0 @@ - - - -Motivation - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- Consider these functions which should return a value but which might not have - a value to return: -

-
    -
  • - (A) double sqrt(double n ); -
    • -
  • - (B) char get_async_input(); -
    • -
  • - (C) point polygon::get_any_point_effectively_inside(); -
    • -
-

- There are different approaches to the issue of not having a value to return. -

-

- A typical approach is to consider the existence of a valid return value as - a postcondition, so that if the function cannot compute the value to return, - it has either undefined behavior (and can use assert in a debug build) or uses - a runtime check and throws an exception if the postcondition is violated. This - is a reasonable choice for example, for function (A), because the lack of a - proper return value is directly related to an invalid parameter (out of domain - argument), so it is appropriate to require the callee to supply only parameters - in a valid domain for execution to continue normally. -

-

- However, function (B), because of its asynchronous nature, does not fail just - because it can't find a value to return; so it is incorrect to consider such - a situation an error and assert or throw an exception. This function must return, - and somehow, must tell the callee that it is not returning a meaningful value. -

-

- A similar situation occurs with function (C): it is conceptually an error to - ask a null-area polygon to return a point inside itself, - but in many applications, it is just impractical for performance reasons to - treat this as an error (because detecting that the polygon has no area might - be too expensive to be required to be tested previously), and either an arbitrary - point (typically at infinity) is returned, or some efficient way to tell the - callee that there is no such point is used. -

-

- There are various mechanisms to let functions communicate that the returned - value is not valid. One such mechanism, which is quite common since it has - zero or negligible overhead, is to use a special value which is reserved to - communicate this. Classical examples of such special values are EOF, string::npos, points - at infinity, etc... -

-

- When those values exist, i.e. the return type can hold all meaningful values - plus the signal value, this mechanism - is quite appropriate and well known. Unfortunately, there are cases when such - values do not exist. In these cases, the usual alternative is either to use - a wider type, such as int in place - of char; or a compound type, such - as std::pair<point,bool>. -

-

- Returning a std::pair<T,bool>, thus attaching a boolean flag to the result - which indicates if the result is meaningful, has the advantage that can be - turned into a consistent idiom since the first element of the pair can be whatever - the function would conceptually return. For example, the last two functions - could have the following interface: -

-
std::pair<char,bool> get_async_input();
-std::pair<point,bool> polygon::get_any_point_effectively_inside();
-
-

- These functions use a consistent interface for dealing with possibly nonexistent - results: -

-
std::pair<point,bool> p = poly.get_any_point_effectively_inside();
-if ( p.second )
-    flood_fill(p.first);
-
-

- However, not only is this quite a burden syntactically, it is also error prone - since the user can easily use the function result (first element of the pair) - without ever checking if it has a valid value. -

-

- Clearly, we need a better idiom. -

-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/optional_references.html b/doc/html/boost_optional/optional_references.html deleted file mode 100644 index 5ff61bf8..00000000 --- a/doc/html/boost_optional/optional_references.html +++ /dev/null @@ -1,114 +0,0 @@ - - - -Optional references - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- This library allows the template parameter T - to be of reference type: T&, and to some extent, T - const&. -

-

- However, since references are not real objects some restrictions apply and - some operations are not available in this case: -

-
    -
  • - Converting constructors -
    • -
  • - 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 occur: -

-
    -
  • - Copies of optional<T&> - will copy the references but all these references will nonetheless refer - to the same object. -
    • -
  • - Value-access will actually provide access to the referenced object rather - than the reference itself. -
    • -
-
- - - - - -
[Warning]Warning

- On compilers that do not conform to Standard C++ rules of reference binding, - operations on optional references might give adverse results: rather than - binding a reference to a designated object they may create an unexpected - temporary and bind to it. For more details see Dependencies - and Portability section. -

-

- - Rvalue - references -

-

- Rvalue references and lvalue references to const have the ability in C++ to - extend the life time of a temporary they bind to. Optional references do not - have this capability, therefore to avoid surprising effects it is not possible - to initialize an optional references from a temporary. Optional rvalue references - are disabled altogether. Also, the initialization and assignment of an optional - reference to const from rvalue reference is disabled. -

-
const int& i = 1;            // legal
-optional<const int&> oi = 1; // illegal
-
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/quick_start.html b/doc/html/boost_optional/quick_start.html deleted file mode 100644 index 0388d430..00000000 --- a/doc/html/boost_optional/quick_start.html +++ /dev/null @@ -1,169 +0,0 @@ - - - -Quick Start - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-
-
Optional - return values
-
Optional - automatic variables
-
Optional - data members
-
Bypassing - unnecessary default construction
-
Storage - in containers
-
-
-
-

- Let's write and use a converter function that converts a std::string - to an int. It is possible that - for a given string (e.g. "cat") - there exists no value of type int - capable of representing the conversion result. We do not consider such situation - an error. We expect that the converter can be used only to check if the conversion - is possible. A natural signature for this function can be: -

-
#include <boost/optional.hpp>
-boost::optional<int> convert(const std::string& text);
-
-

- All necessary functionality can be included with one header <boost/optional.hpp>. - The above function signature means that the function can either return a - value of type int or a flag - indicating that no value of int - is available. This does not indicate an error. It is like one additional - value of int. This is how we - can use our function: -

-
const std::string& text = /*... */;
-boost::optional<int> oi = convert(text); // move-construct
-if (oi)                                  // contextual conversion to bool
-  int i = *oi;                           // operator*
-
-

- In order to test if optional - contains a value, we use the contextual conversion to type bool. Because of this we can combine the initialization - of the optional object and the test into one instruction: -

-
if (boost::optional<int> oi = convert(text))
-  int i = *oi;
-
-

- We extract the contained value with operator* (and with operator-> where it makes sense). An attempt to - extract the contained value of an uninitialized optional object is an undefined - behaviour (UB). This implementation guards the call with BOOST_ASSERT. Therefore you should be sure - that the contained value is there before extracting. For instance, the following - code is reasonably UB-safe: -

-
int i = *convert("100");
-
-

- This is because we know that string value "100" - converts to a valid value of int. - If you do not like this potential UB, you can use an alternative way of extracting - the contained value: -

-
try {
-  int j = convert(text).value();
-}
-catch (const boost::bad_optional_access&) {
-  // deal with it
-}
-
-

- This version throws an exception upon an attempt to access a nonexistent - contained value. If your way of dealing with the missing value is to use - some default, like 0, there exists - a yet another alternative: -

-
int k = convert(text).value_or(0);
-
-

- This uses the atoi-like approach - to conversions: if text does - not represent an integral number just return 0. - Finally, you can provide a callback to be called when trying to access the - contained value fails: -

-
int fallback_to_default()
-{
-  cerr << "could not convert; using -1 instead" << endl;
-  return -1;
-}
-
-int l = convert(text).value_or_eval(fallback_to_default);
-
-

- This will call the provided callback and return whatever the callback returns. - The callback can have side effects: they will only be observed when the optional - object does not contain a value. -

-

- Now, let's consider how function convert - can be implemented. -

-
boost::optional<int> convert(const std::string& text)
-{
-  std::stringstream s(text);
-  int i;
-  if ((s >> i) && s.get() == std::char_traits<char>::eof())
-    return i;
-  else
-    return boost::none;
-}
-
-

- Observe the two return statements. return - i uses the converting constructor - that can create optional<T> - from T. Thus constructed - optional object is initialized and its value is a copy of i. - The other return statement uses another converting constructor from a special - tag boost::none. It is used to indicate that we want - to create an uninitialized optional object. -

-
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/quick_start/bypassing_unnecessary_default_construction.html b/doc/html/boost_optional/quick_start/bypassing_unnecessary_default_construction.html deleted file mode 100644 index b49c8abe..00000000 --- a/doc/html/boost_optional/quick_start/bypassing_unnecessary_default_construction.html +++ /dev/null @@ -1,75 +0,0 @@ - - - -Bypassing unnecessary default construction - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- Suppose we have class Date, - which does not have a default constructor: there is no good candidate for - a default date. We have a function that returns two dates in form of a boost::tuple: -

-
boost::tuple<Date, Date> getPeriod();
-
-

- In other place we want to use the result of getPeriod, - but want the two dates to be named: begin - and end. We want to implement - something like 'multiple return values': -

-
Date begin, end; // Error: no default ctor!
-boost::tie(begin, end) = getPeriod();
-
-

- The second line works already, this is the capability of Boost.Tuple - library, but the first line won't work. We could set some invented initial - dates, but it is confusing and may be an unacceptable cost, given that these - values will be overwritten in the next line anyway. This is where optional can help: -

-
boost::optional<Date> begin, end;
-boost::tie(begin, end) = getPeriod();
-
-

- It works because inside boost::tie a - move-assignment from T is - invoked on optional<T>, - which internally calls a move-constructor of T. -

-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/quick_start/optional_automatic_variables.html b/doc/html/boost_optional/quick_start/optional_automatic_variables.html deleted file mode 100644 index e4bf47a1..00000000 --- a/doc/html/boost_optional/quick_start/optional_automatic_variables.html +++ /dev/null @@ -1,75 +0,0 @@ - - - -Optional automatic variables - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- We could write function convert - in a slightly different manner, so that it has a single return-statement: -

-
boost::optional<int> convert(const std::string& text)
-{
-  boost::optional<int> ans;
-  std::stringstream s(text);
-  int i;
-  if ((s >> i) && s.get() == std::char_traits<char>::eof())
-    ans = i;
-
-  return ans;
-}
-
-

- The default constructor of optional - creates an uninitialized optional object. Unlike with ints - you cannot have an optional<int> - in an indeterminate state. Its state is always well defined. Instruction - ans = - i initializes the optional object. - It uses the 'mixed' assignment from int. - In general, for optional<T>, - when an assignment from T - is invoked, it can do two things. If the optional object is not initialized - (our case here), it initializes the contained value using T's - copy constructor. If the optional object is already initialized, it assigns - the new value to it using T's - copy assignment. -

-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/quick_start/optional_data_members.html b/doc/html/boost_optional/quick_start/optional_data_members.html deleted file mode 100644 index 32684053..00000000 --- a/doc/html/boost_optional/quick_start/optional_data_members.html +++ /dev/null @@ -1,94 +0,0 @@ - - - -Optional data members - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- Suppose we want to implement a lazy load optimization. - This is because we do not want to perform an expensive initialization of - our Resource until (if at - all) it is really used. We can do it this way: -

-
class Widget
-{
-  mutable boost::optional<const Resource> resource_;
-
-public:
-  Widget() {}
-
-  const Resource& getResource() const // not thread-safe
-  {
-    if (resource_ == boost::none)
-        resource_.emplace("resource", "arguments");
-
-    return *resource_;
-  }
-};
-
-

- optional's default constructor - creates an uninitialized optional. No call to Resource's - default constructor is attempted. Resource - doesn't have to be DefaultConstructible. In function - getResource we first check - if resource_ is initialized. - This time we do not use the contextual conversion to bool, - but a comparison with boost::none. - These two ways are equivalent. Function emplace - initializes the optional in-place by perfect-forwarding the arguments to - the constructor of Resource. - No copy- or move-construction is involved here. Resource - doesn't even have to be MoveConstructible. -

-
- - - - - -
[Note]Note

- Function emplace is only - available on compilers that support rvalue references and variadic templates. - If your compiler does not support these features and you still need to - avoid any move-constructions, use In-Place - Factories. -

-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/quick_start/optional_return_values.html b/doc/html/boost_optional/quick_start/optional_return_values.html deleted file mode 100644 index b9953e7e..00000000 --- a/doc/html/boost_optional/quick_start/optional_return_values.html +++ /dev/null @@ -1,135 +0,0 @@ - - - -Optional return values - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- Let's write and use a converter function that converts an a std::string - to an int. It is possible that - for a given string (e.g. "cat") - there exist no value of type int - capable of representing the conversion result. We do not consider such situation - an error. We expect that the converter can be used only to check if the conversion - is possible. A natural signature for this function can be: -

-
#include <boost/optional.hpp>
-boost::optional<int> convert(const std::string& text);
-
-

- All necessary functionality can be included with one header <boost/optional.hpp>. - The above function signature means that the function can either return a - value of type int or a flag - indicating that no value of int - is available. This does not indicate an error. It is like one additional - value of int. This is how we - can use our function: -

-
const std::string& text = /*... */;
-boost::optional<int> oi = convert(text); // move-construct
-if (oi)                                 // contextual conversion to bool
-  int i = *oi;                          // operator*
-
-

- In order to test if optional - contains a value, we use the contextual conversion to type bool. Because of this we can combine the initialization - of the optional object and the test into one instruction: -

-
if (boost::optional<int> oi = convert(text))
-  int i = *oi;
-
-

- We extract the contained value with operator* (and with operator-> where it makes sense). An attempt to - extract the contained value of an uninitialized optional object is an undefined - behaviour (UB). This implementation guards the call with BOOST_ASSERT. Therefore you should be sure - that the contained value is there before extracting. For instance, the following - code is reasonably UB-safe: -

-
int i = *convert("100");
-
-

- This is because we know that string value "100" - converts to a valid value of int. - If you do not like this potential UB, you can use an alternative way of extracting - the contained value: -

-
try {
-  int j = convert(text).value();
-}
-catch (const boost::bad_optional_access&) {
-  // deal with it
-}
-
-

- This version throws an exception upon an attempt to access a nonexistent - contained value. If your way of dealing with the missing value is to use - some default, like 0, there exists - a yet another alternative: -

-
int k = convert(text).value_or(0);
-
-

- This uses the atoi-like approach - to conversions: if text does - not represent an integral number just return 0. - Now, let's consider how function convert - can be implemented. -

-
boost::optional<int> convert(const std::string& text)
-{
-  std::stringstream s(text);
-  int i;
-  if ((s >> i) && s.get() == std::char_traits<char>::eof())
-    return i;
-  else
-    return boost::none;
-}
-
-

- Observe the two return statements. return - i uses the converting constructor - that can create optional<T> - from T. Thus constructed - optional object is initialized and its value is a copy of i. - The other return statement uses another converting constructor from a special - tag boost::none. It is used to indicate that we want - to create an uninitialized optional object. -

-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/quick_start/storage_in_containers.html b/doc/html/boost_optional/quick_start/storage_in_containers.html deleted file mode 100644 index 95809140..00000000 --- a/doc/html/boost_optional/quick_start/storage_in_containers.html +++ /dev/null @@ -1,64 +0,0 @@ - - - -Storage in containers - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- Suppose you want to ask users to choose some number (an int). - One of the valid responses is to choose nothing, which is represented by - an uninitialized optional<int>. - You want to make a histogram showing how many times each choice was made. - You can use an std::map: -

-
std::map<boost::optional<int>, int> choices;
-
-for (int i = 0; i < LIMIT; ++i) {
-  boost::optional<int> choice = readChoice();
-  ++choices[choice];
-}
-
-

- This works because optional<T> - is LessThanComparable whenever T is LessThanComparable. In this case - the state of being uninitialized is treated as a yet another value of T, which is compared less than any value - of T. -

-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/rebinding_semantics_for_assignment_of_optional_references.html b/doc/html/boost_optional/rebinding_semantics_for_assignment_of_optional_references.html deleted file mode 100644 index bfcba148..00000000 --- a/doc/html/boost_optional/rebinding_semantics_for_assignment_of_optional_references.html +++ /dev/null @@ -1,148 +0,0 @@ - - - -Rebinding semantics for assignment of optional references - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- If you assign to an uninitialized optional<T&> - the effect is to bind (for the first time) to the object. Clearly, there is - no other choice. -

-
int x = 1 ;
-int& rx = x ;
-optional<int&> ora ;
-optional<int&> orb(x) ;
-ora = orb ; // now 'ora' is bound to 'x' through 'rx'
-*ora = 2 ; // Changes value of 'x' through 'ora'
-assert(x==2);
-
-

- If you assign to a bare C++ reference, the assignment is forwarded to the referenced - object; its value changes but the reference is never rebound. -

-
int a = 1 ;
-int& ra = a ;
-int b = 2 ;
-int& rb = b ;
-ra = rb ; // Changes the value of 'a' to 'b'
-assert(a==b);
-b = 3 ;
-assert(ra!=b); // 'ra' is not rebound to 'b'
-
-

- Now, if you assign to an initialized optional<T&>, - the effect is to rebind to the new object - instead of assigning the referee. This is unlike bare C++ references. -

-
int a = 1 ;
-int b = 2 ;
-int& ra = a ;
-int& rb = b ;
-optional<int&> ora(ra) ;
-optional<int&> orb(rb) ;
-ora = orb ; // 'ora' is rebound to 'b'
-*ora = 3 ; // Changes value of 'b' (not 'a')
-assert(a==1);
-assert(b==3);
-
-

- - Rationale -

-

- Rebinding semantics for the assignment of initialized - optional references has been - chosen to provide consistency among initialization states - even at the expense of lack of consistency with the semantics of bare 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 ;
-
-

- 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 consistent. -

-

- If in your code rebinding to another object is not an option, then it is very - likely that binding for the first time isn't either. In such case, assignment - to an uninitialized optional<T&> - shall be prohibited. It is quite possible that in such a scenario it is a precondition - that the lvalue must be already initialized. If it isn't, then binding for - the first time is OK while rebinding is not which is IMO very unlikely. In - such a scenario, you can assign the value itself directly, as in: -

-
assert(!!opt);
-*opt=value;
-
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/reference/acknowledgements.html b/doc/html/boost_optional/reference/acknowledgements.html deleted file mode 100644 index f5a719de..00000000 --- a/doc/html/boost_optional/reference/acknowledgements.html +++ /dev/null @@ -1,131 +0,0 @@ - - - -Acknowledgements - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHome -
-
-
-
- - Pre-formal - review -
-
    -
  • - Peter Dimov suggested the name 'optional', and was the first to point - out the need for aligned storage. -
    • -
  • - Douglas Gregor developed 'type_with_alignment', and later Eric Friedman - coded 'aligned_storage', which are the core of the optional class implementation. -
    • -
  • - Andrei Alexandrescu and Brian Parker also worked with aligned storage - techniques and their work influenced the current implementation. -
    • -
  • - Gennadiy Rozental made extensive and important comments which shaped - the design. -
    • -
  • - Vesa Karvonen and Douglas Gregor made quite useful comparisons between - optional, variant and any; and made other relevant comments. -
    • -
  • - Douglas Gregor and Peter Dimov commented on comparisons and evaluation - in boolean contexts. -
    • -
  • - Eric Friedman helped understand the issues involved with aligned storage, - move/copy operations and exception safety. -
    • -
  • - Many others have participated with useful comments: Aleksey Gurotov, - Kevlin Henney, David Abrahams, and others I can't recall. -
    • -
-
- - Post-formal - review -
-
    -
  • - William Kempf carefully considered the originally proposed interface - and suggested the new interface which is currently used. He also started - and fueled the discussion about the analogy optional<>/smart pointer - and about relational operators. -
    • -
  • - Peter Dimov, Joel de Guzman, David Abrahams, Tanton Gibbs and Ian Hanson - focused on the relational semantics of optional (originally undefined); - concluding with the fact that the pointer-like interface doesn't make - it a pointer so it shall have deep relational operators. -
    • -
  • - Augustus Saunders also explored the different relational semantics between - optional<> and a pointer and developed the OptionalPointee concept - as an aid against potential conflicts on generic code. -
    • -
  • - Joel de Guzman noticed that optional<> can be seen as an API on - top of variant<T,nil_t>. -
    • -
  • - Dave Gomboc explained the meaning and usage of the Haskell analog to - optional<>: the Maybe type constructor (analogy originally pointed - out by David Sankel). -
    • -
  • - Other comments were posted by Vincent Finn, Anthony Williams, Ed Brey, - Rob Stewart, and others. -
    • -
  • - Joel de Guzman made the case for the support of references and helped - with the proper semantics. -
    • -
  • - Mat Marcus shown the virtues of a value-oriented interface, influencing - the current design, and contributed the idea of "none". -
    • -
  • - Vladimir Batov's design of Boost.Convert library motivated the development - of value accessors for optional: - functions value, value_or, value_or_eval. -
    • -
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2016 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHome -
- - diff --git a/doc/html/boost_optional/reference/dependencies_and_portability.html b/doc/html/boost_optional/reference/dependencies_and_portability.html deleted file mode 100644 index 5128861e..00000000 --- a/doc/html/boost_optional/reference/dependencies_and_portability.html +++ /dev/null @@ -1,84 +0,0 @@ - - - -Dependencies and Portability - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-
-
-

- The implementation uses the following other Boost modules: -

-
    -
  1. - assert -
    2. -
  2. - config -
    3. -
  3. - core -
    4. -
  4. - detail -
    5. -
  5. - move -
    6. -
  6. - mpl -
    7. -
  7. - static_assert -
    8. -
  8. - throw_exception -
    9. -
  9. - type_traits -
    10. -
  10. - utility -
    11. -
-
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2016 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/reference/dependencies_and_portability/optional_reference_binding.html b/doc/html/boost_optional/reference/dependencies_and_portability/optional_reference_binding.html deleted file mode 100644 index 16c16378..00000000 --- a/doc/html/boost_optional/reference/dependencies_and_portability/optional_reference_binding.html +++ /dev/null @@ -1,100 +0,0 @@ - - - -Optional Reference Binding - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- On compilers that do not conform to Standard C++ rules of reference binding, - operations on optional references might give adverse results: rather than - binding a reference to a designated object they may create an unexpected - temporary and bind to it. Compilers known to have these deficiencies include - GCC versions 4.2, 4.3, 4.4, 4.5; QCC 4.4.2; MSVC versions 8.0, 9.0, 10.0, - 11.0, 12.0. On these compilers prefer using direct-initialization and copy - assignment of optional references to copy-initialization and assignment - from T&: -

-
const int i = 0;
-optional<const int&> or1;
-optional<const int&> or2 = i;  // not portable
-or1 = i;                       // not portable
-
-optional<const int&> or3(i);   // portable
-or1 = optional<const int&>(i); // portable
-
-

- In order to check if your compiler correctly implements reference binding - use this test program. -

-
#include <cassert>
-
-const int global_i = 0;
-
-struct TestingReferenceBinding
-{
-  TestingReferenceBinding(const int& ii)
-  {
-    assert(&ii == &global_i);
-  }
-
-  void operator=(const int& ii)
-  {
-    assert(&ii == &global_i);
-  }
-
-  void operator=(int&&) // remove this if your compiler doesn't have rvalue refs
-  {
-    assert(false);
-  }
-};
-
-int main()
-{
-  const int& iref = global_i;
-  assert(&iref == &global_i);
-
-  TestingReferenceBinding ttt = global_i;
-  ttt = global_i;
-
-  TestingReferenceBinding ttt2 = iref;
-  ttt2 = iref;
-}
-
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2016 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/reference/header__boost_optional_bad_optional_access_hpp_.html b/doc/html/boost_optional/reference/header__boost_optional_bad_optional_access_hpp_.html deleted file mode 100644 index f5b40337..00000000 --- a/doc/html/boost_optional/reference/header__boost_optional_bad_optional_access_hpp_.html +++ /dev/null @@ -1,63 +0,0 @@ - - - -Header <boost/optional/bad_optional_access.hpp> - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-
-
-

-

-
namespace boost {
-
-class bad_optional_access : public std::logic_error
-{
-public:
-    bad_optional_access(); R
-};
-
-} // namespace boost
-
-

-

-
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/reference/header__boost_optional_bad_optional_access_hpp_/detailed_semantics.html b/doc/html/boost_optional/reference/header__boost_optional_bad_optional_access_hpp_/detailed_semantics.html deleted file mode 100644 index eea25e98..00000000 --- a/doc/html/boost_optional/reference/header__boost_optional_bad_optional_access_hpp_/detailed_semantics.html +++ /dev/null @@ -1,60 +0,0 @@ - - - -Detailed semantics - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- space -

-

- bad_optional_access(); -

-
    -
  • - Effect: Constructs an object of class - bad_optional_access. -
    • -
  • - Postconditions: what() returns an implementation-defined - NTBS. -
    • -
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/reference/header__boost_optional_hpp_.html b/doc/html/boost_optional/reference/header__boost_optional_hpp_.html deleted file mode 100644 index 8390a062..00000000 --- a/doc/html/boost_optional/reference/header__boost_optional_hpp_.html +++ /dev/null @@ -1,47 +0,0 @@ - - - -Header <boost/optional.hpp> - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- This is an alias for header <boost/optional/optional.hpp>. -

-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/reference/header__boost_optional_optional_fwd_hpp_.html b/doc/html/boost_optional/reference/header__boost_optional_optional_fwd_hpp_.html deleted file mode 100644 index 45d55b27..00000000 --- a/doc/html/boost_optional/reference/header__boost_optional_optional_fwd_hpp_.html +++ /dev/null @@ -1,66 +0,0 @@ - - - -Header <boost/optional/optional_fwd.hpp> - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-
-
-

-

-
namespace boost {
-
-template <class T> class optional ;
-
-template <class T> void swap ( optional<T>& , optional<T>& );
-
-template <class T> struct optional_swap_should_use_default_constructor ;
-
-} // namespace boost
-
-

-

-

- This header only contains declarations. -

-
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics.html b/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics.html deleted file mode 100644 index 2b6f9eb4..00000000 --- a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics.html +++ /dev/null @@ -1,2423 +0,0 @@ - - - -Detailed Semantics - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- Because T might be of reference - type, in the sequel, those entries whose semantic depends on T being of reference type or not will - be distinguished using the following convention: -

-
    -
  • - If the entry reads: optional<T(not - a ref)>, - the description corresponds only to the case where T - is not of reference type. -
    • -
  • - If the entry reads: optional<T&>, the description corresponds - only to the case where T - is of reference type. -
    • -
  • - If the entry reads: optional<T>, the description is the same for - both cases. -
    • -
-
- - - - - -
[Note]Note

- The following section contains various assert() which are used only to show the postconditions - as sample code. It is not implied that the type T - must support each particular expression but that if the expression is - supported, the implied condition holds. -

-

- space -

-
- - optional - class member functions -
-

- space -

-

- optional<T>::optional() - noexcept; -

-
    -
  • - Effect: Default-Constructs an optional. -
    • -
  • - Postconditions: *this is uninitialized. -
    • -
  • - Notes: T's default constructor is not called. -
    • -
  • - Example: -
    optional<T> def ;
-assert ( !def ) ;
-
    -
    • -
-

- space -

-

- optional<T>::optional( - none_t ) - noexcept; -

-
    -
  • - Effect: Constructs an optional uninitialized. -
    • -
  • - Postconditions: *this is uninitialized. -
    • -
  • - Notes: T's - default constructor is not called. - The expression boost::none - denotes an instance of boost::none_t - that can be used as the parameter. -
    • -
  • - Example: -
    #include <boost/none.hpp>
-optional<T> n(none) ;
-assert ( !n ) ;
-
    -
    • -
-

- space -

-

- optional<T (not a ref)>::optional( T const& v ) -

-
    -
  • - Requires: is_copy_constructible<T>::value - is true. -
    • -
  • - Effect: Directly-Constructs an optional. -
    • -
  • - Postconditions: *this is initialized - and its value is a copy of v. -
    • -
  • - Throws: Whatever T::T( T const& - ) throws. -
    • -
  • - Notes: T::T( T const& - ) is called. -
    • -
  • - Exception Safety: Exceptions can only - be thrown during T::T( T const& - ); in that case, this constructor - has no effect. -
    • -
  • - Example: -
    T v;
-optional<T> opt(v);
-assert ( *opt == v ) ;
-
    -
    • -
-

- space -

-

- optional<T&>::optional( - T& - ref ) -

-
    -
  • - Effect: Directly-Constructs an optional. -
    • -
  • - Postconditions: *this is initialized - and its value is an instance of an internal type wrapping the reference - ref. -
    • -
  • - Throws: Nothing. -
    • -
  • - Example: -
    T v;
-T& vref = v ;
-optional<T&> opt(vref);
-assert ( *opt == v ) ;
-++ v ; // mutate referee
-assert (*opt == v);
-
    -
    • -
-

- space -

-

- optional<T (not a ref)>::optional( T&& v - ) -

-
    -
  • - Requires: is_move_constructible<T>::value - is true. -
    • -
  • - Effect: Directly-Move-Constructs an - optional. -
    • -
  • - Postconditions: *this is initialized - and its value is move-constructed from v. -
    • -
  • - Throws: Whatever T::T( T&& ) - throws. -
    • -
  • - Notes: T::T( T&& ) - is called. -
    • -
  • - Exception Safety: Exceptions can only - be thrown during T::T( T&& ); - in that case, the state of v - is determined by exception safety guarantees for T::T(T&&). -
    • -
  • - Example: -
    T v1, v2;
-optional<T> opt(std::move(v1));
-assert ( *opt == v2 ) ;
-
    -
    • -
-

- space -

-

- optional<T&>::optional( - T&& - ref ) - = delete -

-
  • - Notes: This constructor is deleted -
-

- space -

-

- optional<T (not a ref)>::optional( bool condition, - T const& v ) ; -

-

- optional<T&> - ::optional( bool condition, - T& - v ) - ; -

-
  • - If condition is true, same as: -
-

- optional<T (not a ref)>::optional( T const& v ) -

-

- optional<T&> - ::optional( T& v ) -

-
  • - otherwise, same as: -
-

- optional<T (not a ref)>::optional() -

-

- optional<T&> - ::optional() -

-

- space -

-

- optional<T (not a ref)>::optional( optional - const& - rhs ); -

-
    -
  • - Requires: is_copy_constructible<T>::value - is true. -
    • -
  • - Effect: Copy-Constructs an optional. -
    • -
  • - Postconditions: If rhs is initialized, - *this - is initialized and its value is a copy of the - value of rhs; else - *this - is uninitialized. -
    • -
  • - Throws: Whatever T::T( T const& - ) throws. -
    • -
  • - Notes: If rhs is initialized, T::T(T const& ) - is called. -
    • -
  • - Exception Safety: Exceptions can only - be thrown during T::T( T const& - ); in that case, this constructor - has no effect. -
    • -
  • - Example: -
    optional<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 ) ;
-
    -
    • -
-

- space -

-

- optional<T&>::optional( - optional const& rhs - ); -

-
    -
  • - Effect: Copy-Constructs an optional. -
    • -
  • - Postconditions: If rhs - is initialized, *this - is initialized and its value is another reference to the same object - referenced by *rhs; - else *this - is uninitialized. -
    • -
  • - Throws: Nothing. -
    • -
  • - Notes: If rhs - is initialized, both *this and *rhs will refer to the same object - (they alias). -
    • -
  • - Example: -
    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 ) ;
-
    -
    • -
-

- space -

-

- optional<T (not a ref)>::optional( optional&& rhs - ) noexcept(see below); -

-
    -
  • - Requires: is_move_constructible<T>::value - is true. -
    • -
  • - Effect: Move-constructs an optional. -
    • -
  • - Postconditions: If rhs - is initialized, *this - is initialized and its value is move constructed from rhs; else *this is uninitialized. -
    • -
  • - Throws: Whatever T::T( T&& ) - throws. -
    • -
  • - Remarks: The expression inside noexcept is equivalent to is_nothrow_move_constructible<T>::value. -
    • -
  • - Notes: If rhs - is initialized, T::T( T && - ) is called. -
    • -
  • - Exception Safety: Exceptions can only - be thrown during T::T( T&& ); - in that case, rhs remains - initialized and the value of *rhs is determined by exception safety - of T::T(T&&). -
    • -
  • - Example: -
    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::unique_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) ) ;
-
    -
    • -
-

- space -

-

- optional<T&>::optional( - optional && - rhs ); -

-
    -
  • - Effect: Move-Constructs an optional. -
    • -
  • - Postconditions: If rhs - is initialized, *this - is initialized and its value is another reference to the same object - referenced by *rhs; - else *this - is uninitialized. -
    • -
  • - Throws: Nothing. -
    • -
  • - Notes: If rhs - is initialized, both *this and *rhs will refer to the same object - (they alias). -
    • -
  • - Example: -
    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 ) ;
-
    -
    • -
-

- space -

-

- template<U> explicit optional<T - (not a ref)>::optional( - optional<U> const& rhs ); -

-
    -
  • - Effect: Copy-Constructs an optional. -
    • -
  • - Postconditions: If rhs - is initialized, *this - is initialized and its value is a copy of the - value of rhs converted to type T; - else *this - is uninitialized. -
    • -
  • - Throws: Whatever T::T( U const& - ) throws. -
    • -
  • - Notes: T::T( U const& - ) is called if rhs is initialized, which requires - a valid conversion from U - to T. -
    • -
  • - Exception Safety: Exceptions can only - be thrown during T::T( U const& - ); in that case, this constructor - has no effect. -
    • -
  • - Example: -
    optional<double> x(123.4);
-assert ( *x == 123.4 ) ;
-
-optional<int> y(x) ;
-assert( *y == 123 ) ;
-
    -
    • -
-

- space -

-

- template<U> explicit optional<T - (not a ref)>::optional( - optional<U>&& - rhs ); -

-
    -
  • - Effect: Move-constructs an optional. -
    • -
  • - Postconditions: If rhs - is initialized, *this - is initialized and its value is move-constructed from *rhs; - else *this - is uninitialized. -
    • -
  • - Throws: Whatever T::T( U&& ) - throws. -
    • -
  • - Notes: T::T( U&& ) - is called if rhs is - initialized, which requires a valid conversion from U - to T. -
    • -
  • - Exception Safety: Exceptions can only - be thrown during T::T( U&& ); - in that case, rhs remains - initialized and the value of *rhs is determined by exception safety - guarantee of T::T( U&& - ). -
    • -
  • - Example: -
    optional<double> x(123.4);
-assert ( *x == 123.4 ) ;
-
-optional<int> y(std::move(x)) ;
-assert( *y == 123 ) ;
-
    -
    • -
-

- space -

-

- template<InPlaceFactory> - explicit optional<T - (not a ref)>::optional( - InPlaceFactory const& f ); -

-

- template<TypedInPlaceFactory> - explicit optional<T - (not a ref)>::optional( - TypedInPlaceFactory const& f ); -

-
    -
  • - Effect: Constructs an optional with a value of T obtained from the factory. -
    • -
  • - Postconditions: *this is initialized - and its value is directly given from the factory - f (i.e., the value - is not copied). -
    • -
  • - Throws: Whatever the T constructor called by the factory - throws. -
    • -
  • - Notes: See In-Place - Factories -
    • -
  • - Exception Safety: Exceptions can only - be thrown during the call to the T - constructor used by the factory; in that case, this constructor has - no effect. -
    • -
  • - Example: -
    class C { C ( char, double, std::string ) ; } ;
-
-C v('A',123.4,"hello");
-
-optional<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 ) ;
-
    -
    • -
-

- space -

-

- optional& - optional<T>::operator= ( none_t - ) noexcept; -

-
    -
  • - Effect: If *this is initialized destroys its contained - value. -
    • -
  • - Postconditions: *this is uninitialized. -
    • -
-

- space -

-

- optional& - optional<T (not a ref)>::operator= ( T - const& - rhs ) - ; -

-
    -
  • - Effect: Assigns the value rhs to an optional. -
    • -
  • - Postconditions: *this is initialized and its value is - a copy of rhs. -
    • -
  • - Throws: Whatever T::operator=( T const& - ) or T::T(T const&) - throws. -
    • -
  • - Notes: If *this was initialized, T's assignment operator is used, - otherwise, its copy-constructor is used. -
    • -
  • - Exception Safety: In the event of - an exception, the initialization state of *this is unchanged and its value unspecified - as far as optional - is concerned (it is up to T's - operator=()). - If *this - is initially uninitialized and T's - copy constructor fails, *this is left properly uninitialized. -
    • -
  • - Example: -
    T x;
-optional<T> def ;
-optional<T> opt(x) ;
-
-T y;
-def = y ;
-assert ( *def == y ) ;
-opt = y ;
-assert ( *opt == y ) ;
-
    -
    • -
-

- space -

-

- optional<T&>& - optional<T&>::operator= ( T& rhs - ) ; -

-
    -
  • - Effect: (Re)binds the wrapped reference. -
    • -
  • - Postconditions: *this is initialized and it references - the same object referenced by rhs. -
    • -
  • - Notes: If *this was initialized, it is rebound - to the new object. See here - for details on this behavior. -
    • -
  • - Example: -
    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 ) ;
-
    -
    • -
-

- space -

-

- optional& - optional<T (not a ref)>::operator= ( T&& rhs - ) ; -

-
    -
  • - Effect: Moves the value rhs to an optional. -
    • -
  • - Postconditions: *this is initialized and its value is - moved from rhs. -
    • -
  • - Throws: Whatever T::operator=( T&& ) - or T::T(T &&) - throws. -
    • -
  • - Notes: If *this was initialized, T's move-assignment operator is used, - otherwise, its move-constructor is used. -
    • -
  • - Exception Safety: In the event of - an exception, the initialization state of *this is unchanged and its value unspecified - as far as optional - is concerned (it is up to T's - operator=()). - If *this - is initially uninitialized and T's - move constructor fails, *this is left properly uninitialized. -
    • -
  • - Example: -
    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 ) ;
-
    -
    • -
-

- space -

-

- optional<T&>& - optional<T&>::operator= ( T&& rhs - ) = - delete; -

-
  • - Notes: This assignment operator is - deleted. -
-

- space -

-

- optional& - optional<T (not a ref)>::operator= ( optional - const& - rhs ) - ; -

-
    -
  • - Requires: T - is CopyConstructible and CopyAssignable. -
    • -
  • -

    - Effects: -

    -
    ----- - - - - - - - - - - - - - - - - - - -
    - -

    - *this contains a value -

    -     		-

    - *this does not contain a value -

    -
    -

    - 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 -

    -
    -

    - rhs - does not contain a value -

    -     		-

    - destroys the contained value by calling val->T::~T() -

    -     		-

    - no effect -

    -
    -
    • -
  • - Returns: *this; -
    • -
  • - Postconditions: bool(rhs) == bool(*this). -
    • -
  • - Exception Safety: If any exception - is thrown, the initialization state of *this and rhs - remains unchanged. If an exception is thrown during the call to T's copy constructor, no effect. - 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. -
    • -
  • - Example: -
    T v;
-optional<T> opt(v);
-optional<T> def ;
-
-opt = def ;
-assert ( !def ) ;
-// previous value (copy of 'v') destroyed from within 'opt'.
-
    -
    • -
-

- space -

-

- optional<T&> - & optional<T&>::operator= ( optional<T&> const& rhs - ) ; -

-
    -
  • - Effect: (Re)binds thee wrapped reference. -
    • -
  • - Postconditions: If *rhs is initialized, *this - is initialized and it references the same object referenced by *rhs; - otherwise, *this - is uninitialized (and references no object). -
    • -
  • - Notes: If *this was initialized and so is *rhs, - *this - is rebound to the new object. See here - for details on this behavior. -
    • -
  • - Example: -
    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 ) ;
-
    -
    • -
-

- space -

-

- optional& - optional<T (not a ref)>::operator= ( optional&& rhs - ) noexcept(see below); -

-
    -
  • - Requires: T - is MoveConstructible - and MoveAssignable. -
    • -
  • -

    - Effects: -

    -
    ----- - - - - - - - - - - - - - - - - - - -
    - -

    - *this contains a value -

    -     		-

    - *this does not contain a value -

    -
    -

    - 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) -

    -
    -

    - rhs - does not contain a value -

    -     		-

    - destroys the contained value by calling val->T::~T() -

    -     		-

    - no effect -

    -
    -
    • -
  • - Returns: *this; -
    • -
  • - Postconditions: bool(rhs) == bool(*this). -
    • -
  • - Remarks: The expression inside noexcept is equivalent to is_nothrow_move_constructible<T>::value && - is_nothrow_move_assignable<T>::value. -
    • -
  • - Exception Safety: If any exception - is thrown, the initialization state of *this and rhs - remains unchanged. If an exception is thrown during the call to T's move constructor, the state of - *rhs - is determined by the exception safety guarantee 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. -
    • -
  • - Example: -
    optional<T> opt(T(2)) ;
-optional<T> def ;
-
-opt = def ;
-assert ( def ) ;
-assert ( opt ) ;
-assert ( *opt == T(2) ) ;
-
    -
    • -
-

- space -

-

- optional<T&> - & optional<T&>::operator= ( optional<T&>&& rhs - ) ; -

-
  • - Effect: Same as optional<T&>::operator= ( optional<T&> - const& - rhs ). -
-

- space -

-

- template<U> optional& - optional<T (not a ref)>::operator= ( optional<U> const& rhs - ) ; -

-
    -
  • -

    - Effect: -

    -
    ----- - - - - - - - - - - - - - - - - - - -
    - -

    - *this contains a value -

    -     		-

    - *this does not contain a value -

    -
    -

    - 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 -

    -
    -

    - rhs - does not contain a value -

    -     		-

    - destroys the contained value by calling val->T::~T() -

    -     		-

    - no effect -

    -
    -
    • -
  • - Returns: *this. -
    • -
  • - Postconditions: bool(rhs) == bool(*this). -
    • -
  • - Exception Safety: If any exception - is thrown, the result of the expression bool(*this) remains unchanged. If an exception - is thrown during the call to T's - constructor, no effect. 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. -
    • -
  • - Example: -
    T v;
-optional<T> opt0(v);
-optional<U> opt1;
-
-opt1 = opt0 ;
-assert ( *opt1 == static_cast<U>(v) ) ;
-
    -
    • -
-

- space -

-

- template<U> optional& - optional<T (not a ref)>::operator= ( optional<U>&& rhs - ) ; -

-
    -
  • -

    - Effect: -

    -
    ----- - - - - - - - - - - - - - - - - - - -
    - -

    - *this contains a value -

    -     		-

    - *this does not contain a value -

    -
    -

    - 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) -

    -
    -

    - rhs - does not contain a value -

    -     		-

    - destroys the contained value by calling val->T::~T() -

    -     		-

    - no effect -

    -
    -
    • -
  • - Returns: *this. -
    • -
  • - Postconditions: bool(rhs) == bool(*this). -
    • -
  • - Exception Safety: If any exception - is thrown, the result of the expression bool(*this) remains unchanged. If an exception - is thrown during the call to T's - constructor, no effect. 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. -
    • -
  • - Example: -
    T v;
-optional<T> opt0(v);
-optional<U> opt1;
-
-opt1 = std::move(opt0) ;
-assert ( opt0 );
-assert ( opt1 )
-assert ( *opt1 == static_cast<U>(v) ) ;
-
    -
    • -
-

- space -

-

- template<class... Args> - void optional<T - (not a ref)>::emplace( - Args...&& - args ); -

-
    -
  • - Requires: The compiler supports rvalue - references and variadic templates. -
    • -
  • - Effect: If *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).... -
    • -
  • - Postconditions: *this is initialized. -
    • -
  • - Throws: Whatever the selected T's constructor throws. -
    • -
  • - Exception Safety: If an exception - is thrown during the initialization of T, - *this - is uninitialized. -
    • -
  • - Notes: T - need not be MoveConstructible - or MoveAssignable. - On compilers that do not support variadic templates, the signature - falls back to two overloads:template<class - Arg> - void emplace(Arg&& arg) and void - emplace(). - On compilers that do not support rvalue references, the signature falls - back to three overloads: taking const - and non-const lvalue reference, - and third with empty function argument list. -
    • -
  • - Example: -
    T v;
-optional<const T> opt;
-opt.emplace(0);  // create in-place using ctor T(int)
-opt.emplace();   // destroy previous and default-construct another T
-opt.emplace(v);  // destroy and copy-construct in-place (no assignment called)
-
    -
    • -
-

- space -

-

- 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 ); -

-
    -
  • - Effect: Assigns an optional - with a value of T obtained - from the factory. -
    • -
  • - Postconditions: *this is initialized - and its value is directly given from the factory - f (i.e., the value - is not copied). -
    • -
  • - Throws: Whatever the T constructor called by the factory - throws. -
    • -
  • - Notes: See In-Place - Factories -
    • -
  • - Exception Safety: Exceptions can only - be thrown during the call to the T - constructor used by the factory; in that case, the optional - object will be reset to be uninitialized. -
    • -
-

- space -

-

- void optional<T - (not a ref)>::reset( T const& v ) ; -

-
  • - Deprecated: same as operator= - ( T - const& - v) - ; -
-

- space -

-

- void optional<T>::reset() noexcept - ; -

-
  • - Deprecated: Same as operator=( - none_t ); -
-

- space -

-

- 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)> - &) ; -

-
    -
  • - Requires: *this is initialized -
    • -
  • - Returns: A reference to the contained - value -
    • -
  • - Throws: Nothing. -
    • -
  • - Notes: The requirement is asserted - via BOOST_ASSERT(). -
    • -
-

- space -

-

- T const& optional<T&>::get() const ; -

-

- T& - optional<T&>::get() ; -

-

- inline T - const& - get ( - optional<T&> - const& - ) ; -

-

- inline T& get - ( optional<T&> &) - ; -

-
    -
  • - Requires: *this is initialized -
    • -
  • - Returns: The - reference contained. -
    • -
  • - Throws: Nothing. -
    • -
  • - Notes: The requirement is asserted - via BOOST_ASSERT(). -
    • -
-

- space -

-

- T const& optional<T - (not a ref)>::operator*() - const& - ; -

-

- T& - optional<T (not a ref)>::operator*() &; -

-
    -
  • - Requires: *this is initialized -
    • -
  • - Returns: A reference to the contained - value -
    • -
  • - Throws: Nothing. -
    • -
  • - 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. -
    • -
  • - Example: -
    T v ;
-optional<T> opt ( v );
-T const& u = *opt;
-assert ( u == v ) ;
-T w ;
-*opt = w ;
-assert ( *opt == w ) ;
-
    -
    • -
-

- space -

-

- T&& - optional<T (not a ref)>::operator*() &&; -

-
    -
  • - Requires: *this contains a value. -
    • -
  • - Effects: Equivalent to return std::move(*val);. -
    • -
  • - Notes: The requirement is asserted - via BOOST_ASSERT(). - On compilers that do not support ref-qualifiers on member functions - this overload is not present. -
    • -
-

- space -

-

- T & - optional<T&>::operator*() - const& - ; -

-

- T & - optional<T&>::operator*() - & ; -

-

- T & - optional<T&>::operator*() - && ; -

-
    -
  • - Requires: *this is initialized -
    • -
  • - Returns: The - reference contained. -
    • -
  • - Throws: Nothing. -
    • -
  • - Notes: The requirement is asserted - via 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. -
    • -
  • - Example: -
    T v ;
-T& vref = v ;
-optional<T&> opt ( vref );
-T const& vref2 = *opt;
-assert ( vref2 == v ) ;
-++ v ;
-assert ( *opt == v ) ;
-
    -
    • -
-

- space -

-

- T const& optional<T>::value() const& ; -

-

- T& - optional<T>::value() & ; -

-
    -
  • - Effects: Equivalent to return bool(*this) ? *val : throw bad_optional_access();. -
    • -
  • - 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. -
    • -
  • - Example: -
    T v ;
-optional<T> o0, o1 ( v );
-assert ( o1.value() == v );
-
-try {
-  o0.value(); // throws
-  assert ( false );
-}
-catch(bad_optional_access&) {
-  assert ( true );
-}
-
    -
    • -
-

- space -

-

- T&& - optional<T>::value() && ; -

-
    -
  • - Effects: Equivalent to return bool(*this) ? std::move(*val) : throw bad_optional_access();. -
    • -
  • - Notes: On compilers that do not support - ref-qualifiers on member functions this overload is not present. -
    • -
-

- space -

-

- template<class U> T optional<T>::value_or(U && - v) - const& - ; -

-
    -
  • - Effects: Equivalent to if (*this) return **this; else return - std::forward<U>(v);. -
    • -
  • - Remarks: If T - is not CopyConstructible or U && - is not convertible to T, - the program is ill-formed. -
    • -
  • - 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&. -
    • -
-

- space -

-

- template<class U> T optional<T>::value_or(U && - v) - && ; -

-
    -
  • - Effects: Equivalent to if (*this) return std::move(**this); else return std::forward<U>(v);. -
    • -
  • - Remarks: If T - is not MoveConstructible - or U && - is not convertible to T, - the program is ill-formed. -
    • -
  • - Notes: On compilers that do not support - ref-qualifiers on member functions this overload is not present. -
    • -
-

- space -

-

- template<class F> T optional<T>::value_or_eval(F f) const& ; -

-
    -
  • - Requires: T - is CopyConstructible and F models a Generator whose result type - is convertible to T. -
    • -
  • - Effects: if - (*this) return **this; else return f();. -
    • -
  • - Notes: On compilers that do not support - ref-qualifiers on member functions this overload is replaced with the - const-qualified member - function. -
    • -
  • - Example: -
    int complain_and_0()
-{
-  clog << "no value returned, using default" << endl;
-  return 0;
-}
-
-optional<int> o1 = 1;
-optional<int> oN = none;
-
-int i = o1.value_or_eval(complain_and_0); // fun not called
-assert (i == 1);
-
-int j = oN.value_or_eval(complain_and_0); // fun called
-assert (i == 0);
-
    -
    • -
-

- space -

-

- template<class F> T optional<T>::value_or_eval(F f) && - ; -

-
    -
  • - Requires: T - is MoveConstructible - and F models a Generator - whose result type is convertible to T. -
    • -
  • - Effects: if - (*this) return std::move(**this); else return - f();. -
    • -
  • - Notes: On compilers that do not support - ref-qualifiers on member functions this overload is not present. -
    • -
-

- space -

-

- 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 ) - ; -

-
    -
  • - Deprecated: Use value_or() instead. -
    • -
  • - 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 ) ;
-
    -
    • -
-

- space -

-

- 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)> - &) ; -

-
    -
  • - Returns: If *this is initialized, a pointer to the - contained value; else 0 - (null). -
    • -
  • - Throws: Nothing. -
    • -
  • - Notes: The contained value is permanently - stored within *this, - so you should not hold nor delete this pointer -
    • -
  • - Example: -
    T v;
-optional<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) ) ;
-
    -
    • -
-

- space -

-

- T const* optional<T - (not a ref)>::operator ->() - const ; -

-

- T* - optional<T (not a ref)>::operator - ->() ; -

-
    -
  • - Requires: *this is initialized. -
    • -
  • - Returns: A pointer to the contained - value. -
    • -
  • - Throws: Nothing. -
    • -
  • - Notes: The requirement is asserted - via BOOST_ASSERT(). -
    • -
  • - Example: -
    struct X { int mdata ; } ;
-X x ;
-optional<X> opt (x);
-opt->mdata = 2 ;
-
    -
    • -
-

- space -

-

- explicit optional<T>::operator - bool() - const noexcept - ; -

-
    -
  • - Returns: get_ptr() != 0. -
    • -
  • - Notes: On compilers that do not support - explicit conversion operators this falls back to safe-bool idiom. -
    • -
  • - Example: -
    optional<T> def ;
-assert ( def == 0 );
-optional<T> opt ( v ) ;
-assert ( opt );
-assert ( opt != 0 );
-
    -
    • -
-

- space -

-

- bool optional<T>::operator!() noexcept - ; -

-
    -
  • - Returns: If *this is uninitialized, true; else false. -
    • -
  • - Notes: This operator is provided for - those compilers which can't use the unspecified-bool-type - operator in certain boolean contexts. -
    • -
  • - Example: -
    optional<T> opt ;
-assert ( !opt );
-*opt = some_T ;
-
-// Notice the "double-bang" idiom here.
-assert ( !!opt ) ;
-
    -
    • -
-

- space -

-

- bool optional<T>::is_initialized() const ; -

-
  • - Deprecated: Same as explicit operator - bool () - ; -
-

- space -

-
- - Free - functions -
-

- space -

-

- optional<T (not a ref)> make_optional( T const& v ) -

-
    -
  • - Returns: optional<T>(v) for the deduced - type T of v. -
    • -
  • - Example: -
    template<class T> void foo ( optional<T> const& opt ) ;
-
-foo ( make_optional(1+1) ) ; // Creates an optional<int>
-
    -
    • -
-

- space -

-

- optional<T (not a ref)> make_optional( bool condition, - T const& v ) -

-
    -
  • - Returns: optional<T>(condition,v) for the deduced - type T of v. -
    • -
  • - Example: -
    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");
-
    -
    • -
-

- space -

-

- bool operator - == ( - optional<T> const& x, optional<T> const& y ); -

-
    -
  • - Requires: T - shall meet requirements of EqualityComparable. -
    • -
  • - Returns: If both x - and y are initialized, - (*x - == *y). - If only x or y is initialized, false. - If both are uninitialized, true. -
    • -
  • - 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. 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 equal_pointees() - instead -
    • -
  • - Example: -
    optional<T> oN, oN_;
-optional<T> o1(T(1)), o1_(T(1));
-optional<T> o2(T(2));
-
-assert ( oN == oN );  // Identity implies equality
-assert ( o1 == o1 );  //
-
-assert ( oN == oN_ ); // Both uninitialized compare equal
-
-assert ( oN != o1 );  // Initialized unequal to initialized.
-
-assert ( o1 == o1_ ); // Both initialized compare as (*lhs == *rhs)
-assert ( o1 != o2 );  //
-
    -
    • -
-

- space -

-

- bool operator - < ( - optional<T> const& x, optional<T> const& y ); -

-
    -
  • - Requires: Expression *x < *y shall be well-formed and its result - shall be convertible to bool. -
    • -
  • - Returns: (!y) ? false : (!x) ? true : *x < - *y. -
    • -
  • - 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. 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 less_pointees() - instead. T need not - be LessThanComparable. Only - single operator< - is required. Other relational operations are defined in terms of this - one. If T's operator< - satisfies the axioms of LessThanComparable (transitivity, - antisymmetry and irreflexivity), optional<T> is LessThanComparable. -
    • -
  • - Example: -
    optional<T> oN, oN_;
-optional<T> o0(T(0));
-optional<T> o1(T(1));
-
-assert ( !(oN < oN) );  // Identity implies equivalence
-assert ( !(o1 < o1) );
-
-assert ( !(oN < oN_) ); // Two uninitialized are equivalent
-assert ( !(oN_ < oN) );
-
-assert ( oN < o0 );     // Uninitialized is less than initialized
-assert ( !(o0 < oN) );
-
-assert ( o1 < o2 ) ;    // Two initialized compare as (*lhs < *rhs)
-assert ( !(o2 < o1) ) ;
-assert ( !(o2 < o2) ) ;
-
    -
    • -
-

- space -

-

- bool operator - != ( - optional<T> const& x, optional<T> const& y ); -

-
  • - Returns: !( - x == - y ); -
-

- space -

-

- bool operator - > ( - optional<T> const& x, optional<T> const& y ); -

-
  • - Returns: ( - y < - x ); -
-

- space -

-

- bool operator - <= ( - optional<T> const& x, optional<T> const& y ); -

-
  • - Returns: !( - y < - x ); -
-

- space -

-

- bool operator - >= ( - optional<T> const& x, optional<T> const& y ); -

-
  • - Returns: !( - x < - y ); -
-

- space -

-

- bool operator - == ( - optional<T> const& x, none_t ) - noexcept; -

-

- bool operator - == ( - none_t, - optional<T> const& x ) noexcept; -

-
-

- space -

-

- bool operator - != ( - optional<T> const& x, none_t ) - noexcept; -

-

- bool operator - != ( - none_t, - optional<T> const& x ) noexcept; -

-
  • - Returns: !( - x == - y ); -
-

- space -

-

- void swap - ( optional<T>& x, optional<T>& y - ) ; -

-
    -
  • - Requires: Lvalues of type T shall be swappable and T shall be MoveConstructible. -
    • -
  • -

    - Effects: -

    -
    ----- - - - - - - - - - - - - - - - - - - -
    - -

    - *this contains a value -

    -     		-

    - *this does not contain a value -

    -
    -

    - 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 -

    -
    -

    - 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 -

    -
    -
    • -
  • - Postconditions: The states of x and y - interchanged. -
    • -
  • - Throws: If both are initialized, whatever - swap(T&,T&) - throws. If only one is initialized, whatever T::T ( T&& ) - throws. -
    • -
  • - Example: -
    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 );
-
    -
    • -
-

- space -

-

- void swap - ( optional<T&>& x, optional<T&>& y - ) noexcept - ; -

-
    -
  • - Postconditions: x - refers to what y referred - to before the swap (if anything). y - refers to whatever x - referred to before the swap. -
    • -
  • - Example: -
    T x(12);
-T y(21);
-
-optional<T&> opt0;
-optional<T&> optX (x);
-optional<T&> optY (y);
-
-boost::swap(optX, optY);
-assert (addressof(*optX) == addressof(y));
-assert (addressof(*optY) == addressof(x));
-
-boost::swap(opt0, optX);
-assert ( opt0 );
-assert ( !optX );
-assert (addressof(*opt0) == addressof(y));
-
    - [endsect] -
    • -
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2016 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics____free_functions.html b/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics____free_functions.html deleted file mode 100644 index b3c6401d..00000000 --- a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics____free_functions.html +++ /dev/null @@ -1,447 +0,0 @@ - - - -Detailed Semantics -- Free Functions - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- space -

-

- optional<T> make_optional( - T const& v ) -

-
    -
  • - Returns: optional<T>(v) for the deduced - type T of v. -
    • -
  • - Example: -
    template<class T> void foo ( optional<T> const& opt ) ;
-
-foo ( make_optional(1+1) ) ; // Creates an optional<int>
-
    -
    • -
-

- space -

-

- optional<T (not a ref)> make_optional( bool condition, - T const& v ) -

-
    -
  • - Returns: optional<T>(condition,v) for the deduced - type T of v. -
    • -
  • - Example: -
    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");
-
    -
    • -
-

- space -

-

- bool operator - == ( - optional<T> const& x, optional<T> const& y ); -

-
    -
  • - Requires: T - shall meet requirements of EqualityComparable. -
    • -
  • - Returns: If both x - and y are initialized, - (*x - == *y). - If only x or y is initialized, false. - If both are uninitialized, true. -
    • -
  • - 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. 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 equal_pointees() - instead -
    • -
  • - Example: -
    optional<T> oN, oN_;
-optional<T> o1(T(1)), o1_(T(1));
-optional<T> o2(T(2));
-
-assert ( oN == oN );  // Identity implies equality
-assert ( o1 == o1 );  //
-
-assert ( oN == oN_ ); // Both uninitialized compare equal
-
-assert ( oN != o1 );  // Initialized unequal to initialized.
-
-assert ( o1 == o1_ ); // Both initialized compare as (*lhs == *rhs)
-assert ( o1 != o2 );  //
-
    -
    • -
-

- space -

-

- bool operator - < ( - optional<T> const& x, optional<T> const& y ); -

-
    -
  • - Requires: Expression *x < *y shall be well-formed and its result - shall be convertible to bool. -
    • -
  • - Returns: (!y) ? false : (!x) ? true : *x < - *y. -
    • -
  • - 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. 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 less_pointees() - instead. T need not - be LessThanComparable. Only - single operator< - is required. Other relational operations are defined in terms of this - one. If T's operator< - satisfies the axioms of LessThanComparable (transitivity, - antisymmetry and irreflexivity), optional<T> is LessThanComparable. -
    • -
  • - Example: -
    optional<T> oN, oN_;
-optional<T> o0(T(0));
-optional<T> o1(T(1));
-
-assert ( !(oN < oN) );  // Identity implies equivalence
-assert ( !(o1 < o1) );
-
-assert ( !(oN < oN_) ); // Two uninitialized are equivalent
-assert ( !(oN_ < oN) );
-
-assert ( oN < o0 );     // Uninitialized is less than initialized
-assert ( !(o0 < oN) );
-
-assert ( o1 < o2 ) ;    // Two initialized compare as (*lhs < *rhs)
-assert ( !(o2 < o1) ) ;
-assert ( !(o2 < o2) ) ;
-
    -
    • -
-

- space -

-

- bool operator - != ( - optional<T> const& x, optional<T> const& y ); -

-
  • - Returns: !( - x == - y ); -
-

- space -

-

- bool operator - > ( - optional<T> const& x, optional<T> const& y ); -

-
  • - Returns: ( - y < - x ); -
-

- space -

-

- bool operator - <= ( - optional<T> const& x, optional<T> const& y ); -

-
  • - Returns: !( - y < - x ); -
-

- space -

-

- bool operator - >= ( - optional<T> const& x, optional<T> const& y ); -

-
  • - Returns: !( - x < - y ); -
-

- space -

-

- bool operator - == ( - optional<T> const& x, none_t ) - noexcept; -

-

- bool operator - == ( - none_t, - optional<T> const& x ) noexcept; -

-
-

- space -

-

- bool operator - != ( - optional<T> const& x, none_t ) - noexcept; -

-

- bool operator - != ( - none_t, - optional<T> const& x ) noexcept; -

-
  • - Returns: !( - x == - y ); -
-

- space -

-

- void swap - ( optional<T>& x, optional<T>& y - ) ; -

-
    -
  • - Requires: Lvalues of type T shall be swappable and T shall be MoveConstructible. -
    • -
  • -

    - Effects: -

    -
    ----- - - - - - - - - - - - - - - - - - - -
    - -

    - *this contains a value -

    -     		-

    - *this does not contain a value -

    -
    -

    - 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 -

    -
    -

    - 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 -

    -
    -
    • -
  • - Postconditions: The states of x and y - interchanged. -
    • -
  • - Throws: If both are initialized, whatever - swap(T&,T&) - throws. If only one is initialized, whatever T::T ( T&& ) - throws. -
    • -
  • - Example: -
    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 );
-
    -
    • -
-

- space -

-

- void swap - ( optional<T&>& x, optional<T&>& y - ) noexcept - ; -

-
    -
  • - Postconditions: x - refers to what y referred - to before the swap (if anything). y - refers to whatever x - referred to before the swap. -
    • -
  • - Example: -
    T x(12);
-T y(21);
-
-optional<T&> opt0;
-optional<T&> optX (x);
-optional<T&> optY (y);
-
-boost::swap(optX, optY);
-assert (addressof(*optX) == addressof(y));
-assert (addressof(*optY) == addressof(x));
-
-boost::swap(opt0, optX);
-assert ( opt0 );
-assert ( !optX );
-assert (addressof(*opt0) == addressof(y));
-
    - [endsect] -
    • -
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2016 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics____optional_references.html b/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics____optional_references.html deleted file mode 100644 index 7eedfaba..00000000 --- a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics____optional_references.html +++ /dev/null @@ -1,57 +0,0 @@ - - - -Detailed Semantics -- Optional References - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- space -

-

- optional<&>::optional() - noexcept; -

-

- optional<&>::optional(none_t) noexcept; -

-
  • - Postconditions: *this refers to nothing. -
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2016 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics____optional_values.html b/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics____optional_values.html deleted file mode 100644 index 17eeb386..00000000 --- a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics____optional_values.html +++ /dev/null @@ -1,1983 +0,0 @@ - - - -Detailed Semantics -- Optional Values - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-
- - - - - -
[Note]Note

- The following section contains various assert() which are used only to show the postconditions - as sample code. It is not implied that the type T - must support each particular expression but that if the expression is - supported, the implied condition holds. -

-

- space -

-

- optional<T>::optional() - noexcept; -

-
    -
  • - Effect: Default-Constructs an optional. -
    • -
  • - Postconditions: *this is uninitialized. -
    • -
  • - Notes: T's default constructor is not called. -
    • -
  • - Example: -
    optional<T> def ;
-assert ( !def ) ;
-
    -
    • -
-

- space -

-

- optional<T>::optional( - none_t ) - noexcept; -

-
    -
  • - Effect: Constructs an optional uninitialized. -
    • -
  • - Postconditions: *this is uninitialized. -
    • -
  • - Notes: T's - default constructor is not called. - The expression boost::none - denotes an instance of boost::none_t - that can be used as the parameter. -
    • -
  • - Example: -
    #include <boost/none.hpp>
-optional<T> n(none) ;
-assert ( !n ) ;
-
    -
    • -
-

- space -

-

- optional<T (not a ref)>::optional( T const& v ) -

-
    -
  • - Requires: is_copy_constructible<T>::value - is true. -
    • -
  • - Effect: Directly-Constructs an optional. -
    • -
  • - Postconditions: *this is initialized - and its value is a copy of v. -
    • -
  • - Throws: Whatever T::T( T const& - ) throws. -
    • -
  • - Notes: T::T( T const& - ) is called. -
    • -
  • - Exception Safety: Exceptions can only - be thrown during T::T( T const& - ); in that case, this constructor - has no effect. -
    • -
  • - Example: -
    T v;
-optional<T> opt(v);
-assert ( *opt == v ) ;
-
    -
    • -
-

- space -

-

- optional<T&>::optional( - T& - ref ) -

-
    -
  • - Effect: Directly-Constructs an optional. -
    • -
  • - Postconditions: *this is initialized - and its value is an instance of an internal type wrapping the reference - ref. -
    • -
  • - Throws: Nothing. -
    • -
  • - Example: -
    T v;
-T& vref = v ;
-optional<T&> opt(vref);
-assert ( *opt == v ) ;
-++ v ; // mutate referee
-assert (*opt == v);
-
    -
    • -
-

- space -

-

- optional<T (not a ref)>::optional( T&& v - ) -

-
    -
  • - Requires: is_move_constructible<T>::value - is true. -
    • -
  • - Effect: Directly-Move-Constructs an - optional. -
    • -
  • - Postconditions: *this is initialized - and its value is move-constructed from v. -
    • -
  • - Throws: Whatever T::T( T&& ) - throws. -
    • -
  • - Notes: T::T( T&& ) - is called. -
    • -
  • - Exception Safety: Exceptions can only - be thrown during T::T( T&& ); - in that case, the state of v - is determined by exception safety guarantees for T::T(T&&). -
    • -
  • - Example: -
    T v1, v2;
-optional<T> opt(std::move(v1));
-assert ( *opt == v2 ) ;
-
    -
    • -
-

- space -

-

- optional<T&>::optional( - T&& - ref ) - = delete -

-
  • - Notes: This constructor is deleted -
-

- space -

-

- optional<T (not a ref)>::optional( bool condition, - T const& v ) ; -

-

- optional<T&> - ::optional( bool condition, - T& - v ) - ; -

-
  • - If condition is true, same as: -
-

- optional<T (not a ref)>::optional( T const& v ) -

-

- optional<T&> - ::optional( T& v ) -

-
  • - otherwise, same as: -
-

- optional<T (not a ref)>::optional() -

-

- optional<T&> - ::optional() -

-

- space -

-

- optional<T (not a ref)>::optional( optional - const& - rhs ); -

-
    -
  • - Requires: is_copy_constructible<T>::value - is true. -
    • -
  • - Effect: Copy-Constructs an optional. -
    • -
  • - Postconditions: If rhs is initialized, - *this - is initialized and its value is a copy of the - value of rhs; else - *this - is uninitialized. -
    • -
  • - Throws: Whatever T::T( T const& - ) throws. -
    • -
  • - Notes: If rhs is initialized, T::T(T const& ) - is called. -
    • -
  • - Exception Safety: Exceptions can only - be thrown during T::T( T const& - ); in that case, this constructor - has no effect. -
    • -
  • - Example: -
    optional<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 ) ;
-
    -
    • -
-

- space -

-

- optional<T&>::optional( - optional const& rhs - ); -

-
    -
  • - Effect: Copy-Constructs an optional. -
    • -
  • - Postconditions: If rhs - is initialized, *this - is initialized and its value is another reference to the same object - referenced by *rhs; - else *this - is uninitialized. -
    • -
  • - Throws: Nothing. -
    • -
  • - Notes: If rhs - is initialized, both *this and *rhs will refer to the same object - (they alias). -
    • -
  • - Example: -
    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 ) ;
-
    -
    • -
-

- space -

-

- optional<T (not a ref)>::optional( optional&& rhs - ) noexcept(see below); -

-
    -
  • - Requires: is_move_constructible<T>::value - is true. -
    • -
  • - Effect: Move-constructs an optional. -
    • -
  • - Postconditions: If rhs - is initialized, *this - is initialized and its value is move constructed from rhs; else *this is uninitialized. -
    • -
  • - Throws: Whatever T::T( T&& ) - throws. -
    • -
  • - Remarks: The expression inside noexcept is equivalent to is_nothrow_move_constructible<T>::value. -
    • -
  • - Notes: If rhs - is initialized, T::T( T && - ) is called. -
    • -
  • - Exception Safety: Exceptions can only - be thrown during T::T( T&& ); - in that case, rhs remains - initialized and the value of *rhs is determined by exception safety - of T::T(T&&). -
    • -
  • - Example: -
    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::unique_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) ) ;
-
    -
    • -
-

- space -

-

- optional<T&>::optional( - optional && - rhs ); -

-
    -
  • - Effect: Move-Constructs an optional. -
    • -
  • - Postconditions: If rhs - is initialized, *this - is initialized and its value is another reference to the same object - referenced by *rhs; - else *this - is uninitialized. -
    • -
  • - Throws: Nothing. -
    • -
  • - Notes: If rhs - is initialized, both *this and *rhs will refer to the same object - (they alias). -
    • -
  • - Example: -
    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 ) ;
-
    -
    • -
-

- space -

-

- template<U> explicit optional<T - (not a ref)>::optional( - optional<U> const& rhs ); -

-
    -
  • - Effect: Copy-Constructs an optional. -
    • -
  • - Postconditions: If rhs - is initialized, *this - is initialized and its value is a copy of the - value of rhs converted to type T; - else *this - is uninitialized. -
    • -
  • - Throws: Whatever T::T( U const& - ) throws. -
    • -
  • - Notes: T::T( U const& - ) is called if rhs is initialized, which requires - a valid conversion from U - to T. -
    • -
  • - Exception Safety: Exceptions can only - be thrown during T::T( U const& - ); in that case, this constructor - has no effect. -
    • -
  • - Example: -
    optional<double> x(123.4);
-assert ( *x == 123.4 ) ;
-
-optional<int> y(x) ;
-assert( *y == 123 ) ;
-
    -
    • -
-

- space -

-

- template<U> explicit optional<T - (not a ref)>::optional( - optional<U>&& - rhs ); -

-
    -
  • - Effect: Move-constructs an optional. -
    • -
  • - Postconditions: If rhs - is initialized, *this - is initialized and its value is move-constructed from *rhs; - else *this - is uninitialized. -
    • -
  • - Throws: Whatever T::T( U&& ) - throws. -
    • -
  • - Notes: T::T( U&& ) - is called if rhs is - initialized, which requires a valid conversion from U - to T. -
    • -
  • - Exception Safety: Exceptions can only - be thrown during T::T( U&& ); - in that case, rhs remains - initialized and the value of *rhs is determined by exception safety - guarantee of T::T( U&& - ). -
    • -
  • - Example: -
    optional<double> x(123.4);
-assert ( *x == 123.4 ) ;
-
-optional<int> y(std::move(x)) ;
-assert( *y == 123 ) ;
-
    -
    • -
-

- space -

-

- template<InPlaceFactory> - explicit optional<T - (not a ref)>::optional( - InPlaceFactory const& f ); -

-

- template<TypedInPlaceFactory> - explicit optional<T - (not a ref)>::optional( - TypedInPlaceFactory const& f ); -

-
    -
  • - Effect: Constructs an optional with a value of T obtained from the factory. -
    • -
  • - Postconditions: *this is initialized - and its value is directly given from the factory - f (i.e., the value - is not copied). -
    • -
  • - Throws: Whatever the T constructor called by the factory - throws. -
    • -
  • - Notes: See In-Place - Factories -
    • -
  • - Exception Safety: Exceptions can only - be thrown during the call to the T - constructor used by the factory; in that case, this constructor has - no effect. -
    • -
  • - Example: -
    class C { C ( char, double, std::string ) ; } ;
-
-C v('A',123.4,"hello");
-
-optional<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 ) ;
-
    -
    • -
-

- space -

-

- optional& - optional<T>::operator= ( none_t - ) noexcept; -

-
    -
  • - Effect: If *this is initialized destroys its contained - value. -
    • -
  • - Postconditions: *this is uninitialized. -
    • -
-

- space -

-

- optional& - optional<T (not a ref)>::operator= ( T - const& - rhs ) - ; -

-
    -
  • - Effect: Assigns the value rhs to an optional. -
    • -
  • - Postconditions: *this is initialized and its value is - a copy of rhs. -
    • -
  • - Throws: Whatever T::operator=( T const& - ) or T::T(T const&) - throws. -
    • -
  • - Notes: If *this was initialized, T's assignment operator is used, - otherwise, its copy-constructor is used. -
    • -
  • - Exception Safety: In the event of - an exception, the initialization state of *this is unchanged and its value unspecified - as far as optional - is concerned (it is up to T's - operator=()). - If *this - is initially uninitialized and T's - copy constructor fails, *this is left properly uninitialized. -
    • -
  • - Example: -
    T x;
-optional<T> def ;
-optional<T> opt(x) ;
-
-T y;
-def = y ;
-assert ( *def == y ) ;
-opt = y ;
-assert ( *opt == y ) ;
-
    -
    • -
-

- space -

-

- optional<T&>& - optional<T&>::operator= ( T& rhs - ) ; -

-
    -
  • - Effect: (Re)binds the wrapped reference. -
    • -
  • - Postconditions: *this is initialized and it references - the same object referenced by rhs. -
    • -
  • - Notes: If *this was initialized, it is rebound - to the new object. See here - for details on this behavior. -
    • -
  • - Example: -
    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 ) ;
-
    -
    • -
-

- space -

-

- optional& - optional<T (not a ref)>::operator= ( T&& rhs - ) ; -

-
    -
  • - Effect: Moves the value rhs to an optional. -
    • -
  • - Postconditions: *this is initialized and its value is - moved from rhs. -
    • -
  • - Throws: Whatever T::operator=( T&& ) - or T::T(T &&) - throws. -
    • -
  • - Notes: If *this was initialized, T's move-assignment operator is used, - otherwise, its move-constructor is used. -
    • -
  • - Exception Safety: In the event of - an exception, the initialization state of *this is unchanged and its value unspecified - as far as optional - is concerned (it is up to T's - operator=()). - If *this - is initially uninitialized and T's - move constructor fails, *this is left properly uninitialized. -
    • -
  • - Example: -
    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 ) ;
-
    -
    • -
-

- space -

-

- optional<T&>& - optional<T&>::operator= ( T&& rhs - ) = - delete; -

-
  • - Notes: This assignment operator is - deleted. -
-

- space -

-

- optional& - optional<T (not a ref)>::operator= ( optional - const& - rhs ) - ; -

-
    -
  • - Requires: T - is CopyConstructible and CopyAssignable. -
    • -
  • -

    - Effects: -

    -
    ----- - - - - - - - - - - - - - - - - - - -
    - -

    - *this contains a value -

    -     		-

    - *this does not contain a value -

    -
    -

    - 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 -

    -
    -

    - rhs - does not contain a value -

    -     		-

    - destroys the contained value by calling val->T::~T() -

    -     		-

    - no effect -

    -
    -
    • -
  • - Returns: *this; -
    • -
  • - Postconditions: bool(rhs) == bool(*this). -
    • -
  • - Exception Safety: If any exception - is thrown, the initialization state of *this and rhs - remains unchanged. If an exception is thrown during the call to T's copy constructor, no effect. - 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. -
    • -
  • - Example: -
    T v;
-optional<T> opt(v);
-optional<T> def ;
-
-opt = def ;
-assert ( !def ) ;
-// previous value (copy of 'v') destroyed from within 'opt'.
-
    -
    • -
-

- space -

-

- optional<T&> - & optional<T&>::operator= ( optional<T&> const& rhs - ) ; -

-
    -
  • - Effect: (Re)binds thee wrapped reference. -
    • -
  • - Postconditions: If *rhs is initialized, *this - is initialized and it references the same object referenced by *rhs; - otherwise, *this - is uninitialized (and references no object). -
    • -
  • - Notes: If *this was initialized and so is *rhs, - *this - is rebound to the new object. See here - for details on this behavior. -
    • -
  • - Example: -
    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 ) ;
-
    -
    • -
-

- space -

-

- optional& - optional<T (not a ref)>::operator= ( optional&& rhs - ) noexcept(see below); -

-
    -
  • - Requires: T - is MoveConstructible - and MoveAssignable. -
    • -
  • -

    - Effects: -

    -
    ----- - - - - - - - - - - - - - - - - - - -
    - -

    - *this contains a value -

    -     		-

    - *this does not contain a value -

    -
    -

    - 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) -

    -
    -

    - rhs - does not contain a value -

    -     		-

    - destroys the contained value by calling val->T::~T() -

    -     		-

    - no effect -

    -
    -
    • -
  • - Returns: *this; -
    • -
  • - Postconditions: bool(rhs) == bool(*this). -
    • -
  • - Remarks: The expression inside noexcept is equivalent to is_nothrow_move_constructible<T>::value && - is_nothrow_move_assignable<T>::value. -
    • -
  • - Exception Safety: If any exception - is thrown, the initialization state of *this and rhs - remains unchanged. If an exception is thrown during the call to T's move constructor, the state of - *rhs - is determined by the exception safety guarantee 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. -
    • -
  • - Example: -
    optional<T> opt(T(2)) ;
-optional<T> def ;
-
-opt = def ;
-assert ( def ) ;
-assert ( opt ) ;
-assert ( *opt == T(2) ) ;
-
    -
    • -
-

- space -

-

- optional<T&> - & optional<T&>::operator= ( optional<T&>&& rhs - ) ; -

-
  • - Effect: Same as optional<T&>::operator= ( optional<T&> - const& - rhs ). -
-

- space -

-

- template<U> optional& - optional<T (not a ref)>::operator= ( optional<U> const& rhs - ) ; -

-
    -
  • -

    - Effect: -

    -
    ----- - - - - - - - - - - - - - - - - - - -
    - -

    - *this contains a value -

    -     		-

    - *this does not contain a value -

    -
    -

    - 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 -

    -
    -

    - rhs - does not contain a value -

    -     		-

    - destroys the contained value by calling val->T::~T() -

    -     		-

    - no effect -

    -
    -
    • -
  • - Returns: *this. -
    • -
  • - Postconditions: bool(rhs) == bool(*this). -
    • -
  • - Exception Safety: If any exception - is thrown, the result of the expression bool(*this) remains unchanged. If an exception - is thrown during the call to T's - constructor, no effect. 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. -
    • -
  • - Example: -
    T v;
-optional<T> opt0(v);
-optional<U> opt1;
-
-opt1 = opt0 ;
-assert ( *opt1 == static_cast<U>(v) ) ;
-
    -
    • -
-

- space -

-

- template<U> optional& - optional<T (not a ref)>::operator= ( optional<U>&& rhs - ) ; -

-
    -
  • -

    - Effect: -

    -
    ----- - - - - - - - - - - - - - - - - - - -
    - -

    - *this contains a value -

    -     		-

    - *this does not contain a value -

    -
    -

    - 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) -

    -
    -

    - rhs - does not contain a value -

    -     		-

    - destroys the contained value by calling val->T::~T() -

    -     		-

    - no effect -

    -
    -
    • -
  • - Returns: *this. -
    • -
  • - Postconditions: bool(rhs) == bool(*this). -
    • -
  • - Exception Safety: If any exception - is thrown, the result of the expression bool(*this) remains unchanged. If an exception - is thrown during the call to T's - constructor, no effect. 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. -
    • -
  • - Example: -
    T v;
-optional<T> opt0(v);
-optional<U> opt1;
-
-opt1 = std::move(opt0) ;
-assert ( opt0 );
-assert ( opt1 )
-assert ( *opt1 == static_cast<U>(v) ) ;
-
    -
    • -
-

- space -

-

- template<class... Args> - void optional<T - (not a ref)>::emplace( - Args...&& - args ); -

-
    -
  • - Requires: The compiler supports rvalue - references and variadic templates. -
    • -
  • - Effect: If *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).... -
    • -
  • - Postconditions: *this is initialized. -
    • -
  • - Throws: Whatever the selected T's constructor throws. -
    • -
  • - Exception Safety: If an exception - is thrown during the initialization of T, - *this - is uninitialized. -
    • -
  • - Notes: T - need not be MoveConstructible - or MoveAssignable. - On compilers that do not support variadic templates, the signature - falls back to two overloads:template<class - Arg> - void emplace(Arg&& arg) and void - emplace(). - On compilers that do not support rvalue references, the signature falls - back to three overloads: taking const - and non-const lvalue reference, - and third with empty function argument list. -
    • -
  • - Example: -
    T v;
-optional<const T> opt;
-opt.emplace(0);  // create in-place using ctor T(int)
-opt.emplace();   // destroy previous and default-construct another T
-opt.emplace(v);  // destroy and copy-construct in-place (no assignment called)
-
    -
    • -
-

- space -

-

- 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 ); -

-
    -
  • - Effect: Assigns an optional - with a value of T obtained - from the factory. -
    • -
  • - Postconditions: *this is initialized - and its value is directly given from the factory - f (i.e., the value - is not copied). -
    • -
  • - Throws: Whatever the T constructor called by the factory - throws. -
    • -
  • - Notes: See In-Place - Factories -
    • -
  • - Exception Safety: Exceptions can only - be thrown during the call to the T - constructor used by the factory; in that case, the optional - object will be reset to be uninitialized. -
    • -
-

- space -

-

- void optional<T - (not a ref)>::reset( T const& v ) ; -

-
  • - Deprecated: same as operator= - ( T - const& - v) - ; -
-

- space -

-

- void optional<T>::reset() noexcept - ; -

-
  • - Deprecated: Same as operator=( - none_t ); -
-

- space -

-

- 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)> - &) ; -

-
    -
  • - Requires: *this is initialized -
    • -
  • - Returns: A reference to the contained - value -
    • -
  • - Throws: Nothing. -
    • -
  • - Notes: The requirement is asserted - via BOOST_ASSERT(). -
    • -
-

- space -

-

- T const& optional<T&>::get() const ; -

-

- T& - optional<T&>::get() ; -

-

- inline T - const& - get ( - optional<T&> - const& - ) ; -

-

- inline T& get - ( optional<T&> &) - ; -

-
    -
  • - Requires: *this is initialized -
    • -
  • - Returns: The - reference contained. -
    • -
  • - Throws: Nothing. -
    • -
  • - Notes: The requirement is asserted - via BOOST_ASSERT(). -
    • -
-

- space -

-

- T const& optional<T - (not a ref)>::operator*() - const& - ; -

-

- T& - optional<T (not a ref)>::operator*() &; -

-
    -
  • - Requires: *this is initialized -
    • -
  • - Returns: A reference to the contained - value -
    • -
  • - Throws: Nothing. -
    • -
  • - 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. -
    • -
  • - Example: -
    T v ;
-optional<T> opt ( v );
-T const& u = *opt;
-assert ( u == v ) ;
-T w ;
-*opt = w ;
-assert ( *opt == w ) ;
-
    -
    • -
-

- space -

-

- T&& - optional<T (not a ref)>::operator*() &&; -

-
    -
  • - Requires: *this contains a value. -
    • -
  • - Effects: Equivalent to return std::move(*val);. -
    • -
  • - Notes: The requirement is asserted - via BOOST_ASSERT(). - On compilers that do not support ref-qualifiers on member functions - this overload is not present. -
    • -
-

- space -

-

- T & - optional<T&>::operator*() - const& - ; -

-

- T & - optional<T&>::operator*() - & ; -

-

- T & - optional<T&>::operator*() - && ; -

-
    -
  • - Requires: *this is initialized -
    • -
  • - Returns: The - reference contained. -
    • -
  • - Throws: Nothing. -
    • -
  • - Notes: The requirement is asserted - via 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. -
    • -
  • - Example: -
    T v ;
-T& vref = v ;
-optional<T&> opt ( vref );
-T const& vref2 = *opt;
-assert ( vref2 == v ) ;
-++ v ;
-assert ( *opt == v ) ;
-
    -
    • -
-

- space -

-

- T const& optional<T>::value() const& ; -

-

- T& - optional<T>::value() & ; -

-
    -
  • - Effects: Equivalent to return bool(*this) ? *val : throw bad_optional_access();. -
    • -
  • - 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. -
    • -
  • - Example: -
    T v ;
-optional<T> o0, o1 ( v );
-assert ( o1.value() == v );
-
-try {
-  o0.value(); // throws
-  assert ( false );
-}
-catch(bad_optional_access&) {
-  assert ( true );
-}
-
    -
    • -
-

- space -

-

- T&& - optional<T>::value() && ; -

-
    -
  • - Effects: Equivalent to return bool(*this) ? std::move(*val) : throw bad_optional_access();. -
    • -
  • - Notes: On compilers that do not support - ref-qualifiers on member functions this overload is not present. -
    • -
-

- space -

-

- template<class U> T optional<T>::value_or(U && - v) - const& - ; -

-
    -
  • - Effects: Equivalent to if (*this) return **this; else return - std::forward<U>(v);. -
    • -
  • - Remarks: If T - is not CopyConstructible or U && - is not convertible to T, - the program is ill-formed. -
    • -
  • - 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&. -
    • -
-

- space -

-

- template<class U> T optional<T>::value_or(U && - v) - && ; -

-
    -
  • - Effects: Equivalent to if (*this) return std::move(**this); else return std::forward<U>(v);. -
    • -
  • - Remarks: If T - is not MoveConstructible - or U && - is not convertible to T, - the program is ill-formed. -
    • -
  • - Notes: On compilers that do not support - ref-qualifiers on member functions this overload is not present. -
    • -
-

- space -

-

- template<class F> T optional<T>::value_or_eval(F f) const& ; -

-
    -
  • - Requires: T - is CopyConstructible and F models a Generator whose result type - is convertible to T. -
    • -
  • - Effects: if - (*this) return **this; else return f();. -
    • -
  • - Notes: On compilers that do not support - ref-qualifiers on member functions this overload is replaced with the - const-qualified member - function. -
    • -
  • - Example: -
    int complain_and_0()
-{
-  clog << "no value returned, using default" << endl;
-  return 0;
-}
-
-optional<int> o1 = 1;
-optional<int> oN = none;
-
-int i = o1.value_or_eval(complain_and_0); // fun not called
-assert (i == 1);
-
-int j = oN.value_or_eval(complain_and_0); // fun called
-assert (i == 0);
-
    -
    • -
-

- space -

-

- template<class F> T optional<T>::value_or_eval(F f) && - ; -

-
    -
  • - Requires: T - is MoveConstructible - and F models a Generator - whose result type is convertible to T. -
    • -
  • - Effects: if - (*this) return std::move(**this); else return - f();. -
    • -
  • - Notes: On compilers that do not support - ref-qualifiers on member functions this overload is not present. -
    • -
-

- space -

-

- 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 ) - ; -

-
    -
  • - Deprecated: Use value_or() instead. -
    • -
  • - 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 ) ;
-
    -
    • -
-

- space -

-

- 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)> - &) ; -

-
    -
  • - Returns: If *this is initialized, a pointer to the - contained value; else 0 - (null). -
    • -
  • - Throws: Nothing. -
    • -
  • - Notes: The contained value is permanently - stored within *this, - so you should not hold nor delete this pointer -
    • -
  • - Example: -
    T v;
-optional<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) ) ;
-
    -
    • -
-

- space -

-

- T const* optional<T - (not a ref)>::operator ->() - const ; -

-

- T* - optional<T (not a ref)>::operator - ->() ; -

-
    -
  • - Requires: *this is initialized. -
    • -
  • - Returns: A pointer to the contained - value. -
    • -
  • - Throws: Nothing. -
    • -
  • - Notes: The requirement is asserted - via BOOST_ASSERT(). -
    • -
  • - Example: -
    struct X { int mdata ; } ;
-X x ;
-optional<X> opt (x);
-opt->mdata = 2 ;
-
    -
    • -
-

- space -

-

- explicit optional<T>::operator - bool() - const noexcept - ; -

-
    -
  • - Returns: get_ptr() != 0. -
    • -
  • - Notes: On compilers that do not support - explicit conversion operators this falls back to safe-bool idiom. -
    • -
  • - Example: -
    optional<T> def ;
-assert ( def == 0 );
-optional<T> opt ( v ) ;
-assert ( opt );
-assert ( opt != 0 );
-
    -
    • -
-

- space -

-

- bool optional<T>::operator!() noexcept - ; -

-
    -
  • - Returns: If *this is uninitialized, true; else false. -
    • -
  • - Notes: This operator is provided for - those compilers which can't use the unspecified-bool-type - operator in certain boolean contexts. -
    • -
  • - Example: -
    optional<T> opt ;
-assert ( !opt );
-*opt = some_T ;
-
-// Notice the "double-bang" idiom here.
-assert ( !!opt ) ;
-
    -
    • -
-

- space -

-

- bool optional<T>::is_initialized() const ; -

-
  • - Deprecated: Same as explicit operator - bool () - ; -
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2016 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics___free_functions.html b/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics___free_functions.html deleted file mode 100644 index 776cffbb..00000000 --- a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics___free_functions.html +++ /dev/null @@ -1,521 +0,0 @@ - - - -Detailed Semantics - Free Functions - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- space -

-

- optional<T> make_optional( - T const& v ) -

-
    -
  • - Returns: optional<T>(v) for the deduced - type T of v. -
    • -
  • - Example: -
    template<class T> void foo ( optional<T> const& opt ) ;
-
-foo ( make_optional(1+1) ) ; // Creates an optional<int>
-
    -
    • -
-

- space -

-

- optional<std::decay_t<T>> - make_optional( - T && - v ) -

-
  • - Returns: optional<std::decay_t<T>>(std::move(v)) for the deduced - type T of v. -
-

- space -

-

- optional<T> make_optional( - bool condition, T const& v ) -

-
    -
  • - Returns: optional<T>(condition, v) for the deduced - type T of v. -
    • -
  • - Example: -
    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");
-
    -
    • -
-

- space -

-

- optional<std::decay_t<T>> - make_optional( - bool condition, T && v - ) -

-
  • - Returns: optional<std::decay_t<T>>(condition, std::move(v)) for the deduced - type T of v. -
-

- space -

-

- bool operator - == ( - optional<T> const& x, optional<T> const& y ); -

-
    -
  • - Requires: T - shall meet requirements of EqualityComparable. -
    • -
  • - Returns: If both x - and y are initialized, - (*x - == *y). - If only x or y is initialized, false. - If both are uninitialized, true. -
    • -
  • - 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. 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 equal_pointees() - instead -
    • -
  • - Example: -
    optional<T> oN, oN_;
-optional<T> o1(T(1)), o1_(T(1));
-optional<T> o2(T(2));
-
-assert ( oN == oN );  // Identity implies equality
-assert ( o1 == o1 );  //
-
-assert ( oN == oN_ ); // Both uninitialized compare equal
-
-assert ( oN != o1 );  // Initialized unequal to initialized.
-
-assert ( o1 == o1_ ); // Both initialized compare as (*lhs == *rhs)
-assert ( o1 != o2 );  //
-
    -
    • -
-

- space -

-

- bool operator - < ( - optional<T> const& x, optional<T> const& y ); -

-
    -
  • - Requires: Expression *x < *y shall be well-formed and its result - shall be convertible to bool. -
    • -
  • - Returns: (!y) ? false : (!x) ? true : *x < - *y. -
    • -
  • - 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. 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 less_pointees() - instead. T need not - be LessThanComparable. Only - single operator< - is required. Other relational operations are defined in terms of this - one. If T's operator< - satisfies the axioms of LessThanComparable (transitivity, - antisymmetry and irreflexivity), optional<T> is LessThanComparable. -
    • -
  • - Example: -
    optional<T> oN, oN_;
-optional<T> o0(T(0));
-optional<T> o1(T(1));
-
-assert ( !(oN < oN) );  // Identity implies equivalence
-assert ( !(o1 < o1) );
-
-assert ( !(oN < oN_) ); // Two uninitialized are equivalent
-assert ( !(oN_ < oN) );
-
-assert ( oN < o0 );     // Uninitialized is less than initialized
-assert ( !(o0 < oN) );
-
-assert ( o1 < o2 ) ;    // Two initialized compare as (*lhs < *rhs)
-assert ( !(o2 < o1) ) ;
-assert ( !(o2 < o2) ) ;
-
    -
    • -
-

- space -

-

- bool operator - != ( - optional<T> const& x, optional<T> const& y ); -

-
  • - Returns: !( - x == - y ); -
-

- space -

-

- bool operator - > ( - optional<T> const& x, optional<T> const& y ); -

-
  • - Returns: ( - y < - x ); -
-

- space -

-

- bool operator - <= ( - optional<T> const& x, optional<T> const& y ); -

-
  • - Returns: !( - y < - x ); -
-

- space -

-

- bool operator - >= ( - optional<T> const& x, optional<T> const& y ); -

-
  • - Returns: !( - x < - y ); -
-

- space -

-

- bool operator - == ( - optional<T> const& x, none_t ) - noexcept; -

-

- bool operator - == ( - none_t, - optional<T> const& x ) noexcept; -

-
-

- space -

-

- bool operator - != ( - optional<T> const& x, none_t ) - noexcept; -

-

- bool operator - != ( - none_t, - optional<T> const& x ) noexcept; -

-
  • - Returns: bool(x); -
-

- space -

-

- auto get_pointer - ( optional<T>& o - ) -> - typename optional<T>::pointer_type - ; -

-

- auto get_pointer - ( optional<T> const& o ) -> typename optional<T>::pointer_const_type - ; -

-
    -
  • - Returns: o.get_ptr(). -
    • -
  • - Throws: Nothing. -
    • -
-

- space -

-

- auto get_optional_value_or - ( optional<T>& o, typename optional<T>::reference_type def - ) -> - typename optional<T>::reference_type - ; -

-

- auto get_optional_value_or - ( optional<T> const& o, typename optional<T>::reference_const_type def - ) -> - typename optional<T>::reference_const_type - ; -

-
    -
  • - Returns: o.get_value_or(def). -
    • -
  • - Throws: Nothing. -
    • -
  • - Remarks: This function is deprecated. -
    • -
-

- space -

-

- void swap - ( optional<T>& x, optional<T>& y - ) ; -

-
    -
  • - Requires: Lvalues of type T shall be swappable and T shall be MoveConstructible. -
    • -
  • -

    - Effects: -

    -
    ----- - - - - - - - - - - - - - - - - - - -
    - -

    - *this contains a value -

    -     		-

    - *this does not contain a value -

    -
    -

    - 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 -

    -
    -

    - 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 -

    -
    -
    • -
  • - Postconditions: The states of x and y - interchanged. -
    • -
  • - Throws: If both are initialized, whatever - swap(T&,T&) - throws. If only one is initialized, whatever T::T ( T&& ) - throws. -
    • -
  • - Example: -
    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 );
-
    -
    • -
-

- space -

-

- void swap - ( optional<T&>& x, optional<T&>& y - ) noexcept - ; -

-
    -
  • - Postconditions: x - refers to what y referred - to before the swap (if anything). y - refers to whatever x - referred to before the swap. -
    • -
  • - Example: -
    T x(12);
-T y(21);
-
-optional<T&> opt0;
-optional<T&> optX (x);
-optional<T&> optY (y);
-
-boost::swap(optX, optY);
-assert (addressof(*optX) == addressof(y));
-assert (addressof(*optY) == addressof(x));
-
-boost::swap(opt0, optX);
-assert ( opt0 );
-assert ( !optX );
-assert (addressof(*opt0) == addressof(y));
-
    -
    • -
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics___optional_references.html b/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics___optional_references.html deleted file mode 100644 index 3a4d5fef..00000000 --- a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics___optional_references.html +++ /dev/null @@ -1,552 +0,0 @@ - - - -Detailed Semantics - Optional References - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- space -

-

- optional<T&>::optional() - noexcept; -

-

- optional<T&>::optional(none_t) noexcept; -

-
  • - Postconditions: bool(*this) == false; *this refers to nothing. -
-

- space -

-

- template<class R> optional<T&>::optional(R&& r) noexcept; -

-
    -
  • - Postconditions: bool(*this) == true; addressof(**this) == addressof(r). -
    • -
  • - 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. -
    • -
  • - Notes: This constructor is declared - explicit on compilers - that do not correctly support binding to const lvalues of integral types. - For more details see here. -
    • -
  • - Example: -
    T v;
-T& vref = v ;
-optional<T&> opt(vref);
-assert ( *opt == v ) ;
-++ v ; // mutate referee
-assert (*opt == v);
-
    -
    • -
-

- space -

-

- template<class R> optional<T&>::optional(bool cond, R&& - r) - noexcept; -

-
    -
  • - Effects: Initializes ref with expression cond ? - addressof(r) : nullptr. -
    • -
  • - Postconditions: bool(*this) == cond; If bool(*this), addressof(**this) == addressof(r). -
    • -
  • - 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. -
    • -
-

- space -

-

- optional<T&>::optional ( - optional const& rhs - ) noexcept - ; -

-
    -
  • - Effects: Initializes ref with expression rhs.ref. -
    • -
  • - Postconditions: bool(*this) == bool(rhs). -
    • -
  • - Example: -
    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 ) ;
-
    -
    • -
-

- space -

-

- template<class U> explicit - optional<T&>::optional ( - optional<U&> - const& - rhs ) - noexcept ; -

-
    -
  • - Requires: is_convertible<U&, T&>::value - is true. -
    • -
  • - Effects: Initializes ref with expression rhs.ref. -
    • -
  • - Postconditions: bool(*this) == bool(rhs). -
    • -
-

- space -

-

- optional<T&>::operator= ( none_t - ) noexcept - ; -

-
    -
  • - Effects: Assigns ref - with expression nullptr. -
    • -
  • - returns: *this. -
    • -
  • - Postconditions: bool(*this) == false. -
    • -
-

- optional& - optional<T&>::operator= ( optional - const& - rhs ) - noexcept ; -

-
    -
  • - Effects: Assigns ref - with expression rhs.ref. -
    • -
  • - returns: *this. -
    • -
  • - Postconditions: bool(*this) == bool(rhs). -
    • -
  • - Notes: This behaviour is called rebinding - semantics. See here - for details. -
    • -
  • - Example: -
    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 ) ;
-
    -
    • -
-

- template<class U> optional& optional<T&>::operator= ( optional<U&> const& rhs - ) noexcept - ; -

-
    -
  • - Requires: is_convertible<U&, T&>::value - is true. -
    • -
  • - Effects: Assigns ref - with expression rhs.ref. -
    • -
  • - returns: *this. -
    • -
  • - Postconditions: bool(*this) == bool(rhs). -
    • -
-

- space -

-

- template<class R> optional& optional<T&>::operator= ( R&& r - ) noexcept - ; -

-
    -
  • - Effects: Assigns ref - with expression r. -
    • -
  • - returns: *this. -
    • -
  • - Postconditions: bool(*this) == true. -
    • -
  • - 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. -
    • -
  • - Example: -
    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 ) ;
-
    -
    • -
-

- space -

-

- void optional<T&>::emplace( R&& r - ) noexcept - ; -

-
    -
  • - Effects: Assigns ref - with expression r. -
    • -
  • - Postconditions: bool(*this) == true. -
    • -
  • - 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. -
    • -
-

- space -

-

- T& - optional<T&>::get() const ; -

-

- T& - optional<T&>::operator *() - const ; -

-
    -
  • - Requires: bool(*this) == true. -
    • -
  • - Effects: Returns *ref. -
    • -
  • - Throws: Nothing. -
    • -
  • - Example: -
    T v ;
-T& vref = v ;
-optional<T&> opt ( vref );
-T const& vref2 = *opt;
-assert ( vref2 == v ) ;
-++ v ;
-assert ( *opt == v ) ;
-
    -
    • -
-

- space -

-

- T* - optional<T&>::operator -> - () const - ; -

-
    -
  • - Requires: bool(*this) == true. -
    • -
  • - Effects: Returns ref. -
    • -
  • - Throws: Nothing. -
    • -
-

- space -

-

- T& - optional<T&>::value() const ; -

-
  • - Effects: Equivalent to return bool(*this) ? *val : throw bad_optional_access();. -
-

- space -

-

- template<class R> T& optional<T&>::value_or( R&& r - ) const - noexcept; -

-
    -
  • - Effects: Equivalent to if (*this) return **this; else return - r;. -
    • -
  • - Remarks: Unless R - is an lvalue reference, the program is ill-formed. -
    • -
-

- space -

-

- template<class F> T& optional<T&>::value_or( F f ) const ; -

-
    -
  • - Effects: Equivalent to if (*this) return **this; else return - f();. -
    • -
  • - Remarks: Unless decltype(f()) is an lvalue reference, the program - is ill-formed. -
    • -
-

- space -

-

- template<class F> auto optional<T&>::map( F f ) const -> see below; -

-
    -
  • - Effects: Equivalent to if (*this) return f(**this); else return none;. -
    • -
  • - Remarks: The return type of this function - is optional<decltype(f(**this))>. -
    • -
-

- space -

-

- template<class F> auto optional<T&>::flat_map( - F f - ) const - -> see below; -

-
    -
  • - Requires: The return type of expression - f(**this) - is optional<U> - for some object or reference type U. -
    • -
  • - Effects: Equivalent to if (*this) return f(**this); else return none;. -
    • -
  • - Remarks: The return type of this function - is optional<U>. -
    • -
-

- space -

-

- T* - optional<T&>::get_ptr () - const noexcept; -

-
  • - Returns: ref. -
-

- space -

-

- bool has_value() const noexcept; -

-

- optional<T&>::operator bool - () const - noexcept; -

-
  • - Returns: bool(ref). -
-

- space -

-

- optional<T&>::operator ! () const noexcept; -

-
  • - Returns: !bool(ref). -
-

- space -

-

- void optional<T&>::reset() noexcept; -

-
  • - Effects: Same as *this = none. -
-

- space -

-

- template<class R> void optional<T&>::reset ( R&& - r) - noexcept; -

-
    -
  • - Effects: Equivalent to *this = std::forward<R>(r). -
    • -
  • - Remarks: This function is deprecated. -
    • -
-

- space -

-

- bool optional<T&>::is_initialized() const noexcept; -

-
    -
  • - Effects: Equivalent to return bool(*this). -
    • -
  • - Remarks: This function is deprecated. -
    • -
-

- space -

-

- template<class R> T& optional<T&>::get_value_or( R&& r - ) const - noexcept; -

-
    -
  • - Effects: Equivalent to return value_or(std::forward<R>(r);. -
    • -
  • - Remarks: This function is deprecated. -
    • -
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics___optional_values.html b/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics___optional_values.html deleted file mode 100644 index ce614066..00000000 --- a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics___optional_values.html +++ /dev/null @@ -1,1788 +0,0 @@ - - - -Detailed Semantics - Optional Values - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-
- - - - - -
[Note]Note

- The following section contains various assert() which are used only to show the postconditions - as sample code. It is not implied that the type T - must support each particular expression but that if the expression is - supported, the implied condition holds. -

-

- space -

-

- optional<T>::optional() - noexcept; -

-
    -
  • - Effect: Default-Constructs an optional. -
    • -
  • - Postconditions: *this is uninitialized. -
    • -
  • - Notes: T's default constructor is not called. -
    • -
  • - Example: -
    optional<T> def ;
-assert ( !def ) ;
-
    -
    • -
-

- space -

-

- optional<T>::optional( - none_t ) - noexcept; -

-
    -
  • - Effect: Constructs an optional uninitialized. -
    • -
  • - Postconditions: *this is uninitialized. -
    • -
  • - Notes: T's - default constructor is not called. - The expression boost::none - denotes an instance of boost::none_t - that can be used as the parameter. -
    • -
  • - Example: -
    #include <boost/none.hpp>
-optional<T> n(none) ;
-assert ( !n ) ;
-
    -
    • -
-

- space -

-

- optional<T>::optional( - T const& v ) -

-
    -
  • - Requires: is_copy_constructible<T>::value - is true. -
    • -
  • - Effect: Directly-Constructs an optional. -
    • -
  • - Postconditions: *this is initialized - and its value is a copy of v. -
    • -
  • - Throws: Whatever T::T( T const& - ) throws. -
    • -
  • - Notes: T::T( T const& - ) is called. -
    • -
  • - Exception Safety: Exceptions can only - be thrown during T::T( T const& - ); in that case, this constructor - has no effect. -
    • -
  • - Example: -
    T v;
-optional<T> opt(v);
-assert ( *opt == v ) ;
-
    -
    • -
-

- space -

-

- optional<T>::optional( - T&& - v ) -

-
    -
  • - Requires: is_move_constructible<T>::value - is true. -
    • -
  • - Effect: Directly-Move-Constructs an - optional. -
    • -
  • - Postconditions: *this is initialized - and its value is move-constructed from v. -
    • -
  • - Throws: Whatever T::T( T&& ) - throws. -
    • -
  • - Notes: T::T( T&& ) - is called. -
    • -
  • - Exception Safety: Exceptions can only - be thrown during T::T( T&& ); - in that case, the state of v - is determined by exception safety guarantees for T::T(T&&). -
    • -
  • - Example: -
    T v1, v2;
-optional<T> opt(std::move(v1));
-assert ( *opt == v2 ) ;
-
    -
    • -
-

- space -

-

- optional<T>::optional( - bool condition, T const& v ) ; -

-
  • - If condition is true, same as: -
-

- optional<T>::optional( - T const& v ) -

-
  • - otherwise, same as: -
-

- optional<T>::optional() -

-

- space -

-

- optional<T>::optional( - optional const& rhs - ); -

-
    -
  • - Requires: is_copy_constructible<T>::value - is true. -
    • -
  • - Effect: Copy-Constructs an optional. -
    • -
  • - Postconditions: If rhs is initialized, - *this - is initialized and its value is a copy of the - value of rhs; else - *this - is uninitialized. -
    • -
  • - Throws: Whatever T::T( T const& - ) throws. -
    • -
  • - Notes: If rhs is initialized, T::T(T const& ) - is called. -
    • -
  • - Exception Safety: Exceptions can only - be thrown during T::T( T const& - ); in that case, this constructor - has no effect. -
    • -
  • - Example: -
    optional<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 ) ;
-
    -
    • -
-

- space -

-

- optional<T>::optional( - optional&& - rhs ) - noexcept(see - below); -

-
    -
  • - Requires: is_move_constructible<T>::value - is true. -
    • -
  • - Effect: Move-constructs an optional. -
    • -
  • - Postconditions: If rhs - is initialized, *this - is initialized and its value is move constructed from rhs; else *this is uninitialized. -
    • -
  • - Throws: Whatever T::T( T&& ) - throws. -
    • -
  • - Remarks: The expression inside noexcept is equivalent to is_nothrow_move_constructible<T>::value. -
    • -
  • - Notes: If rhs - is initialized, T::T( T && - ) is called. -
    • -
  • - Exception Safety: Exceptions can only - be thrown during T::T( T&& ); - in that case, rhs remains - initialized and the value of *rhs is determined by exception safety - of T::T(T&&). -
    • -
  • - Example: -
    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::unique_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) ) ;
-
    -
    • -
-

- space -

-

- template<U> explicit optional<T>::optional( optional<U> const& rhs - ); -

-
    -
  • - Effect: Copy-Constructs an optional. -
    • -
  • - Postconditions: If rhs - is initialized, *this - is initialized and its value is a copy of the - value of rhs converted to type T; - else *this - is uninitialized. -
    • -
  • - Throws: Whatever T::T( U const& - ) throws. -
    • -
  • - Notes: T::T( U const& - ) is called if rhs is initialized, which requires - a valid conversion from U - to T. -
    • -
  • - Exception Safety: Exceptions can only - be thrown during T::T( U const& - ); in that case, this constructor - has no effect. -
    • -
  • - Example: -
    optional<double> x(123.4);
-assert ( *x == 123.4 ) ;
-
-optional<int> y(x) ;
-assert( *y == 123 ) ;
-
    -
    • -
-

- space -

-

- template<U> explicit optional<T>::optional( optional<U>&& rhs - ); -

-
    -
  • - Effect: Move-constructs an optional. -
    • -
  • - Postconditions: If rhs - is initialized, *this - is initialized and its value is move-constructed from *rhs; - else *this - is uninitialized. -
    • -
  • - Throws: Whatever T::T( U&& ) - throws. -
    • -
  • - Notes: T::T( U&& ) - is called if rhs is - initialized, which requires a valid conversion from U - to T. -
    • -
  • - Exception Safety: Exceptions can only - be thrown during T::T( U&& ); - in that case, rhs remains - initialized and the value of *rhs is determined by exception safety - guarantee of T::T( U&& - ). -
    • -
  • - Example: -
    optional<double> x(123.4);
-assert ( *x == 123.4 ) ;
-
-optional<int> y(std::move(x)) ;
-assert( *y == 123 ) ;
-
    -
    • -
-

- space -

-

- template<class... Args> - explicit optional<T>::optional( in_place_init_t, Args&&... ars - ); -

-
    -
  • - Requires: is_constructible_v<T, Args&&...> is true. -
    • -
  • - Effect: Initializes the contained - value as if direct-non-list-initializing an object of type T with the arguments std::forward<Args>(args).... -
    • -
  • - Postconditions: *this is initialized. -
    • -
  • - Throws: Any exception thrown by the - selected constructor of T. -
    • -
  • - Notes: T - need not be MoveConstructible. - On compilers that do not support variadic templates or rvalue references, - this constuctor is available in limited functionality. For details - see here. -
    • -
  • - Example: -
    // creates an std::mutex using its default constructor
-optional<std::mutex> om {in_place_init};
-assert (om);
-
-// creates a unique_lock by calling unique_lock(*om, std::defer_lock)
-optional<std::unique_lock<std::mutex>> ol {in_place_init, *om, std::defer_lock};
-assert (ol);
-assert (!ol->owns_lock());
-
    -
    • -
-

- space -

-

- template<class... Args> - explicit optional<T>::optional( in_place_init_if_t, bool condition, - Args&&... - ars ); -

-
    -
  • - Requires: is_constructible_v<T, Args&&...> is true. -
    • -
  • - 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).... -
    • -
  • - Postconditions: bool(*this) == condition. -
    • -
  • - Throws: Any exception thrown by the - selected constructor of T. -
    • -
  • - Notes: T - need not be MoveConstructible. - On compilers that do not support variadic templates or rvalue references, - this constuctor is available in limited functionality. For details - see here. -
    • -
  • - Example: -
    optional<std::vector<std::string>> ov1 {in_place_init_if, false, 3, "A"};
-assert (!ov1);
-
-optional<std::vector<std::string>> ov2 {in_place_init_if, true, 3, "A"};
-assert (ov2);
-assert (ov2->size() == 3);
-
    -
    • -
-

- space -

-

- template<InPlaceFactory> - explicit optional<T>::optional( InPlaceFactory - const& - f ); -

-

- template<TypedInPlaceFactory> - explicit optional<T>::optional( TypedInPlaceFactory - const& - f ); -

-
    -
  • - Effect: Constructs an optional with a value of T obtained from the factory. -
    • -
  • - Postconditions: *this is initialized - and its value is directly given from the factory - f (i.e., the value - is not copied). -
    • -
  • - Throws: Whatever the T constructor called by the factory - throws. -
    • -
  • - Notes: See In-Place - Factories -
    • -
  • - Exception Safety: Exceptions can only - be thrown during the call to the T - constructor used by the factory; in that case, this constructor has - no effect. -
    • -
  • - Example: -
    class C { C ( char, double, std::string ) ; } ;
-
-C v('A',123.4,"hello");
-
-optional<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 ) ;
-
    -
    • -
-

- space -

-

- optional& - optional<T>::operator= ( none_t - ) noexcept; -

-
    -
  • - Effect: If *this is initialized destroys its contained - value. -
    • -
  • - Postconditions: *this is uninitialized. -
    • -
-

- space -

-

- optional& - optional<T>::operator= ( T const& rhs ) ; -

-
    -
  • - Effect: Assigns the value rhs to an optional. -
    • -
  • - Postconditions: *this is initialized and its value is - a copy of rhs. -
    • -
  • - Throws: Whatever T::operator=( T const& - ) or T::T(T const&) - throws. -
    • -
  • - Notes: If *this was initialized, T's assignment operator is used, - otherwise, its copy-constructor is used. -
    • -
  • - Exception Safety: In the event of - an exception, the initialization state of *this is unchanged and its value unspecified - as far as optional - is concerned (it is up to T's - operator=()). - If *this - is initially uninitialized and T's - copy constructor fails, *this is left properly uninitialized. -
    • -
  • - Example: -
    T x;
-optional<T> def ;
-optional<T> opt(x) ;
-
-T y;
-def = y ;
-assert ( *def == y ) ;
-opt = y ;
-assert ( *opt == y ) ;
-
    -
    • -
-

- space -

-

- optional& - optional<T>::operator= ( T&& rhs - ) ; -

-
    -
  • - Effect: Moves the value rhs to an optional. -
    • -
  • - Postconditions: *this is initialized and its value is - moved from rhs. -
    • -
  • - Throws: Whatever T::operator=( T&& ) - or T::T(T &&) - throws. -
    • -
  • - Notes: If *this was initialized, T's move-assignment operator is used, - otherwise, its move-constructor is used. -
    • -
  • - Exception Safety: In the event of - an exception, the initialization state of *this is unchanged and its value unspecified - as far as optional - is concerned (it is up to T's - operator=()). - If *this - is initially uninitialized and T's - move constructor fails, *this is left properly uninitialized. -
    • -
  • - Example: -
    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 ) ;
-
    -
    • -
-

- space -

-

- optional& - optional<T>::operator= ( optional - const& - rhs ) - ; -

-
    -
  • - Requires: T - is CopyConstructible and CopyAssignable. -
    • -
  • -

    - Effects: -

    -
    ----- - - - - - - - - - - - - - - - - - - -
    - -

    - *this contains a value -

    -     		-

    - *this does not contain a value -

    -
    -

    - 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 -

    -
    -

    - rhs - does not contain a value -

    -     		-

    - destroys the contained value by calling val->T::~T() -

    -     		-

    - no effect -

    -
    -
    • -
  • - Returns: *this; -
    • -
  • - Postconditions: bool(rhs) == bool(*this). -
    • -
  • - Exception Safety: If any exception - is thrown, the initialization state of *this and rhs - remains unchanged. If an exception is thrown during the call to T's copy constructor, no effect. - 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. -
    • -
  • - Example: -
    T v;
-optional<T> opt(v);
-optional<T> def ;
-
-opt = def ;
-assert ( !def ) ;
-// previous value (copy of 'v') destroyed from within 'opt'.
-
    -
    • -
-

- space -

-

- optional& - optional<T>::operator= ( optional&& rhs - ) noexcept(see below); -

-
    -
  • - Requires: T - is MoveConstructible - and MoveAssignable. -
    • -
  • -

    - Effects: -

    -
    ----- - - - - - - - - - - - - - - - - - - -
    - -

    - *this contains a value -

    -     		-

    - *this does not contain a value -

    -
    -

    - 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) -

    -
    -

    - rhs - does not contain a value -

    -     		-

    - destroys the contained value by calling val->T::~T() -

    -     		-

    - no effect -

    -
    -
    • -
  • - Returns: *this; -
    • -
  • - Postconditions: bool(rhs) == bool(*this). -
    • -
  • - Remarks: The expression inside noexcept is equivalent to is_nothrow_move_constructible<T>::value && - is_nothrow_move_assignable<T>::value. -
    • -
  • - Exception Safety: If any exception - is thrown, the initialization state of *this and rhs - remains unchanged. If an exception is thrown during the call to T's move constructor, the state of - *rhs - is determined by the exception safety guarantee 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. -
    • -
  • - Example: -
    optional<T> opt(T(2)) ;
-optional<T> def ;
-
-opt = def ;
-assert ( def ) ;
-assert ( opt ) ;
-assert ( *opt == T(2) ) ;
-
    -
    • -
-

- space -

-

- template<U> optional& - optional<T>::operator= ( optional<U> const& rhs - ) ; -

-
    -
  • -

    - Effect: -

    -
    ----- - - - - - - - - - - - - - - - - - - -
    - -

    - *this contains a value -

    -     		-

    - *this does not contain a value -

    -
    -

    - 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 -

    -
    -

    - rhs - does not contain a value -

    -     		-

    - destroys the contained value by calling val->T::~T() -

    -     		-

    - no effect -

    -
    -
    • -
  • - Returns: *this. -
    • -
  • - Postconditions: bool(rhs) == bool(*this). -
    • -
  • - Exception Safety: If any exception - is thrown, the result of the expression bool(*this) remains unchanged. If an exception - is thrown during the call to T's - constructor, no effect. 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. -
    • -
  • - Example: -
    T v;
-optional<T> opt0(v);
-optional<U> opt1;
-
-opt1 = opt0 ;
-assert ( *opt1 == static_cast<U>(v) ) ;
-
    -
    • -
-

- space -

-

- template<U> optional& - optional<T>::operator= ( optional<U>&& rhs - ) ; -

-
    -
  • -

    - Effect: -

    -
    ----- - - - - - - - - - - - - - - - - - - -
    - -

    - *this contains a value -

    -     		-

    - *this does not contain a value -

    -
    -

    - 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) -

    -
    -

    - rhs - does not contain a value -

    -     		-

    - destroys the contained value by calling val->T::~T() -

    -     		-

    - no effect -

    -
    -
    • -
  • - Returns: *this. -
    • -
  • - Postconditions: bool(rhs) == bool(*this). -
    • -
  • - Exception Safety: If any exception - is thrown, the result of the expression bool(*this) remains unchanged. If an exception - is thrown during the call to T's - constructor, no effect. 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. -
    • -
  • - Example: -
    T v;
-optional<T> opt0(v);
-optional<U> opt1;
-
-opt1 = std::move(opt0) ;
-assert ( opt0 );
-assert ( opt1 )
-assert ( *opt1 == static_cast<U>(v) ) ;
-
    -
    • -
-

- space -

-

- template<class... Args> - void optional<T>::emplace( Args&&... args - ); -

-
    -
  • - Requires: The compiler supports rvalue - references and variadic templates. -
    • -
  • - Effect: If *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).... -
    • -
  • - Postconditions: *this is initialized. -
    • -
  • - Throws: Whatever the selected T's constructor throws. -
    • -
  • - Exception Safety: If an exception - is thrown during the initialization of T, - *this - is uninitialized. -
    • -
  • - Notes: T - need not be MoveConstructible - or MoveAssignable. - On compilers that do not support variadic templates or rvalue references, - this function is available in limited functionality. For details see here. -
    • -
  • - Example: -
    T v;
-optional<const T> opt;
-opt.emplace(0);  // create in-place using ctor T(int)
-opt.emplace();   // destroy previous and default-construct another T
-opt.emplace(v);  // destroy and copy-construct in-place (no assignment called)
-
    -
    • -
-

- space -

-

- template<InPlaceFactory> - optional<T>& - optional<T>::operator=( InPlaceFactory const& f ); -

-

- template<TypedInPlaceFactory> - optional<T>& - optional<T>::operator=( TypedInPlaceFactory const& f ); -

-
    -
  • - Effect: Assigns an optional - with a value of T obtained - from the factory. -
    • -
  • - Postconditions: *this is initialized - and its value is directly given from the factory - f (i.e., the value - is not copied). -
    • -
  • - Throws: Whatever the T constructor called by the factory - throws. -
    • -
  • - Notes: See In-Place - Factories -
    • -
  • - Exception Safety: Exceptions can only - be thrown during the call to the T - constructor used by the factory; in that case, the optional - object will be reset to be uninitialized. -
    • -
-

- space -

-

- void optional<T>::reset( T const& v ) ; -

-
  • - Deprecated: same as operator= - ( T - const& - v) - ; -
-

- space -

-

- void optional<T>::reset() noexcept - ; -

-
  • - Effects: Same as operator=( none_t - ); -
-

- space -

-

- T const& optional<T>::get() const ; -

-

- T& - optional<T>::get() ; -

-

- inline T - const& - get ( - optional<T> const& ) ; -

-

- inline T& get - ( optional<T> &) - ; -

-
    -
  • - Requires: *this is initialized -
    • -
  • - Returns: A reference to the contained - value -
    • -
  • - Throws: Nothing. -
    • -
  • - Notes: The requirement is asserted - via BOOST_ASSERT(). -
    • -
-

- space -

-

- T const& optional<T>::operator*() const& ; -

-

- T& - optional<T>::operator*() - &; -

-
    -
  • - Requires: *this is initialized -
    • -
  • - Returns: A reference to the contained - value -
    • -
  • - Throws: Nothing. -
    • -
  • - 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. -
    • -
  • - Example: -
    T v ;
-optional<T> opt ( v );
-T const& u = *opt;
-assert ( u == v ) ;
-T w ;
-*opt = w ;
-assert ( *opt == w ) ;
-
    -
    • -
-

- space -

-

- T&& - optional<T>::operator*() - &&; -

-
    -
  • - Requires: *this contains a value. -
    • -
  • - Effects: Equivalent to return std::move(*val);. -
    • -
  • - Notes: The requirement is asserted - via BOOST_ASSERT(). - On compilers that do not support ref-qualifiers on member functions - this overload is not present. -
    • -
-

- space -

-

- T const& optional<T>::value() const& ; -

-

- T& - optional<T>::value() & ; -

-
    -
  • - Effects: Equivalent to return bool(*this) ? *val : throw bad_optional_access();. -
    • -
  • - 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. -
    • -
  • - Example: -
    T v ;
-optional<T> o0, o1 ( v );
-assert ( o1.value() == v );
-
-try {
-  o0.value(); // throws
-  assert ( false );
-}
-catch(bad_optional_access&) {
-  assert ( true );
-}
-
    -
    • -
-

- space -

-

- T&& - optional<T>::value() && ; -

-
    -
  • - Effects: Equivalent to return bool(*this) ? std::move(*val) : throw bad_optional_access();. -
    • -
  • - Notes: On compilers that do not support - ref-qualifiers on member functions this overload is not present. -
    • -
-

- space -

-

- template<class U> T optional<T>::value_or(U && - v) - const& - ; -

-
    -
  • - Effects: Equivalent to if (*this) return **this; else return - std::forward<U>(v);. -
    • -
  • - Remarks: If T - is not CopyConstructible or U && - is not convertible to T, - the program is ill-formed. -
    • -
  • - 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&. -
    • -
-

- space -

-

- template<class U> T optional<T>::value_or(U && - v) - && ; -

-
    -
  • - Effects: Equivalent to if (*this) return std::move(**this); else return std::forward<U>(v);. -
    • -
  • - Remarks: If T - is not MoveConstructible - or U && - is not convertible to T, - the program is ill-formed. -
    • -
  • - Notes: On compilers that do not support - ref-qualifiers on member functions this overload is not present. -
    • -
-

- space -

-

- template<class F> T optional<T>::value_or_eval(F f) const& ; -

-
    -
  • - Requires: T - is CopyConstructible and F models a Generator whose result type - is convertible to T. -
    • -
  • - Effects: if - (*this) return **this; else return f();. -
    • -
  • - Notes: On compilers that do not support - ref-qualifiers on member functions this overload is replaced with the - const-qualified member - function. -
    • -
  • - Example: -
    int complain_and_0()
-{
-  clog << "no value returned, using default" << endl;
-  return 0;
-}
-
-optional<int> o1 = 1;
-optional<int> oN = none;
-
-int i = o1.value_or_eval(complain_and_0); // fun not called
-assert (i == 1);
-
-int j = oN.value_or_eval(complain_and_0); // fun called
-assert (i == 0);
-
    -
    • -
-

- space -

-

- template<class F> T optional<T>::value_or_eval(F f) && - ; -

-
    -
  • - Requires: T - is MoveConstructible - and F models a Generator - whose result type is convertible to T. -
    • -
  • - Effects: if - (*this) return std::move(**this); else return - f();. -
    • -
  • - Notes: On compilers that do not support - ref-qualifiers on member functions this overload is not present. -
    • -
-

- space -

-

- template<class F> auto optional<T>::map(F f) const& -> - see below ; -

-

- template<class F> auto optional<T>::map(F f) & -> see below - ; -

-
    -
  • - Effects: if - (*this) return f(**this); else return - none; -
    • -
  • - Notes: The return type of these overloads - is optional<decltype(f(**this))>. - On compilers that do not support ref-qualifiers on member functions, - these two (as well as the next one) overloads are replaced with good - old const and non-const overloads. -
    • -
  • - Example: -
    auto length = [](const string& s){ return s.size(); };
-optional<string> o1 {}, o2 {"cat"};
-optional<size_t> os1 = o1.map(length), os2 = o2.map(length);
-assert ( !os1 ) ;
-assert ( os2 ) ;
-assert ( *os2 == 3 ) ;
-
    -
    • -
-

- space -

-

- template<class F> auto optional<T>::map(F f) && - -> see below - ; -

-
    -
  • - Effects: if - (*this) return f(std::move(**this)); else return - none; -
    • -
  • - Notes: The return type of this overload - is optional<decltype(f(istd::move(**this)))>. -
    • -
-

- space -

-

- template<class F> auto optional<T>::flat_map(F f) const& -> - see below ; -

-

- template<class F> auto optional<T>::flat_map(F f) & -> see below - ; -

-
    -
  • - Requires: The return type of expression - f(**this) - is optional<U> - for some object or reference type U. -
    • -
  • - Effects: if - (*this) return f(**this); else return - none; -
    • -
  • - Notes: The return type of these overloads - is optional<U>. - On compilers that do not support ref-qualifiers on member functions, - these two (as well as the next one) overloads are replaced with good - old const and non-const overloads. -
    • -
  • - Example: -
    optional<char> first_char(const string& s) {
-  return s.empty() ? none : optional<char>(s[0]);
-};
-optional<string> o1 {}, o2 {"cat"};
-optional<char> os1 = o1.flat_map(first_char), os2 = o2.flat_map(first_char);
-assert ( !os1 ) ;
-assert ( os2 ) ;
-assert ( *os2 == 'c' ) ;
-
    - space -
    • -
-

- template<class F> auto optional<T>::flat_map(F f) && - -> see below - ; -

-
    -
  • - Requires: The return type of expression - f(std::move(**this)) - is optional<U> - for some object or reference type U. -
    • -
  • - Effects: if - (*this) return f(std::move(**this)); else return - none; -
    • -
  • - Notes: The return type of this overload - is optional<U>. -
    • -
-

- space -

-

- T const& optional<T>::get_value_or( T const& default) const ; -

-

- T& - optional<T>::get_value_or( - T& - default ) - ; -

-
    -
  • - Deprecated: Use value_or() instead. -
    • -
  • - 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 = opt.get_value_or(z);
-assert ( u == v ) ;
-assert ( u != z ) ;
-
    -
    • -
-

- space -

-

- T const* optional<T>::get_ptr() const ; -

-

- T* - optional<T>::get_ptr() - ; -

-
    -
  • - Returns: If *this is initialized, a pointer to the - contained value; else 0 - (null). -
    • -
  • - Throws: Nothing. -
    • -
  • - Notes: The contained value is permanently - stored within *this, - so you should not hold nor delete this pointer -
    • -
  • - Example: -
    T v;
-optional<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) ) ;
-
    -
    • -
-

- space -

-

- T const* optional<T>::operator - ->() const - ; -

-

- T* - optional<T>::operator ->() - ; -

-
    -
  • - Requires: *this is initialized. -
    • -
  • - Returns: A pointer to the contained - value. -
    • -
  • - Throws: Nothing. -
    • -
  • - Notes: The requirement is asserted - via BOOST_ASSERT(). -
    • -
  • - Example: -
    struct X { int mdata ; } ;
-X x ;
-optional<X> opt (x);
-opt->mdata = 2 ;
-
    -
    • -
-

- space -

-

- explicit optional<T>::operator - bool() - const noexcept - ; -

-

- bool optional<T>::has_value() const noexcept ; -

-
    -
  • - Returns: get_ptr() != 0. -
    • -
  • - Notes: On compilers that do not support - explicit conversion operators this falls back to safe-bool idiom. -
    • -
  • - Example: -
    optional<T> def ;
-assert ( def == 0 );
-optional<T> opt ( v ) ;
-assert ( opt );
-assert ( opt != 0 );
-
    -
    • -
-

- space -

-

- bool optional<T>::operator!() noexcept - ; -

-
    -
  • - Returns: If *this is uninitialized, true; else false. -
    • -
  • - Notes: This operator is provided for - those compilers which can't use the unspecified-bool-type - operator in certain boolean contexts. -
    • -
  • - Example: -
    optional<T> opt ;
-assert ( !opt );
-*opt = some_T ;
-
-// Notice the "double-bang" idiom here.
-assert ( !!opt ) ;
-
    -
    • -
-

- space -

-

- bool optional<T>::is_initialized() const ; -

-
  • - Deprecated: Same as explicit operator - bool () - ; -
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/header__boost_optional_hpp_.html b/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/header__boost_optional_hpp_.html deleted file mode 100644 index 8496d372..00000000 --- a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/header__boost_optional_hpp_.html +++ /dev/null @@ -1,47 +0,0 @@ - - - -Header <boost/optional.hpp> - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- This is an alias for header <boost/optional/optional.hpp>. -

-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2016 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/header_optional_in_place_init.html b/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/header_optional_in_place_init.html deleted file mode 100644 index ca73fd90..00000000 --- a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/header_optional_in_place_init.html +++ /dev/null @@ -1,61 +0,0 @@ - - - -Initialization tags - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-
namespace boost {
-
-class in_place_init_t { /* see below */ } ;
-const in_place_init_t in_place_init ( /* see below */ ) ;
-
-class in_place_init_if_t { /*see below*/ } ;
-const in_place_init_if_t in_place_init_if ( /*see below*/ ) ;
-
-}
-
-

- Classes in_place_init_t - and in_place_init_if_t - are empty classes. Their purpose is to control overload resolution in the - initialization of optional objects. They are empty, trivially copyable - classes with disabled default constructor. -

-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/header_optional_optional_refs.html b/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/header_optional_optional_refs.html deleted file mode 100644 index 3244e972..00000000 --- a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/header_optional_optional_refs.html +++ /dev/null @@ -1,118 +0,0 @@ - - - -Optional References - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-
template <class T>
-class optional<T&> // specialization for lvalue references
-{
-public :
-
-    typedef T& value_type;
-    typedef T& reference_type;
-    typedef T& reference_const_type; // no const propagation
-    typedef T& rval_reference_type;
-    typedef T* pointer_type;
-    typedef T* pointer_const_type;   // no const propagation
-
-    optional () noexcept ; R
-
-    optional ( none_t ) noexcept ; R
-
-    template<class R> optional(R&& r) noexcept ;  R
-
-    template <class R> optional(bool cond, R&& r) noexcept ; R
-
-    optional ( optional const& rhs ) noexcept ; R
-
-    template<class U> explicit optional ( optional<U&> const& rhs ) noexcept ; R
-
-    optional& operator = ( none_t ) noexcept ; R
-
-    optional& operator = ( optional const& rhs ) noexcept; R
-
-    template<class U> optional& operator = ( optional<U&> const& rhs ) noexcept ; R
-
-    template<class R> optional& operator = (R&& r) noexcept ; R
-
-    template<class R> void emplace ( R&& r ) noexcept ; R
-
-    T& get() const ; R
-    T& operator *() const ; R
-
-    T* operator ->() const ; R
-
-    T& value() const& ; R
-
-    template<class R> T& value_or( R && r ) const noexcept ; R
-
-    template<class F> T& value_or_eval( F f ) const ; R
-
-    template<class F> auto map( F f ) const -> see below; R
-
-    template<class F> auto flat_map( F f ) const -> see below; R
-
-    T* get_ptr() const noexcept ; R
-
-    bool has_value() const noexcept ; R
-
-    explicit operator bool() const noexcept ; R
-
-    bool operator!() const noexcept ; R
-
-    void reset() noexcept ; R
-
-    // deprecated methods
-
-    // (deprecated)
-    template<class R> void reset ( R && r ) noexcept ; R
-
-    // (deprecated)
-    bool is_initialized() const noexcept ; R
-
-    // (deprecated)
-    template<class R> T& get_value_or( R && r ) constnoexcept; R
-
-private:
-    T* ref; // exposition only
-};
-
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/header_optional_optional_values.html b/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/header_optional_optional_values.html deleted file mode 100644 index 80d648a6..00000000 --- a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/header_optional_optional_values.html +++ /dev/null @@ -1,153 +0,0 @@ - - - -Optional Values - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-
template <class T>
-class optional
-{
-public :
-
-    typedef T         value_type ;
-    typedef T &       reference_type ;
-    typedef T const&  reference_const_type ;
-    typedef T &&      rval_reference_type ;
-    typedef T *       pointer_type ;
-    typedef T const*  pointer_const_type ;
-
-    optional () noexcept ; R
-
-    optional ( none_t ) noexcept ; R
-
-    optional ( T const& v ) ; R
-
-    optional ( T&& v ) ; R
-
-    optional ( bool condition, T const& v ) ; R
-
-    optional ( optional const& rhs ) ; R
-
-    optional ( optional&& rhs ) noexcept(see below) ; R
-
-    template<class U> explicit optional ( optional<U> const& rhs ) ; R
-
-    template<class U> explicit optional ( optional<U>&& rhs ) ; R
-
-    template<class... Args> explicit optional ( in_place_init_t, Args&&... args ) ; R
-
-    template<class... Args> explicit optional ( in_place_init_if_t, bool condition, Args&&... args ) ; R
-
-    template<class InPlaceFactory> explicit optional ( InPlaceFactory const& f ) ; R
-
-    template<class TypedInPlaceFactory> explicit optional ( TypedInPlaceFactory const& f ) ; R
-
-    optional& operator = ( none_t ) noexcept ; R
-
-    optional& operator = ( T const& v ) ; R
-
-    optional& operator = ( T&& v ) ; R
-
-    optional& operator = ( optional const& rhs ) ; R
-
-    optional& operator = ( optional&& rhs ) noexcept(see below) ; R
-
-    template<class U> optional& operator = ( optional<U> const& rhs ) ; R
-
-    template<class U> optional& operator = ( optional<U>&& rhs ) ; R
-
-    template<class... Args> void emplace ( Args&&... args ) ; R
-
-    template<class InPlaceFactory> optional& operator = ( InPlaceFactory const& f ) ; R
-
-    template<class TypedInPlaceFactory> optional& operator = ( TypedInPlaceFactory const& f ) ; R
-
-    T const& get() const ; R
-    T&       get() ; R
-
-    T const* operator ->() const ; R
-    T*       operator ->() ; R
-
-    T const& operator *() const& ; R
-    T&       operator *() & ; R
-    T&&      operator *() && ; R
-
-    T const& value() const& ; R
-    T&       value() & ; R
-    T&&      value() && ; R
-
-    template<class U> T value_or( U && v ) const& ; R
-    template<class U> T value_or( U && v ) && ; R
-
-    template<class F> T value_or_eval( F f ) const& ; R
-    template<class F> T value_or_eval( F f ) && ; R
-
-    template<class F> auto map( F f ) const& -> see below; R
-    template<class F> auto map( F f ) & -> see below; R
-    template<class F> auto map( F f ) && -> see below; R
-
-    template<class F> auto flat_map( F f ) const& -> see below; R
-    template<class F> auto flat_map( F f ) & -> see below; R
-    template<class F> auto flat_map( F f ) && -> see below; R
-
-    T const* get_ptr() const ; R
-    T*       get_ptr() ; R
-
-    bool has_value() const noexcept ; R
-
-    explicit operator bool() const noexcept ; R
-
-    bool operator!() const noexcept ; R
-
-    void reset() noexcept ; R
-
-    // deprecated methods
-
-    // (deprecated)
-    void reset ( T const& ) ; R
-
-    // (deprecated)
-    bool is_initialized() const ; R
-
-    // (deprecated)
-    T const& get_value_or( T const& default ) const ; R
-};
-
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/reference/io_header.html b/doc/html/boost_optional/reference/io_header.html deleted file mode 100644 index 9b33523a..00000000 --- a/doc/html/boost_optional/reference/io_header.html +++ /dev/null @@ -1,72 +0,0 @@ - - - -Header <boost/optional/optional_io.hpp> - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-
-
-

-

-
#include <istream>
-#include <ostream>
-#include <boost/optional/optional.hpp>
-
-namespace boost {
-
-template <class CharType, class CharTrait, class T>
-  std::basic_ostream<CharType, CharTrait>&
-  operator<<(std::basic_ostream<CharType, CharTrait>& out, optional<T> const& v); R
-
-  template <class CharType, class CharTrait>
-  std::basic_ostream<CharType, CharTrait>&
-  operator<<(std::basic_ostream<CharType, CharTrait>& out, none_t const&); R
-
-template<class CharType, class CharTrait, class T>
-  std::basic_istream<CharType, CharTrait>&
-  operator>>(std::basic_istream<CharType, CharTrait>& in, optional<T>& v); R
-
-} // namespace boost
-
-

-

-
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/reference/io_header/io_semantics.html b/doc/html/boost_optional/reference/io_header/io_semantics.html deleted file mode 100644 index f74ff4ac..00000000 --- a/doc/html/boost_optional/reference/io_header/io_semantics.html +++ /dev/null @@ -1,112 +0,0 @@ - - - -Detailed semantics - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- template - <class - CharType, - class CharTrait, class T> -
    std::basic_ostream<CharType, CharTrait>&
    operator<<(std::basic_ostream<CharType, CharTrait>& - out, - optional<T> const& v); -

-
    -
  • - Effect: Outputs an implementation-defined - string. The output contains the information about whether the optional - object contains a value or not. If v - contains a value, the output contains result of calling out << - *v. -
    • -
  • - Returns: out. -
    • -
-

- space -

-

- template <class CharType, class CharTrait, - class T>
    std::basic_ostream<CharType, CharTrait>& -
    operator<<(std::basic_ostream<CharType, CharTrait>& out, none_t); -

-
    -
  • - Effect: Outputs an implementation-defined - string. -
    • -
  • - Returns: out. -
    • -
-

- space -

-

- template <class CharType, class CharTrait, - class T>
    std::basic_ostream<CharType, CharTrait>& -
    operator>>(std::basic_istream<CharType, CharTrait>& in, optional<T>& v); -

-
    -
  • - Requires: T - is DefaultConstructible and - MoveConstructible. -
    • -
  • - Effect: Reads the value of optional - object from in. If - the string representation indicates that the optional object should - contain a value, v - contains a value and its contained value is obtained as if by default-constructing - an object o of type - T and then calling - in >> - o; otherwise v does not contain a value, and the - previously contained value (if any) has been destroyed. -
    • -
  • - Returns: out. -
    • -
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/reference/relnotes.html b/doc/html/boost_optional/reference/relnotes.html deleted file mode 100644 index c67535ea..00000000 --- a/doc/html/boost_optional/reference/relnotes.html +++ /dev/null @@ -1,183 +0,0 @@ - - - -Release Notes - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-
- - Boost Release - X.XX -
-
  • - Now boost::optional is specialized for reference - parameters. This way the sizeof - of optional reference is that of a pointer, and a number of bugs is avoided. -
-
- - Boost Release - 1.60 -
-
  • - Changed the implementation of boost::none - again. Now it is a const object with internal linkage (as any other tag). - This fixes Trac - #11203. -
-
- - Boost Release - 1.59 -
-
    -
  • - For C++03 compilers, added 0-argument overload for member function emplace(), - and therewith removed the dependency on <boost/utility/in_place_factory.hpp>. -
    • -
  • - Fixed Trac - #11241. -
    • -
-
- - Boost Release - 1.58 -
-
    -
  • - boost::none_t is no longer convertible from - literal 0. This avoids a - bug where optional<rational<int>> - oi = - 0; - would initialize an optional object with no contained value. -
    • -
  • - Improved the trick that prevents streaming out optional - without header optional_io.hpp - by using safe-bool idiom. This addresses Trac - #10825. -
    • -
  • - IOStream operators are now mentioned in documentation. -
    • -
  • - Added a way to manually disable move semantics: just define macro BOOST_OPTIONAL_CONFIG_NO_RVALUE_REFERENCES. - This can be used to work around Trac - #10399. -
    • -
  • - It is no longer possible to assign optional<U> to optional<T> when U - is not assignable or convertible to T - (Trac #11087). -
    • -
  • - Value accessors now work correctly on rvalues of optional<T&> (Trac - #10839). -
    • -
-
- - Boost Release - 1.57 -
-
  • - Git pull #9: - "Supply <string> - to fix C++03 compile error on logic_error("...")". -
-
- - Boost Release - 1.56 -
-
    -
  • - Added support for rvalue references. Now optional<T> works with moveable but non-copyable - T's, -
    • -
  • - Improved swap (now uses - move operations), -
    • -
  • - Added function emplace(). This is the last of the requests from - Trac #1841, -
    • -
  • - optional is moveable, - including conditional noexcept - specifications, which make it move_if_noexcept-friendly, -
    • -
  • - Using explicit operator bool() on platforms that support it (Trac - #4227) (breaking change), -
    • -
  • - Forward declaration of operator<<(ostream&, optional - const&) - to prevent inadvertent incorrect serialization of optional objects, -
    • -
  • - Removed deprecated function reset() from examples (Trac - #9005), -
    • -
  • - Equality comparison with boost::none - does not require that T - be EqualityComparable, -
    • -
  • - Optional rvalue references are explicitly disallowed, -
    • -
  • - Binding temporaries to optional references is explicitly disallowed (breaking - change), -
    • -
  • - More ways to access the contained value, functions value(), value_or(), value_or_eval(), -
    • -
  • - Updated and reorganized documentation, added tutorial and quick guide - sections. -
    • -
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2016 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/relnotes.html b/doc/html/boost_optional/relnotes.html deleted file mode 100644 index ae833827..00000000 --- a/doc/html/boost_optional/relnotes.html +++ /dev/null @@ -1,384 +0,0 @@ - - - -Release Notes - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- - Boost - Release 1.79 -

-
    -
  • - Fixed issue - #98. -
    • -
  • - Fixed issue - #92. -
    • -
  • - Added support for BOOST_NO_IOSTREAM. -
    • -
  • - Now aligned storage uses unsigned - char rather than char - to avoid UB. -
    • -
  • - Now using cv-unqualified value_type - with placement new to avoid - UB. -
    • -
-

- - Boost - Release 1.76 -

-
  • - Fixed MSVC warning C4702. -
-

- - Boost - Release 1.75 -

-
    -
  • - boost::none is constexpr-declared. -
    • -
  • - Fixed issue - #78. -
    • -
-

- - Boost - Release 1.73 -

-
    -
  • - Fixed issue - #78. -
    • -
  • - boost::none is now declared as an inline variable - (on compilers that support it): there is only one instance of boost::none across all translation units. -
    • -
  • - Fixed a number of compilation errors in GCC 4.4.7 in optional<T> for trivial Ts. - Thanks to Robert Leahy for the fix. For details see pr - #78. -
    • -
  • - Now suppressing warning -Wweak-vtables. -
    • -
-

- - Boost - Release 1.69 -

-
    -
  • - Remove deprecation mark from reset() method (without arguments). -
    • -
  • - Fixed issue - #59. -
    • -
  • - Fixed bug with initialization of certain wrapper types in clang with -std=c++03. - See pr #64. -
    • -
-

- - Boost - Release 1.68 -

-
    -
  • - Added member function has_value() for compatibility with std::optional (issue - #52). -
    • -
  • - Added member function map() for transforming optional<T> into optional<U> using a function of type T -> U. -
    • -
  • - Added member function flat_map() for transforming optional<T> into optional<U> using a function of type T -> optional<U>. -
    • -
-

- - Boost - Release 1.67 -

-
    -
  • - Fixed issue - #46. -
    • -
  • - Fixed -Wzero-as-null-pointer-constant warnings. -
    • -
-

- - Boost - Release 1.66 -

-
    -
  • - On newer compilers optional - is now trivially-copyable for scalar Ts. - This uses a different storage (just T - rather than aligned_storage). - We require the compiler to support defaulted functions. -
    • -
  • - Changed the implementation of operator== to get rid of the -Wmaybe-uninitialized false-positive warning - from GCC. -
    • -
-

- - Boost - Release 1.63 -

-
    -
  • - Added two new in-place constructors. They work similarly to emplace() - functions: they initialize the contained value by perfect-forwarding the - obtained arguments. One constructor always initializes the contained value, - the other based on a boolean condition. -
    • -
  • - Syntax o = - {} now correctly un-initializes - optional, just like in std::optional. -
    • -
  • - Fixed Trac #12203. -
    • -
  • - Fixed Trac #12563. -
    • -
-

- - Boost - Release 1.62 -

-
-

- - Boost - Release 1.61 -

-
    -
  • - Now boost::optional is specialized for reference - parameters. This addresses a couple of issues: -
      -
    • - the sizeof of optional - reference is that of a pointer, -
      • -
    • - some bugs connected to copying optional references are gone, -
      • -
    • - all run-time bugs caused by incorrect reference binding on some compilers - are now turned into compile-time errors, -
      • -
    • - you can swap optional references: it is like swapping pointers: shallow, - underlying objects are not affected, -
      • -
    • - optional references to abstract types work. -
      • -
    -
    • -
  • - Documented nested typedefs (Trac - #5193). -
    • -
  • - Made the perfect-forwarding constructor SFINAE-friendly, which fixes Trac #12002. - However, this only works in the newer platforms that correctly implement - C++11 <type_traits>. -
    • -
  • - Fixed Trac #10445. -
    • -
-

- - Boost - Release 1.60 -

-
  • - Changed the implementation of boost::none - again. Now it is a const object with internal linkage (as any other tag). - This fixes Trac - #11203. -
-

- - Boost - Release 1.59 -

-
    -
  • - For C++03 compilers, added 0-argument overload for member function emplace(), - and therewith removed the dependency on <boost/utility/in_place_factory.hpp>. -
    • -
  • - Fixed Trac #11241. -
    • -
-

- - Boost - Release 1.58 -

-
    -
  • - boost::none_t is no longer convertible from - literal 0. This avoids a bug - where optional<rational<int>> oi = 0; would - initialize an optional object with no contained value. -
    • -
  • - Improved the trick that prevents streaming out optional - without header optional_io.hpp - by using safe-bool idiom. This addresses Trac - #10825. -
    • -
  • - IOStream operators are now mentioned in documentation. -
    • -
  • - Added a way to manually disable move semantics: just define macro BOOST_OPTIONAL_CONFIG_NO_RVALUE_REFERENCES. - This can be used to work around Trac - #10399. -
    • -
  • - It is no longer possible to assign optional<U> to optional<T> when U - is not assignable or convertible to T - (Trac #11087). -
    • -
  • - Value accessors now work correctly on rvalues of optional<T&> (Trac - #10839). -
    • -
-

- - Boost - Release 1.57 -

-
  • - Git pull #9: - "Supply <string> - to fix C++03 compile error on logic_error("...")". -
-

- - Boost - Release 1.56 -

-
    -
  • - Added support for rvalue references. Now optional<T> works with moveable but non-copyable - T's, -
    • -
  • - Improved swap (now uses - move operations), -
    • -
  • - Added function emplace(). This is the last of the requests from - Trac #1841, -
    • -
  • - optional is moveable, including - conditional noexcept specifications, - which make it move_if_noexcept-friendly, -
    • -
  • - Using explicit operator bool() on platforms that support it (Trac - #4227) (breaking change), -
    • -
  • - Forward declaration of operator<<(ostream&, optional - const&) - to prevent inadvertent incorrect serialization of optional objects, -
    • -
  • - Removed deprecated function reset() from examples (Trac - #9005), -
    • -
  • - Equality comparison with boost::none - does not require that T - be EqualityComparable, -
    • -
  • - Optional rvalue references are explicitly disallowed, -
    • -
  • - Binding temporaries to optional references is explicitly disallowed (breaking - change), -
    • -
  • - More ways to access the contained value, functions value(), value_or(), value_or_eval(), -
    • -
  • - Updated and reorganized documentation, added tutorial and quick guide sections. -
    • -
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/synopsis.html b/doc/html/boost_optional/synopsis.html deleted file mode 100644 index 0de90e79..00000000 --- a/doc/html/boost_optional/synopsis.html +++ /dev/null @@ -1,174 +0,0 @@ - - - -Synopsis - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-
// In Header: <boost/optional/optional.hpp>
-
-namespace boost {
-
-template<class T>
-class optional
-{
-    public :
-
-    // (If T is of reference type, the parameters and results by reference are by value)
-
-    optional () noexcept ; R
-
-    optional ( none_t ) noexcept ; R
-
-    optional ( T const& v ) ; R
-
-    optional ( T&& v ) ; R
-
-    // [new in 1.34]
-    optional ( bool condition, T const& v ) ; R
-
-    optional ( optional const& rhs ) ; R
-
-    optional ( optional&& rhs ) noexcept(see below) ; R
-
-    template<class U> explicit optional ( optional<U> const& rhs ) ; R
-
-    template<class U> explicit optional ( optional<U>&& rhs ) ; R
-
-    template<class InPlaceFactory> explicit optional ( InPlaceFactory const& f ) ; R
-
-    template<class TypedInPlaceFactory> explicit optional ( TypedInPlaceFactory const& f ) ; R
-
-    optional& operator = ( none_t ) noexcept ; R
-
-    optional& operator = ( T const& v ) ; R
-
-    optional& operator = ( T&& v ) ; R
-
-    optional& operator = ( optional const& rhs ) ; R
-
-    optional& operator = ( optional&& rhs ) noexcept(see below) ; R
-
-    template<class U> optional& operator = ( optional<U> const& rhs ) ; R
-
-    template<class U> optional& operator = ( optional<U>&& rhs ) ; R
-
-    template<class... Args> void emplace ( Args...&& args ) ; R
-
-    template<class InPlaceFactory> optional& operator = ( InPlaceFactory const& f ) ; R
-
-    template<class TypedInPlaceFactory> optional& operator = ( TypedInPlaceFactory const& f ) ; R
-
-    T const& get() const ; R
-    T&       get() ; R
-
-    T const* operator ->() const ; R
-    T*       operator ->() ; R
-
-    T const& operator *() const& ; R
-    T&       operator *() &; R
-    T&&      operator *() &&; R
-
-    T const& value() const& ; R
-    T&       value() & ; R
-    T&&      value() && ; R
-
-    template<class U> T value_or( U && v ) const& ; R
-    template<class U> T value_or( U && v ) && ; R
-
-    T const* get_ptr() const ; R
-    T*       get_ptr() ; R
-
-    explicit operator bool() const ; R
-
-    bool operator!() const noexcept ; R
-
-    // deprecated methods
-
-    // (deprecated)
-    void reset() noexcept ; R
-
-    // (deprecated)
-    void reset ( T const& ) ; R
-
-    // (deprecated)
-    bool is_initialized() const ; R
-
-    // (deprecated)
-    T const& get_value_or( T const& default ) const ; R
-};
-
-template<class T> inline bool operator == ( optional<T> const& x, optional<T> const& y ) ; R
-
-template<class T> inline bool operator != ( optional<T> const& x, optional<T> const& y ) ; R
-
-template<class T> inline bool operator <  ( optional<T> const& x, optional<T> const& y ) ; R
-
-template<class T> inline bool operator >  ( optional<T> const& x, optional<T> const& y ) ; R
-
-template<class T> inline bool operator <= ( optional<T> const& x, optional<T> const& y ) ; R
-
-template<class T> inline bool operator >= ( optional<T> const& x, optional<T> const& y ) ; R
-
-template<class T> inline bool operator == ( optional<T> const& x, none_t ) noexcept ; R
-
-template<class T> inline bool operator != ( optional<T> const& x, none_t ) noexcept ; R
-
-template<class T> inline optional<T> make_optional ( T const& v ) ; R
-
-template<class T> inline optional<T> make_optional ( bool condition, T const& v ) ; R
-
-template<class T> inline T const& get_optional_value_or ( optional<T> const& opt, T const& default ) ; R
-
-template<class T> inline T const& get ( optional<T> const& opt ) ; R
-
-template<class T> inline T& get ( optional<T> & opt ) ; R
-
-template<class T> inline T const* get ( optional<T> const* opt ) ; R
-
-template<class T> inline T* get ( optional<T>* opt ) ; R
-
-template<class T> inline T const* get_pointer ( optional<T> const& opt ) ; R
-
-template<class T> inline T* get_pointer ( optional<T> & opt ) ; R
-
-template<class T> inline void swap( optional<T>& x, optional<T>& y ) ; R
-
-} // namespace boost
-
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/tutorial.html b/doc/html/boost_optional/tutorial.html deleted file mode 100644 index 9cee12a2..00000000 --- a/doc/html/boost_optional/tutorial.html +++ /dev/null @@ -1,523 +0,0 @@ - - - -Tutorial - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-
-
Motivation
-
Design Overview
-
-
-
-

- Consider these functions which should return a value but which might not - have a value to return: -

-
    -
  • - (A) double sqrt(double n ); -
    • -
  • - (B) char get_async_input(); -
    • -
  • - (C) point polygon::get_any_point_effectively_inside(); -
    • -
-

- There are different approaches to the issue of not having a value to return. -

-

- A typical approach is to consider the existence of a valid return value as - a postcondition, so that if the function cannot compute the value to return, - it has either undefined behavior (and can use assert in a debug build) or - uses a runtime check and throws an exception if the postcondition is violated. - This is a reasonable choice for example, for function (A), because the lack - of a proper return value is directly related to an invalid parameter (out - of domain argument), so it is appropriate to require the callee to supply - only parameters in a valid domain for execution to continue normally. -

-

- However, function (B), because of its asynchronous nature, does not fail - just because it can't find a value to return; so it is incorrect to consider - such a situation an error and assert or throw an exception. This function - must return, and somehow, must tell the callee that it is not returning a - meaningful value. -

-

- A similar situation occurs with function (C): it is conceptually an error - to ask a null-area polygon to return a point inside - itself, but in many applications, it is just impractical for performance - reasons to treat this as an error (because detecting that the polygon has - no area might be too expensive to be required to be tested previously), and - either an arbitrary point (typically at infinity) is returned, or some efficient - way to tell the callee that there is no such point is used. -

-

- There are various mechanisms to let functions communicate that the returned - value is not valid. One such mechanism, which is quite common since it has - zero or negligible overhead, is to use a special value which is reserved - to communicate this. Classical examples of such special values are EOF, string::npos, - points at infinity, etc... -

-

- When those values exist, i.e. the return type can hold all meaningful values - plus the signal value, this mechanism - is quite appropriate and well known. Unfortunately, there are cases when - such values do not exist. In these cases, the usual alternative is either - to use a wider type, such as int - in place of char; or a compound - type, such as std::pair<point,bool>. -

-

- Returning a std::pair<T,bool>, thus attaching a boolean flag to the - result which indicates if the result is meaningful, has the advantage that - can be turned into a consistent idiom since the first element of the pair - can be whatever the function would conceptually return. For example, the - last two functions could have the following interface: -

-
std::pair<char,bool> get_async_input();
-std::pair<point,bool> polygon::get_any_point_effectively_inside();
-
-

- These functions use a consistent interface for dealing with possibly nonexistent - results: -

-
std::pair<point,bool> p = poly.get_any_point_effectively_inside();
-if ( p.second )
-    flood_fill(p.first);
-
-

- However, not only is this quite a burden syntactically, it is also error - prone since the user can easily use the function result (first element of - the pair) without ever checking if it has a valid value. -

-

- Clearly, we need a better idiom. -

-
-
-
-
-
The - models
-
The - semantics
-
The - Interface
-
-
-
-

- In C++, we can declare an object (a variable) of type - T, and we can give this - variable an initial value (through an initializer. - (cf. 8.5)). When a declaration includes a non-empty initializer (an initial - value is given), it is said that the object has been initialized. If the - declaration uses an empty initializer (no initial value is given), and - neither default nor value initialization applies, it is said that the object - is uninitialized. Its actual value exist - but has an indeterminate initial value (cf. 8.5/11). - optional<T> - intends to formalize the notion of initialization (or lack of it) allowing - a program to test whether an object has been initialized and stating that - access to the value of an uninitialized object is undefined behavior. That - is, when a variable is declared as optional<T> and no initial value is given, the - variable is formally uninitialized. A formally uninitialized - optional object has conceptually no value at all and this situation can - be tested at runtime. It is formally undefined behavior - to try to access the value of an uninitialized optional. An uninitialized - optional can be assigned a value, in which case its initialization state - changes to initialized. Furthermore, given the formal treatment of initialization - states in optional objects, it is even possible to reset an optional to - uninitialized. -

-

- In C++ there is no formal notion of uninitialized objects, which means - that objects always have an initial value even if indeterminate. As discussed - on the previous section, this has a drawback because you need additional - information to tell if an object has been effectively initialized. One - of the typical ways in which this has been historically dealt with is via - a special value: EOF, - npos, -1, etc... This is - equivalent to adding the special value to the set of possible values of - a given type. This super set of T - plus some nil_t—where nil_t - is some stateless POD—can be modeled in modern languages as a discriminated union of T and nil_t. Discriminated - unions are often called variants. A variant has a - current type, which in our case is either T or nil_t. - Using the Boost.Variant - library, this model can be implemented in terms of boost::variant<T,nil_t>. There is precedent for a discriminated - union as a model for an optional value: the Haskell - Maybe built-in type constructor. Thus, - a discriminated union T+nil_t - serves as a conceptual foundation. -

-

- A variant<T,nil_t> follows naturally from the traditional - idiom of extending the range of possible values adding an additional sentinel - value with the special meaning of Nothing. However, - this additional Nothing value is largely irrelevant - for our purpose since our goal is to formalize the notion of uninitialized - objects and, while a special extended value can be used to convey that - meaning, it is not strictly necessary in order to do so. -

-

- The observation made in the last paragraph about the irrelevant nature - of the additional nil_t - with respect to purpose of optional<T> - suggests an alternative model: a container that either - has a value of T or nothing. -

-

- 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. -

-

- In any event, both the discriminated-union or the single-element container - models serve as a conceptual ground for a class representing optional—i.e. - possibly uninitialized—objects. For instance, these models show the - exact semantics required for a wrapper of optional - values: -

-

- Discriminated-union: -

-
    -
  • - deep-copy semantics: copies of the - variant implies copies of the value. -
    • -
  • - deep-relational semantics: comparisons - between variants matches both current types and values -
    • -
  • - If the variant's current type is T, - it is modeling an initialized optional. -
    • -
  • - If the variant's current type is not T, - it is modeling an uninitialized optional. -
    • -
  • - Testing if the variant's current type is T - models testing if the optional is initialized -
    • -
  • - Trying to extract a T - from a variant when its current type is not T, - models the undefined behavior of trying to access the value of an uninitialized - optional -
    • -
-

- Single-element container: -

-
    -
  • - deep-copy semantics: copies of the - container implies copies of the value. -
    • -
  • - deep-relational semantics: comparisons - between containers compare container size and if match, contained value -
    • -
  • - If the container is not empty (contains an object of type T), it is modeling an initialized - optional. -
    • -
  • - If the container is empty, it is modeling an uninitialized - optional. -
    • -
  • - Testing if the container is empty models testing if the optional is - initialized -
    • -
  • - Trying to extract a T - from an empty container models the undefined behavior of trying to - access the value of an uninitialized optional -
    • -
-
-
-
-

- Objects of type optional<T> are intended to be used in places where - objects of type T would - but which might be uninitialized. Hence, optional<T>'s purpose is to formalize the additional - possibly uninitialized state. From the perspective of this role, optional<T> - can have the same operational semantics of T - plus the additional semantics corresponding to this special state. As such, - optional<T> - could be thought of as a supertype of T. Of course, we can't do that in C++, - so we need to compose the desired semantics using a different mechanism. - Doing it the other way around, that is, making optional<T> a subtype of - T is not only conceptually - wrong but also impractical: it is not allowed to derive from a non-class - type, such as a built-in type. -

-

- We can draw from the purpose of optional<T> the required basic semantics: -

-
    -
  • - Default Construction: To introduce - a formally uninitialized wrapped object. -
    • -
  • - Direct Value Construction via copy: - To introduce a formally initialized wrapped object whose value is obtained - as a copy of some object. -
    • -
  • - Deep Copy Construction: To obtain - a new yet equivalent wrapped object. -
    • -
  • - Direct Value Assignment (upon initialized): - To assign a value to the wrapped object. -
    • -
  • - Direct Value Assignment (upon uninitialized): - To initialize the wrapped object with a value obtained as a copy of - some object. -
    • -
  • - Assignment (upon initialized): To - assign to the wrapped object the value of another wrapped object. -
    • -
  • - Assignment (upon uninitialized): To - initialize the wrapped object with value of another wrapped object. -
    • -
  • - Deep Relational Operations (when supported by - the type T): To compare wrapped object values taking into - account the presence of uninitialized states. -
    • -
  • - Value access: To unwrap the wrapped - object. -
    • -
  • - Initialization state query: To determine - if the object is formally initialized or not. -
    • -
  • - Swap: To exchange wrapped objects. - (with whatever exception safety guarantees are provided by T's swap). -
    • -
  • - De-initialization: To release the - wrapped object (if any) and leave the wrapper in the uninitialized - state. -
    • -
-

- Additional operations are useful, such as converting constructors and converting - assignments, in-place construction and assignment, and safe value access - via a pointer to the wrapped object or null. -

-
-
-
-

- Since the purpose of optional is to allow us to use objects with a formal - uninitialized additional state, the interface could try to follow the interface - of the underlying T type - as much as possible. In order to choose the proper degree of adoption of - the native T interface, - the following must be noted: Even if all the operations supported by an - instance of type T are - defined for the entire range of values for such a type, an optional<T> - extends such a set of values with a new value for which most (otherwise - valid) operations are not defined in terms of T. -

-

- Furthermore, since optional<T> itself is merely a T - wrapper (modeling a T supertype), - any attempt to define such operations upon uninitialized optionals will - be totally artificial w.r.t. T. -

-

- This library chooses an interface which follows from T's - interface only for those operations which are well defined (w.r.t the type - T) even if any of the operands - are uninitialized. These operations include: construction, copy-construction, - assignment, swap and relational operations. -

-

- For the value access operations, which are undefined (w.r.t the type T) when the operand is uninitialized, - a different interface is chosen (which will be explained next). -

-

- Also, the presence of the possibly uninitialized state requires additional - operations not provided by T - itself which are supported by a special interface. -

-
- - Lexically-hinted - Value Access in the presence of possibly uninitialized optional objects: - The operators * and -> -
-

- A relevant feature of a pointer is that it can have a null - pointer value. This is a special value - which is used to indicate that the pointer is not referring to any object - at all. In other words, null pointer values convey the notion of nonexistent - objects. -

-

- This meaning of the null pointer value allowed pointers to became a de - facto standard for handling optional objects because all you - have to do to refer to a value which you don't really have is to use a - null pointer value of the appropriate type. Pointers have been used for - decades—from the days of C APIs to modern C++ libraries—to refer - to optional (that is, possibly nonexistent) objects; particularly as optional - arguments to a function, but also quite often as optional data members. -

-

- The possible presence of a null pointer value makes the operations that - access the pointee's value possibly undefined, therefore, expressions which - use dereference and access operators, such as: ( - *p - = 2 ) and ( - p->foo() ), implicitly convey the notion of optionality, - and this information is tied to the syntax of the - expressions. That is, the presence of operators * - and -> tell by themselves - —without any additional context— that the expression will be undefined - unless the implied pointee actually exist. -

-

- Such a de facto idiom for referring to optional objects - can be formalized in the form of a concept: the OptionalPointee - concept. This concept captures the syntactic usage of operators *, -> - and contextual conversion to bool - to convey the notion of optionality. -

-

- However, pointers are good to refer - to optional objects, but not particularly good to handle the optional objects - in all other respects, such as initializing or moving/copying them. The - problem resides in the shallow-copy of pointer semantics: if you need to - effectively move or copy the object, pointers alone are not enough. The - problem is that copies of pointers do not imply copies of pointees. For - example, as was discussed in the motivation, pointers alone cannot be used - to return optional objects from a function because the object must move - outside from the function and into the caller's context. -

-

- A solution to the shallow-copy problem that is often used is to resort - to dynamic allocation and use a smart pointer to automatically handle the - details of this. For example, if a function is to optionally return an - object X, it can use shared_ptr<X> - as the return value. However, this requires dynamic allocation of X. If X - is a built-in or small POD, this technique is very poor in terms of required - resources. Optional objects are essentially values so it is very convenient - to be able to use automatic storage and deep-copy semantics to manipulate - optional values just as we do with ordinary values. Pointers do not have - this semantics, so are inappropriate for the initialization and transport - of optional values, yet are quite convenient for handling the access to - the possible undefined value because of the idiomatic aid present in the - OptionalPointee - concept incarnated by pointers. -

-
- - Optional<T> - as a model of OptionalPointee -
-

- For value access operations optional<> uses operators * - and -> to lexically warn - about the possibly uninitialized state appealing to the familiar pointer - semantics w.r.t. to null pointers. -

-
- - - - - -
[Warning]Warning

- However, it is particularly important to note that optional<> objects are not pointers. optional<> is not, and does not model, a - pointer. -

-

- For instance, optional<> does not have shallow-copy so does - not alias: two different optionals never refer to the same - value unless T itself is - a reference (but may have equivalent values). The - difference between an optional<T> and a pointer must be kept in mind, - particularly because the semantics of relational operators are different: - since optional<T> - is a value-wrapper, relational operators are deep: they compare optional - values; but relational operators for pointers are shallow: they do not - compare pointee values. As a result, you might be able to replace optional<T> - by T* - on some situations but not always. Specifically, on generic code written - for both, you cannot use relational operators directly, and must use the - template functions equal_pointees() - and less_pointees() - instead. -

-
-
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/tutorial/a_note_about_optional_bool_.html b/doc/html/boost_optional/tutorial/a_note_about_optional_bool_.html deleted file mode 100644 index ffd5c3dc..00000000 --- a/doc/html/boost_optional/tutorial/a_note_about_optional_bool_.html +++ /dev/null @@ -1,108 +0,0 @@ - - - -A note about optional<bool> - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- optional<bool> should - be used with special caution and consideration. -

-

- First, it is functionally similar to a tristate boolean (false, maybe, true) - —such as boost::tribool— - except that in a tristate boolean, 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, although optional<> provides a contextual conversion - to bool in C++11, this falls - back to an implicit conversion on older compilers. 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: -

-
void foo ( bool v ) ;
-void bar()
-{
-    optional<bool> v = try();
-
-    // The following intended to pass the value of 'v' to foo():
-    foo(v);
-    // But instead, the initialization state is passed
-    // due to a typo: it should have been foo(*v).
-}
-
-

- The only implicit conversion is to bool, - and it is safe in the sense that typical integral promotions don't apply - (i.e. if foo() - takes an int instead, it won't - compile). -

-

- Third, mixed comparisons with bool - work differently than similar mixed comparisons between pointers and bool, so the results might surprise you: -

-
optional<bool> oEmpty(none), oTrue(true), oFalse(false);
-
-if (oEmpty == none);  // renders true
-if (oEmpty == false); // renders false!
-if (oEmpty == true);  // renders false!
-
-if (oFalse == none);  // renders false
-if (oFalse == false); // renders true!
-if (oFalse == true);  // renders false
-
-if (oTrue == none);   // renders false
-if (oTrue == false);  // renders false
-if (oTrue == true);   // renders true
-
-

- In other words, for optional<>, the following assertion does not - hold: -

-
assert((opt == false) == (!opt));
-
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2016 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/tutorial/design_overview.html b/doc/html/boost_optional/tutorial/design_overview.html deleted file mode 100644 index c467658c..00000000 --- a/doc/html/boost_optional/tutorial/design_overview.html +++ /dev/null @@ -1,184 +0,0 @@ - - - -Design Overview - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-
-
-

- In C++, we can declare an object (a variable) of type - T, and we can give this - variable an initial value (through an initializer. - (cf. 8.5)). When a declaration includes a non-empty initializer (an initial - value is given), it is said that the object has been initialized. If the - declaration uses an empty initializer (no initial value is given), and - neither default nor value initialization applies, it is said that the object - is uninitialized. Its actual value exist - but has an indeterminate initial value (cf. 8.5/11). - optional<T> - intends to formalize the notion of initialization (or lack of it) allowing - a program to test whether an object has been initialized and stating that - access to the value of an uninitialized object is undefined behavior. That - is, when a variable is declared as optional<T> and no initial value is given, the - variable is formally uninitialized. A formally uninitialized - optional object has conceptually no value at all and this situation can - be tested at runtime. It is formally undefined behavior - to try to access the value of an uninitialized optional. An uninitialized - optional can be assigned a value, in which case its initialization state - changes to initialized. Furthermore, given the formal treatment of initialization - states in optional objects, it is even possible to reset an optional to - uninitialized. -

-

- In C++ there is no formal notion of uninitialized objects, which means - that objects always have an initial value even if indeterminate. As discussed - on the previous section, this has a drawback because you need additional - information to tell if an object has been effectively initialized. One - of the typical ways in which this has been historically dealt with is via - a special value: EOF, - npos, -1, etc... This is - equivalent to adding the special value to the set of possible values of - a given type. This super set of T - plus some nil_t—where nil_t - is some stateless POD—can be modeled in modern languages as a discriminated union of T and nil_t. Discriminated - unions are often called variants. A variant has a - current type, which in our case is either T or nil_t. - Using the Boost.Variant - library, this model can be implemented in terms of boost::variant<T,nil_t>. There is precedent for a discriminated - union as a model for an optional value: the Haskell - Maybe built-in type constructor. Thus, - a discriminated union T+nil_t - serves as a conceptual foundation. -

-

- A variant<T,nil_t> follows naturally from the traditional - idiom of extending the range of possible values adding an additional sentinel - value with the special meaning of Nothing. However, - this additional Nothing value is largely irrelevant - for our purpose since our goal is to formalize the notion of uninitialized - objects and, while a special extended value can be used to convey that - meaning, it is not strictly necessary in order to do so. -

-

- The observation made in the last paragraph about the irrelevant nature - of the additional nil_t - with respect to purpose of optional<T> - suggests an alternative model: a container that either - has a value of T or nothing. -

-

- 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. -

-

- In any event, both the discriminated-union or the single-element container - models serve as a conceptual ground for a class representing optional—i.e. - possibly uninitialized—objects. For instance, these models show the - exact semantics required for a wrapper of optional - values: -

-

- Discriminated-union: -

-
    -
  • - deep-copy semantics: copies of the - variant implies copies of the value. -
    • -
  • - deep-relational semantics: comparisons - between variants matches both current types and values -
    • -
  • - If the variant's current type is T, - it is modeling an initialized optional. -
    • -
  • - If the variant's current type is not T, - it is modeling an uninitialized optional. -
    • -
  • - Testing if the variant's current type is T - models testing if the optional is initialized -
    • -
  • - Trying to extract a T - from a variant when its current type is not T, - models the undefined behavior of trying to access the value of an uninitialized - optional -
    • -
-

- Single-element container: -

-
    -
  • - deep-copy semantics: copies of the - container implies copies of the value. -
    • -
  • - deep-relational semantics: comparisons - between containers compare container size and if match, contained value -
    • -
  • - If the container is not empty (contains an object of type T), it is modeling an initialized - optional. -
    • -
  • - If the container is empty, it is modeling an uninitialized - optional. -
    • -
  • - Testing if the container is empty models testing if the optional is - initialized -
    • -
  • - Trying to extract a T - from an empty container models the undefined behavior of trying to - access the value of an uninitialized optional -
    • -
-
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/tutorial/design_overview/the_interface.html b/doc/html/boost_optional/tutorial/design_overview/the_interface.html deleted file mode 100644 index f0bbc860..00000000 --- a/doc/html/boost_optional/tutorial/design_overview/the_interface.html +++ /dev/null @@ -1,187 +0,0 @@ - - - -The Interface - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- Since the purpose of optional is to allow us to use objects with a formal - uninitialized additional state, the interface could try to follow the interface - of the underlying T type - as much as possible. In order to choose the proper degree of adoption of - the native T interface, - the following must be noted: Even if all the operations supported by an - instance of type T are - defined for the entire range of values for such a type, an optional<T> - extends such a set of values with a new value for which most (otherwise - valid) operations are not defined in terms of T. -

-

- Furthermore, since optional<T> itself is merely a T - wrapper (modeling a T supertype), - any attempt to define such operations upon uninitialized optionals will - be totally artificial w.r.t. T. -

-

- This library chooses an interface which follows from T's - interface only for those operations which are well defined (w.r.t the type - T) even if any of the operands - are uninitialized. These operations include: construction, copy-construction, - assignment, swap and relational operations. -

-

- For the value access operations, which are undefined (w.r.t the type T) when the operand is uninitialized, - a different interface is chosen (which will be explained next). -

-

- Also, the presence of the possibly uninitialized state requires additional - operations not provided by T - itself which are supported by a special interface. -

-
- - Lexically-hinted - Value Access in the presence of possibly uninitialized optional objects: - The operators * and -> -
-

- A relevant feature of a pointer is that it can have a null - pointer value. This is a special value - which is used to indicate that the pointer is not referring to any object - at all. In other words, null pointer values convey the notion of nonexistent - objects. -

-

- This meaning of the null pointer value allowed pointers to became a de - facto standard for handling optional objects because all you - have to do to refer to a value which you don't really have is to use a - null pointer value of the appropriate type. Pointers have been used for - decades—from the days of C APIs to modern C++ libraries—to refer - to optional (that is, possibly nonexistent) objects; particularly as optional - arguments to a function, but also quite often as optional data members. -

-

- The possible presence of a null pointer value makes the operations that - access the pointee's value possibly undefined, therefore, expressions which - use dereference and access operators, such as: ( - *p - = 2 ) and ( - p->foo() ), implicitly convey the notion of optionality, - and this information is tied to the syntax of the - expressions. That is, the presence of operators * - and -> tell by themselves - —without any additional context— that the expression will be undefined - unless the implied pointee actually exist. -

-

- Such a de facto idiom for referring to optional objects - can be formalized in the form of a concept: the OptionalPointee concept. This - concept captures the syntactic usage of operators *, - -> and contextual conversion - to bool to convey the notion - of optionality. -

-

- However, pointers are good to refer - to optional objects, but not particularly good to handle the optional objects - in all other respects, such as initializing or moving/copying them. The - problem resides in the shallow-copy of pointer semantics: if you need to - effectively move or copy the object, pointers alone are not enough. The - problem is that copies of pointers do not imply copies of pointees. For - example, as was discussed in the motivation, pointers alone cannot be used - to return optional objects from a function because the object must move - outside from the function and into the caller's context. -

-

- A solution to the shallow-copy problem that is often used is to resort - to dynamic allocation and use a smart pointer to automatically handle the - details of this. For example, if a function is to optionally return an - object X, it can use shared_ptr<X> - as the return value. However, this requires dynamic allocation of X. If X - is a built-in or small POD, this technique is very poor in terms of required - resources. Optional objects are essentially values so it is very convenient - to be able to use automatic storage and deep-copy semantics to manipulate - optional values just as we do with ordinary values. Pointers do not have - this semantics, so are inappropriate for the initialization and transport - of optional values, yet are quite convenient for handling the access to - the possible undefined value because of the idiomatic aid present in the - OptionalPointee - concept incarnated by pointers. -

-
- - Optional<T> - as a model of OptionalPointee -
-

- For value access operations optional<> uses operators * - and -> to lexically warn - about the possibly uninitialized state appealing to the familiar pointer - semantics w.r.t. to null pointers. -

-
- - - - - -
[Caution]Caution

- However, it is particularly important to note that optional<> objects are not pointers. optional<> is not, and does not model, a - pointer. -

-

- For instance, optional<> does not have shallow-copy so does - not alias: two different optionals never refer to the same - value unless T itself is - a reference (but may have equivalent values). The - difference between an optional<T> and a pointer must be kept in mind, - particularly because the semantics of relational operators are different: - since optional<T> - is a value-wrapper, relational operators are deep: they compare optional - values; but relational operators for pointers are shallow: they do not - compare pointee values. As a result, you might be able to replace optional<T> - by T* - on some situations but not always. Specifically, on generic code written - for both, you cannot use relational operators directly, and must use the - template functions equal_pointees() - and less_pointees() - instead. -

-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/tutorial/design_overview/the_semantics.html b/doc/html/boost_optional/tutorial/design_overview/the_semantics.html deleted file mode 100644 index 58e52267..00000000 --- a/doc/html/boost_optional/tutorial/design_overview/the_semantics.html +++ /dev/null @@ -1,121 +0,0 @@ - - - -The semantics - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- Objects of type optional<T> are intended to be used in places where - objects of type T would - but which might be uninitialized. Hence, optional<T>'s purpose is to formalize the additional - possibly uninitialized state. From the perspective of this role, optional<T> - can have the same operational semantics of T - plus the additional semantics corresponding to this special state. As such, - optional<T> - could be thought of as a supertype of T. Of course, we can't do that in C++, - so we need to compose the desired semantics using a different mechanism. - Doing it the other way around, that is, making optional<T> a subtype of - T is not only conceptually - wrong but also impractical: it is not allowed to derive from a non-class - type, such as a built-in type. -

-

- We can draw from the purpose of optional<T> the required basic semantics: -

-
    -
  • - Default Construction: To introduce - a formally uninitialized wrapped object. -
    • -
  • - Direct Value Construction via copy: - To introduce a formally initialized wrapped object whose value is obtained - as a copy of some object. -
    • -
  • - Deep Copy Construction: To obtain - a new yet equivalent wrapped object. -
    • -
  • - Direct Value Assignment (upon initialized): - To assign a value to the wrapped object. -
    • -
  • - Direct Value Assignment (upon uninitialized): - To initialize the wrapped object with a value obtained as a copy of - some object. -
    • -
  • - Assignment (upon initialized): To - assign to the wrapped object the value of another wrapped object. -
    • -
  • - Assignment (upon uninitialized): To - initialize the wrapped object with value of another wrapped object. -
    • -
  • - Deep Relational Operations (when supported by - the type T): To compare wrapped object values taking into - account the presence of uninitialized states. -
    • -
  • - Value access: To unwrap the wrapped - object. -
    • -
  • - Initialization state query: To determine - if the object is formally initialized or not. -
    • -
  • - Swap: To exchange wrapped objects. - (with whatever exception safety guarantees are provided by T's swap). -
    • -
  • - De-initialization: To release the - wrapped object (if any) and leave the wrapper in the uninitialized - state. -
    • -
-

- Additional operations are useful, such as converting constructors and converting - assignments, in-place construction and assignment, and safe value access - via a pointer to the wrapped object or null. -

-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/tutorial/exception_safety_guarantees.html b/doc/html/boost_optional/tutorial/exception_safety_guarantees.html deleted file mode 100644 index 90d817cc..00000000 --- a/doc/html/boost_optional/tutorial/exception_safety_guarantees.html +++ /dev/null @@ -1,175 +0,0 @@ - - - -Exception Safety Guarantees - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- This library assumes that T's - destructor does not throw exceptions. If it does, the behaviour of many operations - on optional<T> is - undefined. -

-

- The following mutating operations never throw exceptions: -

-
    -
  • - optional<T>::operator= ( none_t - ) noexcept -
    • -
  • - optional<T>::reset() noexcept -
    • -
-

- In addition, the following constructors and the destructor never throw exceptions: -

-
    -
  • - optional<T>::optional() - noexcept -
    • -
  • - optional<T>::optional( - none_t ) - noexcept -
    • -
-

- Regarding the following assignment functions: -

-
    -
  • - optional<T>::operator= ( optional<T> const& ) -
    • -
  • - optional<T>::operator= ( T const& ) -
    • -
  • - template<class U> optional<T>::operator= ( optional<U> const& ) -
    • -
  • - template<class InPlaceFactory> optional<T>::operator= ( InPlaceFactory - const& - ) -
    • -
  • - template<class TypedInPlaceFactory> optional<T>::operator= ( TypedInPlaceFactory - const& - ) -
    • -
  • - optional<T>::reset( T const& ) -
    • -
-

- They forward calls to the corresponding T's - constructors or assignments (depending on whether the optional object is - initialized or not); so if both T's - constructor and the assignment provide strong exception safety guarantee, - optional<T>'s - assignment also provides strong exception safety guarantee; otherwise we - only get the basic guarantee. Additionally, if both involved T's constructor and the assignment never - throw, optional<T>'s - assignment also never throws. -

-

- Unless T's constructor or - assignment throws, assignments to optional<T> - do not throw anything else on its own. A throw during assignment never changes - the initialization state of any optional object involved: -

-
optional<T> opt1(val1);
-optional<T> opt2(val2);
-assert(opt1);
-assert(opt2);
-
-try
-{
-  opt1 = opt2; // throws
-}
-catch(...)
-{
-  assert(opt1);
-  assert(opt2);
-}
-
-

- This also applies to move assignments/constructors. However, move operations - are made no-throw more often. -

-

- Operation emplace provides - basic exception safety guarantee. If it throws, the optional object becomes - uninitialized regardless of its initial state, and its previous contained - value (if any) is destroyed. It doesn't call any assignment or move/copy - constructor on T. -

-
- - Swap -
-

- Unless swap on optional is - customized, its primary implementation forwards calls to T's - swap or move constructor - (depending on the initialization state of the optional objects). Thus, if - both T's swap - and move constructor never throw, swap - on optional<T> never - throws. similarly, if both T's - swap and move constructor - offer strong guarantee, swap - on optional<T> also - offers a strong guarantee. -

-

- In case swap on optional - is customized, the call to T's - move constructor are replaced with the calls to T's - default constructor followed by swap. - (This is more useful on older compilers that do not support move semantics, - when one wants to achieve stronger exception safety guarantees.) In this - case the exception safety guarantees for swap - are reliant on the guarantees of T's - swap and default constructor -

-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/tutorial/gotchas.html b/doc/html/boost_optional/tutorial/gotchas.html deleted file mode 100644 index 9382442d..00000000 --- a/doc/html/boost_optional/tutorial/gotchas.html +++ /dev/null @@ -1,112 +0,0 @@ - - - -Gotchas - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-
-
-

- optional<bool> - should be used with special caution and consideration. -

-

- First, it is functionally similar to a tristate boolean (false, maybe, - true) —such as boost::tribool— - except that in a tristate boolean, 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, although optional<> provides a contextual conversion - to bool in C++11, this falls - back to an implicit conversion on older compilers. 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: -

-
void foo ( bool v ) ;
-void bar()
-{
-    optional<bool> v = try();
-
-    // The following intended to pass the value of 'v' to foo():
-    foo(v);
-    // But instead, the initialization state is passed
-    // due to a typo: it should have been foo(*v).
-}
-
-

- The only implicit conversion is to bool, - and it is safe in the sense that typical integral promotions don't apply - (i.e. if foo() - takes an int instead, it won't - compile). -

-

- Third, mixed comparisons with bool - work differently than similar mixed comparisons between pointers and bool, so the results might surprise you: -

-
optional<bool> oEmpty(none), oTrue(true), oFalse(false);
-
-if (oEmpty == none);  // renders true
-if (oEmpty == false); // renders false!
-if (oEmpty == true);  // renders false!
-
-if (oFalse == none);  // renders false
-if (oFalse == false); // renders true!
-if (oFalse == true);  // renders false
-
-if (oTrue == none);   // renders false
-if (oTrue == false);  // renders false
-if (oTrue == true);   // renders true
-
-

- In other words, for optional<>, the following assertion does not - hold: -

-
assert((opt == false) == (!opt));
-
-
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/tutorial/gotchas/false_positive_with__wmaybe_uninitialized.html b/doc/html/boost_optional/tutorial/gotchas/false_positive_with__wmaybe_uninitialized.html deleted file mode 100644 index 0228f2ea..00000000 --- a/doc/html/boost_optional/tutorial/gotchas/false_positive_with__wmaybe_uninitialized.html +++ /dev/null @@ -1,77 +0,0 @@ - - - -False positive with -Wmaybe-uninitialized - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- Sometimes on GCC compilers below version 5.1 you may get an -Wmaybe-uninitialized - warning when compiling with option -02 on a perfectly valid boost::optional usage. For instance in this - program: -

-
#include <boost/optional.hpp>
-
-boost::optional<int> getitem();
-
-int main(int argc, const char *[])
-{
-  boost::optional<int> a = getitem();
-  boost::optional<int> b;
-
-  if (argc > 0)
-    b = argc;
-
-  if (a != b)
-    return 1;
-
-  return 0;
-}
-
-

- This is a bug in the compiler. As a workaround (provided in this - Stack Overflow question) use the following way of initializing - an optional containing no value: -

-
boost::optional<int> b = boost::make_optional(false, int());
-
-

- This is obviously redundant, but makes the warning disappear. -

-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/tutorial/gotchas/mixed_relational_comparisons.html b/doc/html/boost_optional/tutorial/gotchas/mixed_relational_comparisons.html deleted file mode 100644 index c89f67d9..00000000 --- a/doc/html/boost_optional/tutorial/gotchas/mixed_relational_comparisons.html +++ /dev/null @@ -1,59 +0,0 @@ - - - -Mixed relational comparisons - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- Because T is convertible - to optional<T> - and because optional<T> - is LessThanComparable when T is LessThanComparable, you can sometimes - get an unexpected runtime result where you would rather expect a compiler - error: -

-
optional<double> Flight_plan::weight(); // sometimes no weight can be returned
-
-bool is_aircraft_too_heavy(Flight_plan const& p)
-{
-   return p.weight() > p.aircraft().max_weight(); // compiles!
-}                                                 // returns false when the optional contains no value 
-
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/tutorial/gotchas/moved_from__optional_.html b/doc/html/boost_optional/tutorial/gotchas/moved_from__optional_.html deleted file mode 100644 index 7924e618..00000000 --- a/doc/html/boost_optional/tutorial/gotchas/moved_from__optional_.html +++ /dev/null @@ -1,63 +0,0 @@ - - - -Moved-from optional - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- When an optional object that contains a value is moved from (is a source - of move constructor or assignment) it still contains a value and its contained - value is left in a moved-from state. This can be illustrated with the following - example. -

-
optional<std::unique_ptr<int>> opi {std::make_unique<int>(1)};
-optional<std::unique_ptr<int>> opj = std::move(opi);
-assert (opi);
-assert (*opi == nullptr);
-
-

- Quite a lot of people expect that when an object that contains a value - is moved from, its contained value should be destroyed. This is not so, - for performance reasons. Current semantics allow the implementation of - boost::optional<T> - to be trivially copyable when T - is trivial. -

-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/tutorial/in_place_factories.html b/doc/html/boost_optional/tutorial/in_place_factories.html deleted file mode 100644 index 10e62baa..00000000 --- a/doc/html/boost_optional/tutorial/in_place_factories.html +++ /dev/null @@ -1,197 +0,0 @@ - - - -In-Place Factories - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- One of the typical problems with wrappers and containers is that their interfaces - usually provide an operation to initialize or assign the contained object - as a copy of some other object. This not only requires the underlying type - to be CopyConstructible, but also requires - the existence of a fully constructed object, often temporary, just to follow - the copy from: -

-
struct X
-{
-    X ( int, std::string ) ;
-} ;
-
-class W
-{
-    X wrapped_ ;
-
-    public:
-
-    W ( X const& x ) : wrapped_(x) {}
-} ;
-
-void foo()
-{
-    // Temporary object created.
-    W ( X(123,"hello") ) ;
-}
-
-

- A solution to this problem is to support direct construction of the contained - object right in the container's storage. In this scheme, the user only needs - to supply the arguments to the constructor to use in the wrapped object construction. -

-
class W
-{
-    X wrapped_ ;
-
-    public:
-
-    W ( X const& x ) : wrapped_(x) {}
-    W ( int a0, std::string a1) : wrapped_(a0,a1) {}
-} ;
-
-void foo()
-{
-    // Wrapped object constructed in-place
-    // No temporary created.
-    W (123,"hello") ;
-}
-
-

- A limitation of this method is that it doesn't scale well to wrapped objects - with multiple constructors nor to generic code were the constructor overloads - are unknown. -

-

- The solution presented in this library is the family of InPlaceFactories - and TypedInPlaceFactories. These factories - are a family of classes which encapsulate an increasing number of arbitrary - constructor parameters and supply a method to construct an object of a given - type using those parameters at an address specified by the user via placement - new. -

-

- For example, one member of this family looks like: -

-
template<class T,class A0, class A1>
-class TypedInPlaceFactory2
-{
-    A0 m_a0 ; A1 m_a1 ;
-
-    public:
-
-    TypedInPlaceFactory2( A0 const& a0, A1 const& a1 ) : m_a0(a0), m_a1(a1) {}
-
-    void construct ( void* p ) { new (p) T(m_a0,m_a1) ; }
- } ;
-
-

- A wrapper class aware of this can use it as: -

-
class W
-{
-    X wrapped_ ;
-
-    public:
-
-    W ( X const& x ) : wrapped_(x) {}
-    W ( TypedInPlaceFactory2 const& fac ) { fac.construct(&wrapped_) ; }
-} ;
-
-void foo()
-{
-    // Wrapped object constructed in-place via a TypedInPlaceFactory.
-    // No temporary created.
-    W ( TypedInPlaceFactory2<X,int,std::string>(123,"hello")) ;
-}
-
-

- The factories are divided in two groups: -

-
    -
  • - TypedInPlaceFactories: those which - take the target type as a primary template parameter. -
    • -
  • - InPlaceFactories: those with a - template construct(void*) - member function taking the target type. -
    • -
-

- Within each group, all the family members differ only in the number of parameters - allowed. -

-

- This library provides an overloaded set of helper template functions to construct - these factories without requiring unnecessary template parameters: -

-
template<class A0,...,class AN>
-InPlaceFactoryN <A0,...,AN> in_place ( A0 const& a0, ..., AN const& aN) ;
-
-template<class T,class A0,...,class AN>
-TypedInPlaceFactoryN <T,A0,...,AN> in_place ( T const& a0, A0 const& a0, ..., AN const& aN) ;
-
-

- In-place factories can be used generically by the wrapper and user as follows: -

-
class W
-{
-    X wrapped_ ;
-
-    public:
-
-    W ( X const& x ) : wrapped_(x) {}
-
-    template< class InPlaceFactory >
-    W ( InPlaceFactory const& fac ) { fac.template <X>construct(&wrapped_) ; }
-
-} ;
-
-void foo()
-{
-    // Wrapped object constructed in-place via a InPlaceFactory.
-    // No temporary created.
-    W ( in_place(123,"hello") ) ;
-}
-
-

- The factories are implemented in the headers: in_place_factory.hpp - and typed_in_place_factory.hpp -

-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/tutorial/io_operators.html b/doc/html/boost_optional/tutorial/io_operators.html deleted file mode 100644 index d6d9dcbd..00000000 --- a/doc/html/boost_optional/tutorial/io_operators.html +++ /dev/null @@ -1,87 +0,0 @@ - - - -IO operators - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- It is possible to use optional<T> - with IO streams, provided that T - can be used with streams. IOStream operators are defined in a separate header. -

-

-

-
#include <iostream>
-#include <boost/optional/optional_io.hpp>
-
-int main()
-{
-  boost::optional<int> o1 = 1, oN = boost::none;
-  std::cout << o1;
-  std::cin >> oN;
-}
-
-

-

-

- The current implementation does not guarantee any particular output. What - it guarantees is that if streaming out and then back in T - gives the same value, then streaming out and then back in optional<T> - will also give back the same result: -

-

-

-
#include <cassert>
-#include <sstream>
-#include <boost/optional/optional_io.hpp>
-
-int main()
-{
-  boost::optional<int> o1 = 1, oN = boost::none;
-  boost::optional<int> x1, x2;
-  std::stringstream s;
-  s << o1 << oN;
-  s >> x1 >> x2;
-  assert (o1 == x1);
-  assert (oN == x2);
-}
-
-

-

-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/tutorial/motivation.html b/doc/html/boost_optional/tutorial/motivation.html deleted file mode 100644 index 3b9f43cf..00000000 --- a/doc/html/boost_optional/tutorial/motivation.html +++ /dev/null @@ -1,129 +0,0 @@ - - - -Motivation - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- Consider these functions which should return a value but which might not - have a value to return: -

-
    -
  • - (A) double sqrt(double n ); -
    • -
  • - (B) char get_async_input(); -
    • -
  • - (C) point polygon::get_any_point_effectively_inside(); -
    • -
-

- There are different approaches to the issue of not having a value to return. -

-

- A typical approach is to consider the existence of a valid return value as - a postcondition, so that if the function cannot compute the value to return, - it has either undefined behavior (and can use assert in a debug build) or - uses a runtime check and throws an exception if the postcondition is violated. - This is a reasonable choice for example, for function (A), because the lack - of a proper return value is directly related to an invalid parameter (out - of domain argument), so it is appropriate to require the callee to supply - only parameters in a valid domain for execution to continue normally. -

-

- However, function (B), because of its asynchronous nature, does not fail - just because it can't find a value to return; so it is incorrect to consider - such a situation an error and assert or throw an exception. This function - must return, and somehow, must tell the callee that it is not returning a - meaningful value. -

-

- A similar situation occurs with function (C): it is conceptually an error - to ask a null-area polygon to return a point inside - itself, but in many applications, it is just impractical for performance - reasons to treat this as an error (because detecting that the polygon has - no area might be too expensive to be required to be tested previously), and - either an arbitrary point (typically at infinity) is returned, or some efficient - way to tell the callee that there is no such point is used. -

-

- There are various mechanisms to let functions communicate that the returned - value is not valid. One such mechanism, which is quite common since it has - zero or negligible overhead, is to use a special value which is reserved - to communicate this. Classical examples of such special values are EOF, string::npos, - points at infinity, etc... -

-

- When those values exist, i.e. the return type can hold all meaningful values - plus the signal value, this mechanism - is quite appropriate and well known. Unfortunately, there are cases when - such values do not exist. In these cases, the usual alternative is either - to use a wider type, such as int - in place of char; or a compound - type, such as std::pair<point,bool>. -

-

- Returning a std::pair<T,bool>, thus attaching a boolean flag to the - result which indicates if the result is meaningful, has the advantage that - can be turned into a consistent idiom since the first element of the pair - can be whatever the function would conceptually return. For example, the - last two functions could have the following interface: -

-
std::pair<char,bool> get_async_input();
-std::pair<point,bool> polygon::get_any_point_effectively_inside();
-
-

- These functions use a consistent interface for dealing with possibly nonexistent - results: -

-
std::pair<point,bool> p = poly.get_any_point_effectively_inside();
-if ( p.second )
-    flood_fill(p.first);
-
-

- However, not only is this quite a burden syntactically, it is also error - prone since the user can easily use the function result (first element of - the pair) without ever checking if it has a valid value. -

-

- Clearly, we need a better idiom. -

-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/tutorial/optional_references.html b/doc/html/boost_optional/tutorial/optional_references.html deleted file mode 100644 index ff16598d..00000000 --- a/doc/html/boost_optional/tutorial/optional_references.html +++ /dev/null @@ -1,117 +0,0 @@ - - - -Optional references - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-
-
-

- This library allows the template parameter T - to be of reference type: T&, and to some extent, T const&. -

-

- However, since references are not real objects some restrictions apply - and some operations are not available in this case: -

-
    -
  • - Converting constructors -
    • -
  • - 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 - occur: -

-
    -
  • - Copies of optional<T&> will copy the references but - all these references will nonetheless refer to the same object. -
    • -
  • - Value-access will actually provide access to the referenced object - rather than the reference itself. -
    • -
-
- - - - - -
[Caution]Caution

- On compilers that do not conform to Standard C++ rules of reference binding, - some operations on optional references are disabled in order to prevent - subtle bugs. For more details see Dependencies - and Portability section. -

-
- - Rvalue - references -
-

- Rvalue references and lvalue references to const have the ability in C++ - to extend the life time of a temporary they bind to. Optional references - do not have this capability, therefore to avoid surprising effects it is - not possible to initialize an optional references from a temporary. Optional - rvalue references are disabled altogether. Also, the initialization and - assignment of an optional reference to const from rvalue reference is disabled. -

-
const int& i = 1;            // legal
-optional<const int&> oi = 1; // illegal
-
-
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/tutorial/optional_references/rebinding_semantics_for_assignment_of_optional_references.html b/doc/html/boost_optional/tutorial/optional_references/rebinding_semantics_for_assignment_of_optional_references.html deleted file mode 100644 index 112eb5da..00000000 --- a/doc/html/boost_optional/tutorial/optional_references/rebinding_semantics_for_assignment_of_optional_references.html +++ /dev/null @@ -1,147 +0,0 @@ - - - -Rebinding semantics for assignment of optional references - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- If you assign to an uninitialized optional<T&> the effect is to bind (for the - first time) to the object. Clearly, there is no other choice. -

-
int x = 1 ;
-int& rx = x ;
-optional<int&> ora ;
-optional<int&> orb(x) ;
-ora = orb ; // now 'ora' is bound to 'x' through 'rx'
-*ora = 2 ; // Changes value of 'x' through 'ora'
-assert(x==2);
-
-

- If you assign to a bare C++ reference, the assignment is forwarded to the - referenced object; its value changes but the reference is never rebound. -

-
int a = 1 ;
-int& ra = a ;
-int b = 2 ;
-int& rb = b ;
-ra = rb ; // Changes the value of 'a' to 'b'
-assert(a==b);
-b = 3 ;
-assert(ra!=b); // 'ra' is not rebound to 'b'
-
-

- Now, if you assign to an initialized optional<T&>, - the effect is to rebind to the new object - instead of assigning the referee. This is unlike bare C++ references. -

-
int a = 1 ;
-int b = 2 ;
-int& ra = a ;
-int& rb = b ;
-optional<int&> ora(ra) ;
-optional<int&> orb(rb) ;
-ora = orb ; // 'ora' is rebound to 'b'
-*ora = 3 ; // Changes value of 'b' (not 'a')
-assert(a==1);
-assert(b==3);
-
-
- - Rationale -
-

- Rebinding semantics for the assignment of initialized - optional references has - been chosen to provide consistency among initialization - states even at the expense of lack of consistency with the semantics - of bare 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 ;
-
-

- 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 consistent. -

-

- If in your code rebinding to another object is not an option, then it is - very likely that binding for the first time isn't either. In such case, - assignment to an uninitialized optional<T&> shall be prohibited. It is quite - possible that in such a scenario it is a precondition that the lvalue must - be already initialized. If it isn't, then binding for the first time is - OK while rebinding is not which is IMO very unlikely. In such a scenario, - you can assign the value itself directly, as in: -

-
assert(!!opt);
-*opt=value;
-
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/tutorial/performance_considerations.html b/doc/html/boost_optional/tutorial/performance_considerations.html deleted file mode 100644 index e20cf61a..00000000 --- a/doc/html/boost_optional/tutorial/performance_considerations.html +++ /dev/null @@ -1,265 +0,0 @@ - - - -Performance considerations - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- Technical details aside, the memory layout of optional<T> - for a generic T is more-less - this: -

-
template <typename T>
-class optional
-{
-  bool _initialized;
-  std::aligned_storage_t<sizeof(t), alignof(T)> _storage;
-};
-
-

- Lifetime of the T inside - _storage is manually controlled - with placement-news and pseudo-destructor - calls. However, for scalar Ts - we use a different way of storage, by simply holding a T: -

-
template <typename T>
-class optional
-{
-  bool _initialized;
-  T _storage;
-};
-
-

- We call it a direct storage. This makes optional<T> a - trivially-copyable type for scalar Ts. - This only works for compilers that support defaulted functions (including - defaulted move assignment and constructor). On compilers without defaulted - functions we still use the direct storage, but optional<T> - is no longer recognized as trivially-copyable. Apart from scalar types, we - leave the programmer a way of customizing her type, so that it is recognized - by optional as candidate - for optimized storage, by specializing type trait boost::optional_config::optional_uses_direct_storage_for: -

-
struct X // not trivial
-{
-  X() {}
-};
-
-namespace boost { namespace optional_config {
-
-  template <> struct optional_uses_direct_storage_for<X> : boost::true_type {};
-
-}}
-
-
- - Controlling - the size -
-

- For the purpose of the following analysis, considering memory layouts, we - can think of it as: -

-
template <typename T>
-class optional
-{
-  bool _initialized;
-  T _storage;
-};
-
-

- Given type optional<int>, and - assuming that sizeof(int) == - 4, we will get sizeof(optional<int>) - == 8. - This is so because of the alignment rules, for our two members we get the - following alignment: -

-

- opt_align1 -

-

- This means you can fit twice as many ints - as optional<int>s into - the same space of memory. Therefore, if the size of the objects is critical - for your application (e.g., because you want to utilize your CPU cache in - order to gain performance) and you have determined you are willing to trade - the code clarity, it is recommended that you simply go with type int and use some 'magic value' to represent - not-an-int, or use something like markable library. -

-

- Even if you cannot spare any value of int - to represent not-an-int (e.g., because every value is - useful, or you do want to signal not-an-int explicitly), - at least for Trivial types - you should consider storing the value and the bool - flag representing the null-state separately. Consider - the following class: -

-
struct Record
-{
-  optional<int> _min;
-  optional<int> _max;
-};
-
-

- Its memory layout can be depicted as follows: -

-

- opt_align2 -

-

- This is exactly the same as if we had the following members: -

-
struct Record
-{
-  bool _has_min;
-  int  _min;
-  bool _has_max;
-  int  _max;
-};
-
-

- But when they are stored separately, we at least have an option to reorder - them like this: -

-
struct Record
-{
-  bool _has_min;
-  bool _has_max;
-  int  _min;
-  int  _max;
-};
-
-

- Which gives us the following layout (and smaller total size): -

-

- opt_align3 -

-

- Sometimes it requires detailed consideration what data we make optional. - In our case above, if we determine that both minimum and maximum value can - be provided or not provided together, but one is never provided without the - other, we can make only one optional member: -

-
struct Limits
-{
-  int  _min;
-  int  _max;
-};
-
-struct Record
-{
-  optional<Limits> _limits;
-};
-
-

- This would give us the following layout: -

-

- opt_align4 -

-
- - Optional - function parameters -
-

- Having function parameters of type const - optional<T>& - may incur certain unexpected run-time cost connected to copy construction - of T. Consider the following - code. -

-
void fun(const optional<Big>& v)
-{
-  if (v) doSomethingWith(*v);
-  else   doSomethingElse();
-}
-
-int main()
-{
-  optional<Big> ov;
-  Big v;
-  fun(none);
-  fun(ov); // no copy
-  fun(v);  // copy constructor of Big
-}
-
-

- No copy elision or move semantics can save us from copying type Big here. Not that we need any copy, but - this is how optional works. - In order to avoid copying in this case, one could provide second overload - of fun: -

-
void fun(const Big& v)
-{
-  doSomethingWith(v);
-}
-
-int main()
-{
-  optional<Big> ov;
-  Big v;
-  fun(ov); // no copy
-  fun(v);  // no copy: second overload selected
-}
-
-

- Alternatively, you could consider using an optional reference instead: -

-
void fun(optional<const Big&> v) // note where the reference is
-{
-  if (v) doSomethingWith(*v);
-  else   doSomethingElse();
-}
-
-int main()
-{
-  optional<Big> ov;
-  Big v;
-  fun(none);
-  fun(ov); // doesn't compile
-  fun(v);  // no copy
-}
-
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/tutorial/rebinding_semantics_for_assignment_of_optional_references.html b/doc/html/boost_optional/tutorial/rebinding_semantics_for_assignment_of_optional_references.html deleted file mode 100644 index ee693eee..00000000 --- a/doc/html/boost_optional/tutorial/rebinding_semantics_for_assignment_of_optional_references.html +++ /dev/null @@ -1,149 +0,0 @@ - - - -Rebinding semantics for assignment of optional references - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- If you assign to an uninitialized optional<T&> - the effect is to bind (for the first time) to the object. Clearly, there - is no other choice. -

-
int x = 1 ;
-int& rx = x ;
-optional<int&> ora ;
-optional<int&> orb(x) ;
-ora = orb ; // now 'ora' is bound to 'x' through 'rx'
-*ora = 2 ; // Changes value of 'x' through 'ora'
-assert(x==2);
-
-

- If you assign to a bare C++ reference, the assignment is forwarded to the - referenced object; its value changes but the reference is never rebound. -

-
int a = 1 ;
-int& ra = a ;
-int b = 2 ;
-int& rb = b ;
-ra = rb ; // Changes the value of 'a' to 'b'
-assert(a==b);
-b = 3 ;
-assert(ra!=b); // 'ra' is not rebound to 'b'
-
-

- Now, if you assign to an initialized optional<T&>, - the effect is to rebind to the new object - instead of assigning the referee. This is unlike bare C++ references. -

-
int a = 1 ;
-int b = 2 ;
-int& ra = a ;
-int& rb = b ;
-optional<int&> ora(ra) ;
-optional<int&> orb(rb) ;
-ora = orb ; // 'ora' is rebound to 'b'
-*ora = 3 ; // Changes value of 'b' (not 'a')
-assert(a==1);
-assert(b==3);
-
-
- - Rationale -
-

- Rebinding semantics for the assignment of initialized - optional references has been - chosen to provide consistency among initialization - states even at the expense of lack of consistency with the semantics - of bare 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 ;
-
-

- 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 consistent. -

-

- If in your code rebinding to another object is not an option, then it is - very likely that binding for the first time isn't either. In such case, assignment - to an uninitialized optional<T&> - shall be prohibited. It is quite possible that in such a scenario it is a - precondition that the lvalue must be already initialized. If it isn't, then - binding for the first time is OK while rebinding is not which is IMO very - unlikely. In such a scenario, you can assign the value itself directly, as - in: -

-
assert(!!opt);
-*opt=value;
-
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2016 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/tutorial/relational_operators.html b/doc/html/boost_optional/tutorial/relational_operators.html deleted file mode 100644 index e384ab07..00000000 --- a/doc/html/boost_optional/tutorial/relational_operators.html +++ /dev/null @@ -1,113 +0,0 @@ - - - -Relational operators - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- Type optional<T> is - EqualityComparable whenever T is EqualityComparable. Two optional - objects containing a value compare in the same way as their contained values. - The uninitialized state of optional<T> - is treated as a distinct value, equal to itself, and unequal to any value - of type T: -

-
boost::optional<int> oN = boost::none;
-boost::optional<int> o0 = 0;
-boost::optional<int> o1 = 1;
-
-assert(oN != o0);
-assert(o1 != oN);
-assert(o0 != o1);
-assert(oN == oN);
-assert(o0 == o0);
-
-

- The converting constructor from T - as well as from boost::none implies the existence and semantics - of the mixed comparison between T - and optional<T> as - well as between none_t and - optional<T>: -

-
assert(oN != 0);
-assert(o1 != boost::none);
-assert(o0 != 1);
-assert(oN == boost::none);
-assert(o0 == 0);
-
-

- This mixed comparison has a practical interpretation, which is occasionally - useful: -

-
boost::optional<int> choice = ask_user();
-if (choice == 2)
-    start_procedure_2();
-
-

- In the above example, the meaning of the comparison is 'user chose number - 2'. If user chose nothing, he didn't choose number 2. -

-

- In case where optional<T> is - compared to none, it is not - required that T be EqualityComparable. -

-

- In a similar manner, type optional<T> - is LessThanComparable whenever T is LessThanComparable. The optional - object containing no value is compared less than any value of T. To illustrate this, if the default ordering - of size_t is {0, 1, - 2, ...}, the default ordering - of optional<size_t> - is {boost::none, 0, - 1, 2, - ...}. This order does not have a practical interpretation. The goal is to - have any semantically correct default ordering in order for optional<T> to - be usable in ordered associative containers (wherever T - is usable). -

-

- Mixed relational operators are the only case where the contained value of - an optional object can be inspected without the usage of value accessing - function (operator*, - value, value_or). -

-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/tutorial/type_requirements.html b/doc/html/boost_optional/tutorial/type_requirements.html deleted file mode 100644 index 9eac69df..00000000 --- a/doc/html/boost_optional/tutorial/type_requirements.html +++ /dev/null @@ -1,109 +0,0 @@ - - - -Type requirements - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- The very minimum requirement of optional<T> - is that T is a complete type - and that it has a publicly accessible destructor. T - doesn't even need to be constructible. You can use a very minimum interface: -

-
optional<T> o;     // uninitialized
-assert(o == none); // check if initialized
-assert(!o);        //
-o.value();         // always throws
-
-

- But this is practically useless. In order for optional<T> - to be able to do anything useful and offer all the spectrum of ways of accessing - the contained value, T needs - to have at least one accessible constructor. In that case you need to initialize - the optional object with function emplace(), or if your compiler does not support it, - resort to In-Place - Factories: -

-
optional<T> o;
-o.emplace("T", "ctor", "params");
-
-

- If T is MoveConstructible, - optional<T> is - also MoveConstructible and - can be easily initialized from an rvalue of type T - and be passed by value: -

-
optional<T> o = make_T();
-optional<T> p = optional<T>();
-
-

- If T is CopyConstructible, optional<T> is - also CopyConstructible - and can be easily initialized from an lvalue of type T: -

-
T v = make_T();
-optional<T> o = v;
-optional<T> p = o;
-
-

- If T is not MoveAssignable, it is still possible to - reset the value of optional<T> - using function emplace(): -

-
optional<const T> o = make_T();
-o.emplace(make_another_T());
-
-

- If T is Moveable - (both MoveConstructible and - MoveAssignable) then optional<T> is - also Moveable and additionally - can be constructed and assigned from an rvalue of type T. -

-

- Similarly, if T is Copyable (both CopyConstructible and CopyAssignable) then optional<T> - is also Copyable and additionally - can be constructed and assigned from an lvalue of type T. -

-

- T is not - required to be DefaultConstructible. -

-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/tutorial/when_to_use_optional.html b/doc/html/boost_optional/tutorial/when_to_use_optional.html deleted file mode 100644 index 7fa6810e..00000000 --- a/doc/html/boost_optional/tutorial/when_to_use_optional.html +++ /dev/null @@ -1,142 +0,0 @@ - - - -When to use Optional - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- It is recommended to use optional<T> - in situations where there is exactly one, clear (to all parties) reason for - having no value of type T, - and where the lack of value is as natural as having any regular value of - T. One example of such situation - is asking the user in some GUI form to optionally specify some limit on an - int value, but the user is allowed - to say 'I want the number not to be constrained by the maximum'. For another - example, consider a config parameter specifying how many threads the application - should launch. Leaving this parameter unspecified means that the application - should decide itself. For yet another example, consider a function returning - the index of the smallest element in a vector. - We need to be prepared for the situation, where the vector - is empty. Therefore a natural signature for such function would be: -

-
template <typename T>
-optional<size_t> find_smallest_elem(const std::vector<T>& vec);
-
-

- Here, having received an empty vec - and having no size_t to return - is not a failure but a normal, - albeit irregular, situation. -

-

- Another typical situation is to indicate that we do not have a value yet, - but we expect to have it later. This notion can be used in implementing solutions - like lazy initialization or a two-phase initialization. -

-

- optional can be used to take - a non-DefaultConstructible type T and create a sibling type with a default - constructor. This is a way to add a null-state to any - type that doesn't have it already. -

-

- Sometimes type T already - provides a built-in null-state, but it may still be useful to wrap it into - optional. Consider std::string. - When you read a piece of text from a GUI form or a DB table, it is hardly - ever that the empty string indicates anything else but a missing text. And - some data bases do not even distinguish between a null string entry and a - non-null string of length 0. Still, it may be practical to use optional<string> - to indicate in the returned type that we want to treat the empty string in - a special dedicated program path: -

-
if(boost::optional<std::string> name = ask_user_name()) {
-    assert(*name != "");
-    logon_as(*name);
-}
-else {
-    skip_logon();
-}
-
-

- In the example above, the assertion indicates that if we choose to use this - technique, we must translate the empty string state to an optional object - with no contained value (inside function ask_user_name). -

-
- - Not - recommended usages -
-

- It is not recommended to use optional - to indicate that we were not able to compute a value because of a failure. - It is difficult to define what a failure is, but it usually has one common - characteristic: an associated information on the cause of the failure. This - can be the type and member data of an exception object, or an error code. - It is a bad design to signal a failure and not inform about the cause. If - you do not want to use exceptions, and do not like the fact that by returning - error codes you cannot return the computed value, you can use Expected - library. It is sort of Boost.Variant - that contains either a computed value or a reason why the computation failed. -

-

- Sometimes the distinction into what is a failure and what is a valid but - irregular result is blurry and depends on a particular usage and personal - preference. Consider a function that converts a string - to an int. Is it a failure that - you cannot convert? It might in some cases, but in other you may call it - exactly for the purpose of figuring out if a given string - is convertible, and you are not even interested in the resulting value. Sometimes - when a conversion fails you may not consider it a failure, but you need to - know why it cannot be converted; for instance at which character it is determined - that the conversion is impossible. In this case returning optional<T> - will not suffice. Finally, there is a use case where an input string that - does not represent an int is - not a failure condition, but during the conversion we use resources whose - acquisition may fail. In that case the natural representation is to both - return optional<int> and - signal failure: -

-
optional<int> convert1(const string& str); // throws
-expected<ErrorT, optional<int>> convert2(const string& str); // return either optional or error
-
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/boost_optional/type_requirements.html b/doc/html/boost_optional/type_requirements.html deleted file mode 100644 index e1ee7778..00000000 --- a/doc/html/boost_optional/type_requirements.html +++ /dev/null @@ -1,61 +0,0 @@ - - - -Type requirements - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-

- At the very minimum for optional<T> - to work with a minimum interface it is required that T - has a publicly accessible no-throw destructor. In that case you need to initialize - the optional object with function emplace() or use InPlaceFactories. - Additionally, if T is Moveable, optional<T> - is also Moveable and can be - easily initialized from an rvalue of type T - and be passed by value. Additionally, if T - is Copyable, optional<T> is - also Copyable and can be easily - initialized from an lvalue of type T. -

-

- T is - not required to be Default - Constructible. -

-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/images/opt_align1.png b/doc/html/images/opt_align1.png deleted file mode 100644 index 50e0205e..00000000 Binary files a/doc/html/images/opt_align1.png and /dev/null differ diff --git a/doc/html/images/opt_align2.png b/doc/html/images/opt_align2.png deleted file mode 100644 index fd7c079c..00000000 Binary files a/doc/html/images/opt_align2.png and /dev/null differ diff --git a/doc/html/images/opt_align3.png b/doc/html/images/opt_align3.png deleted file mode 100644 index 7ca6ec80..00000000 Binary files a/doc/html/images/opt_align3.png and /dev/null differ diff --git a/doc/html/images/opt_align4.png b/doc/html/images/opt_align4.png deleted file mode 100644 index c7f9b724..00000000 Binary files a/doc/html/images/opt_align4.png and /dev/null differ diff --git a/doc/html/index.html b/doc/html/index.html deleted file mode 100644 index 9f97b8b0..00000000 --- a/doc/html/index.html +++ /dev/null @@ -1,154 +0,0 @@ - - - -Boost.Optional - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
Next
-
-
-

-Boost.Optional

-

-Fernando Luis Cacciola Carballal -

-

Copyright © 2003-2007 Fernando Luis Cacciola Carballal

-

Copyright © 2014-2021 Andrzej Krzemieński

-
-

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-

Table of Contents

-
-
Introduction
-
Quick Start
-
-
Optional - return values
-
Optional - automatic variables
-
Optional - data members
-
Bypassing - unnecessary default construction
-
Storage - in containers
-
-
Tutorial
-
-
Motivation
-
Design Overview
-
When to - use Optional
-
Relational - operators
-
IO operators
-
Optional - references
-
In-Place - Factories
-
Gotchas
-
Exception - Safety Guarantees
-
Type requirements
-
Performance - considerations
-
-
Reference
-
-
Header - <boost/none.hpp>
-
Header - <boost/optional/bad_optional_access.hpp>
-
Header <boost/optional/optional_io.hpp>
-
Header - <boost/optional/optional_fwd.hpp>
-
Header - <boost/optional/optional.hpp>
-
Header - <boost/optional.hpp>
-
-
Dependencies - and Portability
-
-
Dependencies
-
Emplace - operations in older compilers
-
Optional - Reference Binding
-
-
Release Notes
-
Acknowledgements
-
-
-
-
-

- Class template optional is - a wrapper for representing 'optional' (or 'nullable') objects who may not (yet) - contain a valid value. Optional objects offer full value semantics; they are - good for passing by value and usage inside STL containers. This is a header-only - library. -

-

- - Problem -

-

- Suppose we want to read a parameter from a config file which represents some - integral value, let's call it "MaxValue". - It is possible that this parameter is not specified; such situation is no error. - It is valid to not specify the parameter and in that case the program is supposed - to behave slightly differently. Also, suppose that any possible value of type - int is a valid value for "MaxValue", so we cannot just use - -1 - to represent the absence of the parameter in the config file. -

-

- - Solution -

-

- This is how you solve it with boost::optional: -

-
#include <boost/optional.hpp>
-
-boost::optional<int> getConfigParam(std::string name);  // return either an int or a `not-an-int`
-
-int main()
-{
-  if (boost::optional<int> oi = getConfigParam("MaxValue")) // did I get a real int?
-    runWithMax(*oi);                                        // use my int
-  else
-    runWithNoMax();
-}
-
-
-
- - - -

Last revised: March 26, 2022 at 22:47:53 GMT

-
-
Next
- - diff --git a/doc/html/optional/reference.html b/doc/html/optional/reference.html deleted file mode 100644 index 1cbeafab..00000000 --- a/doc/html/optional/reference.html +++ /dev/null @@ -1,89 +0,0 @@ - - - -Reference - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-
-
Header - <boost/none.hpp>
-
Header - <boost/optional/bad_optional_access.hpp>
-
Header <boost/optional/optional_io.hpp>
-
Header - <boost/optional/optional_fwd.hpp>
-
Header - <boost/optional/optional.hpp>
-
Header - <boost/optional.hpp>
-
-
-
-
-
-

-

-
namespace boost {
-
-class none_t {/* see below */};
-
-inline constexpr none_t none (/* see below */);
-
-} // namespace boost
-
-

-

-

- Class none_t is meant to - serve as a tag for selecting appropriate overloads of from optional's interface. It is an empty, - trivially copyable class with disabled default constructor. -

-

- Constant none is used to - indicate an optional object that does not contain a value in initialization, - assignment and relational operations of optional. -

-
-
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/optional/reference/header__boost_optional_optional_hpp_.html b/doc/html/optional/reference/header__boost_optional_optional_hpp_.html deleted file mode 100644 index c905bfce..00000000 --- a/doc/html/optional/reference/header__boost_optional_optional_hpp_.html +++ /dev/null @@ -1,111 +0,0 @@ - - - -Header <boost/optional/optional.hpp> - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-
-
-
// In Header: <boost/optional/optional.hpp>
-
-namespace boost {
-
-class in_place_init_t { /* see below */ } ; R
-const in_place_init_t in_place_init ( /* see below */ ) ;
-
-class in_place_init_if_t { /*see below*/ } ; R
-const in_place_init_if_t in_place_init_if ( /*see below*/ ) ;
-
-template <class T>
-class optional ; R
-
-template <class T>
-class optional<T&> ; R
-
-template<class T> inline bool operator == ( optional<T> const& x, optional<T> const& y ) ; R
-
-template<class T> inline bool operator != ( optional<T> const& x, optional<T> const& y ) ; R
-
-template<class T> inline bool operator <  ( optional<T> const& x, optional<T> const& y ) ; R
-
-template<class T> inline bool operator >  ( optional<T> const& x, optional<T> const& y ) ; R
-
-template<class T> inline bool operator <= ( optional<T> const& x, optional<T> const& y ) ; R
-
-template<class T> inline bool operator >= ( optional<T> const& x, optional<T> const& y ) ; R
-
-template<class T> inline bool operator == ( optional<T> const& x, none_t ) noexcept ; R
-
-template<class T> inline bool operator != ( optional<T> const& x, none_t ) noexcept ; R
-
-template<class T> inline optional<T> make_optional ( T const& v ) ; R
-
-template<class T> inline optional<std::decay_t<T>> make_optional ( T && v ) ; R
-
-template<class T> inline optional<T> make_optional ( bool condition, T const& v ) ; R
-
-template<class T> inline optional<std::decay_t<T>> make_optional ( bool condition, T && v ) ; R
-
-template<class T> inline auto get_optional_value_or ( optional<T> const& opt, typename optional<T>::reference_const_type def ) -> typename optional<T>::reference_const_type; R
-
-template<class T> inline auto get_optional_value_or ( optional<T> const& opt, typename optional<T>::reference_type def ) -> typename optional<T>::reference_type ; R
-
-template<class T> inline T const& get ( optional<T> const& opt ) ; R
-
-template<class T> inline T& get ( optional<T> & opt ) ; R
-
-template<class T> inline T const* get ( optional<T> const* opt ) ; R
-
-template<class T> inline T* get ( optional<T>* opt ) ; R
-
-template<class T> inline auto get_pointer ( optional<T> const& opt ) -> see below; R
-
-template<class T> inline auto get_pointer ( optional<T> & opt ) -> see below; R
-
-template<class T> inline void swap( optional<T>& x, optional<T>& y ) ; R
-
-template<class T> inline void swap( optional<T&>& x, optional<T&>& y ) ; R
-
-} // namespace boost
-
-
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/optional/tutorial.html b/doc/html/optional/tutorial.html deleted file mode 100644 index 1331750c..00000000 --- a/doc/html/optional/tutorial.html +++ /dev/null @@ -1,153 +0,0 @@ - - - -Tutorial - - - - - - - - - - - - - - - -
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-
-
-
Motivation
-
Design Overview
-
When to - use Optional
-
Relational - operators
-
IO operators
-
Optional - references
-
In-Place - Factories
-
Gotchas
-
Exception - Safety Guarantees
-
Type requirements
-
Performance - considerations
-
-
-
-

- Consider these functions which should return a value but which might not - have a value to return: -

-
    -
  • - (A) double sqrt(double n ); -
    • -
  • - (B) char get_async_input(); -
    • -
  • - (C) point polygon::get_any_point_effectively_inside(); -
    • -
-

- There are different approaches to the issue of not having a value to return. -

-

- A typical approach is to consider the existence of a valid return value as - a postcondition, so that if the function cannot compute the value to return, - it has either undefined behavior (and can use assert in a debug build) or - uses a runtime check and throws an exception if the postcondition is violated. - This is a reasonable choice for example, for function (A), because the lack - of a proper return value is directly related to an invalid parameter (out - of domain argument), so it is appropriate to require the callee to supply - only parameters in a valid domain for execution to continue normally. -

-

- However, function (B), because of its asynchronous nature, does not fail - just because it can't find a value to return; so it is incorrect to consider - such a situation an error and assert or throw an exception. This function - must return, and somehow, must tell the callee that it is not returning a - meaningful value. -

-

- A similar situation occurs with function (C): it is conceptually an error - to ask a null-area polygon to return a point inside - itself, but in many applications, it is just impractical for performance - reasons to treat this as an error (because detecting that the polygon has - no area might be too expensive to be required to be tested previously), and - either an arbitrary point (typically at infinity) is returned, or some efficient - way to tell the callee that there is no such point is used. -

-

- There are various mechanisms to let functions communicate that the returned - value is not valid. One such mechanism, which is quite common since it has - zero or negligible overhead, is to use a special value which is reserved - to communicate this. Classical examples of such special values are EOF, string::npos, - points at infinity, etc... -

-

- When those values exist, i.e. the return type can hold all meaningful values - plus the signal value, this mechanism - is quite appropriate and well known. Unfortunately, there are cases when - such values do not exist. In these cases, the usual alternative is either - to use a wider type, such as int - in place of char; or a compound - type, such as std::pair<point,bool>. -

-

- Returning a std::pair<T,bool>, thus attaching a boolean flag to the - result which indicates if the result is meaningful, has the advantage that - can be turned into a consistent idiom since the first element of the pair - can be whatever the function would conceptually return. For example, the - last two functions could have the following interface: -

-
std::pair<char,bool> get_async_input();
-std::pair<point,bool> polygon::get_any_point_effectively_inside();
-
-

- These functions use a consistent interface for dealing with possibly nonexistent - results: -

-
std::pair<point,bool> p = poly.get_any_point_effectively_inside();
-if ( p.second )
-    flood_fill(p.first);
-
-

- However, not only is this quite a burden syntactically, it is also error - prone since the user can easily use the function result (first element of - the pair) without ever checking if it has a valid value. -

-

- Clearly, we need a better idiom. -

-
-
- - - -
Copyright © 2003-2007 Fernando Luis Cacciola Carballal
Copyright © 2014-2021 Andrzej Krzemieński

- Distributed under the Boost Software License, Version 1.0. (See accompanying - file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/images/callouts/R.png b/doc/images/R.png similarity index 100% rename from doc/html/images/callouts/R.png rename to doc/images/R.png diff --git a/doc/html/images/space.png b/doc/images/space.png similarity index 100% rename from doc/html/images/space.png rename to doc/images/space.png