diff --git a/doc/27_ref_optional_synopsis.qbk b/doc/27_ref_optional_synopsis.qbk index 8a9386f..2da3b8f 100644 --- a/doc/27_ref_optional_synopsis.qbk +++ b/doc/27_ref_optional_synopsis.qbk @@ -15,6 +15,12 @@ namespace boost { + class in_place_init_t { /* see below */ } ; ``[link reference_in_place_init __GO_TO__]`` + const in_place_init_t in_place_init ( /* see below */ ) ; + + class in_place_init_if_t { /*see below*/ } ; ``[link reference_in_place_init_if __GO_TO__]`` + const in_place_init_if_t in_place_init_if ( /*see below*/ ) ; + template class optional ; ``[link reference_operator_template __GO_TO__]`` @@ -67,6 +73,26 @@ [endsect] +[section:header_optional_in_place_init Initialization tags] + +[#reference_in_place_init] +[#reference_in_place_init_if] + + namespace boost { + + class in_place_init_t { /* see below */ } ; + const in_place_init_t in_place_init ( /* see below */ ) ; + + class in_place_init_if_t { /*see below*/ } ; + const in_place_init_if_t in_place_init_if ( /*see below*/ ) ; + + } + +Classes `in_place_init_t` and `in_place_init_if_t` are empty clsses. Their purpose is to control overload resolution in the initialization of optional objects. +They are empty, trivially copyable classes with disabled default constructor. + +[endsect] + [section:header_optional_optional_values Optional Values] [#reference_operator_template] @@ -91,7 +117,6 @@ optional ( T&& v ) ; ``[link reference_optional_constructor_move_value __GO_TO__]`` - // [new in 1.34] optional ( bool condition, T const& v ) ; ``[link reference_optional_constructor_bool_value __GO_TO__]`` optional ( optional const& rhs ) ; ``[link reference_optional_constructor_optional __GO_TO__]`` @@ -101,6 +126,10 @@ template explicit optional ( optional const& rhs ) ; ``[link reference_optional_constructor_other_optional __GO_TO__]`` template explicit optional ( optional&& rhs ) ; ``[link reference_optional_move_constructor_other_optional __GO_TO__]`` + + template explicit optional ( in_place_init_t, Args&&... args ) ; ``[link reference_optional_in_place_init __GO_TO__]`` + + template explicit optional ( in_place_init_if_t, bool condition, Args&&... args ) ; ``[link reference_optional_in_place_init_if __GO_TO__]`` template explicit optional ( InPlaceFactory const& f ) ; ``[link reference_optional_constructor_factory __GO_TO__]`` diff --git a/doc/28_ref_optional_semantics.qbk b/doc/28_ref_optional_semantics.qbk index e643a9f..1288c56 100644 --- a/doc/28_ref_optional_semantics.qbk +++ b/doc/28_ref_optional_semantics.qbk @@ -224,6 +224,53 @@ assert( *y == 123 ) ; __SPACE__ +[#reference_optional_in_place_init] + +[: `template explicit optional::optional( in_place_init_t, Args&&... ars );`] + +* [*Requires:] `is_constructible_v` is `true`. +* [*Effect:] Initializes the contained value as if direct-non-list-initializing an object of type `T` with the +arguments `std::forward(args)...`. +* [*Postconditions:] `*this` is initialized. +* [*Throws:] Any exception thrown by the selected constructor of `T`. +* [*Notes: ] `T` need not be __MOVE_CONSTRUCTIBLE__. On compilers that do not suppor variadic templates or rvalue references, this constuctor is available in limited functionality. For details [link optional_emplace_workaround see here]. + +* [*Example:] +`` +// creates an std::mutex using its default constructor +optional om {in_place_init}; +assert (om); + +// creates a unique_lock by calling unique_lock(*om, std::defer_lock) +optional> ol {in_place_init, *om, std::defer_lock}; +assert (ol); +assert (!ol->owns_lock()); +`` + +__SPACE__ + +[#reference_optional_in_place_init_if] + +[: `template explicit optional::optional( in_place_init_if_t, bool condition, Args&&... ars );`] + +* [*Requires:] `is_constructible_v` is `true`. +* [*Effect:] If `condition` is `true`, initializes the contained value as if direct-non-list-initializing an object of type `T` with the arguments `std::forward(args)...`. +* [*Postconditions:] `bool(*this) == condition`. +* [*Throws:] Any exception thrown by the selected constructor of `T`. +* [*Notes: ] `T` need not be __MOVE_CONSTRUCTIBLE__. On compilers that do not suppor variadic templates or rvalue references, this constuctor is available in limited functionality. For details [link optional_emplace_workaround see here]. + +* [*Example:] +`` +optional> ov1 {in_place_init_if, false, 3, "A"}; +assert (!ov1); + +optional> ov2 {in_place_init_if, true, 3, "A"}; +assert (ov2); +assert (ov2->size() == 3); +`` + +__SPACE__ + [#reference_optional_constructor_factory] [: `template explicit optional::optional( InPlaceFactory const& f );`] @@ -455,9 +502,7 @@ __SPACE__ * [*Postconditions: ] `*this` is [_initialized]. * [*Throws:] Whatever the selected `T`'s constructor throws. * [*Exception Safety:] If an exception is thrown during the initialization of `T`, `*this` is ['uninitialized]. -* [*Notes:] `T` need not be __MOVE_CONSTRUCTIBLE__ or `MoveAssignable`. - On compilers that do not support variadic templates, the signature falls back to two overloads:`template void emplace(Arg&& arg)` and `void emplace()`. - On compilers that do not support rvalue references, the signature falls back to three overloads: taking `const` and non-`const` lvalue reference, and third with empty function argument list. +* [*Notes:] `T` need not be __MOVE_CONSTRUCTIBLE__ or `MoveAssignable`. On compilers that do not suppor variadic templates or rvalue references, this function is available in limited functionality. For details [link optional_emplace_workaround see here]. * [*Example:] `` T v; diff --git a/doc/90_dependencies.qbk b/doc/90_dependencies.qbk index 6d0cccc..b5fa97c 100644 --- a/doc/90_dependencies.qbk +++ b/doc/90_dependencies.qbk @@ -27,6 +27,41 @@ The implementation uses the following other Boost modules: [endsect] +[section Emplace operations in older compilers][#optional_emplace_workaround] + +Certain constructors and functions in the interface of `optional` perform a 'perfect forwarding' of arguments: + + template optional(in_place_init_t, Args&&... args); + template optional(in_place_init_if_t, bool condition, Args&&... args); + template void emplace(Args&&... args); + +On compilers that do not support variadic templates, each of these functions is substituted with two overloads, one forwarding a single argument, the other forwarding zero arguments. This forms the following set: + + template optional(in_place_init_t, Arg&& arg); + optional(in_place_init_t); + + template optional(in_place_init_if_t, bool condition, Arg&& arg); + optional(in_place_init_if_t, bool condition); + + template void emplace(Arg&& arg); + void emplace(); + +On compilers that do not support rvalue references, each of these functions is substituted with three overloadss: taking `const` and non-`const` lvalue reference, and third forwarding zero arguments. This forms the following set: + + template optional(in_place_init_t, const Arg& arg); + template optional(in_place_init_t, Arg& arg); + optional(in_place_init_t); + + template optional(in_place_init_if_t, bool condition, const Arg& arg); + template optional(in_place_init_if_t, bool condition, Arg& arg); + optional(in_place_init_if_t, bool condition); + + template void emplace(const Arg& arg); + template void emplace(Arg& arg); + void emplace(); + +This workaround addressess about 40% of all use cases. If this is insufficient, you need to resort to using [link boost_optional.tutorial.in_place_factories In-Place Factories]. +[endsect] [section Optional Reference Binding][#optional_reference_binding] diff --git a/doc/91_relnotes.qbk b/doc/91_relnotes.qbk index ef38e5c..a026a8b 100644 --- a/doc/91_relnotes.qbk +++ b/doc/91_relnotes.qbk @@ -11,6 +11,10 @@ [section:relnotes Release Notes] +[heading Boost Release 1.63] +* Added two new in-place constructors. They work similarly to `emplace()` functions: they initialize the contained value by perfect-forwarding the obtained arguments. One constructor always initializes the contained value, the other based on a boolean condition. +* Fixed [@https://svn.boost.org/trac/boost/ticket/12203 Trac #12203]. + [heading Boost Release 1.62] diff --git a/doc/html/boost_optional/dependencies_and_portability.html b/doc/html/boost_optional/dependencies_and_portability.html index b24c517..ac2309c 100644 --- a/doc/html/boost_optional/dependencies_and_portability.html +++ b/doc/html/boost_optional/dependencies_and_portability.html @@ -7,7 +7,7 @@ - + @@ -20,7 +20,7 @@
-PrevUpHomeNext +PrevUpHomeNext

@@ -29,6 +29,8 @@

Dependencies
+
Emplace + operations in older compilers
Optional Reference Binding
@@ -83,7 +85,7 @@
-PrevUpHomeNext +PrevUpHomeNext
diff --git a/doc/html/boost_optional/dependencies_and_portability/emplace_operations_in_older_compilers.html b/doc/html/boost_optional/dependencies_and_portability/emplace_operations_in_older_compilers.html new file mode 100644 index 0000000..4aedcf7 --- /dev/null +++ b/doc/html/boost_optional/dependencies_and_portability/emplace_operations_in_older_compilers.html @@ -0,0 +1,90 @@ + + + +Emplace operations in older compilers + + + + + + + + + + + + + + + +
Boost C++ LibrariesHomeLibrariesPeopleFAQMore
+
+
+PrevUpHomeNext +
+
+
+

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

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

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

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

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

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

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

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

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

+
+
+
+PrevUpHomeNext +
+ + diff --git a/doc/html/boost_optional/dependencies_and_portability/optional_reference_binding.html b/doc/html/boost_optional/dependencies_and_portability/optional_reference_binding.html index 314bfe6..f38dc20 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 @@ -6,7 +6,7 @@ - + @@ -20,7 +20,7 @@
-PrevUpHomeNext +PrevUpHomeNext

@@ -101,7 +101,7 @@
-PrevUpHomeNext +PrevUpHomeNext
diff --git a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics___optional_values.html b/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics___optional_values.html index bd0877a..0d323b5 100644 --- a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics___optional_values.html +++ b/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/detailed_semantics___optional_values.html @@ -403,6 +403,94 @@

+

+ space +

+

+ template<class... Args> + explicit optional<T>::optional( in_place_init_t, Args&&... ars + ); +

+
    +
  • + Requires: is_constructible_v<T, Args&&...> is true. +
    • +
  • + Effect: Initializes the contained + value as if direct-non-list-initializing an object of type T with the arguments std::forward<Args>(args).... +
    • +
  • + Postconditions: *this is initialized. +
    • +
  • + Throws: Any exception thrown by the + selected constructor of T. +
    • +
  • + Notes: T + need not be MoveConstructible. + On compilers that do not suppor variadic templates or rvalue references, + this constuctor is available in limited functionality. For details + see here. +
    • +
  • + Example: +
    // creates an std::mutex using its default constructor
+optional<std::mutex> om {in_place_init};
+assert (om);
+
+// creates a unique_lock by calling unique_lock(*om, std::defer_lock)
+optional<std::unique_lock<std::mutex>> ol {in_place_init, *om, std::defer_lock};
+assert (ol);
+assert (!ol->owns_lock());
+
    +
    • +
+

+ space +

+

+ template<class... Args> + explicit optional<T>::optional( in_place_init_if_t, bool condition, + Args&&... + ars ); +

+
    +
  • + Requires: is_constructible_v<T, Args&&...> is true. +
    • +
  • + Effect: If condition + is true, initializes the + contained value as if direct-non-list-initializing an object of type + T with the arguments + std::forward<Args>(args).... +
    • +
  • + Postconditions: bool(*this) == condition. +
    • +
  • + Throws: Any exception thrown by the + selected constructor of T. +
    • +
  • + Notes: T + need not be MoveConstructible. + On compilers that do not suppor variadic templates or rvalue references, + this constuctor is available in limited functionality. For details + see here. +
    • +
  • + Example: +
    optional<std::vector<std::string>> ov1 {in_place_init_if, false, 3, "A"};
+assert (!ov1);
+
+optional<std::vector<std::string>> ov2 {in_place_init_if, true, 3, "A"};
+assert (ov2);
+assert (ov2->size() == 3);
+
    +
    • +

space

@@ -1037,15 +1125,8 @@ Notes: T need not be MoveConstructible or MoveAssignable. - On compilers that do not support variadic templates, the signature - falls back to two overloads:template<class - Arg> - void emplace(Arg&& arg) and void - emplace(). - On compilers that do not support rvalue references, the signature falls - back to three overloads: taking const - and non-const lvalue reference, - and third with empty function argument list. + On compilers that do not suppor variadic templates or rvalue references, + this function is available in limited functionality. For details see here.
  • Example: diff --git a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/header_optional_in_place_init.html b/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/header_optional_in_place_init.html new file mode 100644 index 0000000..8c1a467 --- /dev/null +++ b/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/header_optional_in_place_init.html @@ -0,0 +1,61 @@ + + + +Initialization tags + + + + + + + + + + + + + + + +
    Boost C++ LibrariesHomeLibrariesPeopleFAQMore
    +
    +
    +PrevUpHomeNext +
    +
    +
    +
    namespace boost {
+
+class in_place_init_t { /* see below */ } ;
+const in_place_init_t in_place_init ( /* see below */ ) ;
+
+class in_place_init_if_t { /*see below*/ } ;
+const in_place_init_if_t in_place_init_if ( /*see below*/ ) ;
+
+}
+
    +

    + Classes in_place_init_t + and in_place_init_if_t + are empty clsses. Their purpose is to control overload resolution in the + initialization of optional objects. They are empty, trivially copyable + classes with disabled default constructor. +

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

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

    +
    +
    +
    +PrevUpHomeNext +
    + + diff --git a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/header_optional_optional_values.html b/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/header_optional_optional_values.html index 8b5fd70..2d19129 100644 --- a/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/header_optional_optional_values.html +++ b/doc/html/boost_optional/reference/header__boost_optional_optional_hpp_/header_optional_optional_values.html @@ -6,7 +6,7 @@ - + @@ -20,7 +20,7 @@
    -PrevUpHomeNext +PrevUpHomeNext

    @@ -47,7 +47,6 @@ optional ( T&& v ) ; R - // [new in 1.34] optional ( bool condition, T const& v ) ; R optional ( optional const& rhs ) ; R @@ -58,6 +57,10 @@ template<class U> explicit optional ( optional<U>&& rhs ) ; R + template<class... Args> explicit optional ( in_place_init_t, Args&&... args ) ; R + + template<class... Args> explicit optional ( in_place_init_if_t, bool condition, Args&&... args ) ; R + template<class InPlaceFactory> explicit optional ( InPlaceFactory const& f ) ; R template<class TypedInPlaceFactory> explicit optional ( TypedInPlaceFactory const& f ) ; R @@ -135,7 +138,7 @@
    -PrevUpHomeNext +PrevUpHomeNext
    diff --git a/doc/html/boost_optional/relnotes.html b/doc/html/boost_optional/relnotes.html index 15b6373..6a6db62 100644 --- a/doc/html/boost_optional/relnotes.html +++ b/doc/html/boost_optional/relnotes.html @@ -28,6 +28,22 @@

    + Boost + Release 1.63 +

    +
      +
    • + Added two new in-place constructors. They work similarly to emplace() + functions: they initialize the contained value by perfect-forwarding the + obtained arguments. One constructor always initializes the contained value, + the other based on a boolean condition. +
      • +
    • + Fixed Trac #12203. +
      • +
    +

    + Boost Release 1.62

    @@ -35,7 +51,7 @@ Fixed Trac #12179.

    • - + Boost Release 1.61

    @@ -78,7 +94,7 @@

    - + Boost Release 1.60

    @@ -89,7 +105,7 @@ #11203.

    - + Boost Release 1.59

    @@ -103,7 +119,7 @@

    - + Boost Release 1.58

    @@ -139,7 +155,7 @@

    - + Boost Release 1.57

    @@ -149,7 +165,7 @@ to fix C++03 compile error on logic_error("...")".

    - + Boost Release 1.56

    diff --git a/doc/html/index.html b/doc/html/index.html index 03e9413..8d507f2 100644 --- a/doc/html/index.html +++ b/doc/html/index.html @@ -89,6 +89,8 @@ and Portability
    Dependencies
    +
    Emplace + operations in older compilers
    Optional Reference Binding
    @@ -143,7 +145,7 @@ - +

    Last revised: September 16, 2016 at 23:43:36 GMT

    Last revised: October 27, 2016 at 21:57:04 GMT
    diff --git a/doc/html/optional/reference/header__boost_optional_optional_hpp_.html b/doc/html/optional/reference/header__boost_optional_optional_hpp_.html index a395d63..c6eec11 100644 --- a/doc/html/optional/reference/header__boost_optional_optional_hpp_.html +++ b/doc/html/optional/reference/header__boost_optional_optional_hpp_.html @@ -7,7 +7,7 @@ - + @@ -20,7 +20,7 @@
    -PrevUpHomeNext +PrevUpHomeNext

    @@ -35,6 +35,12 @@ namespace boost { +class in_place_init_t { /* see below */ } ; R +const in_place_init_t in_place_init ( /* see below */ ) ; + +class in_place_init_if_t { /*see below*/ } ; R +const in_place_init_if_t in_place_init_if ( /*see below*/ ) ; + template <class T> class optional ; R @@ -95,7 +101,7 @@
    -PrevUpHomeNext +PrevUpHomeNext