Merge branch 'develop'

doc/core.qbk

@@ -49,6 +49,7 @@ criteria for inclusion is that the utility component be:
 [include no_exceptions_support.qbk]
 [include noncopyable.qbk]
 [include null_deleter.qbk]
+[include pointer_traits.qbk]
 [include ref.qbk]
 [include scoped_enum.qbk]
 [include swap.qbk]

doc/pointer_traits.qbk

@@ -0,0 +1,141 @@
+[/
+Copyright 2017 Glen Joseph Fernandes
+(glenjofe@gmail.com)
+
+Distributed under the Boost Software License, Version 1.0.
+(http://www.boost.org/LICENSE_1_0.txt)
+]
+
+[section:pointer_traits pointer_traits]
+
+[simplesect Authors]
+
+* Glen Fernandes
+
+[endsimplesect]
+
+[section Overview]
+
+The header <boost/core/pointer_traits.hpp> provides the class template
+`boost::pointer_traits` to facilitate use of pointer-like types. The C++11
+standard library introduced `std::pointer_traits` along with an allocator
+model which supported pointer-like types in addition to plain raw pointers.
+This implementation also supports C++98, and adds additional functionality
+for obtaining raw pointers from pointers.
+
+[endsect]
+
+[section Examples]
+
+The following function template obtains a raw pointer from a pointer and is
+well defined when the pointer aliases storage that has no object constructed
+in it.
+
+```
+template<class T>
+inline typename boost::pointer_traits<T>::element_type*
+to_raw_pointer(T v) noexcept
+{
+    return boost::pointer_traits<T>::to_address(v);
+}
+```
+
+[endsect]
+
+[section Reference]
+
+```
+namespace boost {
+  template<class T> struct pointer_traits {
+    typedef T pointer;
+    typedef ``['see below]`` element_type;
+    typedef ``['see below]`` difference_type;
+
+    template<class U> struct rebind_to { typedef ``['see below]`` type; };
+    template<class U> using rebind = typename rebind_to<U>::type;
+
+    static pointer pointer_to(``['see below]`` v);
+    static element_type* to_address(pointer v) noexcept;
+  };
+
+  template<class T> struct pointer_traits<T*> {
+    typedef T* pointer;
+    typedef T element_type;
+    typedef std::ptrdiff_t difference_type;
+
+    template<class U> struct rebind_to { typedef U* type; };
+    template<class U> using rebind = typename rebind_to<U>::type;
+
+    static pointer pointer_to(``['see below]`` v) noexcept;
+    static element_type* to_address(pointer v) noexcept;
+  };
+}
+```
+
+[section Member types]
+
+[variablelist
+  [[`typedef` ['see below] `element_type;`]
+    [[variablelist
+      [[Type]
+        [`T::element_type` if such a type exists; otherwise `U` if `T` is a
+          class template instantiation of the form `Pointer<U, Args>`, where
+          `Args` is zero or more type arguments; otherwise the specialization
+          is ill-formed.]]]]]
+  [[`typedef` ['see below] `difference_type;`]
+    [[variablelist
+      [[Type]
+        [`T::difference_type` if such a type exists; otherwise
+          `std::ptrdiff_t`.]]]]]
+  [[`template<class U> struct rebind_to { typedef` ['see below] `type; };`]
+    [[variablelist
+      [[Type]
+        [`type` is `T::rebind<U>` if such a type exists; otherwise,
+          `Pointer<V, Args>` if `T` is a class template instantiation of the
+          form `Pointer<T, Args>`, where `Args` is zero or more type
+          arguments; otherwise, the instantiation of `rebind_to` is
+          ill-formed.]]]]]]
+
+[endsect]
+
+[section Member functions]
+
+[variablelist pointer_traits
+  [[`static pointer pointer_to(`['see below] `v);`]
+    [[variablelist
+      [[Remark]
+        [If `element_type` is a void type, the type of `v` is unspecified;
+          otherwise, it is `element_type&`.]]
+      [[Returns]
+        [A pointer to `v` obtained by calling `T::pointer_to(v)`.]]]]]
+  [[`static element_type* to_address(pointer v) noexcept;`]
+    [[variablelist
+      [[Requires]
+        [`v` is not a null pointer.]]
+      [[Returns]
+        [A pointer of type `element_type*` that references the same location
+          as the argument.]]]]]]
+
+[variablelist pointer_traits<T*>
+  [[`static pointer pointer_to(`['see below] `v) noexcept;`]
+    [[variablelist
+      [[Remark]
+        [If `element_type` is a void type, the type of `v` is unspecified;
+          otherwise, it is `element_type&`.]]
+      [[Returns]
+        [The result of `std::addressof(v)`.]]]]]
+  [[`static element_type* to_address(pointer v) noexcept;`]
+    [[variablelist [[Returns] [The value of `v`.]]]]]]
+
+[endsect]
+
+[endsect]
+
+[section Acknowledgments]
+
+Glen Fernandes implemented `pointer_traits` with reviews and guidance from
+Peter Dimov.
+
+[endsect]
+
+[endsect]