[/
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]