Add documentation for empty_value

doc/core.qbk

@@ -41,6 +41,7 @@ criteria for inclusion is that the utility component be:
 [include addressof.qbk]
 [include checked_delete.qbk]
 [include demangle.qbk]
+[include empty_value.qbk]
 [include enable_if.qbk]
 [include exchange.qbk]
 [include explicit_operator_bool.qbk]

doc/empty_value.qbk

@@ -0,0 +1,123 @@
+[/
+Copyright 2018 Glen Joseph Fernandes
+(glenjofe@gmail.com)
+
+Distributed under the Boost Software License, Version 1.0.
+(http://www.boost.org/LICENSE_1_0.txt)
+]
+
+[section:empty_value empty_value]
+
+[simplesect Authors]
+
+* Glen Fernandes
+
+[endsimplesect]
+
+[section Overview]
+
+The header <boost/core/empty_value.hpp> provides the class template
+`boost::empty_value` for library authors to conveniently leverage the Empty
+Base Optimization to store objects of potentially empty types.
+
+[endsect]
+
+[section Examples]
+
+The following example shows `boost::empty_value` used to create a type that
+stores a pointer, comparer, and allocator, where the comparer and allocator
+could be empty types.
+
+```
+template<class Ptr, class Compare, class Allocator>
+class storage
+    : empty_value<Compare, 0>
+    , empty_value<Allocator, 1> {
+public:
+    storage()
+        : empty_value<Compare, 0>(empty_init_t())
+        , empty_value<Allocator, 1>(empty_init_t())
+        , ptr_() { }
+
+    storage(const Compare& c, const Allocator& a)
+        : empty_value<Compare, 0>(empty_init_t(), c)
+        , empty_value<Allocator, 1>(empty_init_t(), a)
+        , ptr_() { }
+
+    const Ptr& pointer() const
+    { return ptr_; }
+
+    Ptr& pointer()
+    { return ptr_; }
+
+    const Compare& compare() const
+    { return empty_value<Compare, 0>::get(); }
+
+    Compare& compare()
+    { return empty_value<Compare, 0>::get(); }
+
+    const Allocator& allocator() const
+    { return empty_value<Allocator, 1>::get(); }
+
+    Allocator& allocator()
+    { return empty_value<Allocator, 1>::get(); }
+
+private:
+    Ptr ptr_;
+};
+```
+
+[endsect]
+
+[section Reference]
+
+```
+namespace boost {
+
+struct empty_init_t { };
+
+template<class T, unsigned Index = 0, bool Empty = ``/see below/``>
+class empty_value {
+public:
+    empty_value() = default;
+
+    template<class... Args>
+    explicit empty_value(empty_init_t, Args&&... args);
+
+    const T& get() const;
+
+    T& get();
+};
+
+} /* boost */
+```
+
+[section Template parameters]
+
+[variablelist
+[[`T`][The type of value to store]]
+[[`Index`][Optional: Specify to create a distinct base type]]
+[[`Empty`][Optional: Specify to force inheritance from type]]]
+
+[endsect]
+
+[section Constructors]
+
+[variablelist
+[[`empty_value() = default;`][Default initialize the value]]
+[[`template<class... Args> empty_value(empty_init_t, Args&&... args);`]
+[Initialize the value with `std::forward<Args>(args)...`]]]
+
+[endsect]
+
+[section Member functions]
+
+[variablelist
+[[`const T& get() const;`][Returns the value]]
+[[`T& get();`][Returns the value]]]
+
+[endsect]
+
+[endsect]
+
+[endsect]

include/boost/core/empty_value.hpp

@@ -55,7 +55,7 @@ public:
 #if !defined(BOOST_NO_CXX11_RVALUE_REFERENCES)
 #if !defined(BOOST_NO_CXX11_VARIADIC_TEMPLATES)
     template<class... Args>
-    empty_value(empty_init_t, Args&&... args)
+    explicit empty_value(empty_init_t, Args&&... args)
         : value_(std::forward<Args>(args)...) { }
 #else
     template<class U>
@@ -97,7 +97,7 @@ public:
 #if !defined(BOOST_NO_CXX11_RVALUE_REFERENCES)
 #if !defined(BOOST_NO_CXX11_VARIADIC_TEMPLATES)
     template<class... Args>
-    empty_value(empty_init_t, Args&&... args)
+    explicit empty_value(empty_init_t, Args&&... args)
         : T(std::forward<Args>(args)...) { }
 #else
     template<class U>