Author: pme@gcc.gnu.org (Phil Edwards)
Description: SGI extensions preserved in libstdc++-v3.
Keywords: libstdc++, libstdc++-v3, GCC, g++, STL, SGI

# SGI extensions to the library in libstdc++-v3

This page describes the extensions that SGI made to their version of the STL subset of the Standard C++ Library. For a time we tracked and imported changes and updates from most of the SGI STL, up through their (apparently) final release. Their extensions were mostly preserved.

They are listed according to the chapters of the library that they extend (see the chapter-specific notes for a description). Not every chapter may have extensions, and the extensions may come and go. Also, this page is incomplete because the author is pressed for time. Check back often; the latest change was on $Date: 2003/04/16 17:02:47 $ (UTC).

Descriptions range from the scanty to the verbose. You should also check the generated documentation for notes and comments, especially for entries marked with '*'. For more complete doumentation, see the SGI website. For really complete documentation, buy a copy of Matt Austern's book. *grin*

Back to the libstdc++-v3 extensions.

### Chapter 20

The <functional> header contains many additional functors and helper functions, extending section 20.3. They are implemented in the file stl_function.h:

- `identity_element` for addition and multiplication. *
- The functor `identity`, whose `operator()` returns the argument unchanged. *
- Composition functors `unary_function` and `binary_function`, and their helpers `compose1` and `compose2`. *
- `select1st` and `select2nd`, to strip pairs. *
- `project1st` and `project2nd`. *
- A set of functors/functions which always return the same result. They are `constant_void_fun`, `constant_binary_fun`, `constant_unary_fun`, `constant0`, `constant1`, and `constant2`. *
- The class `subtractive_rng`. *
- mem_fun adaptor helpers `mem_fun1` and `mem_fun1_ref` are provided for backwards compatibility.

20.4.1 can use several different allocators; they are described on the main extensions page.

20.4.3 is extended with a special version of `get_temporary_buffer` taking a second argument. The argument is a pointer, which is ignored, but can be used to specify the template type (instead of using explicit function template arguments like the standard version does). That is, in addition to

       get_temporary_buffer<int>(5);

you can also use

       get_temporary_buffer(5, (int*)0);

A class `temporary_buffer` is given in stl_tempbuf.h. *

The specialized algorithms of section 20.4.4 are extended with `uninitialized_copy_n`. *

Return to the main extensions page or to the homepage.

### Chapter 23

A few extensions and nods to backwards-compatibility have been made with containers. Those dealing with older SGI-style allocators are dealt with elsewhere. The remaining ones all deal with bits:

The old pre-standard `bit_vector` class is present for backwards compatibility. It is simply a typedef for the `vector<bool>` specialization.

The `bitset` class has a number of extensions, described in the rest of this item. First, we'll mention that this implementation of `bitset<N>` is specialized for cases where N number of bits will fit into a single word of storage. If your choice of N is within that range (<=32 on i686-pc-linux-gnu, for example), then all of the operations will be faster.

There are versions of single-bit test, set, reset, and flip member functions which do no range-checking. If we call them member functions of an instantiation of "bitset<N>," then their names and signatures are:

       bitset<N>&   _Unchecked_set   (size_t pos);
       bitset<N>&   _Unchecked_set   (size_t pos, int val);
       bitset<N>&   _Unchecked_reset (size_t pos);
       bitset<N>&   _Unchecked_flip  (size_t pos);
       bool         _Unchecked_test  (size_t pos);

Note that these may in fact be removed in the future, although we have no present plans to do so (and there doesn't seem to be any immediate reason to).

The semantics of member function `operator[]` are not specified in the C++ standard. A long-standing defect report calls for sensible obvious semantics, which are already implemented here: `op[]` on a const bitset returns a bool, and for a non-const bitset returns a `reference` (a nested type). However, this implementation does no range-checking on the index argument, which is in keeping with other containers' `op[]` requirements. The defect report's proposed resolution calls for range-checking to be done. We'll just wait and see...

Finally, two additional searching functions have been added. They return the index of the first "on" bit, and the index of the first "on" bit that is after `prev`, respectively:

       size_t _Find_first() const;
       size_t _Find_next (size_t prev) const;

The same caveat given for the _Unchecked_* functions applies here also.

Return to the main extensions page or to the homepage.

### Chapter 24

24.3.2 describes `struct iterator`, which didn't exist in the original HP STL implementation (the language wasn't rich enough at the time). For backwards compatibility, base classes are provided which declare the same nested typedefs:

- input_iterator
- output_iterator
- forward_iterator
- bidirectional_iterator
- random_access_iterator

24.3.4 describes iterator operation `distance`, which takes two iterators and returns a result. It is extended by another signature which takes two iterators and a reference to a result. The result is modified, and the function returns nothing.

Return to the main extensions page or to the homepage.

### Chapter 25

25.1.6 (count, count_if) is extended with two more versions of count and count_if. The standard versions return their results. The additional signatures return void, but take a final parameter by reference to which they assign their results, e.g.,

       void count (first, last, value, n);

25.2 (mutating algorithms) is extended with two families of signatures, random_sample and random_sample_n.

25.2.1 (copy) is extended with

       copy_n (_InputIter first, _Size count, _OutputIter result);

which copies the first 'count' elements at 'first' into 'result'.

25.3 (sorting 'n' heaps 'n' stuff) is extended with some helper predicates. Look in the doxygen-generated pages for notes on these.

- `is_heap` tests whether or not a range is a heap.
- `is_sorted` tests whether or not a range is sorted in nondescending order.

25.3.8 (lexigraphical_compare) is extended with

       lexicographical_compare_3way(_InputIter1 first1, _InputIter1 last1,
                                     _InputIter2 first2, _InputIter2 last2)

which does... what?

Return to the main extensions page or to the homepage.

### Chapter 26

26.4, the generalized numeric operations such as accumulate, are extended with the following functions:

       power (x, n);
       power (x, n, moniod_operation);

Returns, in FORTRAN syntax, "x ** n" where n>=0. In the case of n == 0, returns the identity element for the monoid operation. The two-argument signature uses multiplication (for a true "power" implementation), but addition is supported as well. The operation functor must be associative.

The `iota` function wins the award for Extension With the Coolest Name. It "assigns sequentially increasing values to a range. That is, it assigns value to *first, value + 1 to *(first + 1) and so on." Quoted from SGI documentation.

       void iota(_ForwardIter first, _ForwardIter last, _Tp value);

Return to the main extensions page or to the homepage.

See license.html for copying conditions. Comments and suggestions are welcome, and may be sent to the libstdc++ mailing list.