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

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