Merge branch 'develop'

doc/00_optional.qbk

@@ -38,10 +38,10 @@ Distributed under the Boost Software License, Version 1.0.
 [/ Other web resources ]
 
 [def __HASKELL__ [@http://www.haskell.org/ Haskell]]
-[def __SGI_DEFAULT_CONSTRUCTIBLE__ [@http://www.sgi.com/tech/stl/DefaultConstructible.html `DefaultConstructible`]]
-[def __SGI_LESS_THAN_COMPARABLE__ [@http://www.sgi.com/tech/stl/LessThanComparable.html `LessThanComparable`]]
-[def __SGI_EQUALITY_COMPARABLE__ [@http://www.sgi.com/tech/stl/EqualityComparable.html `EqualityComparable`]]
-[def __SGI_GENERATOR__ [@http://www.sgi.com/tech/stl/Generator.html `Generator`]]
+[def __STD_DEFAULT_CONSTRUCTIBLE__ [@https://en.cppreference.com/w/cpp/named_req/DefaultConstructible `DefaultConstructible`]]
+[def __STD_LESS_THAN_COMPARABLE__ [@https://en.cppreference.com/w/cpp/named_req/LessThanComparable `LessThanComparable`]]
+[def __STD_EQUALITY_COMPARABLE__ [@https://en.cppreference.com/w/cpp/named_req/EqualityComparable `EqualityComparable`]]
+[def __SGI_GENERATOR__ [@http://www.rrsd.com/software_development/stl/stl/Generator.html `Generator`]]
 
 
 [/ Icons ]

doc/01_quick_start.qbk

@@ -25,7 +25,7 @@ All necessary functionality can be included with one header `<boost/optional.hpp
     boost::optional<int> oi = convert(text); // move-construct
     if (oi)                                  // contextual conversion to bool
       int i = *oi;                           // operator*
-    
+
 In order to test if `optional` contains a value, we use the contextual conversion to type `bool`. Because of this we can combine the initialization of the optional object and the test into one instruction:
 
     if (boost::optional<int> oi = convert(text))
@@ -34,7 +34,7 @@ In order to test if `optional` contains a value, we use the contextual conversio
 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 {
@@ -47,15 +47,15 @@ This is because we know that string value `"100"` converts to a valid value of `
 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`. Finally, you can provide a callback to be called when trying to access the contained value fails:
 
     int fallback_to_default()
     {
-      cerr << "could not convert; using -1 instead" << endl; 
+      cerr << "could not convert; using -1 instead" << endl;
       return -1;
     }
-    
+
     int l = convert(text).value_or_eval(fallback_to_default);
 
 This will call the provided callback and return whatever the callback returns. The callback can have side effects: they will only be observed when the optional object does not contain a value.
@@ -63,7 +63,7 @@ This will call the provided callback and return whatever the callback returns. T
 Now, let's consider how function `convert` can be implemented.
 
     boost::optional<int> convert(const std::string& text)
-    {  
+    {
       std::stringstream s(text);
       int i;
       if ((s >> i) && s.get() == std::char_traits<char>::eof())
@@ -72,7 +72,7 @@ Now, let's consider how function `convert` can be implemented.
         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. 
+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.
 
 [endsect]
 
@@ -91,7 +91,7 @@ We could write function `convert` in a slightly different manner, so that it has
       return ans;
     }
 
-The default constructor of `optional` creates an unitialized optional object. Unlike with `int`s you cannot have an `optional<int>` in an indeterminate state. Its state is always well defined. Instruction `ans = i` initializes the optional object. It uses the 'mixed' assignment from `int`. In general, for `optional<T>`, when an assignment from `T` is invoked, it can do two things. If the optional object is not initialized (our case here), it initializes the contained value using `T`'s copy constructor. If the optional object is already initialized, it assigns the new value to it using `T`'s copy assignment.      
+The default constructor of `optional` creates an unitialized optional object. Unlike with `int`s you cannot have an `optional<int>` in an indeterminate state. Its state is always well defined. Instruction `ans = i` initializes the optional object. It uses the 'mixed' assignment from `int`. In general, for `optional<T>`, when an assignment from `T` is invoked, it can do two things. If the optional object is not initialized (our case here), it initializes the contained value using `T`'s copy constructor. If the optional object is already initialized, it assigns the new value to it using `T`'s copy assignment.
 [endsect]
 
 [section Optional data members]
@@ -101,20 +101,20 @@ Suppose we want to implement a ['lazy load] optimization. This is because we do
     class Widget
     {
       mutable boost::optional<const Resource> resource_;
-      
+
     public:
       Widget() {}
-      
+
       const Resource& getResource() const // not thread-safe
       {
         if (resource_ == boost::none)
             resource_.emplace("resource", "arguments");
-        
+
         return *resource_;
       }
     };
-    
-`optional`'s default constructor creates an uninitialized optional. No call to `Resource`'s default constructor is attempted. `Resource` doesn't have to be __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`. 
+
+`optional`'s default constructor creates an uninitialized optional. No call to `Resource`'s default constructor is attempted. `Resource` doesn't have to be __STD_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.tutorial.in_place_factories In-Place Factories].]
 
@@ -125,17 +125,17 @@ Suppose we want to implement a ['lazy load] optimization. This is because we do
 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`.
 [endsect]
 
@@ -144,15 +144,17 @@ It works because inside `boost::tie` a move-assignment from `T` is invoked on `o
 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 __SGI_LESS_THAN_COMPARABLE__ whenever `T` is __SGI_LESS_THAN_COMPARABLE__. 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`.
+
+This works because `optional<T>` is __STD_LESS_THAN_COMPARABLE__ whenever `T` is __STD_LESS_THAN_COMPARABLE__.
+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`.
+`optional<T>` can also be stored as a key in `std::unordered_map` and `std::unordered_set`
+as it provides specializations for `std::hash`.
 [endsect]
 
 [endsect]
-
- 

doc/12_when_to_use.qbk

@@ -11,7 +11,7 @@ Here, having received an empty `vec` and having no `size_t` to return is not a [
 
 Another typical situation is to indicate that we do not have a value yet, but we expect to have it later. This notion can be used in implementing solutions like lazy initialization or a two-phase initialization.
 
-`optional` can be used to take a non-__SGI_DEFAULT_CONSTRUCTIBLE__ type `T` and create a sibling type with a default constructor. This is a way to add a ['null-state] to any type that doesn't have it already.
+`optional` can be used to take a non-__STD_DEFAULT_CONSTRUCTIBLE__ type `T` and create a sibling type with a default constructor. This is a way to add a ['null-state] to any type that doesn't have it already.
 
 Sometimes type `T` already provides a built-in null-state, but it may still be useful to wrap it into `optional`. Consider `std::string`. When you read a piece of text from a GUI form or a DB table, it is hardly ever that the empty string indicates anything else but a missing text. And some data bases do not even distinguish between a null string entry and a non-null string of length 0. Still, it may be practical to use `optional<string>` to indicate in the returned type that we want to treat the empty string in a special dedicated program path:
 

doc/13_relational_operators.qbk

@@ -1,18 +1,18 @@
 
 [section Relational operators]
 
-Type `optional<T>` is __SGI_EQUALITY_COMPARABLE__ whenever `T` is __SGI_EQUALITY_COMPARABLE__. Two optional objects containing a value compare in the same way as their contained values. The uninitialized state of `optional<T>` is treated as a distinct value, equal to itself, and unequal to any value of type `T`:
+Type `optional<T>` is __STD_EQUALITY_COMPARABLE__ whenever `T` is __STD_EQUALITY_COMPARABLE__. Two optional objects containing a value compare in the same way as their contained values. The uninitialized state of `optional<T>` is treated as a distinct value, equal to itself, and unequal to any value of type `T`:
 
     boost::optional<int> oN = boost::none;
     boost::optional<int> o0 = 0;
     boost::optional<int> o1 = 1;
-    
+
     assert(oN != o0);
     assert(o1 != oN);
     assert(o0 != o1);
     assert(oN == oN);
     assert(o0 == o0);
-    
+
 The converting constructor from `T` as well as from `boost::none` implies the existence and semantics of the mixed comparison between `T` and `optional<T>` as well as between `none_t` and `optionl<T>`:
 
     assert(oN != 0);
@@ -20,18 +20,18 @@ The converting constructor from `T` as well as from `boost::none` implies the ex
     assert(o0 != 1);
     assert(oN == boost::none);
     assert(o0 == 0);
-    
+
 This mixed comparison has a practical interpretation, which is occasionally useful:
 
     boost::optional<int> choice = ask_user();
     if (choice == 2)
         start_procedure_2();
-        
+
 In the above example, the meaning of the comparison is 'user chose number 2'. If user chose nothing, he didn't choose number 2.
 
-In case where `optional<T>` is compared to `none`, it is not required that `T` be __SGI_EQUALITY_COMPARABLE__.
+In case where `optional<T>` is compared to `none`, it is not required that `T` be __STD_EQUALITY_COMPARABLE__.
 
-In a similar manner, type `optional<T>` is __SGI_LESS_THAN_COMPARABLE__ whenever `T` is __SGI_LESS_THAN_COMPARABLE__. The optional object containing no value is compared less than any value of `T`. To illustrate this, if the default ordering of `size_t` is {`0`, `1`, `2`, ...}, the default ordering of `optional<size_t>` is {`boost::none`, `0`, `1`, `2`, ...}. This order does not have a practical interpretation. The goal is to have any semantically correct default ordering in order for `optional<T>` to be usable in ordered associative containers (wherever `T` is usable).  
+In a similar manner, type `optional<T>` is __STD_LESS_THAN_COMPARABLE__ whenever `T` is __STD_LESS_THAN_COMPARABLE__. The optional object containing no value is compared less than any value of `T`. To illustrate this, if the default ordering of `size_t` is {`0`, `1`, `2`, ...}, the default ordering of `optional<size_t>` is {`boost::none`, `0`, `1`, `2`, ...}. This order does not have a practical interpretation. The goal is to have any semantically correct default ordering in order for `optional<T>` to be usable in ordered associative containers (wherever `T` is usable).
 
 Mixed relational operators are the only case where the contained value of an optional object can be inspected without the usage of value accessing function (`operator*`, `value`, `value_or`).
 [endsect]

doc/17_gotchas.qbk

@@ -66,7 +66,7 @@ Quite a lot of people expect that when an object that contains a value is moved
 
 [section Mixed relational comparisons]
 
-Because `T` is convertible to `optional<T>` and because `optional<T>` is __SGI_LESS_THAN_COMPARABLE__ when `T` is __SGI_LESS_THAN_COMPARABLE__,
+Because `T` is convertible to `optional<T>` and because `optional<T>` is __STD_LESS_THAN_COMPARABLE__ when `T` is __STD_LESS_THAN_COMPARABLE__,
 you can sometimes get an unexpected runtime result where you would rather expect a compiler error:
 
     optional<double> Flight_plan::weight(); // sometimes no weight can be returned

doc/19_type_requirements.qbk

@@ -33,6 +33,6 @@ If `T` is `Moveable` (both __MOVE_CONSTRUCTIBLE__ and `MoveAssignable`) then `op
 
 Similarly, if `T` is `Copyable` (both __COPY_CONSTRUCTIBLE__ and `CopyAssignable`) then `optional<T>` is also `Copyable` and additionally can be constructed and assigned from an lvalue of type `T`.
 
-`T` ['is not] required to be __SGI_DEFAULT_CONSTRUCTIBLE__.
+`T` ['is not] required to be __STD_DEFAULT_CONSTRUCTIBLE__.
 
 [endsect]

doc/23_ref_optional_io.qbk

@@ -66,7 +66,7 @@ __SPACE__
  std::basic_ostream<CharType, CharTrait>&` [br]
  operator>>(std::basic_istream<CharType, CharTrait>& in, optional<T>& v);`
 
-* [*Requires:] `T` is __SGI_DEFAULT_CONSTRUCTIBLE__ and __MOVE_CONSTRUCTIBLE__.
+* [*Requires:] `T` is __STD_DEFAULT_CONSTRUCTIBLE__ and __MOVE_CONSTRUCTIBLE__.
 * [*Effect:] Reads the value of optional object from `in`. If the string representation indicates that the optional object should contain a value, `v` contains a value and its contained value is obtained as if by default-constructing an object `o` of type `T` and then calling `in >> o`; otherwise `v` does not contain a value, and the previously contained value (if any) has been destroyed.
 * [*Returns:] `out`.
 

doc/28_ref_optional_semantics.qbk

@@ -1216,7 +1216,7 @@ __SPACE__
 
 [: `bool operator == ( optional<T> const& x, optional<T> const& y );`]
 
-* [*Requires:] `T` shall meet requirements of __SGI_EQUALITY_COMPARABLE__.
+* [*Requires:] `T` shall meet requirements of __STD_EQUALITY_COMPARABLE__.
 * [*Returns:] If both `x` and `y` are initialized, `(*x == *y)`. If only
 `x` or `y` is initialized, `false`. If both are uninitialized, `true`.
 * [*Notes:] This definition guarantees that `optional<T>` not containing a value is compared unequal to any `optional<T>` containing any value, and equal to any other `optional<T>` not containing a value.
@@ -1249,7 +1249,7 @@ __SPACE__
 * [*Returns:] `(!y) ? false : (!x) ? true : *x < *y`.
 * [*Notes:] This definition guarantees that `optional<T>` not containing a value is ordered as less than any `optional<T>` containing any value, and equivalent to any other `optional<T>` not containing a value.
 Pointers have shallow relational operators while `optional` has deep relational operators. Do not use `operator<` directly in generic code
-which expect to be given either an `optional<T>` or a pointer; use __FUNCTION_LESS_POINTEES__ instead. `T` need not be __SGI_LESS_THAN_COMPARABLE__. Only single `operator<` is required. Other relational operations are defined in terms of this one. If `T`'s `operator<` satisfies the axioms of __SGI_LESS_THAN_COMPARABLE__ (transitivity, antisymmetry and irreflexivity), `optinal<T>` is __SGI_LESS_THAN_COMPARABLE__.
+which expect to be given either an `optional<T>` or a pointer; use __FUNCTION_LESS_POINTEES__ instead. `T` need not be __STD_LESS_THAN_COMPARABLE__. Only single `operator<` is required. Other relational operations are defined in terms of this one. If `T`'s `operator<` satisfies the axioms of __STD_LESS_THAN_COMPARABLE__ (transitivity, antisymmetry and irreflexivity), `optinal<T>` is __STD_LESS_THAN_COMPARABLE__.
 * [*Example:]
 ``
 optional<T> oN, oN_;
@@ -1310,7 +1310,7 @@ __SPACE__
 [: `bool operator == ( none_t, optional<T> const& x ) noexcept;`]
 
 * [*Returns:] `!x`.
-* [*Notes:] `T` need not meet requirements of __SGI_EQUALITY_COMPARABLE__.
+* [*Notes:] `T` need not meet requirements of __STD_EQUALITY_COMPARABLE__.
 
 
 __SPACE__