libstdc++-v3/doc/xml/manual/containers.xml

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