• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1[/
2Copyright 2017-2018 Glen Joseph Fernandes
3(glenjofe@gmail.com)
4
5Distributed under the Boost Software License, Version 1.0.
6(http://www.boost.org/LICENSE_1_0.txt)
7]
8
9[section:pointer_traits pointer_traits]
10
11[simplesect Authors]
12
13* Glen Fernandes
14
15[endsimplesect]
16
17[section Overview]
18
19The header <boost/core/pointer_traits.hpp> provides the class template
20`boost::pointer_traits` to facilitate use of pointer-like types. The C++11
21standard library introduced `std::pointer_traits` along with an allocator
22model which supported pointer-like types in addition to plain raw pointers.
23This implementation also supports C++98.
24
25It also provides the function template `boost::to_address` to obtain a raw
26pointer from an object of any pointer-like type.
27
28[endsect]
29
30[section Examples]
31
32The following example allocates storage and constructs an object in that
33storage using an allocator.
34
35```
36template<class Allocator>
37void function(Allocator& a)
38{
39    auto p = a.allocate(1);
40    std::allocator_traits<Allocator>::construct(a, boost::to_address(p));
41}
42```
43
44[endsect]
45
46[section Reference]
47
48```
49namespace boost {
50  template<class T> struct pointer_traits {
51    typedef T pointer;
52    typedef ``['see below]`` element_type;
53    typedef ``['see below]`` difference_type;
54
55    template<class U> struct rebind_to { typedef ``['see below]`` type; };
56    template<class U> using rebind = typename rebind_to<U>::type;
57
58    static pointer pointer_to(``['see below]`` v);
59  };
60
61  template<class T> struct pointer_traits<T*> {
62    typedef T* pointer;
63    typedef T element_type;
64    typedef std::ptrdiff_t difference_type;
65
66    template<class U> struct rebind_to { typedef U* type; };
67    template<class U> using rebind = typename rebind_to<U>::type;
68
69    static pointer pointer_to(``['see below]`` v) noexcept;
70  };
71
72  template<class T>
73  constexpr T* to_address(T* v) noexcept;
74
75  template<class T>
76  auto to_address(const T& v) noexcept;
77}
78```
79
80[section Member types]
81
82[variablelist
83[[`typedef` ['see below] `element_type;`]
84[`T::element_type` if such a type exists; otherwise `U` if `T` is a class
85  template instantiation of the form `Pointer<U, Args>`, where `Args` is zero
86  or more type arguments; otherwise the specialization is ill-formed.]]
87[[`typedef` ['see below] `difference_type;`]
88[`T::difference_type` if such a type exists; otherwise `std::ptrdiff_t`.]]
89[[`template<class U> struct rebind_to { typedef` ['see below] `type; };`]
90[`type` is `T::rebind<U>` if such a type exists; otherwise, `Pointer<V, Args>`
91  if `T` is a class template instantiation of the form `Pointer<T, Args>`,
92  where `Args` is zero or more type arguments; otherwise, the instantiation of
93  `rebind_to` is ill-formed.]]]
94
95[endsect]
96
97[section Member functions]
98
99[variablelist
100[[`static pointer pointer_traits::pointer_to(`['see below] `v);`]
101[[variablelist
102[[Remark]
103[If `element_type` is a void type, the type of `v` is unspecified; otherwise,
104  it is `element_type&`.]]
105[[Returns]
106[A pointer to `v` obtained by calling `T::pointer_to(v)`.]]]]]
107[[`static pointer pointer_traits<T*>::pointer_to(`['see below] `v) noexcept;`]
108[[variablelist
109[[Remark]
110[If `element_type` is a void type, the type of `v` is unspecified; otherwise,
111  it is `element_type&`.]]
112[[Returns][`addressof(v)`.]]]]]]
113
114[endsect]
115
116[section Optional members]
117
118[variablelist
119[[`static element_type* to_address(pointer v) noexcept;`]
120[[variablelist
121[[Returns]
122[A pointer of type `element_type*` that references the same location as the
123  argument `p`.]]
124[[Note]
125[This function should be the inverse of `pointer_to`. If defined, it
126  customizes the behavior of the non-member function `to_address`.]]]]]]
127
128[endsect]
129
130[section Free functions]
131
132[variablelist
133[[`template<class T> constexpr T* to_address(T* v) noexcept;`]
134[[variablelist
135[[Returns][`v`.]]]]]
136[[`template<class T> auto to_address(const T& v) noexcept;`]
137[[variablelist
138[[Returns][`pointer_traits<T>::to_address(v)` if that
139  expression is well-formed, otherwise `to_address(v.operator->())`.]]]]]]
140
141[endsect]
142
143[endsect]
144
145[section Acknowledgments]
146
147Glen Fernandes implemented `pointer_traits` and `to_address` with reviews and
148guidance from Peter Dimov.
149
150[endsect]
151
152[endsect]
153