1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>pointer_traits</title> 5<link rel="stylesheet" href="../../../../../doc/src/boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../index.html" title="Chapter 1. Boost.Core"> 8<link rel="up" href="../index.html" title="Chapter 1. Boost.Core"> 9<link rel="prev" href="nvp.html" title="nvp"> 10<link rel="next" href="quick_exit.html" title="quick_exit"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<table cellpadding="2" width="100%"><tr> 14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td> 15<td align="center"><a href="../../../../../index.html">Home</a></td> 16<td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td> 17<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 18<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 19<td align="center"><a href="../../../../../more/index.htm">More</a></td> 20</tr></table> 21<hr> 22<div class="spirit-nav"> 23<a accesskey="p" href="nvp.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="quick_exit.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 27<a name="core.pointer_traits"></a><a class="link" href="pointer_traits.html" title="pointer_traits">pointer_traits</a> 28</h2></div></div></div> 29<div class="toc"><dl class="toc"> 30<dt><span class="section"><a href="pointer_traits.html#core.pointer_traits.overview">Overview</a></span></dt> 31<dt><span class="section"><a href="pointer_traits.html#core.pointer_traits.examples">Examples</a></span></dt> 32<dt><span class="section"><a href="pointer_traits.html#core.pointer_traits.reference">Reference</a></span></dt> 33<dt><span class="section"><a href="pointer_traits.html#core.pointer_traits.acknowledgments">Acknowledgments</a></span></dt> 34</dl></div> 35<div class="simplesect"> 36<div class="titlepage"><div><div><h3 class="title"> 37<a name="idm45312826996976"></a>Authors</h3></div></div></div> 38<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 39 Glen Fernandes 40 </li></ul></div> 41</div> 42<div class="section"> 43<div class="titlepage"><div><div><h3 class="title"> 44<a name="core.pointer_traits.overview"></a><a class="link" href="pointer_traits.html#core.pointer_traits.overview" title="Overview">Overview</a> 45</h3></div></div></div> 46<p> 47 The header <boost/core/pointer_traits.hpp> provides the class template 48 <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">pointer_traits</span></code> to facilitate use of pointer-like 49 types. The C++11 standard library introduced <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pointer_traits</span></code> 50 along with an allocator model which supported pointer-like types in addition 51 to plain raw pointers. This implementation also supports C++98. 52 </p> 53<p> 54 It also provides the function template <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">to_address</span></code> 55 to obtain a raw pointer from an object of any pointer-like type. 56 </p> 57</div> 58<div class="section"> 59<div class="titlepage"><div><div><h3 class="title"> 60<a name="core.pointer_traits.examples"></a><a class="link" href="pointer_traits.html#core.pointer_traits.examples" title="Examples">Examples</a> 61</h3></div></div></div> 62<p> 63 The following example allocates storage and constructs an object in that 64 storage using an allocator. 65 </p> 66<pre class="programlisting"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">Allocator</span><span class="special">></span> 67<span class="keyword">void</span> <span class="identifier">function</span><span class="special">(</span><span class="identifier">Allocator</span><span class="special">&</span> <span class="identifier">a</span><span class="special">)</span> 68<span class="special">{</span> 69 <span class="keyword">auto</span> <span class="identifier">p</span> <span class="special">=</span> <span class="identifier">a</span><span class="special">.</span><span class="identifier">allocate</span><span class="special">(</span><span class="number">1</span><span class="special">);</span> 70 <span class="identifier">std</span><span class="special">::</span><span class="identifier">allocator_traits</span><span class="special"><</span><span class="identifier">Allocator</span><span class="special">>::</span><span class="identifier">construct</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">to_address</span><span class="special">(</span><span class="identifier">p</span><span class="special">));</span> 71<span class="special">}</span> 72</pre> 73</div> 74<div class="section"> 75<div class="titlepage"><div><div><h3 class="title"> 76<a name="core.pointer_traits.reference"></a><a class="link" href="pointer_traits.html#core.pointer_traits.reference" title="Reference">Reference</a> 77</h3></div></div></div> 78<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span> <span class="special">{</span> 79 <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">struct</span> <span class="identifier">pointer_traits</span> <span class="special">{</span> 80 <span class="keyword">typedef</span> <span class="identifier">T</span> <span class="identifier">pointer</span><span class="special">;</span> 81 <span class="keyword">typedef</span> <span class="emphasis"><em>see below</em></span> <span class="identifier">element_type</span><span class="special">;</span> 82 <span class="keyword">typedef</span> <span class="emphasis"><em>see below</em></span> <span class="identifier">difference_type</span><span class="special">;</span> 83 84 <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">U</span><span class="special">></span> <span class="keyword">struct</span> <span class="identifier">rebind_to</span> <span class="special">{</span> <span class="keyword">typedef</span> <span class="emphasis"><em>see below</em></span> <span class="identifier">type</span><span class="special">;</span> <span class="special">};</span> 85 <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">U</span><span class="special">></span> <span class="keyword">using</span> <span class="identifier">rebind</span> <span class="special">=</span> <span class="keyword">typename</span> <span class="identifier">rebind_to</span><span class="special"><</span><span class="identifier">U</span><span class="special">>::</span><span class="identifier">type</span><span class="special">;</span> 86 87 <span class="keyword">static</span> <span class="identifier">pointer</span> <span class="identifier">pointer_to</span><span class="special">(</span><span class="emphasis"><em>see below</em></span> <span class="identifier">v</span><span class="special">);</span> 88 <span class="special">};</span> 89 90 <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">struct</span> <span class="identifier">pointer_traits</span><span class="special"><</span><span class="identifier">T</span><span class="special">*></span> <span class="special">{</span> 91 <span class="keyword">typedef</span> <span class="identifier">T</span><span class="special">*</span> <span class="identifier">pointer</span><span class="special">;</span> 92 <span class="keyword">typedef</span> <span class="identifier">T</span> <span class="identifier">element_type</span><span class="special">;</span> 93 <span class="keyword">typedef</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">ptrdiff_t</span> <span class="identifier">difference_type</span><span class="special">;</span> 94 95 <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">U</span><span class="special">></span> <span class="keyword">struct</span> <span class="identifier">rebind_to</span> <span class="special">{</span> <span class="keyword">typedef</span> <span class="identifier">U</span><span class="special">*</span> <span class="identifier">type</span><span class="special">;</span> <span class="special">};</span> 96 <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">U</span><span class="special">></span> <span class="keyword">using</span> <span class="identifier">rebind</span> <span class="special">=</span> <span class="keyword">typename</span> <span class="identifier">rebind_to</span><span class="special"><</span><span class="identifier">U</span><span class="special">>::</span><span class="identifier">type</span><span class="special">;</span> 97 98 <span class="keyword">static</span> <span class="identifier">pointer</span> <span class="identifier">pointer_to</span><span class="special">(</span><span class="emphasis"><em>see below</em></span> <span class="identifier">v</span><span class="special">)</span> <span class="keyword">noexcept</span><span class="special">;</span> 99 <span class="special">};</span> 100 101 <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> 102 <span class="keyword">constexpr</span> <span class="identifier">T</span><span class="special">*</span> <span class="identifier">to_address</span><span class="special">(</span><span class="identifier">T</span><span class="special">*</span> <span class="identifier">v</span><span class="special">)</span> <span class="keyword">noexcept</span><span class="special">;</span> 103 104 <span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> 105 <span class="keyword">auto</span> <span class="identifier">to_address</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">&</span> <span class="identifier">v</span><span class="special">)</span> <span class="keyword">noexcept</span><span class="special">;</span> 106<span class="special">}</span> 107</pre> 108<div class="section"> 109<div class="titlepage"><div><div><h4 class="title"> 110<a name="core.pointer_traits.reference.member_types"></a><a class="link" href="pointer_traits.html#core.pointer_traits.reference.member_types" title="Member types">Member 111 types</a> 112</h4></div></div></div> 113<div class="variablelist"> 114<p class="title"><b></b></p> 115<dl class="variablelist"> 116<dt><span class="term"><code class="computeroutput"><span class="keyword">typedef</span></code> <span class="emphasis"><em>see 117 below</em></span> <code class="computeroutput"><span class="identifier">element_type</span><span class="special">;</span></code></span></dt> 118<dd><p> 119 <code class="computeroutput"><span class="identifier">T</span><span class="special">::</span><span class="identifier">element_type</span></code> if such a type exists; 120 otherwise <code class="computeroutput"><span class="identifier">U</span></code> if <code class="computeroutput"><span class="identifier">T</span></code> is a class template instantiation 121 of the form <code class="computeroutput"><span class="identifier">Pointer</span><span class="special"><</span><span class="identifier">U</span><span class="special">,</span> <span class="identifier">Args</span><span class="special">></span></code>, where <code class="computeroutput"><span class="identifier">Args</span></code> 122 is zero or more type arguments; otherwise the specialization is ill-formed. 123 </p></dd> 124<dt><span class="term"><code class="computeroutput"><span class="keyword">typedef</span></code> <span class="emphasis"><em>see 125 below</em></span> <code class="computeroutput"><span class="identifier">difference_type</span><span class="special">;</span></code></span></dt> 126<dd><p> 127 <code class="computeroutput"><span class="identifier">T</span><span class="special">::</span><span class="identifier">difference_type</span></code> if such a type 128 exists; otherwise <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ptrdiff_t</span></code>. 129 </p></dd> 130<dt><span class="term"><code class="computeroutput"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">U</span><span class="special">></span> <span class="keyword">struct</span> 131 <span class="identifier">rebind_to</span> <span class="special">{</span> 132 <span class="keyword">typedef</span></code> <span class="emphasis"><em>see below</em></span> 133 <code class="computeroutput"><span class="identifier">type</span><span class="special">;</span> 134 <span class="special">};</span></code></span></dt> 135<dd><p> 136 <code class="computeroutput"><span class="identifier">type</span></code> is <code class="computeroutput"><span class="identifier">T</span><span class="special">::</span><span class="identifier">rebind</span><span class="special"><</span><span class="identifier">U</span><span class="special">></span></code> 137 if such a type exists; otherwise, <code class="computeroutput"><span class="identifier">Pointer</span><span class="special"><</span><span class="identifier">V</span><span class="special">,</span> <span class="identifier">Args</span><span class="special">></span></code> if <code class="computeroutput"><span class="identifier">T</span></code> 138 is a class template instantiation of the form <code class="computeroutput"><span class="identifier">Pointer</span><span class="special"><</span><span class="identifier">T</span><span class="special">,</span> <span class="identifier">Args</span><span class="special">></span></code>, where <code class="computeroutput"><span class="identifier">Args</span></code> 139 is zero or more type arguments; otherwise, the instantiation of 140 <code class="computeroutput"><span class="identifier">rebind_to</span></code> is ill-formed. 141 </p></dd> 142</dl> 143</div> 144</div> 145<div class="section"> 146<div class="titlepage"><div><div><h4 class="title"> 147<a name="core.pointer_traits.reference.member_functions"></a><a class="link" href="pointer_traits.html#core.pointer_traits.reference.member_functions" title="Member functions">Member 148 functions</a> 149</h4></div></div></div> 150<div class="variablelist"> 151<p class="title"><b></b></p> 152<dl class="variablelist"> 153<dt><span class="term"><code class="computeroutput"><span class="keyword">static</span> <span class="identifier">pointer</span> 154 <span class="identifier">pointer_traits</span><span class="special">::</span><span class="identifier">pointer_to</span><span class="special">(</span></code><span class="emphasis"><em>see 155 below</em></span> <code class="computeroutput"><span class="identifier">v</span><span class="special">);</span></code></span></dt> 156<dd><div class="variablelist"> 157<p class="title"><b></b></p> 158<dl class="variablelist"> 159<dt><span class="term">Remark</span></dt> 160<dd><p> 161 If <code class="computeroutput"><span class="identifier">element_type</span></code> 162 is a void type, the type of <code class="computeroutput"><span class="identifier">v</span></code> 163 is unspecified; otherwise, it is <code class="computeroutput"><span class="identifier">element_type</span><span class="special">&</span></code>. 164 </p></dd> 165<dt><span class="term">Returns</span></dt> 166<dd><p> 167 A pointer to <code class="computeroutput"><span class="identifier">v</span></code> 168 obtained by calling <code class="computeroutput"><span class="identifier">T</span><span class="special">::</span><span class="identifier">pointer_to</span><span class="special">(</span><span class="identifier">v</span><span class="special">)</span></code>. 169 </p></dd> 170</dl> 171</div></dd> 172<dt><span class="term"><code class="computeroutput"><span class="keyword">static</span> <span class="identifier">pointer</span> 173 <span class="identifier">pointer_traits</span><span class="special"><</span><span class="identifier">T</span><span class="special">*>::</span><span class="identifier">pointer_to</span><span class="special">(</span></code><span class="emphasis"><em>see 174 below</em></span> <code class="computeroutput"><span class="identifier">v</span><span class="special">)</span> 175 <span class="keyword">noexcept</span><span class="special">;</span></code></span></dt> 176<dd><div class="variablelist"> 177<p class="title"><b></b></p> 178<dl class="variablelist"> 179<dt><span class="term">Remark</span></dt> 180<dd><p> 181 If <code class="computeroutput"><span class="identifier">element_type</span></code> 182 is a void type, the type of <code class="computeroutput"><span class="identifier">v</span></code> 183 is unspecified; otherwise, it is <code class="computeroutput"><span class="identifier">element_type</span><span class="special">&</span></code>. 184 </p></dd> 185<dt><span class="term">Returns</span></dt> 186<dd><p> 187 <code class="computeroutput"><span class="identifier">addressof</span><span class="special">(</span><span class="identifier">v</span><span class="special">)</span></code>. 188 </p></dd> 189</dl> 190</div></dd> 191</dl> 192</div> 193</div> 194<div class="section"> 195<div class="titlepage"><div><div><h4 class="title"> 196<a name="core.pointer_traits.reference.optional_members"></a><a class="link" href="pointer_traits.html#core.pointer_traits.reference.optional_members" title="Optional members">Optional 197 members</a> 198</h4></div></div></div> 199<div class="variablelist"> 200<p class="title"><b></b></p> 201<dl class="variablelist"> 202<dt><span class="term"><code class="computeroutput"><span class="keyword">static</span> <span class="identifier">element_type</span><span class="special">*</span> <span class="identifier">to_address</span><span class="special">(</span><span class="identifier">pointer</span> 203 <span class="identifier">v</span><span class="special">)</span> 204 <span class="keyword">noexcept</span><span class="special">;</span></code></span></dt> 205<dd><div class="variablelist"> 206<p class="title"><b></b></p> 207<dl class="variablelist"> 208<dt><span class="term">Returns</span></dt> 209<dd><p> 210 A pointer of type <code class="computeroutput"><span class="identifier">element_type</span><span class="special">*</span></code> that references the same location 211 as the argument <code class="computeroutput"><span class="identifier">p</span></code>. 212 </p></dd> 213<dt><span class="term">Note</span></dt> 214<dd><p> 215 This function should be the inverse of <code class="computeroutput"><span class="identifier">pointer_to</span></code>. 216 If defined, it customizes the behavior of the non-member function 217 <code class="computeroutput"><span class="identifier">to_address</span></code>. 218 </p></dd> 219</dl> 220</div></dd> 221</dl> 222</div> 223</div> 224<div class="section"> 225<div class="titlepage"><div><div><h4 class="title"> 226<a name="core.pointer_traits.reference.free_functions"></a><a class="link" href="pointer_traits.html#core.pointer_traits.reference.free_functions" title="Free functions">Free 227 functions</a> 228</h4></div></div></div> 229<div class="variablelist"> 230<p class="title"><b></b></p> 231<dl class="variablelist"> 232<dt><span class="term"><code class="computeroutput"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">constexpr</span> 233 <span class="identifier">T</span><span class="special">*</span> 234 <span class="identifier">to_address</span><span class="special">(</span><span class="identifier">T</span><span class="special">*</span> <span class="identifier">v</span><span class="special">)</span> <span class="keyword">noexcept</span><span class="special">;</span></code></span></dt> 235<dd><div class="variablelist"> 236<p class="title"><b></b></p> 237<dl class="variablelist"> 238<dt><span class="term">Returns</span></dt> 239<dd><p> 240 <code class="computeroutput"><span class="identifier">v</span></code>. 241 </p></dd> 242</dl> 243</div></dd> 244<dt><span class="term"><code class="computeroutput"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> <span class="keyword">auto</span> <span class="identifier">to_address</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">T</span><span class="special">&</span> <span class="identifier">v</span><span class="special">)</span> <span class="keyword">noexcept</span><span class="special">;</span></code></span></dt> 245<dd><div class="variablelist"> 246<p class="title"><b></b></p> 247<dl class="variablelist"> 248<dt><span class="term">Returns</span></dt> 249<dd><p> 250 <code class="computeroutput"><span class="identifier">pointer_traits</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">to_address</span><span class="special">(</span><span class="identifier">v</span><span class="special">)</span></code> if that expression is well-formed, 251 otherwise <code class="computeroutput"><span class="identifier">to_address</span><span class="special">(</span><span class="identifier">v</span><span class="special">.</span><span class="keyword">operator</span><span class="special">->())</span></code>. 252 </p></dd> 253</dl> 254</div></dd> 255</dl> 256</div> 257</div> 258</div> 259<div class="section"> 260<div class="titlepage"><div><div><h3 class="title"> 261<a name="core.pointer_traits.acknowledgments"></a><a class="link" href="pointer_traits.html#core.pointer_traits.acknowledgments" title="Acknowledgments">Acknowledgments</a> 262</h3></div></div></div> 263<p> 264 Glen Fernandes implemented <code class="computeroutput"><span class="identifier">pointer_traits</span></code> 265 and <code class="computeroutput"><span class="identifier">to_address</span></code> with reviews 266 and guidance from Peter Dimov. 267 </p> 268</div> 269</div> 270<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 271<td align="left"></td> 272<td align="right"><div class="copyright-footer">Copyright © 2014 Peter Dimov<br>Copyright © 2014 Glen Fernandes<br>Copyright © 2014 Andrey Semashev<p> 273 Distributed under the <a href="http://boost.org/LICENSE_1_0.txt" target="_top">Boost 274 Software License, Version 1.0</a>. 275 </p> 276</div></td> 277</tr></table> 278<hr> 279<div class="spirit-nav"> 280<a accesskey="p" href="nvp.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.html"><img src="../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="quick_exit.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a> 281</div> 282</body> 283</html> 284
