containers.xml revision 1.3
1<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" 2 xml:id="std.containers" xreflabel="Containers"> 3<?dbhtml filename="containers.html"?> 4 5<info><title> 6 Containers 7 <indexterm><primary>Containers</primary></indexterm> 8</title> 9 <keywordset> 10 <keyword>ISO C++</keyword> 11 <keyword>library</keyword> 12 </keywordset> 13</info> 14 15 16 17<!-- Sect1 01 : Sequences --> 18<section xml:id="std.containers.sequences" xreflabel="Sequences"><info><title>Sequences</title></info> 19<?dbhtml filename="sequences.html"?> 20 21 22<section xml:id="containers.sequences.list" xreflabel="list"><info><title>list</title></info> 23<?dbhtml filename="list.html"?> 24 25 <section xml:id="sequences.list.size" xreflabel="list::size() is O(n)"><info><title>list::size() is O(n)</title></info> 26 27 <para> 28 Yes it is, and that was okay until the 2011 edition of the C++ standard. 29 In future GCC will change it to O(1) but O(N) was a decision that we 30 preserved when we imported SGI's STL implementation. The following is 31 quoted from <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sgi.com/tech/stl/FAQ.html">their FAQ</link>: 32 </para> 33 <blockquote> 34 <para> 35 The size() member function, for list and slist, takes time 36 proportional to the number of elements in the list. This was a 37 deliberate tradeoff. The only way to get a constant-time 38 size() for linked lists would be to maintain an extra member 39 variable containing the list's size. This would require taking 40 extra time to update that variable (it would make splice() a 41 linear time operation, for example), and it would also make the 42 list larger. Many list algorithms don't require that extra 43 word (algorithms that do require it might do better with 44 vectors than with lists), and, when it is necessary to maintain 45 an explicit size count, it's something that users can do 46 themselves. 47 </para> 48 <para> 49 This choice is permitted by the C++ standard. The standard says 50 that size() <quote>should</quote> be constant time, and 51 <quote>should</quote> does not mean the same thing as 52 <quote>shall</quote>. This is the officially recommended ISO 53 wording for saying that an implementation is supposed to do 54 something unless there is a good reason not to. 55 </para> 56 <para> 57 One implication of linear time size(): you should never write 58 </para> 59 <programlisting> 60 if (L.size() == 0) 61 ... 62 </programlisting> 63 64 <para> 65 Instead, you should write 66 </para> 67 68 <programlisting> 69 if (L.empty()) 70 ... 71 </programlisting> 72 </blockquote> 73 </section> 74</section> 75 76</section> 77 78<!-- Sect1 02 : Associative --> 79<section xml:id="std.containers.associative" xreflabel="Associative"><info><title>Associative</title></info> 80<?dbhtml filename="associative.html"?> 81 82 83 <section xml:id="containers.associative.insert_hints" xreflabel="Insertion Hints"><info><title>Insertion Hints</title></info> 84 85 <para> 86 Section [23.1.2], Table 69, of the C++ standard lists this 87 function for all of the associative containers (map, set, etc): 88 </para> 89 <programlisting> 90 a.insert(p,t); 91 </programlisting> 92 <para> 93 where 'p' is an iterator into the container 'a', and 't' is the 94 item to insert. The standard says that <quote><code>t</code> is 95 inserted as close as possible to the position just prior to 96 <code>p</code>.</quote> (Library DR #233 addresses this topic, 97 referring to <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1780.html">N1780</link>. 98 Since version 4.2 GCC implements the resolution to DR 233, so 99 that insertions happen as close as possible to the hint. For 100 earlier releases the hint was only used as described below. 101 </para> 102 <para> 103 Here we'll describe how the hinting works in the libstdc++ 104 implementation, and what you need to do in order to take 105 advantage of it. (Insertions can change from logarithmic 106 complexity to amortized constant time, if the hint is properly 107 used.) Also, since the current implementation is based on the 108 SGI STL one, these points may hold true for other library 109 implementations also, since the HP/SGI code is used in a lot of 110 places. 111 </para> 112 <para> 113 In the following text, the phrases <emphasis>greater 114 than</emphasis> and <emphasis>less than</emphasis> refer to the 115 results of the strict weak ordering imposed on the container by 116 its comparison object, which defaults to (basically) 117 <quote><</quote>. Using those phrases is semantically sloppy, 118 but I didn't want to get bogged down in syntax. I assume that if 119 you are intelligent enough to use your own comparison objects, 120 you are also intelligent enough to assign <quote>greater</quote> 121 and <quote>lesser</quote> their new meanings in the next 122 paragraph. *grin* 123 </para> 124 <para> 125 If the <code>hint</code> parameter ('p' above) is equivalent to: 126 </para> 127 <itemizedlist> 128 <listitem> 129 <para> 130 <code>begin()</code>, then the item being inserted should 131 have a key less than all the other keys in the container. 132 The item will be inserted at the beginning of the container, 133 becoming the new entry at <code>begin()</code>. 134 </para> 135 </listitem> 136 <listitem> 137 <para> 138 <code>end()</code>, then the item being inserted should have 139 a key greater than all the other keys in the container. The 140 item will be inserted at the end of the container, becoming 141 the new entry before <code>end()</code>. 142 </para> 143 </listitem> 144 <listitem> 145 <para> 146 neither <code>begin()</code> nor <code>end()</code>, then: 147 Let <code>h</code> be the entry in the container pointed to 148 by <code>hint</code>, that is, <code>h = *hint</code>. Then 149 the item being inserted should have a key less than that of 150 <code>h</code>, and greater than that of the item preceding 151 <code>h</code>. The new item will be inserted between 152 <code>h</code> and <code>h</code>'s predecessor. 153 </para> 154 </listitem> 155 </itemizedlist> 156 <para> 157 For <code>multimap</code> and <code>multiset</code>, the 158 restrictions are slightly looser: <quote>greater than</quote> 159 should be replaced by <quote>not less than</quote>and <quote>less 160 than</quote> should be replaced by <quote>not greater 161 than.</quote> (Why not replace greater with 162 greater-than-or-equal-to? You probably could in your head, but 163 the mathematicians will tell you that it isn't the same thing.) 164 </para> 165 <para> 166 If the conditions are not met, then the hint is not used, and the 167 insertion proceeds as if you had called <code> a.insert(t) 168 </code> instead. (<emphasis>Note </emphasis> that GCC releases 169 prior to 3.0.2 had a bug in the case with <code>hint == 170 begin()</code> for the <code>map</code> and <code>set</code> 171 classes. You should not use a hint argument in those releases.) 172 </para> 173 <para> 174 This behavior goes well with other containers' 175 <code>insert()</code> functions which take an iterator: if used, 176 the new item will be inserted before the iterator passed as an 177 argument, same as the other containers. 178 </para> 179 <para> 180 <emphasis>Note </emphasis> also that the hint in this 181 implementation is a one-shot. The older insertion-with-hint 182 routines check the immediately surrounding entries to ensure that 183 the new item would in fact belong there. If the hint does not 184 point to the correct place, then no further local searching is 185 done; the search begins from scratch in logarithmic time. 186 </para> 187 </section> 188 189 190 <section xml:id="containers.associative.bitset" xreflabel="bitset"><info><title>bitset</title></info> 191 <?dbhtml filename="bitset.html"?> 192 193 <section xml:id="associative.bitset.size_variable" xreflabel="Variable"><info><title>Size Variable</title></info> 194 195 <para> 196 No, you cannot write code of the form 197 </para> 198 <!-- Careful, the leading spaces in PRE show up directly. --> 199 <programlisting> 200 #include <bitset> 201 202 void foo (size_t n) 203 { 204 std::bitset<n> bits; 205 .... 206 } 207 </programlisting> 208 <para> 209 because <code>n</code> must be known at compile time. Your 210 compiler is correct; it is not a bug. That's the way templates 211 work. (Yes, it <emphasis>is</emphasis> a feature.) 212 </para> 213 <para> 214 There are a couple of ways to handle this kind of thing. Please 215 consider all of them before passing judgement. They include, in 216 no chaptericular order: 217 </para> 218 <itemizedlist> 219 <listitem><para>A very large N in <code>bitset<N></code>.</para></listitem> 220 <listitem><para>A container<bool>.</para></listitem> 221 <listitem><para>Extremely weird solutions.</para></listitem> 222 </itemizedlist> 223 <para> 224 <emphasis>A very large N in 225 <code>bitset<N></code>.����</emphasis> It has been 226 pointed out a few times in newsgroups that N bits only takes up 227 (N/8) bytes on most systems, and division by a factor of eight is 228 pretty impressive when speaking of memory. Half a megabyte given 229 over to a bitset (recall that there is zero space overhead for 230 housekeeping info; it is known at compile time exactly how large 231 the set is) will hold over four million bits. If you're using 232 those bits as status flags (e.g., 233 <quote>changed</quote>/<quote>unchanged</quote> flags), that's a 234 <emphasis>lot</emphasis> of state. 235 </para> 236 <para> 237 You can then keep track of the <quote>maximum bit used</quote> 238 during some testing runs on representative data, make note of how 239 many of those bits really need to be there, and then reduce N to 240 a smaller number. Leave some extra space, of course. (If you 241 plan to write code like the incorrect example above, where the 242 bitset is a local variable, then you may have to talk your 243 compiler into allowing that much stack space; there may be zero 244 space overhead, but it's all allocated inside the object.) 245 </para> 246 <para> 247 <emphasis>A container<bool>.����</emphasis> The 248 Committee made provision for the space savings possible with that 249 (N/8) usage previously mentioned, so that you don't have to do 250 wasteful things like <code>Container<char></code> or 251 <code>Container<short int></code>. Specifically, 252 <code>vector<bool></code> is required to be specialized for 253 that space savings. 254 </para> 255 <para> 256 The problem is that <code>vector<bool></code> doesn't 257 behave like a normal vector anymore. There have been 258 journal articles which discuss the problems (the ones by Herb 259 Sutter in the May and July/August 1999 issues of C++ Report cover 260 it well). Future revisions of the ISO C++ Standard will change 261 the requirement for <code>vector<bool></code> 262 specialization. In the meantime, <code>deque<bool></code> 263 is recommended (although its behavior is sane, you probably will 264 not get the space savings, but the allocation scheme is different 265 than that of vector). 266 </para> 267 <para> 268 <emphasis>Extremely weird solutions.����</emphasis> If 269 you have access to the compiler and linker at runtime, you can do 270 something insane, like figuring out just how many bits you need, 271 then writing a temporary source code file. That file contains an 272 instantiation of <code>bitset</code> for the required number of 273 bits, inside some wrapper functions with unchanging signatures. 274 Have your program then call the compiler on that file using 275 Position Independent Code, then open the newly-created object 276 file and load those wrapper functions. You'll have an 277 instantiation of <code>bitset<N></code> for the exact 278 <code>N</code> that you need at the time. Don't forget to delete 279 the temporary files. (Yes, this <emphasis>can</emphasis> be, and 280 <emphasis>has been</emphasis>, done.) 281 </para> 282 <!-- I wonder if this next paragraph will get me in trouble... --> 283 <para> 284 This would be the approach of either a visionary genius or a 285 raving lunatic, depending on your programming and management 286 style. Probably the latter. 287 </para> 288 <para> 289 Which of the above techniques you use, if any, are up to you and 290 your intended application. Some time/space profiling is 291 indicated if it really matters (don't just guess). And, if you 292 manage to do anything along the lines of the third category, the 293 author would love to hear from you... 294 </para> 295 <para> 296 Also note that the implementation of bitset used in libstdc++ has 297 <link linkend="manual.ext.containers.sgi">some extensions</link>. 298 </para> 299 300 </section> 301 <section xml:id="associative.bitset.type_string" xreflabel="Type String"><info><title>Type String</title></info> 302 303 <para> 304 </para> 305 <para> 306 Bitmasks do not take char* nor const char* arguments in their 307 constructors. This is something of an accident, but you can read 308 about the problem: follow the library's <quote>Links</quote> from 309 the homepage, and from the C++ information <quote>defect 310 reflector</quote> link, select the library issues list. Issue 311 number 116 describes the problem. 312 </para> 313 <para> 314 For now you can simply make a temporary string object using the 315 constructor expression: 316 </para> 317 <programlisting> 318 std::bitset<5> b ( std::string(<quote>10110</quote>) ); 319 </programlisting> 320 321 <para> 322 instead of 323 </para> 324 325 <programlisting> 326 std::bitset<5> b ( <quote>10110</quote> ); // invalid 327 </programlisting> 328 </section> 329 </section> 330 331</section> 332 333<!-- Sect1 03 : Unordered Associative --> 334<section xml:id="std.containers.unordered" xreflabel="Unordered"> 335 <info><title>Unordered Associative</title></info> 336 <?dbhtml filename="unordered_associative.html"?> 337 338 <section xml:id="containers.unordered.hash" xreflabel="Hash"> 339 <info><title>Hash Code</title></info> 340 341 <section xml:id="containers.unordered.cache" xreflabel="Cache"> 342 <info><title>Hash Code Caching Policy</title></info> 343 344 <para> 345 The unordered containers in libstdc++ may cache the hash code for each 346 element alongside the element itself. In some cases not recalculating 347 the hash code every time it's needed can improve performance, but the 348 additional memory overhead can also reduce performance, so whether an 349 unordered associative container caches the hash code or not depends on 350 a number of factors. The caching policy for GCC 4.8 is described below. 351 </para> 352 <para> 353 The C++ standard requires that <code>erase</code> and <code>swap</code> 354 operations must not throw exceptions. Those operations might need an 355 element's hash code, but cannot use the hash function if it could 356 throw. 357 This means the hash codes will be cached unless the hash function 358 has a non-throwing exception specification such as <code>noexcept</code> 359 or <code>throw()</code>. 360 </para> 361 <para> 362 Secondly, libstdc++ also needs the hash code in the implementation of 363 <code>local_iterator</code> and <code>const_local_iterator</code> in 364 order to know when the iterator has reached the end of the bucket. 365 This means that the local iterator types will embed a copy of the hash 366 function when possible. 367 Because the local iterator types must be DefaultConstructible and 368 CopyAssignable, if the hash function type does not model those concepts 369 then it cannot be embedded and so the hash code must be cached. 370 Note that a hash function might not be safe to use when 371 default-constructed (e.g if it a function pointer) so a hash 372 function that is contained in a local iterator won't be used until 373 the iterator is valid, so the hash function has been copied from a 374 correctly-initialized object. 375 </para> 376 <para> 377 If the hash function is non-throwing, DefaultConstructible and 378 CopyAssignable then libstdc++ doesn't need to cache the hash code for 379 correctness, but might still do so for performance if computing a 380 hash code is an expensive operation, as it may be for arbitrarily 381 long strings. 382 As an extension libstdc++ provides a trait type to describe whether 383 a hash function is fast. By default hash functions are assumed to be 384 fast unless the trait is specialized for the hash function and the 385 trait's value is false, in which case the hash code will always be 386 cached. 387 The trait can be specialized for user-defined hash functions like so: 388 </para> 389 <programlisting> 390 #include <unordered_set> 391 392 struct hasher 393 { 394 std::size_t operator()(int val) const noexcept 395 { 396 // Some very slow computation of a hash code from an int ! 397 ... 398 } 399 } 400 401 namespace std 402 { 403 template<> 404 struct __is_fast_hash<hasher> : std::false_type 405 { }; 406 } 407 </programlisting> 408 </section> 409</section> 410 411</section> 412 413<!-- Sect1 04 : Interacting with C --> 414<section xml:id="std.containers.c" xreflabel="Interacting with C"><info><title>Interacting with C</title></info> 415<?dbhtml filename="containers_and_c.html"?> 416 417 418 <section xml:id="containers.c.vs_array" xreflabel="Containers vs. Arrays"><info><title>Containers vs. Arrays</title></info> 419 420 <para> 421 You're writing some code and can't decide whether to use builtin 422 arrays or some kind of container. There are compelling reasons 423 to use one of the container classes, but you're afraid that 424 you'll eventually run into difficulties, change everything back 425 to arrays, and then have to change all the code that uses those 426 data types to keep up with the change. 427 </para> 428 <para> 429 If your code makes use of the standard algorithms, this isn't as 430 scary as it sounds. The algorithms don't know, nor care, about 431 the kind of <quote>container</quote> on which they work, since 432 the algorithms are only given endpoints to work with. For the 433 container classes, these are iterators (usually 434 <code>begin()</code> and <code>end()</code>, but not always). 435 For builtin arrays, these are the address of the first element 436 and the <link linkend="iterators.predefined.end">past-the-end</link> element. 437 </para> 438 <para> 439 Some very simple wrapper functions can hide all of that from the 440 rest of the code. For example, a pair of functions called 441 <code>beginof</code> can be written, one that takes an array, 442 another that takes a vector. The first returns a pointer to the 443 first element, and the second returns the vector's 444 <code>begin()</code> iterator. 445 </para> 446 <para> 447 The functions should be made template functions, and should also 448 be declared inline. As pointed out in the comments in the code 449 below, this can lead to <code>beginof</code> being optimized out 450 of existence, so you pay absolutely nothing in terms of increased 451 code size or execution time. 452 </para> 453 <para> 454 The result is that if all your algorithm calls look like 455 </para> 456 <programlisting> 457 std::transform(beginof(foo), endof(foo), beginof(foo), SomeFunction); 458 </programlisting> 459 <para> 460 then the type of foo can change from an array of ints to a vector 461 of ints to a deque of ints and back again, without ever changing 462 any client code. 463 </para> 464 465<programlisting> 466// beginof 467template<typename T> 468 inline typename vector<T>::iterator 469 beginof(vector<T> &v) 470 { return v.begin(); } 471 472template<typename T, unsigned int sz> 473 inline T* 474 beginof(T (&array)[sz]) { return array; } 475 476// endof 477template<typename T> 478 inline typename vector<T>::iterator 479 endof(vector<T> &v) 480 { return v.end(); } 481 482template<typename T, unsigned int sz> 483 inline T* 484 endof(T (&array)[sz]) { return array + sz; } 485 486// lengthof 487template<typename T> 488 inline typename vector<T>::size_type 489 lengthof(vector<T> &v) 490 { return v.size(); } 491 492template<typename T, unsigned int sz> 493 inline unsigned int 494 lengthof(T (&)[sz]) { return sz; } 495</programlisting> 496 497 <para> 498 Astute readers will notice two things at once: first, that the 499 container class is still a <code>vector<T></code> instead 500 of a more general <code>Container<T></code>. This would 501 mean that three functions for <code>deque</code> would have to be 502 added, another three for <code>list</code>, and so on. This is 503 due to problems with getting template resolution correct; I find 504 it easier just to give the extra three lines and avoid confusion. 505 </para> 506 <para> 507 Second, the line 508 </para> 509 <programlisting> 510 inline unsigned int lengthof (T (&)[sz]) { return sz; } 511 </programlisting> 512 <para> 513 looks just weird! Hint: unused parameters can be left nameless. 514 </para> 515 </section> 516 517</section> 518 519</chapter> 520