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