libstdc++-v3/docs/html/ext/sgiexts.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
   2 <html>
   3 <head>
   4    <meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)">
   5    <meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++, STL, SGI">
   6    <meta name="DESCRIPTION" content="SGI extensions preserved in libstdc++-v3.">
   7    <meta name="GENERATOR" content="vi and eight fingers">
   8    <title>SGI extensions to the library in libstdc++-v3</title>
   9 <link rel="StyleSheet" href="lib3styles.css">
  10 </head>
  11 <body>
  12
  13 <h1 class="centered"><a name="top">SGI extensions to the library in
  14 libstdc++-v3</a></h1>
  15
  16 <p>This page describes the extensions that SGI made to their version of the
  17    STL subset of the Standard C++ Library.  For a time we
  18    <a href="../faq/index.html#5_3">tracked and imported changes and updates
  19    from most of the SGI STL</a>, up through their (apparently) final release.
  20    Their extensions were mostly preserved.
  21 </p>
  22
  23 <p>They are listed according to the chapters of the library that they
  24    extend (see <a href="../documentation.html#3">the chapter-specific notes</a>
  25    for a description).  Not every chapter may have extensions, and the
  26    extensions may come and go.  Also, this page is incomplete because the
  27    author is pressed for time.  Check back often; the latest change was on
  28    $Date: 2001/10/11 18:41:47 $ (UTC).
  29 </p>
  30
  31 <p>Descriptions range from the scanty to the verbose.  You should also check
  32    the <a href="../documentation.html#4">generated documentation</a> for notes
  33    and comments, especially for entries marked with '*'.  For more complete
  34    doumentation, see the SGI website.  For <em>really</em> complete
  35    documentation, buy a copy of Matt Austern's book.  *grin*
  36 </p>
  37
  38 <p>Back to the <a href="howto.html">libstdc++-v3 extensions</a>.
  39
  40
  41 <!-- ####################################################### -->
  42 <hr>
  43 <a name="ch20"><h3>Chapter 20</h3></a>
  44 <p>The &lt;functional&gt; header contains many additional functors and
  45    helper functions, extending section 20.3.  They are implemented in the
  46    file stl_function.h:
  47  <ul>
  48   <li><code>identity_element</code> for addition and multiplication. *
  49   <li>The functor <code>identity</code>, whose op() returns the argument
  50       unchanged. *
  51   <li>Composition functors <code>unary_function</code> and
  52       <code>binary_function</code>, and their helpers <code>compose1</code>
  53       and <code>compose2</code>. *
  54   <li><code>select1st</code> and <code>select2nd</code>, to strip pairs. *
  55   <li><code>project1st</code> and <code>project2nd</code>. *
  56   <li>A set of functors/functions which always return the same result.  They
  57       are <code>constant_void_fun, constant_binary_fun, constant_unary_fun,
  58       constant0, constant1, and constant2. *
  59   <li>The class <code>subtractive_rng</code>. *
  60   <li>mem_fun adaptor helpers mem_fun1 and mem_fun1_ref are provided for
  61       backwards compatibility.
  62 </ul></p>
  63 <p>20.4.3 is extended with a special version of
  64    <code>get_temporary_buffer</code> taking a second argument.  The argument
  65    is a pointer, which is ignored, but can be used to specify the template
  66    type (instead of using explicit function template arguments like the
  67    standard version does).  That is, in addition to
  68    <pre>
  69    get_temporary_buffer&lt;int&gt;(5);</pre>
  70    you can also use
  71    <pre>
  72    get_temporary_buffer(5, (int*)0);</pre>
  73 </p>
  74 <p>A class <code>temporary_buffer</code> is given in stl_tempbuf.h. *
  75 </p>
  76 <p>The specialized algorithms of section 20.4.4 are extended with
  77    <code>uninitialized_copy_n</code>. *
  78 </p>
  79 <p>Return <a href="howto.html">to the main extensions page</a> or
  80    <a href="http://gcc.gnu.org/libstdc++/">to the homepage</a>.
  81 </p>
  82
  83
  84 <hr>
  85 <a name="ch23"><h3>Chapter 23</h3></a>
  86 <p>A few extensions and nods to backwards-compatibility have been made with
  87    containers.  Those dealing with older SGI-style allocators are dealt with
  88    elsewhere.  The remaining ones all deal with bits:
  89 </p>
  90 <p>The old pre-standard <code>bit_vector</code> class is present for
  91    backwards compatibility.  It is simply a typedef for the
  92    <code>vector&lt;bool&gt;</code> specialization.
  93 </p>
  94 <p>The <code>bitset</code> class has a number of extensions, described in the
  95    rest of this item.  First, we'll mention that this implementation of
  96    <code>bitset&lt;N&gt;</code> is specialized for cases where N number of
  97    bits will fit into a single word of storage.  If your choice of N is
  98    within that range (&lt;=32 on i686-pc-linux-gnu, for example), then all
  99    of the operations will be faster.
 100 </p>
 101 <p>There are
 102    versions of single-bit test, set, reset, and flip member functions which
 103    do no range-checking.  If we call them member functions of an instantiation
 104    of &quot;bitset&lt;N&gt;,&quot; then their names and signatures are:
 105    <pre>
 106    bitset&lt;N&gt;&amp;   _Unchecked_set   (size_t pos);
 107    bitset&lt;N&gt;&amp;   _Unchecked_set   (size_t pos, int val);
 108    bitset&lt;N&gt;&amp;   _Unchecked_reset (size_t pos);
 109    bitset&lt;N&gt;&amp;   _Unchecked_flip  (size_t pos);
 110    bool         _Unchecked_test  (size_t pos);</pre>
 111    Note that these may in fact be removed in the future, although we have
 112    no present plans to do so (and there doesn't seem to be any immediate
 113    reason to).
 114 </p>
 115 <p>
 116    The semantics of member function <code>operator[]</code> are not specified
 117    in the C++ standard.  A long-standing defect report calls for sensible
 118    obvious semantics, which are already implemented here:  <code>op[]</code>
 119    on a const bitset returns a bool, and for a non-const bitset returns a
 120    <code>reference</code> (a nested type).  However, this implementation does
 121    no range-checking on the index argument, which is in keeping with other
 122    containers' <code>op[]</code> requirements.  The defect report's proposed
 123    resolution calls for range-checking to be done.  We'll just wait and see...
 124 </p>
 125 <p>Finally, two additional searching functions have been added.  They return
 126    the index of the first &quot;on&quot; bit, and the index of the first
 127    &quot;on&quot; bit that is after <code>prev</code>, respectively:
 128    <pre>
 129    size_t _Find_first() const;
 130    size_t _Find_next (size_t prev) const;</pre>
 131    The same caveat given for the _Unchecked_* functions applies here also.
 132 </p>
 133 <p>Return <a href="howto.html">to the main extensions page</a> or
 134    <a href="http://gcc.gnu.org/libstdc++/">to the homepage</a>.
 135 </p>
 136
 137
 138 <hr>
 139 <a name="ch24"><h3>Chapter 24</h3></a>
 140 <p>24.3.2 describes <code>struct iterator</code>, which didn't exist in the
 141    original HP STL implementation (the language wasn't rich enough at the
 142    time).  For backwards compatibility, base classes are provided which
 143    declare the same nested typedefs:
 144    <ul>
 145     <li>input_iterator
 146     <li>output_iterator
 147     <li>forward_iterator
 148     <li>bidirectional_iterator
 149     <li>random_access_iterator
 150    </ul>
 151 </p>
 152 <p>24.3.4 describes iterator operation <code>distance</code>, which takes
 153    two iterators and returns a result.  It is extended by another signature
 154    which takes two iterators and a reference to a result.  The result is
 155    modified, and the function returns nothing.
 156 </p>
 157 <p>Return <a href="howto.html">to the main extensions page</a> or
 158    <a href="http://gcc.gnu.org/libstdc++/">to the homepage</a>.
 159 </p>
 160
 161
 162 <hr>
 163 <a name="ch25"><h3>Chapter 25</h3></a>
 164 <p>25.1.6 (count, count_if) is extended with two more versions of count
 165    and count_if.  The standard versions return their results.  The
 166    additional signatures return void, but take a final parameter by
 167    reference to which they assign their results, e.g.,
 168    <pre>
 169    void count (first, last, value, n);</pre>
 170 </p>
 171 <p>25.2 (mutating algorithms) is extended with two families of signatures,
 172    random_sample and random_sample_n.
 173 </p>
 174 <p>25.2.1 (copy) is extended with
 175    <pre>
 176    copy_n (_InputIter first, _Size count, _OutputIter result);</pre>
 177    which copies the first 'count' elements at 'first' into 'result'.
 178 </p>
 179 <p>25.3 (sorting 'n' heaps 'n' stuff) is extended with some helper
 180    predicates.  Look in the doxygen-generated pages for notes on these.
 181    <ul>
 182     <li><code>is_heap</code> tests whether or not a range is a heap.
 183     <li><code>is_sorted</code> tests whether or not a range is sorted in
 184         nondescending order.
 185    </ul>
 186 </p>
 187 <p>25.3.8 (lexigraphical_compare) is extended with
 188    <pre>
 189    lexicographical_compare_3way(_InputIter1 first1, _InputIter1 last1,
 190                                  _InputIter2 first2, _InputIter2 last2)</pre>
 191    which does... what?
 192 </p>
 193 <p>Return <a href="howto.html">to the main extensions page</a> or
 194    <a href="http://gcc.gnu.org/libstdc++/">to the homepage</a>.
 195 </p>
 196
 197
 198 <hr>
 199 <a name="ch26"><h3>Chapter 26</h3></a>
 200 <p>26.4, the generalized numeric operations such as accumulate, are extended
 201    with the following functions:
 202    <pre>
 203    power (x, n);
 204    power (x, n, moniod_operation);</pre>
 205    Returns, in FORTRAN syntax, &quot;x ** n&quot; where n&gt;=0.  In the
 206    case of n == 0, returns the <a href="#ch20">identity element</a> for the
 207    monoid operation.  The two-argument signature uses multiplication (for
 208    a true &quot;power&quot; implementation), but addition is supported as well.
 209    The operation functor must be associative.
 210 </p>
 211 <p>The <code>iota</code> function wins the award for Extension With the
 212    Coolest Name.  It &quot;assigns sequentially increasing values to a range.
 213    That is, it assigns value to *first, value + 1 to *(first + 1) and so
 214    on.&quot;  Quoted from SGI documentation.
 215    <pre>
 216    void iota(_ForwardIter first, _ForwardIter last, _Tp value);</pre>
 217 </p>
 218 <p>Return <a href="howto.html">to the main extensions page</a> or
 219    <a href="http://gcc.gnu.org/libstdc++/">to the homepage</a>.
 220 </p>
 221
 222
 223 <!-- ####################################################### -->
 224
 225 <hr>
 226 <p class="fineprint"><em>
 227 See <a href="../17_intro/license.html">license.html</a> for copying conditions.
 228 Comments and suggestions are welcome, and may be sent to
 229 <a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
 230 </em></p>
 231
 232
 233 </body>
 234 </html>