ceph/src/boost/libs/optional/doc/90_dependencies.qbk

   1 [/
   2     Boost.Optional
   3
   4     Copyright (c) 2003-2007 Fernando Luis Cacciola Carballal
   5
   6     Distributed under the Boost Software License, Version 1.0.
   7     (See accompanying file LICENSE_1_0.txt or copy at
   8     http://www.boost.org/LICENSE_1_0.txt)
   9 ]
  10
  11
  12 [section Dependencies and Portability]
  13
  14 [section Dependencies]
  15 The implementation uses the following other Boost modules:
  16
  17 # assert
  18 # config
  19 # core
  20 # detail
  21 # move
  22 # mpl
  23 # static_assert
  24 # throw_exception
  25 # type_traits
  26 # utility
  27
  28 [endsect]
  29
  30 [section Emplace operations in older compilers][#optional_emplace_workaround]
  31
  32 Certain constructors and functions in the interface of `optional` perform a 'perfect forwarding' of arguments:
  33
  34     template<class... Args> optional(in_place_init_t, Args&&... args);
  35     template<class... Args> optional(in_place_init_if_t, bool condition, Args&&... args);
  36     template<class... Args> void emplace(Args&&... args);
  37
  38 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:
  39
  40     template<class Arg> optional(in_place_init_t, Arg&& arg);
  41     optional(in_place_init_t);
  42
  43     template<class Arg> optional(in_place_init_if_t, bool condition, Arg&& arg);
  44     optional(in_place_init_if_t, bool condition);
  45
  46     template<class Arg> void emplace(Arg&& arg);
  47     void emplace();
  48
  49 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:
  50
  51     template<class Arg> optional(in_place_init_t, const Arg& arg);
  52     template<class Arg> optional(in_place_init_t, Arg& arg);
  53     optional(in_place_init_t);
  54
  55     template<class Arg> optional(in_place_init_if_t, bool condition, const Arg& arg);
  56     template<class Arg> optional(in_place_init_if_t, bool condition, Arg& arg);
  57     optional(in_place_init_if_t, bool condition);
  58
  59     template<class Arg> void emplace(const Arg& arg);
  60     template<class Arg> void emplace(Arg& arg);
  61     void emplace();
  62
  63 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].
  64 [endsect]
  65
  66 [section Optional Reference Binding][#optional_reference_binding]
  67
  68 A number of compilers incorrectly treat const lvalues of integral type as rvalues, and create an illegal temporary when binding to an lvalue reference to const in some expressions. This could result in creating an optional lvalue reference that is in fact bound to an unexpected temporary rather than to the intended object. In order to prevent hard to find run-time bugs, this library performs compile-time checks to prevent expressions that would otherwise bind an optional reference to an unexpected temporary. As a consequence, on certain compilers certain pieces of functionality in optional references are missing. In order to maintain a portability of your code across diferent compilers, it is recommended that you only stick to the minimum portable interface of optional references: prefer direct-initialization and copy assignment of optional references to copy-initialization and assignment from `T&`:
  69
  70     const int i = 0;
  71     optional<const int&> or1;
  72     optional<const int&> or2 = i;  // caution: not portable
  73     or1 = i;                       // caution: not portable
  74
  75     optional<const int&> or3(i);   // portable
  76     or1 = optional<const int&>(i); // portable
  77
  78 Compilers known to have these deficiencies include GCC versions 4.2, 4.3, 4.4, 4.5, 5.1, 5.2; QCC 4.4.2; MSVC versions 8.0, 9.0, 10.0, 11.0, 12.0. In order to check if your compiler correctly implements reference binding use this test program.
  79
  80     #include <cassert>
  81
  82     const int global_i = 0;
  83
  84     struct TestingReferenceBinding
  85     {
  86       TestingReferenceBinding(const int& ii)
  87       {
  88         assert(&ii == &global_i);
  89       }
  90
  91       void operator=(const int& ii)
  92       {
  93         assert(&ii == &global_i);
  94       }
  95
  96       void operator=(int&&) // remove this if your compiler doesn't have rvalue refs
  97       {
  98         assert(false);
  99       }
 100     };
 101
 102     int main()
 103     {
 104       const int& iref = global_i;
 105       assert(&iref == &global_i);
 106
 107       TestingReferenceBinding ttt = global_i;
 108       ttt = global_i;
 109
 110       TestingReferenceBinding ttt2 = iref;
 111       ttt2 = iref;
 112     }
 113
 114 [endsect]
 115
 116 [endsect]