1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<head> 4<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 5<title>Extended functionality: Configurable containers</title> 6<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> 7<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 8<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> 9<link rel="up" href="../container.html" title="Chapter 9. Boost.Container"> 10<link rel="prev" href="extended_functionality.html" title="Extended functionality: Basic extensions"> 11<link rel="next" href="extended_allocators.html" title="Extended functionality: Extended allocators"> 12</head> 13<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 14<table cellpadding="2" width="100%"><tr> 15<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td> 16<td align="center"><a href="../../../index.html">Home</a></td> 17<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> 18<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 19<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 20<td align="center"><a href="../../../more/index.htm">More</a></td> 21</tr></table> 22<hr> 23<div class="spirit-nav"> 24<a accesskey="p" href="extended_functionality.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../container.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="extended_allocators.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> 25</div> 26<div class="section"> 27<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 28<a name="container.configurable_containers"></a><a class="link" href="configurable_containers.html" title="Extended functionality: Configurable containers">Extended functionality: 29 Configurable containers</a> 30</h2></div></div></div> 31<div class="toc"><dl class="toc"> 32<dt><span class="section"><a href="configurable_containers.html#container.configurable_containers.configurable_tree_based_associative_containers">Configurable 33 tree-based associative ordered containers</a></span></dt> 34<dt><span class="section"><a href="configurable_containers.html#container.configurable_containers.configurable_vectors">Configurable 35 vectors</a></span></dt> 36<dt><span class="section"><a href="configurable_containers.html#container.configurable_containers.configurable_deques">Configurable 37 deques</a></span></dt> 38<dt><span class="section"><a href="configurable_containers.html#container.configurable_containers.configurable_static_vectors">Configurable 39 static vector</a></span></dt> 40<dt><span class="section"><a href="configurable_containers.html#container.configurable_containers.configurable_small_vectors">Configurable 41 small vector</a></span></dt> 42</dl></div> 43<p> 44 <span class="bold"><strong>Boost.Container</strong></span> offers the possibility to 45 configure at compile time some parameters of several containers, apart from 46 the stored type and the allocator. This configuration is passed as the last 47 template parameter and defined using the utility classes. The following containers 48 can receive useful configuration options: 49 </p> 50<div class="section"> 51<div class="titlepage"><div><div><h3 class="title"> 52<a name="container.configurable_containers.configurable_tree_based_associative_containers"></a><a class="link" href="configurable_containers.html#container.configurable_containers.configurable_tree_based_associative_containers" title="Configurable tree-based associative ordered containers">Configurable 53 tree-based associative ordered containers</a> 54</h3></div></div></div> 55<p> 56 <code class="computeroutput"><a class="link" href="../boost/container/set.html" title="Class template set">set</a></code>, <code class="computeroutput"><a class="link" href="../boost/container/multiset.html" title="Class template multiset">multiset</a></code>, 57 <code class="computeroutput"><a class="link" href="../boost/container/map.html" title="Class template map">map</a></code> and <code class="computeroutput"><a class="link" href="../boost/container/multimap.html" title="Class template multimap">multimap</a></code> 58 associative containers are implemented as binary search trees which offer 59 the needed complexity and stability guarantees required by the C++ standard 60 for associative containers. 61 </p> 62<p> 63 <span class="bold"><strong>Boost.Container</strong></span> offers the possibility to 64 configure at compile time some parameters of the binary search tree implementation. 65 This configuration is passed as the last template parameter and defined using 66 the utility class <code class="computeroutput"><a class="link" href="../boost/container/tree_assoc_options.html" title="Struct template tree_assoc_options">tree_assoc_options</a></code>. 67 The following parameters can be configured: 68 </p> 69<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 70<li class="listitem"> 71 The underlying <span class="bold"><strong>tree implementation</strong></span> type 72 (<code class="computeroutput"><a class="link" href="../boost/container/tree_type.html" title="Struct template tree_type">tree_type</a></code>). 73 By default these containers use a red-black tree but the user can use 74 other tree types: 75 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "> 76<li class="listitem"> 77 <a href="http://en.wikipedia.org/wiki/Red%E2%80%93black_tree" target="_top">Red-Black 78 Tree</a> 79 </li> 80<li class="listitem"> 81 <a href="http://en.wikipedia.org/wiki/Avl_trees" target="_top">AVL tree</a> 82 </li> 83<li class="listitem"> 84 <a href="http://en.wikipedia.org/wiki/Scapegoat_tree" target="_top">Scapegoat 85 tree</a>. In this case Insertion and Deletion are amortized 86 O(log n) instead of O(log n). 87 </li> 88<li class="listitem"> 89 <a href="http://en.wikipedia.org/wiki/Splay_tree" target="_top">Splay tree</a>. 90 In this case Searches, Insertions and Deletions are amortized O(log 91 n) instead of O(log n). 92 </li> 93</ul></div> 94 </li> 95<li class="listitem"> 96 Whether the <span class="bold"><strong>size saving</strong></span> mechanisms are 97 used to implement the tree nodes (<code class="computeroutput"><a class="link" href="../boost/container/optimize_size.html" title="Struct template optimize_size">optimize_size</a></code>). 98 By default this option is activated and is only meaningful to red-black 99 and avl trees (in other cases, this option will be ignored). This option 100 will try to put rebalancing metadata inside the "parent" pointer 101 of the node if the pointer type has enough alignment. Usually, due to 102 alignment issues, the metadata uses the size of a pointer yielding to 103 four pointer size overhead per node, whereas activating this option usually 104 leads to 3 pointer size overhead. Although some mask operations must 105 be performed to extract data from this special "parent" pointer, 106 in several systems this option also improves performance due to the improved 107 cache usage produced by the node size reduction. 108 </li> 109</ul></div> 110<p> 111 See the following example to see how <code class="computeroutput"><a class="link" href="../boost/container/tree_assoc_options.html" title="Struct template tree_assoc_options">tree_assoc_options</a></code> 112 can be used to customize these containers: 113 </p> 114<p> 115</p> 116<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">container</span><span class="special">/</span><span class="identifier">set</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 117 118<span class="comment">//Make sure assertions are active</span> 119<span class="preprocessor">#ifdef</span> <span class="identifier">NDEBUG</span> 120<span class="preprocessor">#undef</span> <span class="identifier">NDEBUG</span> 121<span class="preprocessor">#endif</span> 122<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">cassert</span><span class="special">></span> 123 124<span class="keyword">int</span> <span class="identifier">main</span> <span class="special">()</span> 125<span class="special">{</span> 126 <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">container</span><span class="special">;</span> 127 128 <span class="comment">//First define several options</span> 129 <span class="comment">//</span> 130 131 <span class="comment">//This option specifies an AVL tree based associative container</span> 132 <span class="keyword">typedef</span> <span class="identifier">tree_assoc_options</span><span class="special"><</span> <span class="identifier">tree_type</span><span class="special"><</span><span class="identifier">avl_tree</span><span class="special">></span> <span class="special">>::</span><span class="identifier">type</span> <span class="identifier">AVLTree</span><span class="special">;</span> 133 134 <span class="comment">//This option specifies an AVL tree based associative container</span> 135 <span class="comment">//disabling node size optimization.</span> 136 <span class="keyword">typedef</span> <span class="identifier">tree_assoc_options</span><span class="special"><</span> <span class="identifier">tree_type</span><span class="special"><</span><span class="identifier">avl_tree</span><span class="special">></span> 137 <span class="special">,</span> <span class="identifier">optimize_size</span><span class="special"><</span><span class="keyword">false</span><span class="special">></span> <span class="special">>::</span><span class="identifier">type</span> <span class="identifier">AVLTreeNoSizeOpt</span><span class="special">;</span> 138 139 <span class="comment">//This option specifies an Splay tree based associative container</span> 140 <span class="keyword">typedef</span> <span class="identifier">tree_assoc_options</span><span class="special"><</span> <span class="identifier">tree_type</span><span class="special"><</span><span class="identifier">splay_tree</span><span class="special">></span> <span class="special">>::</span><span class="identifier">type</span> <span class="identifier">SplayTree</span><span class="special">;</span> 141 142 <span class="comment">//Now define new tree-based associative containers</span> 143 <span class="comment">//</span> 144 145 <span class="comment">//AVLTree based set container</span> 146 <span class="keyword">typedef</span> <span class="identifier">set</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">less</span><span class="special"><</span><span class="keyword">int</span><span class="special">>,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">allocator</span><span class="special"><</span><span class="keyword">int</span><span class="special">>,</span> <span class="identifier">AVLTree</span><span class="special">></span> <span class="identifier">AvlSet</span><span class="special">;</span> 147 148 <span class="comment">//AVLTree based set container without size optimization</span> 149 <span class="keyword">typedef</span> <span class="identifier">set</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">less</span><span class="special"><</span><span class="keyword">int</span><span class="special">>,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">allocator</span><span class="special"><</span><span class="keyword">int</span><span class="special">>,</span> <span class="identifier">AVLTreeNoSizeOpt</span><span class="special">></span> <span class="identifier">AvlSetNoSizeOpt</span><span class="special">;</span> 150 151 <span class="comment">//Splay tree based multiset container</span> 152 <span class="keyword">typedef</span> <span class="identifier">multiset</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">less</span><span class="special"><</span><span class="keyword">int</span><span class="special">>,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">allocator</span><span class="special"><</span><span class="keyword">int</span><span class="special">>,</span> <span class="identifier">SplayTree</span><span class="special">></span> <span class="identifier">SplayMultiset</span><span class="special">;</span> 153 154 <span class="comment">//Use them</span> 155 <span class="comment">//</span> 156 <span class="identifier">AvlSet</span> <span class="identifier">avl_set</span><span class="special">;</span> 157 <span class="identifier">avl_set</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span><span class="number">0</span><span class="special">);</span> 158 <span class="identifier">assert</span><span class="special">(</span><span class="identifier">avl_set</span><span class="special">.</span><span class="identifier">find</span><span class="special">(</span><span class="number">0</span><span class="special">)</span> <span class="special">!=</span> <span class="identifier">avl_set</span><span class="special">.</span><span class="identifier">end</span><span class="special">());</span> 159 160 <span class="identifier">AvlSetNoSizeOpt</span> <span class="identifier">avl_set_no_szopt</span><span class="special">;</span> 161 <span class="identifier">avl_set_no_szopt</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span><span class="number">1</span><span class="special">);</span> 162 <span class="identifier">avl_set_no_szopt</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span><span class="number">1</span><span class="special">);</span> 163 <span class="identifier">assert</span><span class="special">(</span><span class="identifier">avl_set_no_szopt</span><span class="special">.</span><span class="identifier">count</span><span class="special">(</span><span class="number">1</span><span class="special">)</span> <span class="special">==</span> <span class="number">1</span><span class="special">);</span> 164 165 <span class="identifier">SplayMultiset</span> <span class="identifier">splay_mset</span><span class="special">;</span> 166 <span class="identifier">splay_mset</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span><span class="number">2</span><span class="special">);</span> 167 <span class="identifier">splay_mset</span><span class="special">.</span><span class="identifier">insert</span><span class="special">(</span><span class="number">2</span><span class="special">);</span> 168 <span class="identifier">assert</span><span class="special">(</span><span class="identifier">splay_mset</span><span class="special">.</span><span class="identifier">count</span><span class="special">(</span><span class="number">2</span><span class="special">)</span> <span class="special">==</span> <span class="number">2</span><span class="special">);</span> 169 <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> 170<span class="special">}</span> 171</pre> 172<p> 173 </p> 174</div> 175<div class="section"> 176<div class="titlepage"><div><div><h3 class="title"> 177<a name="container.configurable_containers.configurable_vectors"></a><a class="link" href="configurable_containers.html#container.configurable_containers.configurable_vectors" title="Configurable vectors">Configurable 178 vectors</a> 179</h3></div></div></div> 180<p> 181 The configuration for <code class="computeroutput"><a class="link" href="../boost/container/vector.html" title="Class template vector">vector</a></code> 182 is passed as the last template parameter and defined using the utility class 183 <code class="computeroutput"><a class="link" href="../boost/container/vector_options.html" title="Struct template vector_options">vector_options</a></code>. 184 The following parameters can be configured: 185 </p> 186<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 187<li class="listitem"> 188 <code class="computeroutput"><a class="link" href="../boost/container/growth_factor.html" title="Struct template growth_factor">growth_factor</a></code>: 189 the growth policy of the vector. The rate at which the capacity of a 190 vector grows is implementation dependent and implementations choose exponential 191 growth in order to meet the amortized constant time requirement for push_back. 192 A higher growth factor will make it faster as it will require less data 193 movement, but it will have a greater memory impact (on average, more 194 memory will be unused). A user can provide a custom implementation of 195 the growth factor and some predefined policies are available: <code class="computeroutput"><a class="link" href="../boost/container/growth_factor_50.html" title="Struct growth_factor_50">growth_factor_50</a></code>, 196 <code class="computeroutput"><a class="link" href="../boost/container/growth_factor_60.html" title="Struct growth_factor_60">growth_factor_60</a></code> 197 and <code class="computeroutput"><a class="link" href="../boost/container/growth_factor_50.html" title="Struct growth_factor_50">growth_factor_100</a></code>. 198 </li> 199<li class="listitem"> 200 <code class="computeroutput"><a class="link" href="../boost/container/stored_size.html" title="Struct template stored_size">stored_size</a></code>: 201 the type that will be used to store size-related parameters inside of 202 the vector. Sometimes, when the maximum capacity to be used is much less 203 than the theoretical maximum that a vector can hold, it's interesting 204 to use smaller unsigned integer types to represent <code class="computeroutput"><span class="identifier">size</span><span class="special">()</span></code> and <code class="computeroutput"><span class="identifier">capacity</span><span class="special">()</span></code> inside vector, so that the size of 205 an empty vector is minimized and cache performance might be improved. 206 See <code class="computeroutput"><a class="link" href="../boost/container/stored_size.html" title="Struct template stored_size">stored_size</a></code> 207 for more details. 208 </li> 209</ul></div> 210<p> 211 See the following example to see how <code class="computeroutput"><a class="link" href="../boost/container/vector_options.html" title="Struct template vector_options">vector_options</a></code> 212 can be used to customize <code class="computeroutput"><span class="identifier">vector</span></code> 213 container: 214 </p> 215<p> 216</p> 217<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">container</span><span class="special">/</span><span class="identifier">vector</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 218<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="keyword">static_assert</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 219 220<span class="comment">//Make sure assertions are active</span> 221<span class="preprocessor">#ifdef</span> <span class="identifier">NDEBUG</span> 222<span class="preprocessor">#undef</span> <span class="identifier">NDEBUG</span> 223<span class="preprocessor">#endif</span> 224<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">cassert</span><span class="special">></span> 225 226<span class="keyword">int</span> <span class="identifier">main</span> <span class="special">()</span> 227<span class="special">{</span> 228 <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">container</span><span class="special">;</span> 229 230 <span class="comment">//This option specifies that a vector that will use "unsigned char" as</span> 231 <span class="comment">//the type to store capacity or size internally.</span> 232 <span class="keyword">typedef</span> <span class="identifier">vector_options</span><span class="special"><</span> <span class="identifier">stored_size</span><span class="special"><</span><span class="keyword">unsigned</span> <span class="keyword">char</span><span class="special">></span> <span class="special">>::</span><span class="identifier">type</span> <span class="identifier">size_option_t</span><span class="special">;</span> 233 234 <span class="comment">//Size-optimized vector is smaller than the default one.</span> 235 <span class="keyword">typedef</span> <span class="identifier">vector</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">new_allocator</span><span class="special"><</span><span class="keyword">int</span><span class="special">>,</span> <span class="identifier">size_option_t</span> <span class="special">></span> <span class="identifier">size_optimized_vector_t</span><span class="special">;</span> 236 <span class="identifier">BOOST_STATIC_ASSERT</span><span class="special">((</span> <span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">size_optimized_vector_t</span><span class="special">)</span> <span class="special"><</span> <span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">vector</span><span class="special"><</span><span class="keyword">int</span><span class="special">>)</span> <span class="special">));</span> 237 238 <span class="comment">//Requesting capacity for more elements than representable by "unsigned char"</span> 239 <span class="comment">//is an error in the size optimized vector.</span> 240 <span class="keyword">bool</span> <span class="identifier">exception_thrown</span> <span class="special">=</span> <span class="keyword">false</span><span class="special">;</span> 241 <span class="keyword">try</span> <span class="special">{</span> <span class="identifier">size_optimized_vector_t</span> <span class="identifier">v</span><span class="special">(</span><span class="number">256</span><span class="special">);</span> <span class="special">}</span> 242 <span class="keyword">catch</span><span class="special">(...){</span> <span class="identifier">exception_thrown</span> <span class="special">=</span> <span class="keyword">true</span><span class="special">;</span> <span class="special">}</span> 243 <span class="identifier">assert</span><span class="special">(</span><span class="identifier">exception_thrown</span> <span class="special">==</span> <span class="keyword">true</span><span class="special">);</span> 244 245 <span class="comment">//This option specifies that a vector will increase its capacity 50%</span> 246 <span class="comment">//each time the previous capacity was exhausted.</span> 247 <span class="keyword">typedef</span> <span class="identifier">vector_options</span><span class="special"><</span> <span class="identifier">growth_factor</span><span class="special"><</span><span class="identifier">growth_factor_50</span><span class="special">></span> <span class="special">>::</span><span class="identifier">type</span> <span class="identifier">growth_50_option_t</span><span class="special">;</span> 248 249 <span class="comment">//Fill the vector until full capacity is reached</span> 250 <span class="identifier">vector</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">new_allocator</span><span class="special"><</span><span class="keyword">int</span><span class="special">>,</span> <span class="identifier">growth_50_option_t</span> <span class="special">></span> <span class="identifier">growth_50_vector</span><span class="special">(</span><span class="number">5</span><span class="special">,</span> <span class="number">0</span><span class="special">);</span> 251 <span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">old_cap</span> <span class="special">=</span> <span class="identifier">growth_50_vector</span><span class="special">.</span><span class="identifier">capacity</span><span class="special">();</span> 252 <span class="identifier">growth_50_vector</span><span class="special">.</span><span class="identifier">resize</span><span class="special">(</span><span class="identifier">old_cap</span><span class="special">);</span> 253 254 <span class="comment">//Now insert an additional item and check the new buffer is 50% bigger</span> 255 <span class="identifier">growth_50_vector</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">1</span><span class="special">);</span> 256 <span class="identifier">assert</span><span class="special">(</span><span class="identifier">growth_50_vector</span><span class="special">.</span><span class="identifier">capacity</span><span class="special">()</span> <span class="special">==</span> <span class="identifier">old_cap</span><span class="special">*</span><span class="number">3</span><span class="special">/</span><span class="number">2</span><span class="special">);</span> 257 258 <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> 259<span class="special">}</span> 260</pre> 261<p> 262 </p> 263</div> 264<div class="section"> 265<div class="titlepage"><div><div><h3 class="title"> 266<a name="container.configurable_containers.configurable_deques"></a><a class="link" href="configurable_containers.html#container.configurable_containers.configurable_deques" title="Configurable deques">Configurable 267 deques</a> 268</h3></div></div></div> 269<p> 270 The configuration for <code class="computeroutput"><a class="link" href="../boost/container/deque.html" title="Class template deque">deque</a></code> 271 is passed as the last template parameter and defined using the utility class 272 <code class="computeroutput"><a class="link" href="../boost/container/deque_options.html" title="Struct template deque_options">deque_options</a></code>. 273 The following parameters can be configured: 274 </p> 275<p> 276 Parameters that control the size of deque's 'block' (deque allocates contiguous 277 chunks of elements, called 'blocks'). Only one of these paratemers can be 278 specified: 279 </p> 280<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 281<li class="listitem"> 282 <code class="computeroutput"><a class="link" href="../boost/container/block_bytes.html" title="Struct template block_bytes">block_bytes</a></code>: 283 the number of bytes deque will allocate for store elements contiguously: 284 <code class="computeroutput"><span class="identifier">deque</span><span class="special">::</span><span class="identifier">get_block_size</span><span class="special">()</span></code> 285 will return aproximately <code class="computeroutput"><span class="identifier">block_bytes</span><span class="special">/</span><span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">value_type</span><span class="special">)</span></code>. A value of zero means the default value. 286 </li> 287<li class="listitem"> 288 <code class="computeroutput"><a class="link" href="../boost/container/block_size.html" title="Struct template block_size">block_size</a></code>: 289 the number of elements deque will allocate contiguously. If this option 290 is specified, <code class="computeroutput"><span class="identifier">deque</span><span class="special">::</span><span class="identifier">get_block_size</span><span class="special">()</span></code> 291 will return the specified <code class="computeroutput"><span class="identifier">block_size</span></code>. 292 A value of zero means the default value. 293 </li> 294</ul></div> 295<p> 296 See the following example to see how <code class="computeroutput"><a class="link" href="../boost/container/deque_options.html" title="Struct template deque_options">deque_options</a></code> 297 can be used to customize <code class="computeroutput"><span class="identifier">deque</span></code> 298 container: 299 </p> 300<p> 301</p> 302<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">container</span><span class="special">/</span><span class="identifier">deque</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 303<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="keyword">static_assert</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 304 305<span class="comment">//Make sure assertions are active</span> 306<span class="preprocessor">#ifdef</span> <span class="identifier">NDEBUG</span> 307<span class="preprocessor">#undef</span> <span class="identifier">NDEBUG</span> 308<span class="preprocessor">#endif</span> 309<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">cassert</span><span class="special">></span> 310 311<span class="keyword">int</span> <span class="identifier">main</span> <span class="special">()</span> 312<span class="special">{</span> 313 <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">container</span><span class="special">;</span> 314 315 <span class="comment">//This option specifies the desired block size for deque</span> 316 <span class="keyword">typedef</span> <span class="identifier">deque_options</span><span class="special"><</span> <span class="identifier">block_size</span><span class="special"><</span><span class="number">128u</span><span class="special">></span> <span class="special">>::</span><span class="identifier">type</span> <span class="identifier">block_128_option_t</span><span class="special">;</span> 317 318 <span class="comment">//This deque will allocate blocks of 128 elements</span> 319 <span class="keyword">typedef</span> <span class="identifier">deque</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">void</span><span class="special">,</span> <span class="identifier">block_128_option_t</span> <span class="special">></span> <span class="identifier">block_128_deque_t</span><span class="special">;</span> 320 <span class="identifier">assert</span><span class="special">(</span><span class="identifier">block_128_deque_t</span><span class="special">::</span><span class="identifier">get_block_size</span><span class="special">()</span> <span class="special">==</span> <span class="number">128u</span><span class="special">);</span> 321 322 <span class="comment">//This option specifies the maximum block size for deque</span> 323 <span class="comment">//in bytes</span> 324 <span class="keyword">typedef</span> <span class="identifier">deque_options</span><span class="special"><</span> <span class="identifier">block_bytes</span><span class="special"><</span><span class="number">1024u</span><span class="special">></span> <span class="special">>::</span><span class="identifier">type</span> <span class="identifier">block_1024_bytes_option_t</span><span class="special">;</span> 325 326 <span class="comment">//This deque will allocate blocks of 1024 bytes</span> 327 <span class="keyword">typedef</span> <span class="identifier">deque</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">void</span><span class="special">,</span> <span class="identifier">block_1024_bytes_option_t</span> <span class="special">></span> <span class="identifier">block_1024_bytes_deque_t</span><span class="special">;</span> 328 <span class="identifier">assert</span><span class="special">(</span><span class="identifier">block_1024_bytes_deque_t</span><span class="special">::</span><span class="identifier">get_block_size</span><span class="special">()</span> <span class="special">==</span> <span class="number">1024u</span><span class="special">/</span><span class="keyword">sizeof</span><span class="special">(</span><span class="keyword">int</span><span class="special">));</span> 329 330 <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> 331<span class="special">}</span> 332</pre> 333<p> 334 </p> 335</div> 336<div class="section"> 337<div class="titlepage"><div><div><h3 class="title"> 338<a name="container.configurable_containers.configurable_static_vectors"></a><a class="link" href="configurable_containers.html#container.configurable_containers.configurable_static_vectors" title="Configurable static vector">Configurable 339 static vector</a> 340</h3></div></div></div> 341<p> 342 The configuration for <code class="computeroutput"><a class="link" href="../boost/container/static_vector.html" title="Class template static_vector">static_vector</a></code> 343 is passed as the last template parameter and defined using the utility class 344 <code class="computeroutput"><a class="link" href="../boost/container/static_vector_options.html" title="Struct template static_vector_options">static_vector_options</a></code>. 345 The following parameters can be configured: 346 </p> 347<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 348<li class="listitem"> 349 <code class="computeroutput"><a class="link" href="../boost/container/inplace_alignment.html" title="Struct template inplace_alignment">inplace_alignment</a></code>: 350 the minimum alignment (in bytes) that the stored value type needs. This 351 option allows static vectors that need non-default alignments, e.g., 352 to be used in SIMD operations. 353 </li> 354<li class="listitem"> 355 <code class="computeroutput"><a class="link" href="../boost/container/throw_on_overflow.html" title="Struct template throw_on_overflow">throw_on_overflow</a></code>: 356 A boolean that specifies if the container should throw an exception when 357 the compile-time capacity is not enough to hold the requesteed number 358 of objects. When "false", if the capacit is overflowd, the 359 implementation calls to BOOST_ASSERT and if that assertion does not throw 360 or abort, undefined behavior is triggered. 361 </li> 362</ul></div> 363<p> 364 See the following example to see how <code class="computeroutput"><a class="link" href="../boost/container/static_vector_options.html" title="Struct template static_vector_options">static_vector_options</a></code> 365 can be used to customize <code class="computeroutput"><span class="identifier">static_vector</span></code> 366 container: 367 </p> 368<p> 369</p> 370<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">container</span><span class="special">/</span><span class="identifier">static_vector</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 371<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="keyword">static_assert</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 372 373<span class="comment">//Make sure assertions are active</span> 374<span class="preprocessor">#ifdef</span> <span class="identifier">NDEBUG</span> 375<span class="preprocessor">#undef</span> <span class="identifier">NDEBUG</span> 376<span class="preprocessor">#endif</span> 377<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">cassert</span><span class="special">></span> 378 379<span class="keyword">int</span> <span class="identifier">main</span> <span class="special">()</span> 380<span class="special">{</span> 381 <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">container</span><span class="special">;</span> 382 383 <span class="comment">//This option specifies the desired alignment for value_type</span> 384 <span class="keyword">typedef</span> <span class="identifier">static_vector_options</span><span class="special"><</span> <span class="identifier">inplace_alignment</span><span class="special"><</span><span class="number">16u</span><span class="special">></span> <span class="special">>::</span><span class="identifier">type</span> <span class="identifier">alignment_16_option_t</span><span class="special">;</span> 385 386 <span class="comment">//Check 16 byte alignment option</span> 387 <span class="identifier">static_vector</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="number">10</span><span class="special">,</span> <span class="identifier">alignment_16_option_t</span> <span class="special">></span> <span class="identifier">sv</span><span class="special">;</span> 388 <span class="identifier">assert</span><span class="special">(((</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">)</span><span class="identifier">sv</span><span class="special">.</span><span class="identifier">data</span><span class="special">()</span> <span class="special">%</span> <span class="number">16u</span><span class="special">)</span> <span class="special">==</span> <span class="number">0</span><span class="special">);</span> 389 390 <span class="comment">//This static_vector won't throw on overflow, for maximum performance</span> 391 <span class="keyword">typedef</span> <span class="identifier">static_vector_options</span><span class="special"><</span> <span class="identifier">throw_on_overflow</span><span class="special"><</span><span class="keyword">false</span><span class="special">></span> <span class="special">>::</span><span class="identifier">type</span> <span class="identifier">no_throw_options_t</span><span class="special">;</span> 392 393 <span class="comment">//Create static_vector with no throw on overflow</span> 394 <span class="identifier">static_vector</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="number">10</span><span class="special">,</span> <span class="identifier">no_throw_options_t</span> <span class="special">></span> <span class="identifier">sv2</span><span class="special">;</span> 395 396 <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> 397<span class="special">}</span> 398</pre> 399<p> 400 </p> 401</div> 402<div class="section"> 403<div class="titlepage"><div><div><h3 class="title"> 404<a name="container.configurable_containers.configurable_small_vectors"></a><a class="link" href="configurable_containers.html#container.configurable_containers.configurable_small_vectors" title="Configurable small vector">Configurable 405 small vector</a> 406</h3></div></div></div> 407<p> 408 The configuration for <code class="computeroutput"><a class="link" href="../boost/container/small_vector.html" title="Class template small_vector">small_vector</a></code> 409 is passed as the last template parameter and defined using the utility class 410 <code class="computeroutput"><a class="link" href="../boost/container/small_vector_options.html" title="Struct template small_vector_options">small_vector_options</a></code>. 411 The following parameters can be configured: 412 </p> 413<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 414<li class="listitem"> 415 <code class="computeroutput"><a class="link" href="../boost/container/inplace_alignment.html" title="Struct template inplace_alignment">inplace_alignment</a></code>: 416 the minimum alignment (in bytes) for the in-place storage used to build 417 the "small" number of elements. <span class="bold"><strong>The alignment 418 of the dynamic memory must be provided by the allocator and it is not 419 affected by this option</strong></span>. 420 </li> 421<li class="listitem"> 422 <code class="computeroutput"><a class="link" href="../boost/container/growth_factor.html" title="Struct template growth_factor">growth_factor</a></code>: 423 the growth policy of the vector. The rate at which the capacity of a 424 vector grows is implementation dependent and implementations choose exponential 425 growth in order to meet the amortized constant time requirement for push_back. 426 A higher growth factor will make it faster as it will require less data 427 movement, but it will have a greater memory impact (on average, more 428 memory will be unused). A user can provide a custom implementation of 429 the growth factor and some predefined policies are available: <code class="computeroutput"><a class="link" href="../boost/container/growth_factor_50.html" title="Struct growth_factor_50">growth_factor_50</a></code>, 430 <code class="computeroutput"><a class="link" href="../boost/container/growth_factor_60.html" title="Struct growth_factor_60">growth_factor_60</a></code> 431 and <code class="computeroutput"><a class="link" href="../boost/container/growth_factor_50.html" title="Struct growth_factor_50">growth_factor_100</a></code>. 432 </li> 433</ul></div> 434<p> 435 See the following example to see how <code class="computeroutput"><a class="link" href="../boost/container/small_vector_options.html" title="Struct template small_vector_options">small_vector_options</a></code> 436 can be used to customize <code class="computeroutput"><span class="identifier">small_vector</span></code> 437 container: 438 </p> 439<p> 440</p> 441<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">container</span><span class="special">/</span><span class="identifier">small_vector</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 442<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="keyword">static_assert</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 443 444<span class="comment">//Make sure assertions are active</span> 445<span class="preprocessor">#ifdef</span> <span class="identifier">NDEBUG</span> 446<span class="preprocessor">#undef</span> <span class="identifier">NDEBUG</span> 447<span class="preprocessor">#endif</span> 448<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">cassert</span><span class="special">></span> 449 450<span class="keyword">int</span> <span class="identifier">main</span> <span class="special">()</span> 451<span class="special">{</span> 452 <span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">container</span><span class="special">;</span> 453 454 <span class="comment">//This option specifies the desired alignment for the internal value_type</span> 455 <span class="keyword">typedef</span> <span class="identifier">small_vector_options</span><span class="special"><</span> <span class="identifier">inplace_alignment</span><span class="special"><</span><span class="number">16u</span><span class="special">></span> <span class="special">>::</span><span class="identifier">type</span> <span class="identifier">alignment_16_option_t</span><span class="special">;</span> 456 457 <span class="comment">//Check 16 byte alignment option</span> 458 <span class="identifier">small_vector</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="number">10</span><span class="special">,</span> <span class="keyword">void</span><span class="special">,</span> <span class="identifier">alignment_16_option_t</span> <span class="special">></span> <span class="identifier">sv</span><span class="special">;</span> 459 <span class="identifier">assert</span><span class="special">(((</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span><span class="special">)</span><span class="identifier">sv</span><span class="special">.</span><span class="identifier">data</span><span class="special">()</span> <span class="special">%</span> <span class="number">16u</span><span class="special">)</span> <span class="special">==</span> <span class="number">0</span><span class="special">);</span> 460 461 462 <span class="comment">//This option specifies that a vector will increase its capacity 50%</span> 463 <span class="comment">//each time the previous capacity was exhausted.</span> 464 <span class="keyword">typedef</span> <span class="identifier">small_vector_options</span><span class="special"><</span> <span class="identifier">growth_factor</span><span class="special"><</span><span class="identifier">growth_factor_50</span><span class="special">></span> <span class="special">>::</span><span class="identifier">type</span> <span class="identifier">growth_50_option_t</span><span class="special">;</span> 465 466 <span class="comment">//Fill the vector until full capacity is reached</span> 467 <span class="identifier">small_vector</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="number">10</span><span class="special">,</span> <span class="keyword">void</span><span class="special">,</span> <span class="identifier">growth_50_option_t</span> <span class="special">></span> <span class="identifier">growth_50_vector</span><span class="special">(</span><span class="number">10</span><span class="special">,</span> <span class="number">0</span><span class="special">);</span> 468 <span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span> <span class="identifier">old_cap</span> <span class="special">=</span> <span class="identifier">growth_50_vector</span><span class="special">.</span><span class="identifier">capacity</span><span class="special">();</span> 469 <span class="identifier">growth_50_vector</span><span class="special">.</span><span class="identifier">resize</span><span class="special">(</span><span class="identifier">old_cap</span><span class="special">);</span> 470 471 <span class="comment">//Now insert an additional item and check the new buffer is 50% bigger</span> 472 <span class="identifier">growth_50_vector</span><span class="special">.</span><span class="identifier">push_back</span><span class="special">(</span><span class="number">1</span><span class="special">);</span> 473 <span class="identifier">assert</span><span class="special">(</span><span class="identifier">growth_50_vector</span><span class="special">.</span><span class="identifier">capacity</span><span class="special">()</span> <span class="special">==</span> <span class="identifier">old_cap</span><span class="special">*</span><span class="number">3</span><span class="special">/</span><span class="number">2</span><span class="special">);</span> 474 475 <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> 476<span class="special">}</span> 477</pre> 478<p> 479 </p> 480</div> 481</div> 482<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 483<td align="left"></td> 484<td align="right"><div class="copyright-footer">Copyright © 2009-2018 Ion Gaztanaga<p> 485 Distributed under the Boost Software License, Version 1.0. (See accompanying 486 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) 487 </p> 488</div></td> 489</tr></table> 490<hr> 491<div class="spirit-nav"> 492<a accesskey="p" href="extended_functionality.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../container.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="extended_allocators.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> 493</div> 494</body> 495</html> 496
