123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152 |
- [/
- Copyright 2017-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: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.
- It also provides the function template `boost::to_address` to obtain a raw
- pointer from an object of any pointer-like type.
- [endsect]
- [section Examples]
- The following example allocates storage and constructs an object in that
- storage using an allocator.
- ```
- template<class Allocator>
- void function(Allocator& a)
- {
- auto p = a.allocate(1);
- std::allocator_traits<Allocator>::construct(a, boost::to_address(p));
- }
- ```
- [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);
- };
- 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;
- };
- template<class T>
- constexpr T* to_address(T* v) noexcept;
- template<class T>
- auto to_address(const T& v) noexcept;
- }
- ```
- [section Member types]
- [variablelist
- [[`typedef` ['see below] `element_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;`]
- [`T::difference_type` if such a type exists; otherwise `std::ptrdiff_t`.]]
- [[`template<class U> struct rebind_to { typedef` ['see below] `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
- [[`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][`addressof(v)`.]]]]]]
- [endsect]
- [section Optional members]
- [variablelist
- [[`static element_type* to_address(pointer v) noexcept;`]
- [[variablelist
- [[Returns]
- [A pointer of type `element_type*` that references the same location as the
- argument `p`.]]
- [[Note]
- [This function should be the inverse of `pointer_to`. If defined, it
- customizes the behavior of the non-member function `to_address`.]]]]]]
- [endsect]
- [section Free functions]
- [variablelist
- [[`template<class T> constexpr T* to_address(T* v) noexcept;`]
- [[variablelist
- [[Returns][`v`.]]]]]
- [[`template<class T> auto to_address(const T& v) noexcept;`]
- [[variablelist
- [[Returns][`pointer_traits<T>::to_address(v)` if that
- expression is well-formed, otherwise `to_address(v.operator->())`.]]]]]]
- [endsect]
- [endsect]
- [section Acknowledgments]
- Glen Fernandes implemented `pointer_traits` and `to_address` with reviews and
- guidance from Peter Dimov.
- [endsect]
- [endsect]
|