From 87dd2883b81235b5fcf84ee311cb17428a1ac934 Mon Sep 17 00:00:00 2001
From: Glen Fernandes <glen.fernandes@gmail.com>
Date: Sat, 20 May 2017 09:29:01 -0400
Subject: [PATCH] Add pointer_traits documentation

---
 doc/core.qbk           |   1 +
 doc/pointer_traits.qbk | 133 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 134 insertions(+)
 create mode 100644 doc/pointer_traits.qbk

diff --git a/doc/core.qbk b/doc/core.qbk
index 1f2bcf8..5382bf6 100644
--- a/doc/core.qbk
+++ b/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]
diff --git a/doc/pointer_traits.qbk b/doc/pointer_traits.qbk
new file mode 100644
index 0000000..703eb16
--- /dev/null
+++ b/doc/pointer_traits.qbk
@@ -0,0 +1,133 @@
+[/
+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 can obtaining a raw pointer from a pointer,
+which works with null pointers and also 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;
+  };
+}
+```
+
+[heading Member types]
+
+[ordered_list
+  [`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.]]]]]
+
+[heading Member functions]
+
+[ordered_list
+  [`static pointer pointer_traits::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 pointer pointer_traits<T*>::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* pointer_traits::to_address(pointer v) noexcept;`
+    [variablelist
+      [[Returns]
+        [A plain pointer of type `element_type*` obtained by calling
+          `pointer_traits::to_address` on the value of `v.operator->()`.]]]]
+  [`static element_type* pointer_traits<T*>::to_address(pointer v) noexcept;`
+    [variablelist [[Returns] [The value of `v`.]]]]]
+
+[endsect]
+
+[section Acknowledgments]
+
+Glen Fernandes implemented `pointer_traits` with reviews and guidance from
+Peter Dimov.
+
+[endsect]
+
+[endsect]