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, at least using the <link linkend="manual.intro.using.abi">old 29 ABI</link>, and that's okay. This is a decision that we preserved 30 when we imported SGI's STL implementation. The following is 31 quoted from <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://web.archive.org/web/20171225062613/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 particular 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("10110") ); 319 </programlisting> 320 321 <para> 322 instead of 323 </para> 324 325 <programlisting> 326 std::bitset<5> b ( "10110" ); // 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.insert_hints" xreflabel="Insertion Hints"> 339 <info><title>Insertion Hints</title></info> 340 341 <para> 342 Here is how the hinting works in the libstdc++ implementation of unordered 343 containers, and the rationale behind this behavior. 344 </para> 345 <para> 346 In the following text, the phrase <emphasis>equivalent to</emphasis> refer 347 to the result of the invocation of the equal predicate imposed on the 348 container by its <code>key_equal</code> object, which defaults to (basically) 349 <quote>==</quote>. 350 </para> 351 <para> 352 Unordered containers can be seen as a <code>std::vector</code> of 353 <code>std::forward_list</code>. The <code>std::vector</code> represents 354 the buckets and each <code>std::forward_list</code> is the list of nodes 355 belonging to the same bucket. When inserting an element in such a data 356 structure we first need to compute the element hash code to find the 357 bucket to insert the element to, the second step depends on the uniqueness 358 of elements in the container. 359 </para> 360 <para> 361 In the case of <code>std::unordered_set</code> and 362 <code>std::unordered_map</code> you need to look through all bucket's 363 elements for an equivalent one. If there is none the insertion can be 364 achieved, otherwise the insertion fails. As we always need to loop though 365 all bucket's elements, the hint doesn't tell us if the element is already 366 present, and we don't have any constraint on where the new element is to 367 be inserted, the hint won't be of any help and will then be ignored. 368 </para> 369 <para> 370 In the case of <code>std::unordered_multiset</code> 371 and <code>std::unordered_multimap</code> equivalent elements must be 372 linked together so that the <code>equal_range(const key_type&)</code> 373 can return the range of iterators pointing to all equivalent elements. 374 This is where hinting can be used to point to another equivalent element 375 already part of the container and so skip all non equivalent elements of 376 the bucket. So to be useful the hint shall point to an element equivalent 377 to the one being inserted. The new element will be then inserted right 378 after the hint. Note that because of an implementation detail inserting 379 after a node can require updating the bucket of the following node. To 380 check if the next bucket is to be modified we need to compute the 381 following node's hash code. So if you want your hint to be really efficient 382 it should be followed by another equivalent element, the implementation 383 will detect this equivalence and won't compute next element hash code. 384 </para> 385 <para> 386 It is highly advised to start using unordered containers hints only if you 387 have a benchmark that will demonstrate the benefit of it. If you don't then do 388 not use hints, it might do more harm than good. 389 </para> 390 </section> 391 392 <section xml:id="containers.unordered.hash" xreflabel="Hash"> 393 <info><title>Hash Code</title></info> 394 395 <section xml:id="containers.unordered.cache" xreflabel="Cache"> 396 <info><title>Hash Code Caching Policy</title></info> 397 398 <para> 399 The unordered containers in libstdc++ may cache the hash code for each 400 element alongside the element itself. In some cases not recalculating 401 the hash code every time it's needed can improve performance, but the 402 additional memory overhead can also reduce performance, so whether an 403 unordered associative container caches the hash code or not depends on 404 the properties described below. 405 </para> 406 <para> 407 The C++ standard requires that <code>erase</code> and <code>swap</code> 408 operations must not throw exceptions. Those operations might need an 409 element's hash code, but cannot use the hash function if it could 410 throw. 411 This means the hash codes will be cached unless the hash function 412 has a non-throwing exception specification such as <code>noexcept</code> 413 or <code>throw()</code>. 414 </para> 415 <para> 416 If the hash function is non-throwing then libstdc++ doesn't need to 417 cache the hash code for 418 correctness, but might still do so for performance if computing a 419 hash code is an expensive operation, as it may be for arbitrarily 420 long strings. 421 As an extension libstdc++ provides a trait type to describe whether 422 a hash function is fast. By default hash functions are assumed to be 423 fast unless the trait is specialized for the hash function and the 424 trait's value is false, in which case the hash code will always be 425 cached. 426 The trait can be specialized for user-defined hash functions like so: 427 </para> 428 <programlisting> 429 #include <unordered_set> 430 431 struct hasher 432 { 433 std::size_t operator()(int val) const noexcept 434 { 435 // Some very slow computation of a hash code from an int ! 436 ... 437 } 438 } 439 440 namespace std 441 { 442 template<> 443 struct __is_fast_hash<hasher> : std::false_type 444 { }; 445 } 446 </programlisting> 447 </section> 448</section> 449 450</section> 451 452<!-- Sect1 04 : Interacting with C --> 453<section xml:id="std.containers.c" xreflabel="Interacting with C"><info><title>Interacting with C</title></info> 454<?dbhtml filename="containers_and_c.html"?> 455 456 457 <section xml:id="containers.c.vs_array" xreflabel="Containers vs. Arrays"><info><title>Containers vs. Arrays</title></info> 458 459 <para> 460 You're writing some code and can't decide whether to use builtin 461 arrays or some kind of container. There are compelling reasons 462 to use one of the container classes, but you're afraid that 463 you'll eventually run into difficulties, change everything back 464 to arrays, and then have to change all the code that uses those 465 data types to keep up with the change. 466 </para> 467 <para> 468 If your code makes use of the standard algorithms, this isn't as 469 scary as it sounds. The algorithms don't know, nor care, about 470 the kind of <quote>container</quote> on which they work, since 471 the algorithms are only given endpoints to work with. For the 472 container classes, these are iterators (usually 473 <code>begin()</code> and <code>end()</code>, but not always). 474 For builtin arrays, these are the address of the first element 475 and the <link linkend="iterators.predefined.end">past-the-end</link> element. 476 </para> 477 <para> 478 Some very simple wrapper functions can hide all of that from the 479 rest of the code. For example, a pair of functions called 480 <code>beginof</code> can be written, one that takes an array, 481 another that takes a vector. The first returns a pointer to the 482 first element, and the second returns the vector's 483 <code>begin()</code> iterator. 484 </para> 485 <para> 486 The functions should be made template functions, and should also 487 be declared inline. As pointed out in the comments in the code 488 below, this can lead to <code>beginof</code> being optimized out 489 of existence, so you pay absolutely nothing in terms of increased 490 code size or execution time. 491 </para> 492 <para> 493 The result is that if all your algorithm calls look like 494 </para> 495 <programlisting> 496 std::transform(beginof(foo), endof(foo), beginof(foo), SomeFunction); 497 </programlisting> 498 <para> 499 then the type of foo can change from an array of ints to a vector 500 of ints to a deque of ints and back again, without ever changing 501 any client code. 502 </para> 503 504<programlisting> 505// beginof 506template<typename T> 507 inline typename vector<T>::iterator 508 beginof(vector<T> &v) 509 { return v.begin(); } 510 511template<typename T, unsigned int sz> 512 inline T* 513 beginof(T (&array)[sz]) { return array; } 514 515// endof 516template<typename T> 517 inline typename vector<T>::iterator 518 endof(vector<T> &v) 519 { return v.end(); } 520 521template<typename T, unsigned int sz> 522 inline T* 523 endof(T (&array)[sz]) { return array + sz; } 524 525// lengthof 526template<typename T> 527 inline typename vector<T>::size_type 528 lengthof(vector<T> &v) 529 { return v.size(); } 530 531template<typename T, unsigned int sz> 532 inline unsigned int 533 lengthof(T (&)[sz]) { return sz; } 534</programlisting> 535 536 <para> 537 Astute readers will notice two things at once: first, that the 538 container class is still a <code>vector<T></code> instead 539 of a more general <code>Container<T></code>. This would 540 mean that three functions for <code>deque</code> would have to be 541 added, another three for <code>list</code>, and so on. This is 542 due to problems with getting template resolution correct; I find 543 it easier just to give the extra three lines and avoid confusion. 544 </para> 545 <para> 546 Second, the line 547 </para> 548 <programlisting> 549 inline unsigned int lengthof (T (&)[sz]) { return sz; } 550 </programlisting> 551 <para> 552 looks just weird! Hint: unused parameters can be left nameless. 553 </para> 554 </section> 555 556</section> 557 558</chapter> 559