From 5e59e10f9391c6adb84b6e8ebf490689768000bc Mon Sep 17 00:00:00 2001 From: Andrey Semashev Date: Thu, 22 May 2014 10:15:11 +0400 Subject: [PATCH 1/9] Fix warnings with gcc 4.4 in C++11 mode GCC 4.4 has support for an early draft of rvalue references. When compiling the conforming code it produces warnings such as '../boost/optional/optional.hpp:152: warning: returning reference to temporary'. In order to fix this regression use a special implementation of move(), similar to std::move() on this compiler. --- include/boost/optional/optional.hpp | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/include/boost/optional/optional.hpp b/include/boost/optional/optional.hpp index 57fa522..d9e8a97 100644 --- a/include/boost/optional/optional.hpp +++ b/include/boost/optional/optional.hpp @@ -149,7 +149,13 @@ struct types_when_isnt_ref typedef T & reference_type ; #ifndef BOOST_NO_CXX11_RVALUE_REFERENCES typedef T && rval_reference_type ; +#ifdef BOOST_MOVE_OLD_RVALUE_REF_BINDING_RULES + // GCC 4.4 has support for an early draft of rvalue references. The conforming version below + // causes warnings about returning references to a temporary. + static T&& move(T&& r) { return r; } +#else static rval_reference_type move(reference_type r) { return boost::move(r); } +#endif #endif typedef T const* pointer_const_type ; typedef T * pointer_type ; From 75271b73a8484cb5add003f65f1432c05c47dc8b Mon Sep 17 00:00:00 2001 From: Andrzej Krzemienski Date: Thu, 22 May 2014 23:32:49 +0200 Subject: [PATCH 2/9] Member fun value() that throws on uninitialized --- .../boost_optional/detailed_semantics.html | 37 ++++++ .../exception_safety_guarantees.html | 4 +- doc/html/boost_optional/synopsis.html | 3 + doc/html/index.html | 2 +- doc/reference.qbk | 28 +++++ doc/special_cases.qbk | 2 +- include/boost/bad_optional_access.hpp | 28 +++++ include/boost/optional/optional.hpp | 18 +++ include/boost/optional/optional_fwd.hpp | 2 - test/Jamfile.v2 | 1 + test/optional_test_value_access.cpp | 107 ++++++++++++++++++ 11 files changed, 226 insertions(+), 6 deletions(-) create mode 100644 include/boost/bad_optional_access.hpp create mode 100644 test/optional_test_value_access.cpp diff --git a/doc/html/boost_optional/detailed_semantics.html b/doc/html/boost_optional/detailed_semantics.html index 4a5394e..dbfe0cb 100644 --- a/doc/html/boost_optional/detailed_semantics.html +++ b/doc/html/boost_optional/detailed_semantics.html @@ -1200,6 +1200,43 @@ +

+ space +

+

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

+

+ 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. +
    • +
  • + Example: +
    T v ;
+optional<T> o0, o1 ( v );
+assert ( o1.value() == v );
+
+try {
+  o0.value(); // throws
+  assert ( false );
+}
+catch(bad_optional_access&) {
+  asert ( true );
+}
+
    +
    • +

space

diff --git a/doc/html/boost_optional/exception_safety_guarantees.html b/doc/html/boost_optional/exception_safety_guarantees.html index eb29f92..4b2b0a5 100644 --- a/doc/html/boost_optional/exception_safety_guarantees.html +++ b/doc/html/boost_optional/exception_safety_guarantees.html @@ -95,8 +95,8 @@

Unless T's constructor or assignment - throws, optional<T> does - not throw anything else on its own. A throw during assignment never changes + 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);
diff --git a/doc/html/boost_optional/synopsis.html b/doc/html/boost_optional/synopsis.html
index 075bfbf..0e2b20e 100644
--- a/doc/html/boost_optional/synopsis.html
+++ b/doc/html/boost_optional/synopsis.html
@@ -90,6 +90,9 @@
     T const& operator *() const ; R
     T&       operator *() ; R
 
+    T const& value() const ; R
+    T&       value() ; R
+
     T const* get_ptr() const ; R
     T*       get_ptr() ; R
 
diff --git a/doc/html/index.html b/doc/html/index.html
index 1bb9006..5c74f5b 100644
--- a/doc/html/index.html
+++ b/doc/html/index.html
@@ -92,7 +92,7 @@
 
 
 
-
+
Last revised: May 08, 2014 at 12:05:10 GMT
Last revised: May 22, 2014 at 21:28:38 GMT

 

 

 

diff --git a/doc/reference.qbk b/doc/reference.qbk
index 5cbaf6b..80c6927 100644
--- a/doc/reference.qbk
+++ b/doc/reference.qbk
@@ -74,6 +74,9 @@
 
         T const& operator *() const ; ``[link reference_optional_get __GO_TO__]``
         T&       operator *() ; ``[link reference_optional_get __GO_TO__]``
+        
+        T const& value() const ; ``[link reference_optional_value __GO_TO__]``
+        T&       value() ; ``[link reference_optional_value __GO_TO__]``
 
         T const* get_ptr() const ; ``[link reference_optional_get_ptr __GO_TO__]``
         T*       get_ptr() ; ``[link reference_optional_get_ptr __GO_TO__]``
@@ -803,6 +806,31 @@ assert ( *opt == w ) ;
 
 __SPACE__
 
+
+[#reference_optional_value]
+
+[: `T const& optional::value() const ;`]
+[: `T&       optional::value();`]
+
+* [*Returns:] A reference to the contained value, if `*this` is initialized.
+* [*Throws:] An instance of `bad_optional_access`, if `*this` is not initialized.
+* [*Example:]
+``
+T v ;
+optional o0, o1 ( v );
+assert ( o1.value() == v );
+
+try {
+  o0.value(); // throws
+  assert ( false );
+}
+catch(bad_optional_access&) {
+  asert ( true );
+}
+``
+
+__SPACE__
+
 [#reference_optional_get_value_or_value]
 
 [: `T const& optional::get_value_or( T const& default) const ;`]
diff --git a/doc/special_cases.qbk b/doc/special_cases.qbk
index adc191e..6173c16 100644
--- a/doc/special_cases.qbk
+++ b/doc/special_cases.qbk
@@ -336,7 +336,7 @@ Regarding the following assignment functions:
 
 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`'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`'s assignment also never throws.
 
-Unless `T`'s constructor or assignment throws, `optional` does not throw anything else on its own. A throw during assignment never changes the initialization state of any optional object involved:
+Unless `T`'s constructor or assignment throws, assignments to `optional` do not throw anything else on its own. A throw during assignment never changes the initialization state of any optional object involved:
 
 
     optional opt1(val1);
diff --git a/include/boost/bad_optional_access.hpp b/include/boost/bad_optional_access.hpp
new file mode 100644
index 0000000..95abf3a
--- /dev/null
+++ b/include/boost/bad_optional_access.hpp
@@ -0,0 +1,28 @@
+// Copyright (C) 2014, Andrzej Krzemienski.
+//
+// Use, modification, and distribution is subject to 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)
+//
+// See http://www.boost.org/libs/optional for documentation.
+//
+// You are welcome to contact the author at:
+//  akrzemi1@gmail.com
+//
+#ifndef BOOST_BAD_OPTIONAL_ACCESS_22MAY2014_HPP
+#define BOOST_BAD_OPTIONAL_ACCESS_22MAY2014_HPP
+
+#include 
+
+namespace boost {
+
+class bad_optional_access : public std::logic_error
+{
+public:
+  explicit bad_optional_access(const std::string& what_arg) : std::logic_error(what_arg) {}
+  explicit bad_optional_access(const char* what_arg) : std::logic_error(what_arg) {}
+};
+
+} // namespace boost
+
+#endif
diff --git a/include/boost/optional/optional.hpp b/include/boost/optional/optional.hpp
index d9e8a97..b6ca7e9 100644
--- a/include/boost/optional/optional.hpp
+++ b/include/boost/optional/optional.hpp
@@ -23,7 +23,9 @@
 
 #include 
 #include 
+#include 
 #include 
+#include 
 #include 
 #include 
 #include 
@@ -935,6 +937,22 @@ class optional : public optional_detail::optional_base
     // No-throw
     reference_const_type operator *() const { return this->get() ; }
     reference_type       operator *()       { return this->get() ; }
+    
+    reference_const_type value() const
+      { 
+        if (this->is_initialized())
+          return this->get() ;
+        else
+          throw_exception(bad_optional_access("Attempted to access the value of an uninitialized optional object."));
+      }
+      
+    reference_type value()
+      { 
+        if (this->is_initialized())
+          return this->get() ;
+        else
+          throw_exception(bad_optional_access("Attempted to access the value of an uninitialized optional object."));
+      }
 
     bool operator!() const BOOST_NOEXCEPT { return !this->is_initialized() ; }
     
diff --git a/include/boost/optional/optional_fwd.hpp b/include/boost/optional/optional_fwd.hpp
index 29cee49..fb59682 100644
--- a/include/boost/optional/optional_fwd.hpp
+++ b/include/boost/optional/optional_fwd.hpp
@@ -11,11 +11,9 @@
 //
 // Revisions:
 // 10 May 2008 (added swap related forward declaration) Niels Dekker
-// 17 Apr 2014 (added noexcept) Andrzej Krzemienski 
 //
 #ifndef BOOST_OPTIONAL_OPTIONAL_FWD_FLC_19NOV2002_HPP
 #define BOOST_OPTIONAL_OPTIONAL_FWD_FLC_19NOV2002_HPP
-#include 
 
 
 namespace boost {
diff --git a/test/Jamfile.v2 b/test/Jamfile.v2
index 7218ffa..10fd597 100644
--- a/test/Jamfile.v2
+++ b/test/Jamfile.v2
@@ -23,6 +23,7 @@ import testing ;
     [ run optional_test_io.cpp ]
     [ run optional_test_move.cpp ]
     [ run optional_test_equals_none.cpp ]
+    [ run optional_test_value_access.cpp ]
     [ compile-fail optional_test_fail1.cpp ]
     [ compile-fail optional_test_fail3a.cpp ]
     [ compile-fail optional_test_fail3b.cpp ]
diff --git a/test/optional_test_value_access.cpp b/test/optional_test_value_access.cpp
new file mode 100644
index 0000000..5cff1b7
--- /dev/null
+++ b/test/optional_test_value_access.cpp
@@ -0,0 +1,107 @@
+// Copyright (C) 2014 Andrzej Krzemienski.
+//
+// Use, modification, and distribution is subject to 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)
+//
+// See http://www.boost.org/lib/optional for documentation.
+//
+// You are welcome to contact the author at:
+//  akrzemi1@gmail.com
+//
+// Revisions:
+//
+#include
+#include
+#include
+
+#define BOOST_ENABLE_ASSERT_HANDLER
+
+#include "boost/bind/apply.hpp" // Included just to test proper interaction with boost::apply<> as reported by Daniel Wallin
+#include "boost/mpl/bool.hpp"
+#include "boost/mpl/bool_fwd.hpp"  // For mpl::true_ and mpl::false_
+
+#include "boost/optional/optional.hpp"
+
+#ifdef __BORLANDC__
+#pragma hdrstop
+#endif
+
+#include "boost/none.hpp"
+
+#include "boost/test/minimal.hpp"
+
+#include "optional_test_common.cpp"
+
+struct IntWrapper
+{
+  int _i;
+  IntWrapper(int i) : _i(i) {}
+  bool operator==(IntWrapper const& rhs) const { return _i == rhs._i; }
+};
+
+template 
+void test_function_value_for()
+{
+  optional o0;
+  optional o1(1);
+  const optional oC(2);
+  
+  try
+  {
+    T& v = o1.value();
+    BOOST_CHECK(v == 1);
+  }
+  catch(...)
+  {
+    BOOST_CHECK(false);
+  }
+  
+  try
+  {
+    T const& v = oC.value();
+    BOOST_CHECK(v == 2);
+  }
+  catch(...)
+  {
+    BOOST_CHECK(false);
+  }
+  
+  try
+  {
+    T& v = o0.value();
+    BOOST_CHECK(false);
+    unused_variable(v);
+  }
+  catch(boost::bad_optional_access const&)
+  {
+  }
+  catch(...)
+  {
+    BOOST_CHECK(false);
+  }
+}
+
+void test_function_value()
+{
+    test_function_value_for();
+    test_function_value_for();
+    test_function_value_for();
+}
+
+int test_main( int, char* [] )
+{
+  try
+  {
+    test_function_value();
+
+  }
+  catch ( ... )
+  {
+    BOOST_ERROR("Unexpected Exception caught!");
+  }
+
+  return 0;
+}
+
+

From 3984c9f9a157ef116cea69bc8bb20f433320eb61 Mon Sep 17 00:00:00 2001
From: Andrzej Krzemienski 
Date: Fri, 23 May 2014 16:38:42 +0200
Subject: [PATCH 3/9] Added function value_or()

---
 .../boost_optional/detailed_semantics.html    | 27 ++++++++++++
 doc/html/boost_optional/synopsis.html         | 10 ++---
 doc/html/index.html                           |  2 +-
 doc/reference.qbk                             | 22 +++++++---
 .../{ => optional}/bad_optional_access.hpp    |  0
 include/boost/optional/optional.hpp           | 14 ++++--
 test/optional_test_value_access.cpp           | 43 ++++++++++++++++++-
 7 files changed, 100 insertions(+), 18 deletions(-)
 rename include/boost/{ => optional}/bad_optional_access.hpp (100%)

diff --git a/doc/html/boost_optional/detailed_semantics.html b/doc/html/boost_optional/detailed_semantics.html
index dbfe0cb..8495d41 100644
--- a/doc/html/boost_optional/detailed_semantics.html
+++ b/doc/html/boost_optional/detailed_semantics.html
@@ -1235,6 +1235,30 @@
   asert ( true );
 }
+ space + + +

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

+
    +
  • + Requires: T + is CopyConstructible. +
    • +
  • + Returns: bool(*this) + ? **this : static_cast<T>(forward<U>(v)). +
    • +
  • + Throws: Any exception thrown by the selected + constructor of T. +
    • +
  • + Notes: On compilers without rvalue reference + support the type of v becomes + U const&.

@@ -1264,6 +1288,9 @@ o, T& default ) ;

    +
  • + Deprecated: Use value_or() instead. +
  • Returns: A reference to the contained value, if any, or default. diff --git a/doc/html/boost_optional/synopsis.html b/doc/html/boost_optional/synopsis.html index 0e2b20e..8a22968 100644 --- a/doc/html/boost_optional/synopsis.html +++ b/doc/html/boost_optional/synopsis.html @@ -81,9 +81,6 @@ T const& get() const ; R T& get() ; R - // [new in 1.34] - T const& get_value_or( T const& default ) const ; R - T const* operator ->() const ; R T* operator ->() ; R @@ -93,6 +90,8 @@ T const& value() const ; R T& value() ; R + template<class U> T value_or( U && v ) const ; R + T const* get_ptr() const ; R T* get_ptr() ; R @@ -111,6 +110,8 @@ // (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 @@ -129,13 +130,10 @@ template<class T> inline bool operator != ( optional<T> const& x, none_t ) noexcept ; R -// [new in 1.34] template<class T> inline optional<T> make_optional ( T const& v ) ; R -// [new in 1.34] template<class T> inline optional<T> make_optional ( bool condition, T const& v ) ; R -// [new in 1.34] 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 diff --git a/doc/html/index.html b/doc/html/index.html index 5c74f5b..9854163 100644 --- a/doc/html/index.html +++ b/doc/html/index.html @@ -92,7 +92,7 @@
- +

Last revised: May 22, 2014 at 21:28:38 GMT

Last revised: May 23, 2014 at 14:35:08 GMT
diff --git a/doc/reference.qbk b/doc/reference.qbk index 80c6927..cd2e354 100644 --- a/doc/reference.qbk +++ b/doc/reference.qbk @@ -66,9 +66,6 @@ T const& get() const ; ``[link reference_optional_get __GO_TO__]`` T& get() ; ``[link reference_optional_get __GO_TO__]`` - // [new in 1.34] - T const& get_value_or( T const& default ) const ; ``[link reference_optional_get_value_or_value __GO_TO__]`` - T const* operator ->() const ; ``[link reference_optional_operator_arrow __GO_TO__]`` T* operator ->() ; ``[link reference_optional_operator_arrow __GO_TO__]`` @@ -77,6 +74,8 @@ T const& value() const ; ``[link reference_optional_value __GO_TO__]`` T& value() ; ``[link reference_optional_value __GO_TO__]`` + + template T value_or( U && v ) const ; ``[link reference_optional_value_or __GO_TO__]`` T const* get_ptr() const ; ``[link reference_optional_get_ptr __GO_TO__]`` T* get_ptr() ; ``[link reference_optional_get_ptr __GO_TO__]`` @@ -96,6 +95,8 @@ // (deprecated) bool is_initialized() const ; ``[link reference_optional_is_initialized __GO_TO__]`` + // (deprecated) + T const& get_value_or( T const& default ) const ; ``[link reference_optional_get_value_or_value __GO_TO__]`` }; template inline bool operator == ( optional const& x, optional const& y ) ; ``[link reference_operator_compare_equal_optional_optional __GO_TO__]`` @@ -114,13 +115,10 @@ template inline bool operator != ( optional const& x, none_t ) noexcept ; ``[link reference_operator_compare_not_equal_optional_none __GO_TO__]`` - // [new in 1.34] template inline optional make_optional ( T const& v ) ; ``[link reference_make_optional_value __GO_TO__]`` - // [new in 1.34] template inline optional make_optional ( bool condition, T const& v ) ; ``[link reference_make_optional_bool_value __GO_TO__]`` - // [new in 1.34] template inline T const& get_optional_value_or ( optional const& opt, T const& default ) ; ``[link reference_optional_get_value_or_value __GO_TO__]`` template inline T const& get ( optional const& opt ) ; ``[link reference_optional_get __GO_TO__]`` @@ -828,6 +826,17 @@ catch(bad_optional_access&) { asert ( true ); } `` +__SPACE__ + + +[#reference_optional_value_or] + +[: `template T optional::value_or(U && v) const ;`] + +* [*Requires:] `T` is CopyConstructible. +* [*Returns:] `bool(*this) ? **this : static_cast(forward(v))`. +* [*Throws:] Any exception thrown by the selected constructor of `T`. +* [*Notes:] On compilers without rvalue reference support the type of `v` becomes `U const&`. __SPACE__ @@ -839,6 +848,7 @@ __SPACE__ [: `inline T const& get_optional_value_or ( optional const& o, T const& default ) ;`] [: `inline T& get_optional_value_or ( optional& o, T& default ) ;`] +* [*Deprecated:] Use `value_or()` instead. * [*Returns:] A reference to the contained value, if any, or `default`. * [*Throws:] Nothing. * [*Example:] diff --git a/include/boost/bad_optional_access.hpp b/include/boost/optional/bad_optional_access.hpp similarity index 100% rename from include/boost/bad_optional_access.hpp rename to include/boost/optional/bad_optional_access.hpp diff --git a/include/boost/optional/optional.hpp b/include/boost/optional/optional.hpp index b6ca7e9..5a9cc46 100644 --- a/include/boost/optional/optional.hpp +++ b/include/boost/optional/optional.hpp @@ -23,7 +23,7 @@ #include #include -#include +#include #include #include #include @@ -441,11 +441,11 @@ class optional_base : public optional_tag public : - // Destroys the current value, if any, leaving this UNINITIALIZED + // **DEPPRECATED** Destroys the current value, if any, leaving this UNINITIALIZED // No-throw (assuming T::~T() doesn't) void reset() BOOST_NOEXCEPT { destroy(); } - // Replaces the current value -if any- with 'val' + // **DEPPRECATED** Replaces the current value -if any- with 'val' void reset ( argument_type val ) { assign(val); } // Returns a pointer to the value if this is initialized, otherwise, @@ -954,6 +954,14 @@ class optional : public optional_detail::optional_base throw_exception(bad_optional_access("Attempted to access the value of an uninitialized optional object.")); } +#ifndef BOOST_NO_CXX11_RVALUE_REFERENCES + template + value_type value_or ( U&& v ) const { return this->is_initialized() ? get() : static_cast(boost::forward(v)); } +#else + template + value_type value_or ( U const& v ) const { return this->is_initialized() ? get() : static_cast(v); } +#endif + bool operator!() const BOOST_NOEXCEPT { return !this->is_initialized() ; } BOOST_EXPLICIT_OPERATOR_BOOL() diff --git a/test/optional_test_value_access.cpp b/test/optional_test_value_access.cpp index 5cff1b7..73dc3fd 100644 --- a/test/optional_test_value_access.cpp +++ b/test/optional_test_value_access.cpp @@ -40,6 +40,20 @@ struct IntWrapper bool operator==(IntWrapper const& rhs) const { return _i == rhs._i; } }; +template +void test_function_value_or_for() +{ + optional oM0; + const optional oC0; + optional oM1(1); + const optional oC2(2); + + BOOST_CHECK(oM0.value_or(5) == 5); + BOOST_CHECK(oC0.value_or(5) == 5); + BOOST_CHECK(oM1.value_or(5) == 1); + BOOST_CHECK(oC2.value_or(5) == 2); +} + template void test_function_value_for() { @@ -85,16 +99,41 @@ void test_function_value_for() void test_function_value() { test_function_value_for(); - test_function_value_for(); + test_function_value_for(); test_function_value_for(); } +struct FatToIntConverter +{ + static int conversions; + int _val; + FatToIntConverter(int val) : _val(val) {} + operator int() { conversions += 1; return _val; } +}; + +int FatToIntConverter::conversions = 0; + +void test_function_value_or() +{ + test_function_value_or_for(); + test_function_value_or_for(); + test_function_value_or_for(); + + optional oi(1); + BOOST_CHECK(oi.value_or(FatToIntConverter(2)) == 1); + BOOST_CHECK(FatToIntConverter::conversions == 0); + + oi = boost::none; + BOOST_CHECK(oi.value_or(FatToIntConverter(2)) == 2); + BOOST_CHECK(FatToIntConverter::conversions == 1); +} + int test_main( int, char* [] ) { try { test_function_value(); - + test_function_value_or(); } catch ( ... ) { From 22baf1dd09153e07589e0cb3015724f4e355b27e Mon Sep 17 00:00:00 2001 From: Andrzej Krzemienski Date: Sat, 24 May 2014 13:44:07 +0200 Subject: [PATCH 4/9] Fixed bug in test on compiler with no rvalue refs --- test/optional_test_value_access.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/optional_test_value_access.cpp b/test/optional_test_value_access.cpp index 73dc3fd..bd3ea9e 100644 --- a/test/optional_test_value_access.cpp +++ b/test/optional_test_value_access.cpp @@ -108,7 +108,7 @@ struct FatToIntConverter static int conversions; int _val; FatToIntConverter(int val) : _val(val) {} - operator int() { conversions += 1; return _val; } + operator int() const { conversions += 1; return _val; } }; int FatToIntConverter::conversions = 0; From 2e583aaf30964afd66c1284aa71d0d8b42fa440d Mon Sep 17 00:00:00 2001 From: Andrzej Krzemienski Date: Tue, 3 Jun 2014 17:36:18 +0200 Subject: [PATCH 5/9] Fixed code, updated docs, added emplace() --- doc/{optional.qbk => 00_optional.qbk} | 46 ++-- doc/01_tutorial.qbk | 113 +++++++++ doc/{motivation.qbk => 02_discussion.qbk} | 2 +- doc/{development.qbk => 03_development.qbk} | 8 +- doc/{reference.qbk => 04_reference.qbk} | 19 +- doc/{examples.qbk => 05_examples.qbk} | 0 doc/10_optional_references.qbk | 120 +++++++++ ...special_cases.qbk => 11_special_cases.qbk} | 127 +--------- doc/{dependencies.qbk => 90_dependencies.qbk} | 0 ...owledgments.qbk => 91_acknowledgments.qbk} | 0 doc/Jamfile.v2 | 2 +- .../boost_optional/detailed_semantics.html | 38 ++- doc/html/boost_optional/development.html | 27 +- doc/html/boost_optional/discussion.html | 128 ++++++++++ .../exception_safety_guarantees.html | 7 + doc/html/boost_optional/synopsis.html | 2 + doc/html/boost_optional/tutorial.html | 239 ++++++++++++++++++ .../boost_optional/type_requirements.html | 14 +- doc/html/index.html | 73 +++++- include/boost/detail/none_t.hpp | 28 -- include/boost/optional/optional.hpp | 27 +- test/Jamfile.v2 | 1 + test/optional_test_emplace.cpp | 169 +++++++++++++ 23 files changed, 986 insertions(+), 204 deletions(-) rename doc/{optional.qbk => 00_optional.qbk} (53%) create mode 100644 doc/01_tutorial.qbk rename doc/{motivation.qbk => 02_discussion.qbk} (99%) rename doc/{development.qbk => 03_development.qbk} (98%) rename doc/{reference.qbk => 04_reference.qbk} (97%) rename doc/{examples.qbk => 05_examples.qbk} (100%) create mode 100644 doc/10_optional_references.qbk rename doc/{special_cases.qbk => 11_special_cases.qbk} (63%) rename doc/{dependencies.qbk => 90_dependencies.qbk} (100%) rename doc/{acknowledgments.qbk => 91_acknowledgments.qbk} (100%) create mode 100644 doc/html/boost_optional/discussion.html create mode 100644 doc/html/boost_optional/tutorial.html delete mode 100644 include/boost/detail/none_t.hpp create mode 100644 test/optional_test_emplace.cpp diff --git a/doc/optional.qbk b/doc/00_optional.qbk similarity index 53% rename from doc/optional.qbk rename to doc/00_optional.qbk index 3a74566..abf5fd7 100644 --- a/doc/optional.qbk +++ b/doc/00_optional.qbk @@ -46,23 +46,39 @@ Distributed under the Boost Software License, Version 1.0. [section Introduction] -This library can be used to represent 'optional' (or 'nullable') objects that can be safely passed by value: +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. - optional readInt(); // this function may return either an int or a not-an-int - - if (optional oi = readInt()) // did I get a real int - cout << "my int is: " << *oi; // use my int - else - cout << "I have no int"; - +[section Problem] +Suppose we want to read a parameter form 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 different. Also suppose that any possible value of type `int` is a valid value for `"MaxValue"`, so we cannot jut use `-1` to represent the absence of the parameter in the config file. [endsect] -[include motivation.qbk] -[include development.qbk] -[include reference.qbk] -[include examples.qbk] -[include special_cases.qbk] -[include dependencies.qbk] -[include acknowledgments.qbk] +[section Solution] + +This is how you solve it with `boost::optional`: + + #include + + boost::optional getConfigParam(std::string name); // return either an int or a `not-an-int` + + int main() + { + if (boost::optional oi = getConfigParam("MaxValue")) // did I get a real int? + runWithMax(*oi); // use my int + else + runWithNoMax(); + } + +[endsect] +[endsect] + +[include 01_tutorial.qbk] +[include 02_discussion.qbk] +[include 03_development.qbk] +[include 04_reference.qbk] +[include 05_examples.qbk] +[include 10_optional_references.qbk] +[include 11_special_cases.qbk] +[include 90_dependencies.qbk] +[include 91_acknowledgments.qbk] diff --git a/doc/01_tutorial.qbk b/doc/01_tutorial.qbk new file mode 100644 index 0000000..cf8be16 --- /dev/null +++ b/doc/01_tutorial.qbk @@ -0,0 +1,113 @@ +[/ + Boost.Optional + + Copyright (c) 2003-2007 Fernando Luis Cacciola Carballal + Copyright (c) 2014 Andrzej Krzemienski + + 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) +] + + +[section Tutorial] + +[section Optional return values] + +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::optionl convert(const std::string& text); + +All necessary functionality can be included with one header ``. 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::optionl 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::optionl 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 non-existent 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::optionl convert(const std::string& text) + { + std::stringstream s(text); + int i; + if ((s >> i) && s.get() == std::char_traits::eof()) + return i; + else + return boost::none; + } + +Observe the two return statements. `return i` uses the converting constructor that can create `optional` 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. + + +[endsect] + +[section Optional data members] +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 + { + boost::optional resource_; + + public: + Widget() {} + + Resource& getResource() // 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 __SGI_DEFAULT_CONSTRUCTIBLE__. 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 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 [link boost_optional.in_place_factories In-Place Factories].] + +[endsect] + +[section Bypassing unnecessary default construction] +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 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 initial invented 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 begin, end; + boost::tie(begin, end) = getPeriod(); + +It works because inside `boost::tie` a move-assignment from `T` is invoked on `optional`, which internally calls a move-constructor of `T`. +[endsect] + +[endsect] + + diff --git a/doc/motivation.qbk b/doc/02_discussion.qbk similarity index 99% rename from doc/motivation.qbk rename to doc/02_discussion.qbk index fc014c3..ee69444 100644 --- a/doc/motivation.qbk +++ b/doc/02_discussion.qbk @@ -9,7 +9,7 @@ http://www.boost.org/LICENSE_1_0.txt) ] -[section Motivation] +[section Discussion] Consider these functions which should return a value but which might not have a value to return: diff --git a/doc/development.qbk b/doc/03_development.qbk similarity index 98% rename from doc/development.qbk rename to doc/03_development.qbk index 9340407..bb89134 100644 --- a/doc/development.qbk +++ b/doc/03_development.qbk @@ -13,13 +13,13 @@ [section The models] In C++, we can ['declare] an object (a variable) of type `T`, and we can give this -variable an ['initial value] (through an ['initializer]. (c.f. 8.5)). +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] -(c.f. 8.5.9). +(cf. 8.5/11). `optional` 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 @@ -38,7 +38,7 @@ 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]—were `nil_t` is some stateless POD-can be modeled in modern +`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`. @@ -197,7 +197,7 @@ 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 __OPTIONAL_POINTEE__ concept. This concept captures the syntactic usage of operators `*`, `->` and -conversion to `bool` to convey the notion of optionality. +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 diff --git a/doc/reference.qbk b/doc/04_reference.qbk similarity index 97% rename from doc/reference.qbk rename to doc/04_reference.qbk index cd2e354..fbeb821 100644 --- a/doc/reference.qbk +++ b/doc/04_reference.qbk @@ -58,6 +58,8 @@ template optional& operator = ( optional const& rhs ) ; ``[link reference_optional_operator_equal_other_optional __GO_TO__]`` template optional& operator = ( optional&& rhs ) ; ``[link reference_optional_operator_move_equal_other_optional __GO_TO__]`` + + template void emplace ( Args...&& args ) ; ``[link reference_optional_emplace __GO_TO__]`` template optional& operator = ( InPlaceFactory const& f ) ; ``[link reference_optional_operator_equal_factory __GO_TO__]`` @@ -746,6 +748,21 @@ assert ( *opt1 == static_cast(v) ) ; __SPACE__ +[#reference_optional_emplace] + +[: `template void optional::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)...`. +* [*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__ + [#reference_optional_operator_equal_factory] [: `template optional& optional::operator=( InPlaceFactory const& f );`] @@ -823,7 +840,7 @@ try { assert ( false ); } catch(bad_optional_access&) { - asert ( true ); + assert ( true ); } `` __SPACE__ diff --git a/doc/examples.qbk b/doc/05_examples.qbk similarity index 100% rename from doc/examples.qbk rename to doc/05_examples.qbk diff --git a/doc/10_optional_references.qbk b/doc/10_optional_references.qbk new file mode 100644 index 0000000..2f8b3c6 --- /dev/null +++ b/doc/10_optional_references.qbk @@ -0,0 +1,120 @@ + +[section Optional references] + +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` treats it wrapped pseudo-object much as +a real value, a true real reference is stored so aliasing will ocurr: + +* Copies of `optional` 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 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 [link boost_optional.dependencies_and_portability.optional_reference_binding Dependencies and Portability section].] + +[heading 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 oi = 1; // illegal + +[endsect] + +[section Rebinding semantics for assignment of optional references] + +If you assign to an ['uninitialized ] `optional` 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 ora ; + optional 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`, 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 ora(ra) ; + optional orb(rb) ; + ora = orb ; // 'ora' is rebound to 'b' + *ora = 3 ; // Changes value of 'b' (not 'a') + assert(a==1); + assert(b==3); + +[heading 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` 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` forwarding assignment to the referenced object (thus +changing the referenced object value but not rebinding), and consider the +following code: + + optional a = get(); + int x = 1 ; + int& rx = x ; + optional 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` 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` 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; + +[endsect] diff --git a/doc/special_cases.qbk b/doc/11_special_cases.qbk similarity index 63% rename from doc/special_cases.qbk rename to doc/11_special_cases.qbk index 6173c16..110ef78 100644 --- a/doc/special_cases.qbk +++ b/doc/11_special_cases.qbk @@ -1,124 +1,4 @@  -[section Optional references] - -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` treats it wrapped pseudo-object much as -a real value, a true real reference is stored so aliasing will ocurr: - -* Copies of `optional` 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 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 [link boost_optional.dependencies_and_portability.optional_reference_binding Dependencies and Portability section].] - -[heading 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 oi = 1; // illegal - -[endsect] - -[section Rebinding semantics for assignment of optional references] - -If you assign to an ['uninitialized ] `optional` 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 ora ; - optional 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`, 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 ora(ra) ; - optional orb(rb) ; - ora = orb ; // 'ora' is rebound to 'b' - *ora = 3 ; // Changes value of 'b' (not 'a') - assert(a==1); - assert(b==3); - -[heading 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` 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` forwarding assignment to the referenced object (thus -changing the referenced object value but not rebinding), and consider the -following code: - - optional a = get(); - int x = 1 ; - int& rx = x ; - optional 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` 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` 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; - -[endsect] - [section In-Place Factories] One of the typical problems with wrappers and containers is that their @@ -356,6 +236,8 @@ Unless `T`'s constructor or assignment throws, assignments to `optional` do n 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`. + [heading 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` never throws. similarly, if both `T`'s `swap` and move constructor offer strong guarantee, `swap` on `optional` also offers a strong guarantee. @@ -365,8 +247,9 @@ In case `swap` on optional is customized, the call to `T`'s move constructor are [section Type requirements] -In general, `T` must be `MoveConstructible` and have a no-throw destructor. -The `MoveConstructible` requirement is not needed if [*InPlaceFactories] are used. +At the very minimum for `optional` 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` 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` is also `Copyable` and can be easily initialized from an lvalue of type `T`. `T` [_is not] required to be __SGI_DEFAULT_CONSTRUCTIBLE__. diff --git a/doc/dependencies.qbk b/doc/90_dependencies.qbk similarity index 100% rename from doc/dependencies.qbk rename to doc/90_dependencies.qbk diff --git a/doc/acknowledgments.qbk b/doc/91_acknowledgments.qbk similarity index 100% rename from doc/acknowledgments.qbk rename to doc/91_acknowledgments.qbk diff --git a/doc/Jamfile.v2 b/doc/Jamfile.v2 index 95de749..5014bb2 100644 --- a/doc/Jamfile.v2 +++ b/doc/Jamfile.v2 @@ -17,7 +17,7 @@ path-constant images : html ; xml optional : - optional.qbk + 00_optional.qbk ; boostbook standalone diff --git a/doc/html/boost_optional/detailed_semantics.html b/doc/html/boost_optional/detailed_semantics.html index 8495d41..8374254 100644 --- a/doc/html/boost_optional/detailed_semantics.html +++ b/doc/html/boost_optional/detailed_semantics.html @@ -1080,6 +1080,42 @@ +

+ 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

@@ -1232,7 +1268,7 @@ assert ( false ); } catch(bad_optional_access&) { - asert ( true ); + assert ( true ); } space diff --git a/doc/html/boost_optional/development.html b/doc/html/boost_optional/development.html index f289a04..1ff950f 100644 --- a/doc/html/boost_optional/development.html +++ b/doc/html/boost_optional/development.html @@ -6,7 +6,7 @@ - + @@ -20,7 +20,7 @@
-PrevUpHomeNext +PrevUpHomeNext

@@ -39,12 +39,12 @@ In C++, we can declare an object (a variable) of type T, and we can give this variable an initial value (through an initializer. - (c.f. 8.5)). When a declaration includes a non-empty initializer (an initial + (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 (c.f. 8.5.9). optional<T> intends + 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 @@ -67,13 +67,12 @@ 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—were 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>. + 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 @@ -329,8 +328,8 @@ 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 conversion to bool to convey - the notion of optionality. + and contextual conversion to bool + to convey the notion of optionality.

However, pointers are good to refer @@ -407,7 +406,7 @@

-PrevUpHomeNext +PrevUpHomeNext
diff --git a/doc/html/boost_optional/discussion.html b/doc/html/boost_optional/discussion.html new file mode 100644 index 0000000..5eb1c93 --- /dev/null +++ b/doc/html/boost_optional/discussion.html @@ -0,0 +1,128 @@ + + + +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/exception_safety_guarantees.html b/doc/html/boost_optional/exception_safety_guarantees.html index 4b2b0a5..2537918 100644 --- a/doc/html/boost_optional/exception_safety_guarantees.html +++ b/doc/html/boost_optional/exception_safety_guarantees.html @@ -118,6 +118,13 @@ 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 diff --git a/doc/html/boost_optional/synopsis.html b/doc/html/boost_optional/synopsis.html index 8a22968..b350ded 100644 --- a/doc/html/boost_optional/synopsis.html +++ b/doc/html/boost_optional/synopsis.html @@ -74,6 +74,8 @@ 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 diff --git a/doc/html/boost_optional/tutorial.html b/doc/html/boost_optional/tutorial.html new file mode 100644 index 0000000..c1b6173 --- /dev/null +++ b/doc/html/boost_optional/tutorial.html @@ -0,0 +1,239 @@ + + + +Tutorial + + + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+
+
+PrevUpHomeNext +
+
+
+
+
Optional + return values
+
Optional + data members
+
Bypassing + unnecessary default construction
+
+
+
+

+ 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::optionl<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::optionl<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::optionl<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 non-existent + 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::optionl<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. +

+
+
+
+

+ 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
+{
+  boost::optional<Resource> resource_;
+
+public:
+  Widget() {}
+
+  Resource& getResource() // 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 Default + Constructible. 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. +

+
+
+
+

+ 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 initial invented 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 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 index 6c68e88..8ffd2ea 100644 --- a/doc/html/boost_optional/type_requirements.html +++ b/doc/html/boost_optional/type_requirements.html @@ -27,9 +27,17 @@ Type requirements

- In general, T must be MoveConstructible and have a no-throw destructor. - The MoveConstructible requirement - is not needed if InPlaceFactories are used. + 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 diff --git a/doc/html/index.html b/doc/html/index.html index 9854163..4f602c2 100644 --- a/doc/html/index.html +++ b/doc/html/index.html @@ -5,7 +5,7 @@ - + @@ -17,7 +17,7 @@
More

-
Next
+
Next

@@ -38,7 +38,20 @@

Table of Contents

Introduction
-
Motivation
+
+
Problem
+
Solution
+
+
Tutorial
+
+
Optional + return values
+
Optional + data members
+
Bypassing + unnecessary default construction
+
+
Discussion
Development
The models
@@ -78,24 +91,60 @@
+
+
Problem
+
Solution
+

- This library can be used to represent 'optional' (or 'nullable') objects that - can be safely passed by value: + 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.

-
optional<int> readInt(); // this function may return either an int or a not-an-int
+

+

+

+        Suppose we want to read a parameter form 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 different. Also suppose that any possible
+        value of type int is a valid
+        value for "MaxValue",
+        so we cannot jut use -1
+        to represent the absence of the parameter in the config file.
+      

+

+

+

+

+        This is how you solve it with boost::optional:
+      

+
#include <boost/optional.hpp>
 
-if (optional<int> oi = readInt()) // did I get a real int
-  cout << "my int is: " << *oi;   // use my int
-else
-  cout << "I have no int";
+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: May 23, 2014 at 14:35:08 GMT

Last revised: June 03, 2014 at 14:35:30 GMT
-
Next
+
Next
diff --git a/include/boost/detail/none_t.hpp b/include/boost/detail/none_t.hpp deleted file mode 100644 index 40805ec..0000000 --- a/include/boost/detail/none_t.hpp +++ /dev/null @@ -1,28 +0,0 @@ -// Copyright (C) 2003, Fernando Luis Cacciola Carballal. -// -// Use, modification, and distribution is subject to 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) -// -// See http://www.boost.org/libs/optional for documentation. -// -// You are welcome to contact the author at: -// fernando_cacciola@hotmail.com -// -#ifndef BOOST_DETAIL_NONE_T_17SEP2003_HPP -#define BOOST_DETAIL_NONE_T_17SEP2003_HPP - -namespace boost { - -namespace detail { - -struct none_helper{}; - -typedef int none_helper::*none_t ; - -} // namespace detail - -} // namespace boost - -#endif - diff --git a/include/boost/optional/optional.hpp b/include/boost/optional/optional.hpp index 5a9cc46..4a8dc5e 100644 --- a/include/boost/optional/optional.hpp +++ b/include/boost/optional/optional.hpp @@ -460,14 +460,26 @@ class optional_base : public optional_tag void construct ( argument_type val ) { - new (m_storage.address()) internal_type(val) ; + ::new (m_storage.address()) internal_type(val) ; m_initialized = true ; } #ifndef BOOST_NO_CXX11_RVALUE_REFERENCES void construct ( rval_reference_type val ) { - new (m_storage.address()) internal_type( types::move(val) ) ; + ::new (m_storage.address()) internal_type( types::move(val) ) ; + m_initialized = true ; + } +#endif + +#if (!defined BOOST_NO_CXX11_RVALUE_REFERENCES) && (!defined BOOST_NO_CXX11_VARIADIC_TEMPLATES) + // Constructs in-place + // upon exception *this is always uninitialized + template + void emplace_assign ( Args&&... args ) + { + destroy(); + ::new (m_storage.address()) internal_type( boost::forward(args)... ); m_initialized = true ; } #endif @@ -507,6 +519,7 @@ class optional_base : public optional_tag destroy(); construct(factory,tag); } + #else // Constructs in-place using the given factory template @@ -907,6 +920,16 @@ class optional : public optional_detail::optional_base this->assign( none_ ) ; return *this ; } + +#if (!defined BOOST_NO_CXX11_RVALUE_REFERENCES) && (!defined BOOST_NO_CXX11_VARIADIC_TEMPLATES) + // Constructs in-place + // upon exception *this is always uninitialized + template + void emplace ( Args&&... args ) + { + this->emplace_assign( boost::forward(args)... ); + } +#endif void swap( optional & arg ) BOOST_NOEXCEPT_IF(::boost::is_nothrow_move_constructible::value && ::boost::is_nothrow_move_assignable::value) diff --git a/test/Jamfile.v2 b/test/Jamfile.v2 index 10fd597..48ddf3f 100644 --- a/test/Jamfile.v2 +++ b/test/Jamfile.v2 @@ -24,6 +24,7 @@ import testing ; [ run optional_test_move.cpp ] [ run optional_test_equals_none.cpp ] [ run optional_test_value_access.cpp ] + [ run optional_test_emplace.cpp ] [ compile-fail optional_test_fail1.cpp ] [ compile-fail optional_test_fail3a.cpp ] [ compile-fail optional_test_fail3b.cpp ] diff --git a/test/optional_test_emplace.cpp b/test/optional_test_emplace.cpp new file mode 100644 index 0000000..2bc761a --- /dev/null +++ b/test/optional_test_emplace.cpp @@ -0,0 +1,169 @@ +// Copyright (C) 2014 Andrzej Krzemienski. +// +// Use, modification, and distribution is subject to 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) +// +// See http://www.boost.org/lib/optional for documentation. +// +// You are welcome to contact the author at: +// akrzemi1@gmail.com +// +// Revisions: +// +#include +#include +#include + +#define BOOST_ENABLE_ASSERT_HANDLER + +#include "boost/bind/apply.hpp" // Included just to test proper interaction with boost::apply<> as reported by Daniel Wallin +#include "boost/mpl/bool.hpp" +#include "boost/mpl/bool_fwd.hpp" // For mpl::true_ and mpl::false_ +#include "boost/static_assert.hpp" + +#include "boost/optional/optional.hpp" + +#ifdef __BORLANDC__ +#pragma hdrstop +#endif + +#include "boost/none.hpp" + +#include "boost/test/minimal.hpp" + +#include "optional_test_common.cpp" + +//#ifndef BOOST_OPTIONAL_NO_CONVERTING_ASSIGNMENT +//#ifndef BOOST_OPTIONAL_NO_CONVERTING_COPY_CTOR + +#if (!defined BOOST_NO_CXX11_RVALUE_REFERENCES) && (!defined BOOST_NO_CXX11_VARIADIC_TEMPLATES) + +class Guard +{ +public: + int which_ctor; + Guard () : which_ctor(0) { } + Guard (int&, double&&) : which_ctor(1) { } + Guard (int&&, double&) : which_ctor(2) { } + Guard (int&&, double&&) : which_ctor(3) { } + Guard (int&, double&) : which_ctor(4) { } + Guard (std::string const&) : which_ctor(5) { } + Guard (std::string &) : which_ctor(6) { } + Guard (std::string &&) : which_ctor(7) { } +private: + Guard(Guard&&); + Guard(Guard const&); + void operator=(Guard &&); + void operator=(Guard const&); +}; + +struct Thrower +{ + Thrower(bool throw_) { if (throw_) throw int(); } + +private: + Thrower(Thrower const&); + Thrower(Thrower&&); +}; + +struct ThrowOnMove +{ + ThrowOnMove(ThrowOnMove&&) { throw int(); } + ThrowOnMove(ThrowOnMove const&) { throw int(); } + ThrowOnMove(int){} +}; + +void test_emplace() +{ + int i = 0; + double d = 0.0; + const std::string cs; + std::string ms; + optional o; + + o.emplace(); + BOOST_CHECK(o); + BOOST_CHECK(0 == o->which_ctor); + + o.emplace(i, 2.0); + BOOST_CHECK(o); + BOOST_CHECK(1 == o->which_ctor); + + o.emplace(1, d); + BOOST_CHECK(o); + BOOST_CHECK(2 == o->which_ctor); + + o.emplace(1, 2.0); + BOOST_CHECK(o); + BOOST_CHECK(3 == o->which_ctor); + + o.emplace(i, d); + BOOST_CHECK(o); + BOOST_CHECK(4 == o->which_ctor); + + o.emplace(cs); + BOOST_CHECK(o); + BOOST_CHECK(5 == o->which_ctor); + + o.emplace(ms); + BOOST_CHECK(o); + BOOST_CHECK(6 == o->which_ctor); + + o.emplace(std::string()); + BOOST_CHECK(o); + BOOST_CHECK(7 == o->which_ctor); +} + +void test_clear_on_throw() +{ + optional ot; + try { + ot.emplace(false); + BOOST_CHECK(ot); + } catch(...) { + BOOST_CHECK(false); + } + + try { + ot.emplace(true); + BOOST_CHECK(false); + } catch(...) { + BOOST_CHECK(!ot); + } +} + +void test_no_moves_on_emplacement() +{ + try { + optional o; + o.emplace(1); + BOOST_CHECK(o); + } + catch (...) { + BOOST_CHECK(false); + } +} + +#endif + + +int test_main( int, char* [] ) +{ + try + { +#if (!defined BOOST_NO_CXX11_RVALUE_REFERENCES) && (!defined BOOST_NO_CXX11_VARIADIC_TEMPLATES) + test_emplace(); + test_clear_on_throw(); + test_no_moves_on_emplacement(); +#endif + } + catch ( ... ) + { + BOOST_ERROR("Unexpected Exception caught!"); + } + + return 0; +} + + From f99618f09bff6aa244f3b683d339676ebd474630 Mon Sep 17 00:00:00 2001 From: Andrzej Krzemienski Date: Tue, 3 Jun 2014 23:07:19 +0200 Subject: [PATCH 6/9] Added ref-qualifiers to some accessors --- include/boost/optional/optional.hpp | 47 +++++++++++++++++++++++++++-- test/optional_test_common.cpp | 2 +- test/optional_test_value_access.cpp | 29 ++++++++++++++++++ 3 files changed, 74 insertions(+), 4 deletions(-) diff --git a/include/boost/optional/optional.hpp b/include/boost/optional/optional.hpp index 4a8dc5e..b3319b0 100644 --- a/include/boost/optional/optional.hpp +++ b/include/boost/optional/optional.hpp @@ -958,9 +958,40 @@ class optional : public optional_detail::optional_base // Returns a reference to the value if this is initialized, otherwise, // the behaviour is UNDEFINED // No-throw +#ifndef BOOST_NO_CXX11_REF_QUALIFIERS + reference_const_type operator *() const& { return this->get() ; } + reference_type operator *() & { return this->get() ; } + rval_reference_type operator *() && { return boost::move(this->get()) ; } +#else reference_const_type operator *() const { return this->get() ; } reference_type operator *() { return this->get() ; } - +#endif + +#ifndef BOOST_NO_CXX11_REF_QUALIFIERS + reference_const_type value() const& + { + if (this->is_initialized()) + return this->get() ; + else + throw_exception(bad_optional_access("Attempted to access the value of an uninitialized optional object.")); + } + + reference_type value() & + { + if (this->is_initialized()) + return this->get() ; + else + throw_exception(bad_optional_access("Attempted to access the value of an uninitialized optional object.")); + } + + rval_reference_type value() && + { + if (this->is_initialized()) + return boost::move(this->get()) ; + else + throw_exception(bad_optional_access("Attempted to access the value of an uninitialized optional object.")); + } +#else reference_const_type value() const { if (this->is_initialized()) @@ -976,10 +1007,20 @@ class optional : public optional_detail::optional_base else throw_exception(bad_optional_access("Attempted to access the value of an uninitialized optional object.")); } +#endif -#ifndef BOOST_NO_CXX11_RVALUE_REFERENCES +#ifndef BOOST_NO_CXX11_REF_QUALIFIERS template - value_type value_or ( U&& v ) const { return this->is_initialized() ? get() : static_cast(boost::forward(v)); } + value_type value_or ( U&& v ) const& + { return this->is_initialized() ? get() : static_cast(boost::forward(v)); } + + template + value_type value_or ( U&& v ) && + { return this->is_initialized() ? boost::move(get()) : static_cast(boost::forward(v)); } +#elif !defined BOOST_NO_CXX11_RVALUE_REFERENCES + template + value_type value_or ( U&& v ) const + { return this->is_initialized() ? get() : static_cast(boost::forward(v)); } #else template value_type value_or ( U const& v ) const { return this->is_initialized() ? get() : static_cast(v); } diff --git a/test/optional_test_common.cpp b/test/optional_test_common.cpp index 385651e..ba04a6a 100644 --- a/test/optional_test_common.cpp +++ b/test/optional_test_common.cpp @@ -37,7 +37,7 @@ void assertion_failed (char const * expr, char const * func, char const * file, using boost::optional ; -template inline void unused_variable ( T ) {} +template inline void unused_variable ( const T& ) {} #ifdef BOOST_NO_ARGUMENT_DEPENDENT_LOOKUP using boost::swap ; diff --git a/test/optional_test_value_access.cpp b/test/optional_test_value_access.cpp index bd3ea9e..506278f 100644 --- a/test/optional_test_value_access.cpp +++ b/test/optional_test_value_access.cpp @@ -128,6 +128,35 @@ void test_function_value_or() BOOST_CHECK(FatToIntConverter::conversions == 1); } +#ifndef BOOST_NO_CXX11_REF_QUALIFIERS +struct MoveOnly +{ + explicit MoveOnly(int){} + MoveOnly(MoveOnly &&){} + void operator=(MoveOnly &&); +private: + MoveOnly(MoveOnly const&); + void operator=(MoveOnly const&); +}; + +optional makeMoveOnly() +{ + return MoveOnly(1); +} + +// compile-time test +void test_move_only_getters() +{ + MoveOnly m1 = *makeMoveOnly(); + MoveOnly m2 = makeMoveOnly().value(); + MoveOnly m3 = makeMoveOnly().value_or(MoveOnly(1)); + unused_variable(m1); + unused_variable(m2); + unused_variable(m3); +} + +#endif + int test_main( int, char* [] ) { try From 3dd614fd91c8ff4efb7bb14a39ede8d703b5dd4a Mon Sep 17 00:00:00 2001 From: Andrzej Krzemienski Date: Wed, 4 Jun 2014 18:13:06 +0200 Subject: [PATCH 7/9] Reorganized docs. Minor code fix wrt opt refs --- doc/00_optional.qbk | 30 +- doc/{01_tutorial.qbk => 01_quick_start.qbk} | 37 +- doc/05_examples.qbk | 102 - doc/11_special_cases.qbk | 258 --- doc/{02_discussion.qbk => 12_motivation.qbk} | 4 +- ...{03_development.qbk => 13_development.qbk} | 2 +- ...erences.qbk => 14_optional_references.qbk} | 0 doc/15_in_place_factories.qbk | 139 ++ doc/16_optional_bool.qbk | 52 + doc/17_exception_safety.qbk | 57 + doc/18_type_requirements.qbk | 10 + doc/{04_reference.qbk => 20_reference.qbk} | 108 +- doc/Jamfile.v2 | 3 +- .../a_note_about_optional_bool_.html | 6 +- doc/html/boost_optional/acknowledgments.html | 6 +- .../dependencies_and_portability.html | 72 +- .../optional_reference_binding.html | 100 + .../boost_optional/detailed_semantics.html | 227 +- doc/html/boost_optional/development.html | 6 +- doc/html/boost_optional/discussion.html | 6 +- .../boost_optional/in_place_factories.html | 6 +- .../boost_optional/optional_references.html | 8 +- doc/html/boost_optional/quick_start.html | 261 +++ ...sing_unnecessary_default_construction.html | 75 + .../optional_automatic_variables.html | 75 + .../quick_start/optional_data_members.html | 92 + .../quick_start/optional_return_values.html | 135 ++ .../reference/detailed_semantics.html | 1963 +++++++++++++++++ .../boost_optional/reference/synopsis.html | 174 ++ doc/html/boost_optional/synopsis.html | 19 +- doc/html/boost_optional/tutorial.html | 630 ++++-- .../tutorial/a_note_about_optional_bool_.html | 108 + .../tutorial/design_overview.html | 423 ++++ .../tutorial/exception_safety_guarantees.html | 175 ++ .../tutorial/in_place_factories.html | 197 ++ .../boost_optional/tutorial/motivation.html | 129 ++ .../tutorial/optional_references.html | 115 + ...for_assignment_of_optional_references.html | 149 ++ .../tutorial/type_requirements.html | 61 + .../boost_optional/type_requirements.html | 2 +- doc/html/index.html | 133 +- doc/html/optional/introduction.html | 82 + doc/html/optional/introduction/problem.html | 54 + doc/html/optional/introduction/solution.html | 58 + doc/html/optional/reference.html | 48 + doc/html/optional/tutorial.html | 58 + include/boost/optional/optional.hpp | 8 +- 47 files changed, 5607 insertions(+), 856 deletions(-) rename doc/{01_tutorial.qbk => 01_quick_start.qbk} (81%) delete mode 100644 doc/05_examples.qbk delete mode 100644 doc/11_special_cases.qbk rename doc/{02_discussion.qbk => 12_motivation.qbk} (99%) rename doc/{03_development.qbk => 13_development.qbk} (99%) rename doc/{10_optional_references.qbk => 14_optional_references.qbk} (100%) create mode 100644 doc/15_in_place_factories.qbk create mode 100644 doc/16_optional_bool.qbk create mode 100644 doc/17_exception_safety.qbk create mode 100644 doc/18_type_requirements.qbk rename doc/{04_reference.qbk => 20_reference.qbk} (92%) create mode 100644 doc/html/boost_optional/dependencies_and_portability/optional_reference_binding.html create mode 100644 doc/html/boost_optional/quick_start.html create mode 100644 doc/html/boost_optional/quick_start/bypassing_unnecessary_default_construction.html create mode 100644 doc/html/boost_optional/quick_start/optional_automatic_variables.html create mode 100644 doc/html/boost_optional/quick_start/optional_data_members.html create mode 100644 doc/html/boost_optional/quick_start/optional_return_values.html create mode 100644 doc/html/boost_optional/reference/detailed_semantics.html create mode 100644 doc/html/boost_optional/reference/synopsis.html create mode 100644 doc/html/boost_optional/tutorial/a_note_about_optional_bool_.html create mode 100644 doc/html/boost_optional/tutorial/design_overview.html create mode 100644 doc/html/boost_optional/tutorial/exception_safety_guarantees.html create mode 100644 doc/html/boost_optional/tutorial/in_place_factories.html create mode 100644 doc/html/boost_optional/tutorial/motivation.html create mode 100644 doc/html/boost_optional/tutorial/optional_references.html create mode 100644 doc/html/boost_optional/tutorial/rebinding_semantics_for_assignment_of_optional_references.html create mode 100644 doc/html/boost_optional/tutorial/type_requirements.html create mode 100644 doc/html/optional/introduction.html create mode 100644 doc/html/optional/introduction/problem.html create mode 100644 doc/html/optional/introduction/solution.html create mode 100644 doc/html/optional/reference.html create mode 100644 doc/html/optional/tutorial.html diff --git a/doc/00_optional.qbk b/doc/00_optional.qbk index abf5fd7..7a63714 100644 --- a/doc/00_optional.qbk +++ b/doc/00_optional.qbk @@ -45,14 +45,13 @@ Distributed under the Boost Software License, Version 1.0. [def __GO_TO__ [$images/callouts/R.png]] -[section Introduction] +[heading Introduction] 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. -[section Problem] +[heading Problem] Suppose we want to read a parameter form 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 different. Also suppose that any possible value of type `int` is a valid value for `"MaxValue"`, so we cannot jut use `-1` to represent the absence of the parameter in the config file. -[endsect] -[section Solution] +[heading Solution] This is how you solve it with `boost::optional`: @@ -68,16 +67,21 @@ This is how you solve it with `boost::optional`: runWithNoMax(); } -[endsect] -[endsect] -[include 01_tutorial.qbk] -[include 02_discussion.qbk] -[include 03_development.qbk] -[include 04_reference.qbk] -[include 05_examples.qbk] -[include 10_optional_references.qbk] -[include 11_special_cases.qbk] + +[include 01_quick_start.qbk] +[section Tutorial] +[include 12_motivation.qbk] +[include 13_development.qbk] +[include 14_optional_references.qbk] +[include 15_in_place_factories.qbk] +[include 16_optional_bool.qbk] +[include 17_exception_safety.qbk] +[include 18_type_requirements.qbk] +[endsect] +[section Reference] +[include 20_reference.qbk] +[endsect] [include 90_dependencies.qbk] [include 91_acknowledgments.qbk] diff --git a/doc/01_tutorial.qbk b/doc/01_quick_start.qbk similarity index 81% rename from doc/01_tutorial.qbk rename to doc/01_quick_start.qbk index cf8be16..03f6eee 100644 --- a/doc/01_tutorial.qbk +++ b/doc/01_quick_start.qbk @@ -10,9 +10,9 @@ ] -[section Tutorial] +[section Quick Start] -[section Optional return values] +[heading Optional return values] 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: @@ -62,10 +62,28 @@ This uses the `atoi`-like approach to conversions: if `text` does not represent Observe the two return statements. `return i` uses the converting constructor that can create `optional` 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. +[/endsect] -[endsect] +[heading Optional automatic variables] + +We could write function `convert` in a slightly different manner, so that it has a single `return`-statement: + + boost::optionl convert(const std::string& text) + { + boost::optionl ans; + std::stringstream s(text); + int i; + if ((s >> i) && s.get() == std::char_traits::eof()) + ans = i; + + return ans; + } + +The default constructor of `optional` creates an unitialized optional object. Unlike with `int`s you cannot have an `optional` in an indeterminate state. Its state is always well defined. Instruction `ans = i` initializes the optional object. It uses the assignment from `int`. In general, for `optional`, when an assignment from `T` is invoked, it can do two things. If the optional object is not initialized our case here), it initializes it with `T`'s copy constructor. If the optional object is already initialized, it assigns the new value to it using `T`'s copy assignment. +[/endsect] + +[heading Optional data members] -[section Optional data members] 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 @@ -86,11 +104,12 @@ Suppose we want to implement a ['lazy load] optimization. This is because we do `optional`'s default constructor creates an uninitialized optional. No call to `Resource`'s default constructor is attempted. `Resource` doesn't have to be __SGI_DEFAULT_CONSTRUCTIBLE__. 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 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 [link boost_optional.in_place_factories In-Place Factories].] +[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 [link boost_optional.tutorial.in_place_factories In-Place Factories].] -[endsect] +[/endsect] + +[heading Bypassing unnecessary default construction] -[section Bypassing unnecessary default construction] 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 getPeriod(); @@ -100,13 +119,13 @@ In other place we want to use the result of `getPeriod`, but want the two dates 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 initial invented 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: +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 begin, end; boost::tie(begin, end) = getPeriod(); It works because inside `boost::tie` a move-assignment from `T` is invoked on `optional`, which internally calls a move-constructor of `T`. -[endsect] +[/endsect] [endsect] diff --git a/doc/05_examples.qbk b/doc/05_examples.qbk deleted file mode 100644 index 00dbd99..0000000 --- a/doc/05_examples.qbk +++ /dev/null @@ -1,102 +0,0 @@ -[/ - Boost.Optional - - Copyright (c) 2003-2007 Fernando Luis Cacciola Carballal - - 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) -] - - -[section Examples] - -[section Optional return values] - - optional get_async_input() - { - if ( !queue.empty() ) - return optional(queue.top()); - else return optional(); // uninitialized - } - - void receive_async_message() - { - optional rcv ; - // The safe boolean conversion from 'rcv' is used here. - while ( (rcv = get_async_input()) && !timeout() ) - output(*rcv); - } - -[endsect] - -[section Optional local variables] - - optional 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!"); - -[endsect] - -[section Optional data members] - - 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 m_clipping_rect ; - - }; - -[endsect] - -[section Bypassing expensive unnecessary default construction] - - class ExpensiveCtor { ... } ; - class Fred - { - Fred() : mLargeVector(10000) {} - - std::vector< optional > mLargeVector ; - } ; - -[endsect] - -[endsect] - - diff --git a/doc/11_special_cases.qbk b/doc/11_special_cases.qbk deleted file mode 100644 index 110ef78..0000000 --- a/doc/11_special_cases.qbk +++ /dev/null @@ -1,258 +0,0 @@ - -[section In-Place Factories] - -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 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(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 - InPlaceFactoryN in_place ( A0 const& a0, ..., AN const& aN) ; - - template - TypedInPlaceFactoryN 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 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__ - -[endsect] - -[section A note about optional] - -`optional` 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`. -It should be carefully considered if an `optional` 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` - can lead to subtle errors due to the implicit `bool` conversion: - - void foo ( bool v ) ; - void bar() - { - optional 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 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)); -[endsect] - -[section Exception Safety Guarantees] - -This library assumes that `T`'s destructor does not throw exceptions. If it does, the behaviour of many operations on `optional` is undefined. - -The following mutating operations never throw exceptions: - -* `optional::operator= ( none_t ) noexcept` -* `optional::reset() noexcept` - -In addition, the following constructors and the destructor never throw exceptions: - -* `optional::optional() noexcept` -* `optional::optional( none_t ) noexcept` - - -Regarding the following assignment functions: - -* `optional::operator= ( optional const& )` -* `optional::operator= ( T const& )` -* `template optional::operator= ( optional const& )` -* `template optional::operator= ( InPlaceFactory const& )` -* `template optional::operator= ( TypedInPlaceFactory const& ) ` -* `optional::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`'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`'s assignment also never throws. - -Unless `T`'s constructor or assignment throws, assignments to `optional` do not throw anything else on its own. A throw during assignment never changes the initialization state of any optional object involved: - - - optional opt1(val1); - optional 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`. - -[heading 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` never throws. similarly, if both `T`'s `swap` and move constructor offer strong guarantee, `swap` on `optional` 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 acheive 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 -[endsect] - -[section Type requirements] - -At the very minimum for `optional` 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` 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` is also `Copyable` and can be easily initialized from an lvalue of type `T`. - -`T` [_is not] required to be __SGI_DEFAULT_CONSTRUCTIBLE__. - -[endsect] - - diff --git a/doc/02_discussion.qbk b/doc/12_motivation.qbk similarity index 99% rename from doc/02_discussion.qbk rename to doc/12_motivation.qbk index ee69444..fe5b6da 100644 --- a/doc/02_discussion.qbk +++ b/doc/12_motivation.qbk @@ -9,7 +9,7 @@ http://www.boost.org/LICENSE_1_0.txt) ] -[section Discussion] +[section Motivation] Consider these functions which should return a value but which might not have a value to return: @@ -77,4 +77,4 @@ without ever checking if it has a valid value. Clearly, we need a better idiom. -[endsect] \ No newline at end of file +[endsect] diff --git a/doc/03_development.qbk b/doc/13_development.qbk similarity index 99% rename from doc/03_development.qbk rename to doc/13_development.qbk index bb89134..d2f1b1f 100644 --- a/doc/03_development.qbk +++ b/doc/13_development.qbk @@ -8,7 +8,7 @@ http://www.boost.org/LICENSE_1_0.txt) ] -[section Development] +[section Design Overview] [section The models] diff --git a/doc/10_optional_references.qbk b/doc/14_optional_references.qbk similarity index 100% rename from doc/10_optional_references.qbk rename to doc/14_optional_references.qbk diff --git a/doc/15_in_place_factories.qbk b/doc/15_in_place_factories.qbk new file mode 100644 index 0000000..d9df24d --- /dev/null +++ b/doc/15_in_place_factories.qbk @@ -0,0 +1,139 @@ + +[section In-Place Factories] + +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 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(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 + InPlaceFactoryN in_place ( A0 const& a0, ..., AN const& aN) ; + + template + TypedInPlaceFactoryN 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 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__ + +[endsect] diff --git a/doc/16_optional_bool.qbk b/doc/16_optional_bool.qbk new file mode 100644 index 0000000..6f3664f --- /dev/null +++ b/doc/16_optional_bool.qbk @@ -0,0 +1,52 @@ + +[section A note about optional] + +`optional` 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`. +It should be carefully considered if an `optional` 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` + can lead to subtle errors due to the implicit `bool` conversion: + + void foo ( bool v ) ; + void bar() + { + optional 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 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)); +[endsect] diff --git a/doc/17_exception_safety.qbk b/doc/17_exception_safety.qbk new file mode 100644 index 0000000..331104b --- /dev/null +++ b/doc/17_exception_safety.qbk @@ -0,0 +1,57 @@ + +[section Exception Safety Guarantees] + +This library assumes that `T`'s destructor does not throw exceptions. If it does, the behaviour of many operations on `optional` is undefined. + +The following mutating operations never throw exceptions: + +* `optional::operator= ( none_t ) noexcept` +* `optional::reset() noexcept` + +In addition, the following constructors and the destructor never throw exceptions: + +* `optional::optional() noexcept` +* `optional::optional( none_t ) noexcept` + + +Regarding the following assignment functions: + +* `optional::operator= ( optional const& )` +* `optional::operator= ( T const& )` +* `template optional::operator= ( optional const& )` +* `template optional::operator= ( InPlaceFactory const& )` +* `template optional::operator= ( TypedInPlaceFactory const& ) ` +* `optional::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`'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`'s assignment also never throws. + +Unless `T`'s constructor or assignment throws, assignments to `optional` do not throw anything else on its own. A throw during assignment never changes the initialization state of any optional object involved: + + + optional opt1(val1); + optional 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`. + +[heading 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` never throws. similarly, if both `T`'s `swap` and move constructor offer strong guarantee, `swap` on `optional` 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 acheive 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 +[endsect] + + diff --git a/doc/18_type_requirements.qbk b/doc/18_type_requirements.qbk new file mode 100644 index 0000000..b8fd405 --- /dev/null +++ b/doc/18_type_requirements.qbk @@ -0,0 +1,10 @@ + +[section Type requirements] + +At the very minimum for `optional` 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` 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` is also `Copyable` and can be easily initialized from an lvalue of type `T`. + +`T` [_is not] required to be __SGI_DEFAULT_CONSTRUCTIBLE__. + +[endsect] diff --git a/doc/04_reference.qbk b/doc/20_reference.qbk similarity index 92% rename from doc/04_reference.qbk rename to doc/20_reference.qbk index fbeb821..966f8ec 100644 --- a/doc/04_reference.qbk +++ b/doc/20_reference.qbk @@ -71,13 +71,16 @@ T const* operator ->() const ; ``[link reference_optional_operator_arrow __GO_TO__]`` T* operator ->() ; ``[link reference_optional_operator_arrow __GO_TO__]`` - T const& operator *() const ; ``[link reference_optional_get __GO_TO__]`` - T& operator *() ; ``[link reference_optional_get __GO_TO__]`` + T const& operator *() const& ; ``[link reference_optional_operator_asterisk __GO_TO__]`` + T& operator *() &; ``[link reference_optional_operator_asterisk __GO_TO__]`` + T&& operator *() &&; ``[link reference_optional_operator_asterisk __GO_TO__]`` - T const& value() const ; ``[link reference_optional_value __GO_TO__]`` - T& value() ; ``[link reference_optional_value __GO_TO__]`` + T const& value() const& ; ``[link reference_optional_value __GO_TO__]`` + T& value() & ; ``[link reference_optional_value __GO_TO__]`` + T&& value() && ; ``[link reference_optional_value __GO_TO__]`` - template T value_or( U && v ) const ; ``[link reference_optional_value_or __GO_TO__]`` + template T value_or( U && v ) const& ; ``[link reference_optional_value_or __GO_TO__]`` + template T value_or( U && v ) && ; ``[link reference_optional_value_or __GO_TO__]`` T const* get_ptr() const ; ``[link reference_optional_get_ptr __GO_TO__]`` T* get_ptr() ; ``[link reference_optional_get_ptr __GO_TO__]`` @@ -467,7 +470,7 @@ 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 [link boost_optional.in_place_factories In-Place Factories] +* [*Notes:] See [link boost_optional.tutorial.in_place_factories 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. @@ -530,7 +533,7 @@ __SPACE__ * [*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 [link boost_optional.rebinding_semantics_for_assignment_of_optional_references here] for details on this behavior. +See [link boost_optional.tutorial.rebinding_semantics_for_assignment_of_optional_references here] for details on this behavior. * [*Example:] `` int a = 1 ; @@ -625,7 +628,7 @@ __SPACE__ 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 [link boost_optional.rebinding_semantics_for_assignment_of_optional_references here] for details on this behavior. +the new object. See [link boost_optional.tutorial.rebinding_semantics_for_assignment_of_optional_references here] for details on this behavior. * [*Example:] `` int a = 1 ; @@ -773,7 +776,7 @@ 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 [link boost_optional.in_place_factories In-Place Factories] +* [*Notes:] See [link boost_optional.tutorial.in_place_factories 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]. @@ -790,14 +793,12 @@ __SPACE__ [#reference_optional_reset] [: `void optional::reset() noexcept ;`] -* [*Deprecated:] Same as `operator=( detail::none_t );` +* [*Deprecated:] Same as `operator=( none_t );` __SPACE__ [#reference_optional_get] -[: `T const& optional::operator*() const ;`] -[: `T& optional::operator*();`] [: `T const& optional::get() const ;`] [: `T& optional::get() ;`] @@ -808,6 +809,32 @@ __SPACE__ * [*Returns:] A reference to the contained value * [*Throws:] Nothing. * [*Notes:] The requirement is asserted via `BOOST_ASSERT()`. + +__SPACE__ + +[: `T const& optional::get() const ;`] +[: `T& optional::get() ;`] + +[: `inline T const& get ( optional const& ) ;`] +[: `inline T& get ( optional &) ;`] + +* [*Requires: ] `*this` is initialized +* [*Returns:] [_The] reference contained. +* [*Throws:] Nothing. +* [*Notes:] The requirement is asserted via `BOOST_ASSERT()`. + +__SPACE__ + +[#reference_optional_operator_asterisk] + +[: `T const& optional::operator*() const& ;`] +[: `T& optional::operator*() &;`] +[: `T&& optional::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 ; @@ -821,14 +848,36 @@ assert ( *opt == w ) ; __SPACE__ +[: `T const& optional::operator*() const& ;`] +[: `T & optional::operator*() & ;`] +[: `T & optional::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 opt ( vref ); +T const& vref2 = *opt; +assert ( vref2 == v ) ; +++ v ; +assert ( *opt == v ) ; +`` + +__SPACE__ [#reference_optional_value] -[: `T const& optional::value() const ;`] -[: `T& optional::value();`] +[: `T const& optional::value() const& ;`] +[: `T& optional::value() & ;`] +[: `T&& optional::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 ; @@ -848,12 +897,13 @@ __SPACE__ [#reference_optional_value_or] -[: `template T optional::value_or(U && v) const ;`] +[: `template T optional::value_or(U && v) const& ;`] +[: `template T optional::value_or(U && v) && ;`] * [*Requires:] `T` is CopyConstructible. -* [*Returns:] `bool(*this) ? **this : static_cast(forward(v))`. +* [*Returns:] First overload: `bool(*this) ? **this : static_cast(forward(v))`. second overload: `bool(*this) ? std::move(**this) : static_cast(forward(v))`. * [*Throws:] Any exception thrown by the selected constructor of `T`. -* [*Notes:] On compilers without rvalue reference support the type of `v` becomes `U const&`. +* [*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__ @@ -881,30 +931,6 @@ assert ( u == v ) ; assert ( u != z ) ; `` -__SPACE__ - -[: `T const& optional::operator*() const ;`] -[: `T & optional::operator*();`] -[: `T const& optional::get() const ;`] -[: `T& optional::get() ;`] - -[: `inline T const& get ( optional const& ) ;`] -[: `inline T& get ( optional &) ;`] - -* [*Requires: ] `*this` is initialized -* [*Returns:] [_The] reference contained. -* [*Throws:] Nothing. -* [*Notes:] The requirement is asserted via `BOOST_ASSERT()`. -* [*Example:] -`` -T v ; -T& vref = v ; -optional opt ( vref ); -T const& vref2 = *opt; -assert ( vref2 == v ) ; -++ v ; -assert ( *opt == v ) ; -`` __SPACE__ diff --git a/doc/Jamfile.v2 b/doc/Jamfile.v2 index 5014bb2..2a8b727 100644 --- a/doc/Jamfile.v2 +++ b/doc/Jamfile.v2 @@ -27,7 +27,8 @@ boostbook standalone boost.root=../../../.. toc.max.depth=2 toc.section.depth=2 - chunk.section.depth=1 + chunk.first.sections=2 + chunk.section.depth=2 pdf:img.src.path=$(images)/ pdf:boost.url.prefix=http://www.boost.org/doc/libs/release/libs/optional/doc/html ; diff --git a/doc/html/boost_optional/a_note_about_optional_bool_.html b/doc/html/boost_optional/a_note_about_optional_bool_.html index 169813c..64f37f6 100644 --- a/doc/html/boost_optional/a_note_about_optional_bool_.html +++ b/doc/html/boost_optional/a_note_about_optional_bool_.html @@ -6,7 +6,7 @@ - + @@ -20,7 +20,7 @@
-PrevUpHomeNext +PrevUpHomeNext

@@ -102,7 +102,7 @@
-PrevUpHomeNext +PrevUpHomeNext
diff --git a/doc/html/boost_optional/acknowledgments.html b/doc/html/boost_optional/acknowledgments.html index 58c4f2d..19d24d9 100644 --- a/doc/html/boost_optional/acknowledgments.html +++ b/doc/html/boost_optional/acknowledgments.html @@ -6,7 +6,7 @@ - + @@ -19,7 +19,7 @@
-PrevUpHome +PrevUpHome

@@ -119,7 +119,7 @@
-PrevUpHome +PrevUpHome
diff --git a/doc/html/boost_optional/dependencies_and_portability.html b/doc/html/boost_optional/dependencies_and_portability.html index 5049104..d9f62c1 100644 --- a/doc/html/boost_optional/dependencies_and_portability.html +++ b/doc/html/boost_optional/dependencies_and_portability.html @@ -6,8 +6,8 @@ - - + + @@ -20,81 +20,19 @@
-PrevUpHomeNext +PrevUpHomeNext
-
Optional +
Optional Reference Binding

The implementation uses type_traits/alignment_of.hpp and type_traits/type_with_alignment.hpp

-
-
-

- 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;
-}
-
-
@@ -106,7 +44,7 @@
-PrevUpHomeNext +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 new file mode 100644 index 0000000..70316bc --- /dev/null +++ b/doc/html/boost_optional/dependencies_and_portability/optional_reference_binding.html @@ -0,0 +1,100 @@ + + + +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 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 index 8374254..b93515f 100644 --- a/doc/html/boost_optional/detailed_semantics.html +++ b/doc/html/boost_optional/detailed_semantics.html @@ -7,7 +7,7 @@ - + @@ -20,7 +20,7 @@
-PrevUpHomeNext +PrevUpHomeNext

@@ -606,7 +606,7 @@ constructor called by the factory throws.
  • - Notes: See In-Place + Notes: See In-Place Factories
  • @@ -712,7 +712,7 @@
  • Notes: If *this was initialized, it is rebound - to the new object. See here + to the new object. See here for details on this behavior.
  • @@ -872,7 +872,7 @@
  • Notes: If *this was initialized and so is *rhs, *this - is rebound to the new object. See here + is rebound to the new object. See here for details on this behavior.
  • @@ -1147,7 +1147,7 @@ constructor called by the factory throws.
  • - Notes: See In-Place + Notes: See In-Place Factories
  • @@ -1177,20 +1177,12 @@ void optional<T>::reset() noexcept ;

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

    space

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

    -

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

    -

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

    @@ -1224,6 +1216,76 @@ 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 ;
@@ -1236,15 +1298,63 @@
    +

    + 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 const& optional<T>::value() const& ;

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

    +

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

    • @@ -1257,6 +1367,12 @@ 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 ;
@@ -1276,7 +1392,11 @@

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

    +

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

    • @@ -1284,17 +1404,22 @@ is CopyConstructible.
    • - Returns: bool(*this) - ? **this : static_cast<T>(forward<U>(v)). + 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 without rvalue reference - support the type of v becomes - U const&. + 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&.

    @@ -1348,60 +1473,6 @@

    -

    - space -

    -

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

    -

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

    -

    - 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(). -
      • -
    • - Example: -
      T v ;
-T& vref = v ;
-optional<T&> opt ( vref );
-T const& vref2 = *opt;
-assert ( vref2 == v ) ;
-++ v ;
-assert ( *opt == v ) ;
-
      -
      • -

    space

    @@ -1898,7 +1969,7 @@
    -PrevUpHomeNext +PrevUpHomeNext
    diff --git a/doc/html/boost_optional/development.html b/doc/html/boost_optional/development.html index 1ff950f..70bc6e4 100644 --- a/doc/html/boost_optional/development.html +++ b/doc/html/boost_optional/development.html @@ -6,7 +6,7 @@ - + @@ -20,7 +20,7 @@
    -PrevUpHomeNext +PrevUpHomeNext

    @@ -406,7 +406,7 @@
    -PrevUpHomeNext +PrevUpHomeNext
    diff --git a/doc/html/boost_optional/discussion.html b/doc/html/boost_optional/discussion.html index 5eb1c93..d17a70e 100644 --- a/doc/html/boost_optional/discussion.html +++ b/doc/html/boost_optional/discussion.html @@ -6,7 +6,7 @@ - + @@ -20,7 +20,7 @@
    -PrevUpHomeNext +PrevUpHomeNext

    @@ -122,7 +122,7 @@
    -PrevUpHomeNext +PrevUpHomeNext
    diff --git a/doc/html/boost_optional/in_place_factories.html b/doc/html/boost_optional/in_place_factories.html index 4bb6fe7..1cc1e05 100644 --- a/doc/html/boost_optional/in_place_factories.html +++ b/doc/html/boost_optional/in_place_factories.html @@ -6,7 +6,7 @@ - + @@ -20,7 +20,7 @@
    -PrevUpHomeNext +PrevUpHomeNext

    @@ -190,7 +190,7 @@
    -PrevUpHomeNext +PrevUpHomeNext
    diff --git a/doc/html/boost_optional/optional_references.html b/doc/html/boost_optional/optional_references.html index 2b36c3e..4da272e 100644 --- a/doc/html/boost_optional/optional_references.html +++ b/doc/html/boost_optional/optional_references.html @@ -6,7 +6,7 @@ - + @@ -20,7 +20,7 @@
    -PrevUpHomeNext +PrevUpHomeNext

    @@ -77,7 +77,7 @@ 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 + temporary and bind to it. For more details see Dependencies and Portability section.

    @@ -108,7 +108,7 @@
    -PrevUpHomeNext +PrevUpHomeNext
    diff --git a/doc/html/boost_optional/quick_start.html b/doc/html/boost_optional/quick_start.html new file mode 100644 index 0000000..dbe86fc --- /dev/null +++ b/doc/html/boost_optional/quick_start.html @@ -0,0 +1,261 @@ + + + +Quick Start + + + + + + + + + + + + + + + +
    Boost C++ LibrariesHomeLibrariesPeopleFAQMore
    +
    +
    +PrevUpHomeNext +
    +
    +
    +

    + + Optional + return values +

    +

    + 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::optionl<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::optionl<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::optionl<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 non-existent 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::optionl<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. +

    +

    + + Optional + automatic variables +

    +

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

    +
    boost::optionl<int> convert(const std::string& text)
+{
+  boost::optionl<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 unitialized 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 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 it with T's + copy constructor. If the optional object is already initialized, it assigns + the new value to it using T's + copy assignment. +

    +

    + + Optional + data members +

    +

    + 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
+{
+  boost::optional<Resource> resource_;
+
+public:
+  Widget() {}
+
+  Resource& getResource() // 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 Default + Constructible. 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. +

    +

    + + Bypassing + unnecessary default construction +

    +

    + 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 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 new file mode 100644 index 0000000..33ac25d --- /dev/null +++ b/doc/html/boost_optional/quick_start/bypassing_unnecessary_default_construction.html @@ -0,0 +1,75 @@ + + + +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 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 new file mode 100644 index 0000000..34c9ac7 --- /dev/null +++ b/doc/html/boost_optional/quick_start/optional_automatic_variables.html @@ -0,0 +1,75 @@ + + + +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::optionl<int> convert(const std::string& text)
+{
+  boost::optionl<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 unitialized 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 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 it with 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 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 new file mode 100644 index 0000000..00f5457 --- /dev/null +++ b/doc/html/boost_optional/quick_start/optional_data_members.html @@ -0,0 +1,92 @@ + + + +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
+{
+  boost::optional<Resource> resource_;
+
+public:
+  Widget() {}
+
+  Resource& getResource() // 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 Default + Constructible. 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 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 new file mode 100644 index 0000000..9ad85ef --- /dev/null +++ b/doc/html/boost_optional/quick_start/optional_return_values.html @@ -0,0 +1,135 @@ + + + +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::optionl<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::optionl<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::optionl<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 non-existent + 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::optionl<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/reference/detailed_semantics.html b/doc/html/boost_optional/reference/detailed_semantics.html new file mode 100644 index 0000000..c5e5d9e --- /dev/null +++ b/doc/html/boost_optional/reference/detailed_semantics.html @@ -0,0 +1,1963 @@ + + + +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::uniqye_ptr<T>(new T(2)) );
+assert ( **init == T(2) ) ;
+
+optional<std::unique_ptr<T>> init2 ( std::move(init) ) ;
+assert ( init );
+assert ( *init == nullptr );
+assert ( init2 );
+assert ( **init2 == T(2) ) ;
+
      +
      • +
    +

    + 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/reference/synopsis.html b/doc/html/boost_optional/reference/synopsis.html new file mode 100644 index 0000000..99adcfd --- /dev/null +++ b/doc/html/boost_optional/reference/synopsis.html @@ -0,0 +1,174 @@ + + + +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/synopsis.html b/doc/html/boost_optional/synopsis.html index b350ded..0de90e7 100644 --- a/doc/html/boost_optional/synopsis.html +++ b/doc/html/boost_optional/synopsis.html @@ -6,7 +6,7 @@ - + @@ -20,7 +20,7 @@
    -PrevUpHomeNext +PrevUpHomeNext

    @@ -86,13 +86,16 @@ T const* operator ->() const ; R T* operator ->() ; 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 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 ) const& ; R + template<class U> T value_or( U && v ) && ; R T const* get_ptr() const ; R T* get_ptr() ; R @@ -165,7 +168,7 @@
    -PrevUpHomeNext +PrevUpHomeNext
    diff --git a/doc/html/boost_optional/tutorial.html b/doc/html/boost_optional/tutorial.html index c1b6173..8f033e8 100644 --- a/doc/html/boost_optional/tutorial.html +++ b/doc/html/boost_optional/tutorial.html @@ -6,8 +6,8 @@ - - + + @@ -20,207 +20,491 @@
    -PrevUpHomeNext +PrevUpHomeNext
    -
    Optional - return values
    -
    Optional - data members
    -
    Bypassing - unnecessary default construction
    +
    Motivation
    +
    Design Overview

    - 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: + Consider these functions which should return a value but which might not + have a value to return:

    -
    #include <boost/optional.hpp>
-boost::optionl<int> convert(const std::string& text);
+
      
+
    • 
+            (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();
 
    
 
    
-        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:
+        These functions use a consistent interface for dealing with possibly nonexistent
+        results:
       
    
-
    const std::string& text = /*... */;
-boost::optionl<int> oi = convert(text); // move-construct
-if (oi)                                 // contextual conversion to bool
-  int i = *oi;                          // operator*
+
    std::pair<point,bool> p = poly.get_any_point_effectively_inside();
+if ( p.second )
+    flood_fill(p.first);
 
    
 
    
-        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:
+        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.
       
    
-
    if (boost::optionl<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 non-existent
-        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::optionl<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.
+        Clearly, we need a better idiom.
    +
    +
    The + models
    +
    The + semantics
    +
    The + Interface
    +
    +
    +

    - 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
-{
-  boost::optional<Resource> resource_;
-
-public:
-  Widget() {}
-
-  Resource& getResource() // not thread-safe
-  {
-    if (resource_ == boost::none)
-        resource_.emplace("resource", "arguments");
-
-    return *resource_;
-  }
-};
-
    + 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. +

    - optional's default constructor - creates an uninitialized optional. No call to Resource's - default constructor is attempted. Resource - doesn't have to be Default - Constructible. 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. -

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

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

    [Note]Note[Warning]Warning

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

    +

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

    -
    -
    -

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

    @@ -233,7 +517,7 @@
    -PrevUpHomeNext +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 new file mode 100644 index 0000000..706bf49 --- /dev/null +++ b/doc/html/boost_optional/tutorial/a_note_about_optional_bool_.html @@ -0,0 +1,108 @@ + + + +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/tutorial/design_overview.html b/doc/html/boost_optional/tutorial/design_overview.html new file mode 100644 index 0000000..d2493ce --- /dev/null +++ b/doc/html/boost_optional/tutorial/design_overview.html @@ -0,0 +1,423 @@ + + + +Design Overview + + + + + + + + + + + + + + + +
    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 untitialized 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/exception_safety_guarantees.html b/doc/html/boost_optional/tutorial/exception_safety_guarantees.html new file mode 100644 index 0000000..ede593d --- /dev/null +++ b/doc/html/boost_optional/tutorial/exception_safety_guarantees.html @@ -0,0 +1,175 @@ + + + +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 acheive 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/tutorial/in_place_factories.html b/doc/html/boost_optional/tutorial/in_place_factories.html new file mode 100644 index 0000000..3d7500a --- /dev/null +++ b/doc/html/boost_optional/tutorial/in_place_factories.html @@ -0,0 +1,197 @@ + + + +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/tutorial/motivation.html b/doc/html/boost_optional/tutorial/motivation.html new file mode 100644 index 0000000..3b9f43c --- /dev/null +++ b/doc/html/boost_optional/tutorial/motivation.html @@ -0,0 +1,129 @@ + + + +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 new file mode 100644 index 0000000..77d73f5 --- /dev/null +++ b/doc/html/boost_optional/tutorial/optional_references.html @@ -0,0 +1,115 @@ + + + +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 ocurr: +

    +
      +
    • + 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/tutorial/rebinding_semantics_for_assignment_of_optional_references.html b/doc/html/boost_optional/tutorial/rebinding_semantics_for_assignment_of_optional_references.html new file mode 100644 index 0000000..b2bd32d --- /dev/null +++ b/doc/html/boost_optional/tutorial/rebinding_semantics_for_assignment_of_optional_references.html @@ -0,0 +1,149 @@ + + + +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/tutorial/type_requirements.html b/doc/html/boost_optional/tutorial/type_requirements.html new file mode 100644 index 0000000..84959d2 --- /dev/null +++ b/doc/html/boost_optional/tutorial/type_requirements.html @@ -0,0 +1,61 @@ + + + +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/boost_optional/type_requirements.html b/doc/html/boost_optional/type_requirements.html index 8ffd2ea..e1ee777 100644 --- a/doc/html/boost_optional/type_requirements.html +++ b/doc/html/boost_optional/type_requirements.html @@ -34,7 +34,7 @@ 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 + 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. diff --git a/doc/html/index.html b/doc/html/index.html index 4f602c2..3508307 100644 --- a/doc/html/index.html +++ b/doc/html/index.html @@ -5,7 +5,7 @@ - + @@ -17,7 +17,7 @@
    More
    -
    Next
    +
    Next

    @@ -37,94 +37,67 @@

    Table of Contents

    -
    Introduction
    +
    Quick Start
    +
    Tutorial
    -
    Problem
    -
    Solution
    +
    Motivation
    +
    Design Overview
    +
    Optional + references
    +
    Rebinding + semantics for assignment of optional references
    +
    In-Place + Factories
    +
    A + note about optional<bool>
    +
    Exception + Safety Guarantees
    +
    Type requirements
    -
    Tutorial
    +
    Reference
    -
    Optional - return values
    -
    Optional - data members
    -
    Bypassing - unnecessary default construction
    +
    Synopsis
    +
    Detailed + Semantics
    -
    Discussion
    -
    Development
    -
    -
    The models
    -
    The semantics
    -
    The Interface
    -
    -
    Synopsis
    -
    Detailed Semantics
    -
    Examples
    -
    -
    Optional - return values
    -
    Optional - local variables
    -
    Optional - data members
    -
    Bypassing - expensive unnecessary default construction
    -
    -
    Optional references
    -
    Rebinding - semantics for assignment of optional references
    -
    In-Place Factories
    -
    A note about - optional<bool>
    -
    Exception Safety - Guarantees
    -
    Type requirements
    Dependencies and Portability
    -
    Optional +
    Optional Reference Binding
    Acknowledgments
    -
    -
    -
    -
    Problem
    -
    Solution
    -
    +

    + + Introduction +

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

    -
    -
    + 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 form 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 different. Also suppose that any possible - value of type int is a valid - value for "MaxValue", - so we cannot jut use -1 - to represent the absence of the parameter in the config file. -

    -
    -
    -
    + Suppose we want to read a parameter form 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 different. Also suppose that any possible value of type int is a valid value for "MaxValue", + so we cannot jut use -1 + to represent the absence of the parameter in the config file. +

    +

    + + Solution +

    - This is how you solve it with boost::optional: -

    + 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`
@@ -138,13 +111,11 @@
 }
    -
    -

    - +

    Last revised: June 03, 2014 at 14:35:30 GMT

    Last revised: June 04, 2014 at 16:06:37 GMT
    -
    Next
    +
    Next
    diff --git a/doc/html/optional/introduction.html b/doc/html/optional/introduction.html new file mode 100644 index 0000000..8f63804 --- /dev/null +++ b/doc/html/optional/introduction.html @@ -0,0 +1,82 @@ + + + +Introduction + + + + + + + + + + + + + + + +
    Boost C++ LibrariesHomeLibrariesPeopleFAQMore
    +
    +
    +PrevUpHomeNext +
    +
    +
    +

    + 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 form 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 different. Also suppose that any possible value of type + int is a valid value for "MaxValue", so we cannot jut 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();
+}
+
    +
    + + + +
    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/optional/introduction/problem.html b/doc/html/optional/introduction/problem.html new file mode 100644 index 0000000..126a786 --- /dev/null +++ b/doc/html/optional/introduction/problem.html @@ -0,0 +1,54 @@ + + + +Problem + + + + + + + + + + + + + + + +
    Boost C++ LibrariesHomeLibrariesPeopleFAQMore
    +
    +
    +PrevUpHomeNext +
    +
    +
    +

    + Suppose we want to read a parameter form 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 different. Also suppose that any possible + value of type int is a valid + value for "MaxValue", + so we cannot jut use -1 + to represent the absence of the parameter in the config file. +

    +
    + + + +
    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/optional/introduction/solution.html b/doc/html/optional/introduction/solution.html new file mode 100644 index 0000000..01b95ba --- /dev/null +++ b/doc/html/optional/introduction/solution.html @@ -0,0 +1,58 @@ + + + +Solution + + + + + + + + + + + + + + + +
    Boost C++ LibrariesHomeLibrariesPeopleFAQMore
    +
    +
    +PrevUpHomeNext +
    +
    +
    +

    + 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();
+}
+
    +
    + + + +
    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/optional/reference.html b/doc/html/optional/reference.html new file mode 100644 index 0000000..57d96f2 --- /dev/null +++ b/doc/html/optional/reference.html @@ -0,0 +1,48 @@ + + + +Reference + + + + + + + + + + + + + + + +
    Boost C++ LibrariesHomeLibrariesPeopleFAQMore
    +
    +
    +PrevUpHomeNext +
    +
    +
    +
    +
    Synopsis
    +
    Detailed + Semantics
    +
    +
    + + + +
    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/optional/tutorial.html b/doc/html/optional/tutorial.html new file mode 100644 index 0000000..35fd387 --- /dev/null +++ b/doc/html/optional/tutorial.html @@ -0,0 +1,58 @@ + + + +Tutorial + + + + + + + + + + + + + + + +
    Boost C++ LibrariesHomeLibrariesPeopleFAQMore
    +
    +
    +PrevUpHomeNext +
    +
    +
    +
    +
    Motivation
    +
    Design Overview
    +
    Optional + references
    +
    Rebinding + semantics for assignment of optional references
    +
    In-Place + Factories
    +
    A + note about optional<bool>
    +
    Exception + Safety Guarantees
    +
    Type requirements
    +
    +
    + + + +
    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/include/boost/optional/optional.hpp b/include/boost/optional/optional.hpp index b3319b0..6e3b160 100644 --- a/include/boost/optional/optional.hpp +++ b/include/boost/optional/optional.hpp @@ -151,6 +151,7 @@ struct types_when_isnt_ref typedef T & reference_type ; #ifndef BOOST_NO_CXX11_RVALUE_REFERENCES typedef T && rval_reference_type ; + typedef T && reference_type_of_temporary_wrapper; #ifdef BOOST_MOVE_OLD_RVALUE_REF_BINDING_RULES // GCC 4.4 has support for an early draft of rvalue references. The conforming version below // causes warnings about returning references to a temporary. @@ -173,6 +174,7 @@ struct types_when_is_ref typedef raw_type& reference_type ; #ifndef BOOST_NO_CXX11_RVALUE_REFERENCES typedef BOOST_DEDUCED_TYPENAME remove_const::type&& rval_reference_type ; + typedef raw_type& reference_type_of_temporary_wrapper; static reference_type move(reference_type r) { return r; } #endif typedef raw_type* pointer_const_type ; @@ -227,6 +229,7 @@ class optional_base : public optional_tag typedef BOOST_DEDUCED_TYPENAME types::reference_const_type reference_const_type ; #ifndef BOOST_NO_CXX11_RVALUE_REFERENCES typedef BOOST_DEDUCED_TYPENAME types::rval_reference_type rval_reference_type ; + typedef BOOST_DEDUCED_TYPENAME types::reference_type_of_temporary_wrapper reference_type_of_temporary_wrapper ; #endif typedef BOOST_DEDUCED_TYPENAME types::pointer_type pointer_type ; typedef BOOST_DEDUCED_TYPENAME types::pointer_const_type pointer_const_type ; @@ -725,6 +728,7 @@ class optional : public optional_detail::optional_base typedef BOOST_DEDUCED_TYPENAME base::reference_const_type reference_const_type ; #ifndef BOOST_NO_CXX11_RVALUE_REFERENCES typedef BOOST_DEDUCED_TYPENAME base::rval_reference_type rval_reference_type ; + typedef BOOST_DEDUCED_TYPENAME base::reference_type_of_temporary_wrapper reference_type_of_temporary_wrapper ; #endif typedef BOOST_DEDUCED_TYPENAME base::pointer_type pointer_type ; typedef BOOST_DEDUCED_TYPENAME base::pointer_const_type pointer_const_type ; @@ -961,7 +965,7 @@ class optional : public optional_detail::optional_base #ifndef BOOST_NO_CXX11_REF_QUALIFIERS reference_const_type operator *() const& { return this->get() ; } reference_type operator *() & { return this->get() ; } - rval_reference_type operator *() && { return boost::move(this->get()) ; } + reference_type_of_temporary_wrapper operator *() && { return boost::move(this->get()) ; } #else reference_const_type operator *() const { return this->get() ; } reference_type operator *() { return this->get() ; } @@ -984,7 +988,7 @@ class optional : public optional_detail::optional_base throw_exception(bad_optional_access("Attempted to access the value of an uninitialized optional object.")); } - rval_reference_type value() && + reference_type_of_temporary_wrapper value() && { if (this->is_initialized()) return boost::move(this->get()) ; From 402f15e9963d73ed5b1399c7b44967f1d907ddb7 Mon Sep 17 00:00:00 2001 From: Andrzej Krzemienski Date: Wed, 4 Jun 2014 23:04:02 +0200 Subject: [PATCH 8/9] described relops in docs --- doc/01_quick_start.qbk | 14 +++++++++++ doc/html/boost_optional/quick_start.html | 30 ++++++++++++++++++++++++ doc/html/index.html | 2 +- 3 files changed, 45 insertions(+), 1 deletion(-) diff --git a/doc/01_quick_start.qbk b/doc/01_quick_start.qbk index 03f6eee..53a8e67 100644 --- a/doc/01_quick_start.qbk +++ b/doc/01_quick_start.qbk @@ -127,6 +127,20 @@ The second line works already, this is the capability of Boost.Tuple library, bu It works because inside `boost::tie` a move-assignment from `T` is invoked on `optional`, which internally calls a move-constructor of `T`. [/endsect] +[heading Storage in containers] + +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`. You want to make a histogram showing how many times each choice was made. You can use an `std::map`: + + std::map, int> choices; + + for (int i = 0; i < LIMIT; ++i) { + boost::optional choice = readChoice(); + ++choices[choice]; + } + +This works because `optional` 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`. So the set of values that type `optional` can assume is {`boost::none`, -2147483648, -2147483647, ..., -1, 0, 1, ..., 2147483647} (assuming a 32-bit `int`). +[/endsect] + [endsect] diff --git a/doc/html/boost_optional/quick_start.html b/doc/html/boost_optional/quick_start.html index dbe86fc..5434009 100644 --- a/doc/html/boost_optional/quick_start.html +++ b/doc/html/boost_optional/quick_start.html @@ -244,6 +244,36 @@ from T is invoked on optional<T>, which internally calls a move-constructor of T.

    +

    + + Storage + in containers +

    +

    + 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. So the + set of values that type optional<T> + can assume is {boost::none, -2147483648, -2147483647, ..., -1, + 0, 1, ..., 2147483647} (assuming a 32-bit int). +

    diff --git a/doc/html/index.html b/doc/html/index.html index 3508307..0ae3385 100644 --- a/doc/html/index.html +++ b/doc/html/index.html @@ -112,7 +112,7 @@
    - +

    Last revised: June 04, 2014 at 16:06:37 GMT

    Last revised: June 04, 2014 at 21:00:26 GMT
    From dec71d338d0784ede751c3e77a85d69c82b4f6aa Mon Sep 17 00:00:00 2001 From: Andrzej Krzemienski Date: Fri, 6 Jun 2014 00:53:15 +0200 Subject: [PATCH 9/9] Cleaned up docs --- doc/00_optional.qbk | 4 +- doc/01_quick_start.qbk | 20 +- doc/90_dependencies.qbk | 18 +- doc/Jamfile.v2 | 7 +- doc/html/boost_optional/acknowledgments.html | 4 +- .../dependencies_and_portability.html | 53 +++- .../optional_reference_binding.html | 2 +- doc/html/boost_optional/quick_start.html | 287 +++++------------- ...sing_unnecessary_default_construction.html | 8 +- .../optional_automatic_variables.html | 8 +- .../quick_start/optional_data_members.html | 2 +- .../quick_start/storage_in_containers.html | 69 +++++ .../reference/detailed_semantics.html | 8 +- .../tutorial/a_note_about_optional_bool_.html | 2 +- .../tutorial/design_overview.html | 249 +-------------- .../design_overview/the_interface.html | 186 ++++++++++++ .../design_overview/the_semantics.html | 121 ++++++++ .../tutorial/exception_safety_guarantees.html | 2 +- .../tutorial/in_place_factories.html | 2 +- .../tutorial/optional_references.html | 8 +- ...for_assignment_of_optional_references.html | 2 +- .../tutorial/type_requirements.html | 2 +- doc/html/index.html | 89 +++--- doc/html/optional/introduction.html | 82 ----- doc/html/optional/introduction/problem.html | 54 ---- doc/html/optional/introduction/solution.html | 58 ---- doc/html/optional/reference.html | 48 --- doc/html/optional/tutorial.html | 58 ---- 28 files changed, 611 insertions(+), 842 deletions(-) create mode 100644 doc/html/boost_optional/quick_start/storage_in_containers.html create mode 100644 doc/html/boost_optional/tutorial/design_overview/the_interface.html create mode 100644 doc/html/boost_optional/tutorial/design_overview/the_semantics.html delete mode 100644 doc/html/optional/introduction.html delete mode 100644 doc/html/optional/introduction/problem.html delete mode 100644 doc/html/optional/introduction/solution.html delete mode 100644 doc/html/optional/reference.html delete mode 100644 doc/html/optional/tutorial.html diff --git a/doc/00_optional.qbk b/doc/00_optional.qbk index 7a63714..9cceee1 100644 --- a/doc/00_optional.qbk +++ b/doc/00_optional.qbk @@ -45,7 +45,7 @@ Distributed under the Boost Software License, Version 1.0. [def __GO_TO__ [$images/callouts/R.png]] -[heading Introduction] +[section Introduction] 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. [heading Problem] @@ -67,7 +67,7 @@ This is how you solve it with `boost::optional`: runWithNoMax(); } - +[endsect] [include 01_quick_start.qbk] [section Tutorial] diff --git a/doc/01_quick_start.qbk b/doc/01_quick_start.qbk index 53a8e67..2b642df 100644 --- a/doc/01_quick_start.qbk +++ b/doc/01_quick_start.qbk @@ -12,7 +12,7 @@ [section Quick Start] -[heading Optional return values] +[section Optional return values] 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: @@ -62,9 +62,9 @@ This uses the `atoi`-like approach to conversions: if `text` does not represent Observe the two return statements. `return i` uses the converting constructor that can create `optional` 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. -[/endsect] +[endsect] -[heading Optional automatic variables] +[section Optional automatic variables] We could write function `convert` in a slightly different manner, so that it has a single `return`-statement: @@ -80,9 +80,9 @@ We could write function `convert` in a slightly different manner, so that it has } The default constructor of `optional` creates an unitialized optional object. Unlike with `int`s you cannot have an `optional` in an indeterminate state. Its state is always well defined. Instruction `ans = i` initializes the optional object. It uses the assignment from `int`. In general, for `optional`, when an assignment from `T` is invoked, it can do two things. If the optional object is not initialized our case here), it initializes it with `T`'s copy constructor. If the optional object is already initialized, it assigns the new value to it using `T`'s copy assignment. -[/endsect] +[endsect] -[heading Optional data members] +[section Optional data members] 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: @@ -106,9 +106,9 @@ Suppose we want to implement a ['lazy load] optimization. This is because we do [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 [link boost_optional.tutorial.in_place_factories In-Place Factories].] -[/endsect] +[endsect] -[heading Bypassing unnecessary default construction] +[section Bypassing unnecessary default construction] 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`: @@ -125,9 +125,9 @@ The second line works already, this is the capability of Boost.Tuple library, bu boost::tie(begin, end) = getPeriod(); It works because inside `boost::tie` a move-assignment from `T` is invoked on `optional`, which internally calls a move-constructor of `T`. -[/endsect] +[endsect] -[heading Storage in containers] +[section Storage in containers] 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`. You want to make a histogram showing how many times each choice was made. You can use an `std::map`: @@ -139,7 +139,7 @@ Suppose you want to ask users to choose some number (an `int`). One of the valid } This works because `optional` 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`. So the set of values that type `optional` can assume is {`boost::none`, -2147483648, -2147483647, ..., -1, 0, 1, ..., 2147483647} (assuming a 32-bit `int`). -[/endsect] +[endsect] [endsect] diff --git a/doc/90_dependencies.qbk b/doc/90_dependencies.qbk index fce4ca8..cf678dc 100644 --- a/doc/90_dependencies.qbk +++ b/doc/90_dependencies.qbk @@ -11,8 +11,22 @@ [section Dependencies and Portability] -The implementation uses `type_traits/alignment_of.hpp` and -`type_traits/type_with_alignment.hpp` +[section Dependencies] +The implementation uses the following other Boost modules: + +# assert +# config +# core +# detail +# move +# mpl +# static_assert +# throw_exception +# type_traits +# utility + +[endsect] + [section Optional Reference Binding] diff --git a/doc/Jamfile.v2 b/doc/Jamfile.v2 index 2a8b727..b6f4a79 100644 --- a/doc/Jamfile.v2 +++ b/doc/Jamfile.v2 @@ -25,10 +25,11 @@ boostbook standalone optional : boost.root=../../../.. - toc.max.depth=2 + chapter.autolabel=0 + chunk.section.depth=8 toc.section.depth=2 - chunk.first.sections=2 - chunk.section.depth=2 + toc.max.depth=2 + generate.section.toc.level=1 pdf:img.src.path=$(images)/ pdf:boost.url.prefix=http://www.boost.org/doc/libs/release/libs/optional/doc/html ; diff --git a/doc/html/boost_optional/acknowledgments.html b/doc/html/boost_optional/acknowledgments.html index 19d24d9..b09cf6e 100644 --- a/doc/html/boost_optional/acknowledgments.html +++ b/doc/html/boost_optional/acknowledgments.html @@ -4,8 +4,8 @@ Acknowledgments - - + + diff --git a/doc/html/boost_optional/dependencies_and_portability.html b/doc/html/boost_optional/dependencies_and_portability.html index d9f62c1..b99d3b1 100644 --- a/doc/html/boost_optional/dependencies_and_portability.html +++ b/doc/html/boost_optional/dependencies_and_portability.html @@ -4,8 +4,8 @@ Dependencies and Portability - - + + @@ -27,12 +27,51 @@ Dependencies and Portability

    -
    Optional - Reference Binding
    +
    +
    Dependencies
    +
    Optional + Reference Binding
    +
    +
    +

    - The implementation uses type_traits/alignment_of.hpp and - type_traits/type_with_alignment.hpp -

    + 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. +
    +
    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 index 70316bc..991a0cf 100644 --- a/doc/html/boost_optional/dependencies_and_portability/optional_reference_binding.html +++ b/doc/html/boost_optional/dependencies_and_portability/optional_reference_binding.html @@ -4,7 +4,7 @@ Optional Reference Binding - + diff --git a/doc/html/boost_optional/quick_start.html b/doc/html/boost_optional/quick_start.html index 5434009..e8cc11b 100644 --- a/doc/html/boost_optional/quick_start.html +++ b/doc/html/boost_optional/quick_start.html @@ -4,10 +4,10 @@ Quick Start - - - - + + + +
    @@ -20,65 +20,78 @@
    -PrevUpHomeNext +PrevUpHomeNext
    -

    - - Optional +
    +
    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 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: -

    + 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::optionl<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: -

    + 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::optionl<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: -

    + 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::optionl<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: -

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

    + 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();
 }
@@ -87,20 +100,20 @@
 }

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

    + This version throws an exception upon an attempt to access a non-existent + 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. -

    + 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::optionl<int> convert(const std::string& text)
 {
   std::stringstream s(text);
@@ -112,168 +125,16 @@
 }

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

    -

    - - Optional - automatic variables -

    -

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

    -
    boost::optionl<int> convert(const std::string& text)
-{
-  boost::optionl<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 unitialized 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 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 it with T's - copy constructor. If the optional object is already initialized, it assigns - the new value to it using T's - copy assignment. -

    -

    - - Optional - data members -

    -

    - 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
-{
-  boost::optional<Resource> resource_;
-
-public:
-  Widget() {}
-
-  Resource& getResource() // 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 Default - Constructible. 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. -

    -

    - - Bypassing - unnecessary default construction -

    -

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

    -

    - - Storage - in containers -

    -

    - 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. So the - set of values that type optional<T> - can assume is {boost::none, -2147483648, -2147483647, ..., -1, - 0, 1, ..., 2147483647} (assuming a 32-bit int). -

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

    +

    @@ -285,7 +146,7 @@
    -PrevUpHomeNext +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 index 33ac25d..844742b 100644 --- a/doc/html/boost_optional/quick_start/bypassing_unnecessary_default_construction.html +++ b/doc/html/boost_optional/quick_start/bypassing_unnecessary_default_construction.html @@ -4,10 +4,10 @@ Bypassing unnecessary default construction - + - + @@ -20,7 +20,7 @@
    -PrevUpHomeNext +PrevUpHomeNext

    @@ -69,7 +69,7 @@
    -PrevUpHomeNext +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 index 34c9ac7..f577e11 100644 --- a/doc/html/boost_optional/quick_start/optional_automatic_variables.html +++ b/doc/html/boost_optional/quick_start/optional_automatic_variables.html @@ -4,9 +4,9 @@ Optional automatic variables - + - + @@ -20,7 +20,7 @@
    -PrevUpHomeNext +PrevUpHomeNext

    @@ -69,7 +69,7 @@
    -PrevUpHomeNext +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 index 00f5457..fe7fd78 100644 --- a/doc/html/boost_optional/quick_start/optional_data_members.html +++ b/doc/html/boost_optional/quick_start/optional_data_members.html @@ -4,7 +4,7 @@ Optional data members - + diff --git a/doc/html/boost_optional/quick_start/storage_in_containers.html b/doc/html/boost_optional/quick_start/storage_in_containers.html new file mode 100644 index 0000000..1715431 --- /dev/null +++ b/doc/html/boost_optional/quick_start/storage_in_containers.html @@ -0,0 +1,69 @@ + + + +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. + So the set of values that type optional<T> + can assume is {boost::none, -2147483648, -2147483647, ..., -1, + 0, 1, ..., 2147483647} (assuming a 32-bit int). +

    +
    + + + +
    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/detailed_semantics.html b/doc/html/boost_optional/reference/detailed_semantics.html index c5e5d9e..2bf9023 100644 --- a/doc/html/boost_optional/reference/detailed_semantics.html +++ b/doc/html/boost_optional/reference/detailed_semantics.html @@ -4,9 +4,9 @@ Detailed Semantics - + - + @@ -20,7 +20,7 @@
    -PrevUpHomeNext +PrevUpHomeNext

    @@ -1957,7 +1957,7 @@
    -PrevUpHomeNext +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 index 706bf49..ea3618b 100644 --- a/doc/html/boost_optional/tutorial/a_note_about_optional_bool_.html +++ b/doc/html/boost_optional/tutorial/a_note_about_optional_bool_.html @@ -4,7 +4,7 @@ A note about optional<bool> - + diff --git a/doc/html/boost_optional/tutorial/design_overview.html b/doc/html/boost_optional/tutorial/design_overview.html index d2493ce..d6598bc 100644 --- a/doc/html/boost_optional/tutorial/design_overview.html +++ b/doc/html/boost_optional/tutorial/design_overview.html @@ -4,10 +4,10 @@ Design Overview - + - - + + @@ -20,20 +20,12 @@
    -PrevUpHomeNext +PrevUpHomeNext
    -
    -
    The - models
    -
    The - semantics
    -
    The - Interface
    -
    -
    -
    -

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

    -
    @@ -417,7 +178,7 @@
    -PrevUpHomeNext +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 new file mode 100644 index 0000000..e0c3a31 --- /dev/null +++ b/doc/html/boost_optional/tutorial/design_overview/the_interface.html @@ -0,0 +1,186 @@ + + + +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 untitialized 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/design_overview/the_semantics.html b/doc/html/boost_optional/tutorial/design_overview/the_semantics.html new file mode 100644 index 0000000..5dbc63b --- /dev/null +++ b/doc/html/boost_optional/tutorial/design_overview/the_semantics.html @@ -0,0 +1,121 @@ + + + +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 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 index ede593d..ea3fa8f 100644 --- a/doc/html/boost_optional/tutorial/exception_safety_guarantees.html +++ b/doc/html/boost_optional/tutorial/exception_safety_guarantees.html @@ -4,7 +4,7 @@ Exception Safety Guarantees - + diff --git a/doc/html/boost_optional/tutorial/in_place_factories.html b/doc/html/boost_optional/tutorial/in_place_factories.html index 3d7500a..3c26b05 100644 --- a/doc/html/boost_optional/tutorial/in_place_factories.html +++ b/doc/html/boost_optional/tutorial/in_place_factories.html @@ -4,7 +4,7 @@ In-Place Factories - + diff --git a/doc/html/boost_optional/tutorial/optional_references.html b/doc/html/boost_optional/tutorial/optional_references.html index 77d73f5..0ca70b6 100644 --- a/doc/html/boost_optional/tutorial/optional_references.html +++ b/doc/html/boost_optional/tutorial/optional_references.html @@ -4,9 +4,9 @@ Optional references - + - + @@ -20,7 +20,7 @@
    -PrevUpHomeNext +PrevUpHomeNext

    @@ -109,7 +109,7 @@
    -PrevUpHomeNext +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 index b2bd32d..26bbf66 100644 --- 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 @@ -4,7 +4,7 @@ Rebinding semantics for assignment of optional references - + diff --git a/doc/html/boost_optional/tutorial/type_requirements.html b/doc/html/boost_optional/tutorial/type_requirements.html index 84959d2..f8501dd 100644 --- a/doc/html/boost_optional/tutorial/type_requirements.html +++ b/doc/html/boost_optional/tutorial/type_requirements.html @@ -4,7 +4,7 @@ Type requirements - + diff --git a/doc/html/index.html b/doc/html/index.html index 0ae3385..30310e9 100644 --- a/doc/html/index.html +++ b/doc/html/index.html @@ -1,10 +1,10 @@ -Chapter 1. Boost.Optional +Boost.Optional - + @@ -21,7 +21,7 @@

    -Chapter 1. Boost.Optional

    +Boost.Optional

    Fernando Luis Cacciola Carballal

    @@ -37,10 +37,23 @@

    Table of Contents

    +
    Introduction
    Quick Start
    +
    +
    Optional + return values
    +
    Optional + automatic variables
    +
    Optional + data members
    +
    Bypassing + unnecessary default construction
    +
    Storage + in containers
    +
    Tutorial
    -
    Motivation
    +
    Motivation
    Design Overview
    Optional references
    @@ -56,48 +69,51 @@
    Reference
    -
    Synopsis
    +
    Synopsis
    Detailed Semantics
    Dependencies and Portability
    -
    Optional - Reference Binding
    +
    +
    Dependencies
    +
    Optional + Reference Binding
    +
    Acknowledgments
    -

    - - Introduction -

    +
    +

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

    + 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 form 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 different. Also suppose that any possible value of type int is a valid value for "MaxValue", - so we cannot jut use -1 - to represent the absence of the parameter in the config file. -

    -

    - - Solution -

    + Suppose we want to read a parameter form 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 different. Also suppose that any possible value of type + int is a valid value for "MaxValue", so we cannot jut use -1 to represent + the absence of the parameter in the config file. +

    +

    + + Solution +

    - This is how you solve it with boost::optional: -

    + 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`
@@ -111,8 +127,9 @@
 }
    +
    - +

    Last revised: June 04, 2014 at 21:00:26 GMT

    Last revised: June 05, 2014 at 22:46:34 GMT
    diff --git a/doc/html/optional/introduction.html b/doc/html/optional/introduction.html deleted file mode 100644 index 8f63804..0000000 --- a/doc/html/optional/introduction.html +++ /dev/null @@ -1,82 +0,0 @@ - - - -Introduction - - - - - - - - - - - - - - - -
    Boost C++ LibrariesHomeLibrariesPeopleFAQMore
    -
    -
    -PrevUpHomeNext -
    -
    -
    -

    - 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 form 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 different. Also suppose that any possible value of type - int is a valid value for "MaxValue", so we cannot jut 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();
-}
-
    -
    - - - -
    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/optional/introduction/problem.html b/doc/html/optional/introduction/problem.html deleted file mode 100644 index 126a786..0000000 --- a/doc/html/optional/introduction/problem.html +++ /dev/null @@ -1,54 +0,0 @@ - - - -Problem - - - - - - - - - - - - - - - -
    Boost C++ LibrariesHomeLibrariesPeopleFAQMore
    -
    -
    -PrevUpHomeNext -
    -
    -
    -

    - Suppose we want to read a parameter form 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 different. Also suppose that any possible - value of type int is a valid - value for "MaxValue", - so we cannot jut use -1 - to represent the absence of the parameter in the config file. -

    -
    - - - -
    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/optional/introduction/solution.html b/doc/html/optional/introduction/solution.html deleted file mode 100644 index 01b95ba..0000000 --- a/doc/html/optional/introduction/solution.html +++ /dev/null @@ -1,58 +0,0 @@ - - - -Solution - - - - - - - - - - - - - - - -
    Boost C++ LibrariesHomeLibrariesPeopleFAQMore
    -
    -
    -PrevUpHomeNext -
    -
    -
    -

    - 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();
-}
-
    -
    - - - -
    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/optional/reference.html b/doc/html/optional/reference.html deleted file mode 100644 index 57d96f2..0000000 --- a/doc/html/optional/reference.html +++ /dev/null @@ -1,48 +0,0 @@ - - - -Reference - - - - - - - - - - - - - - - -
    Boost C++ LibrariesHomeLibrariesPeopleFAQMore
    -
    -
    -PrevUpHomeNext -
    -
    -
    -
    -
    Synopsis
    -
    Detailed - Semantics
    -
    -
    - - - -
    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/optional/tutorial.html b/doc/html/optional/tutorial.html deleted file mode 100644 index 35fd387..0000000 --- a/doc/html/optional/tutorial.html +++ /dev/null @@ -1,58 +0,0 @@ - - - -Tutorial - - - - - - - - - - - - - - - -
    Boost C++ LibrariesHomeLibrariesPeopleFAQMore
    -
    -
    -PrevUpHomeNext -
    -
    -
    -
    -
    Motivation
    -
    Design Overview
    -
    Optional - references
    -
    Rebinding - semantics for assignment of optional references
    -
    In-Place - Factories
    -
    A - note about optional<bool>
    -
    Exception - Safety Guarantees
    -
    Type requirements
    -
    -
    - - - -
    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 -
    - -