# STL extensions from SGI

## Classes

class | __gnu_cxx::unary_compose< Operation1, Operation2 >
| An SGI extension . More...
class | __gnu_cxx::binary_compose< Operation1, Operation2, Operation3 >
| An SGI extension . More...
struct | __gnu_cxx::select1st< Pair >
| An SGI extension . More...
struct | __gnu_cxx::select2nd< Pair >
| An SGI extension . More...
struct | __gnu_cxx::project1st< Arg1, Arg2 >
| An SGI extension . More...
struct | __gnu_cxx::project2nd< Arg1, Arg2 >
| An SGI extension . More...
struct | __gnu_cxx::constant_void_fun< Result >
| An SGI extension . More...
struct | __gnu_cxx::constant_unary_fun< Result, Argument >
| An SGI extension . More...
struct | __gnu_cxx::constant_binary_fun< Result, Arg1, Arg2 >
| An SGI extension . More...
class | __gnu_cxx::subtractive_rng
class | __gnu_cxx::hash_map< Key, Type, HashFcn, EqualKey, Alloc >
class | __gnu_cxx::hash_multimap< Key, Type, HashFcn, EqualKey, Alloc >
class | __gnu_cxx::hash_set< Value, HashFcn, EqualKey, Alloc >
class | __gnu_cxx::hash_multiset< Value, HashFcn, EqualKey, Alloc >
struct | __gnu_cxx::temporary_buffer< ForwardIterator, Type >
struct | __gnu_cxx::rb_tree< Key, Value, KeyOfValue, Compare, Alloc >
class | __gnu_cxx::rope< CharT, Alloc >
class | __gnu_cxx::slist< Type, Alloc >

## [NOHEADER]

bitset< Nb > & | std::bitset::Unchecked_set (size_t position)
bitset< Nb > & | std::bitset::Unchecked_set (size_t position, int __val)
bitset< Nb > & | std::bitset::Unchecked_reset (size_t position)
bitset< Nb > & | std::bitset::Unchecked_flip (size_t position)
bool | std::bitset::Unchecked_test (size_t position) const

## Functions

template<typename Type> const Type & | std::__median (const Type &a, const Type &__b, const Type &c)
| Find the median of three values.
template<typename Type, typename Compare> const Type & | std::__median (const Type &a, const Type &__b, const Type &c, Compare comp)
| Find the median of three values using a predicate for comparison.
size_t | std::bitset::Find_first () const
| Finds the index of the first "on" bit.
size_t | std::bitset::Find_next (size_t __prev) const
| Finds the index of the next "on" bit after prev.
template<typename InputIterator, typename Size, typename OutputIterator> pair< InputIterator, OutputIterator > | __gnu_cxx::copy_n (InputIterator first, Size count, OutputIterator __result)
| Copies the range [first,first+count) into [result,result+count).
template<typename InputIterator1, typename InputIterator2> int | __gnu_cxx::lexicographical_compare_3way (InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, InputIterator2 last2)
| `memcmp` on steroids.
template<typename ForwardIterator, typename OutputIterator, typename Distance> OutputIterator | __gnu_cxx::random_sample_n (ForwardIterator first, ForwardIterator last, OutputIterator out, const Distance n)
template<typename ForwardIterator, typename OutputIterator, typename Distance, typename RandomNumberGenerator> OutputIterator | __gnu_cxx::random_sample_n (ForwardIterator first, ForwardIterator last, OutputIterator out, const Distance n, RandomNumberGenerator &__rand)
template<typename InputIterator, typename RandomAccessIterator> RandomAccessIterator | __gnu_cxx::random_sample (InputIterator first, InputIterator last, RandomAccessIterator out_first, RandomAccessIterator out_last)
template<typename InputIterator, typename RandomAccessIterator, typename RandomNumberGenerator> RandomAccessIterator | __gnu_cxx::random_sample (InputIterator first, InputIterator last, RandomAccessIterator out_first, RandomAccessIterator out_last, RandomNumberGenerator &__rand)
template<typename RandomAccessIterator> bool | __gnu_cxx::is_heap (RandomAccessIterator first, RandomAccessIterator last)
template<typename RandomAccessIterator, typename StrictWeakOrdering> bool | __gnu_cxx::is_heap (RandomAccessIterator first, RandomAccessIterator last, StrictWeakOrdering comp)
template<typename ForwardIterator> bool | __gnu_cxx::is_sorted (ForwardIterator first, ForwardIterator last)
template<typename ForwardIterator, typename StrictWeakOrdering> bool | __gnu_cxx::is_sorted (ForwardIterator first, ForwardIterator last, StrictWeakOrdering comp)
template<class Type> Type | __gnu_cxx::identity_element (std::plus< Type >)
| An SGI extension .
template<class Type> Type | __gnu_cxx::identity_element (std::multiplies< Type >)
| An SGI extension .
template<class Operation1, class Operation2> unary_compose< Operation1, Operation2 > | __gnu_cxx::compose1 (const Operation1 &__fn1, const Operation2 &__fn2)
| An SGI extension .
template<class Operation1, class Operation2, class Operation3> binary_compose< Operation1, Operation2, Operation3 > | __gnu_cxx::compose2 (const Operation1 &__fn1, const Operation2 &__fn2, const Operation3 &__fn3)
| An SGI extension .
template<class Result> constant_void_fun< Result > | __gnu_cxx::constant0 (const Result &__val)
| An SGI extension .
template<class Result> constant_unary_fun< Result, Result > | __gnu_cxx::constant1 (const Result &__val)
| An SGI extension .
template<class Result> constant_binary_fun< Result, Result, Result > | __gnu_cxx::constant2 (const Result &__val)
| An SGI extension .
template<typename InputIterator, typename Distance> void | __gnu_cxx::distance (InputIterator first, InputIterator last, Distance &n)
template<typename InputIter, typename Size, typename ForwardIter> pair< InputIter, ForwardIter > | __gnu_cxx::uninitialized_copy_n (InputIter first, Size count, ForwardIter __result)
| Copies the range [first,last) into result.
template<typename Type, typename Integer, typename MonoidOperation> Type | __gnu_cxx::power (Type x, Integer n, MonoidOperation __monoid_op)
template<typename Type, typename Integer> Type | __gnu_cxx::power (Type x, Integer n)
template<typename ForwardIter, typename Type> void | __gnu_cxx::iota (ForwardIter first, ForwardIter last, Type value)

## Detailed Description

Because libstdc++-v3 based its implementation of the STL subsections of the library on the SGI 3.3 implementation, we inherited their extensions as well.

They are additionally documented in the online documentation, a copy of which is also shipped with the library source code (in .../docs/html/documentation.html). You can also read the documentation on SGI's site, which is still running even though the code is not maintained.

NB that the following notes are pulled from various comments all over the place, so they may seem stilted.

The `identity_element` functions are not part of the C++ standard; SGI provided them as an extension. Its argument is an operation, and its return value is the identity element for that operation. It is overloaded for addition and multiplication, and you can overload it for your own nefarious operations.

As an extension to the binders, SGI provided composition functors and wrapper functions to aid in their creation. The `unary_compose` functor is constructed from two functions/functors, `f` and `g`. Calling `operator()` with a single argument `x` returns `f`(g(x)). The function `compose1` takes the two functions and constructs a `unary_compose` variable for you.

`binary_compose` is constructed from three functors, `f`, `g1`, and `g2`. Its `operator()` returns `f`(g1(x),g2(x)). The function takes f, g1, and g2, and constructs the `binary_compose` instance for you. For example, if `f` returns an int, then

      int answer = (compose2(f,g1,g2))(x);

is equivalent to

      int temp1 = g1(x);
      int temp2 = g2(x);
      int answer = f(temp1,temp2);

But the first form is more compact, and can be passed around as a functor to other algorithms.

As an extension, SGI provided a functor called `identity`. When a functor is required but no operations are desired, this can be used as a pass-through. Its `operator()` returns its argument unchanged.

`select1st` and `select2nd` are extensions provided by SGI. Their `operator()s` take a `std::pair` as an argument, and return either the first member or the second member, respectively. They can be used (especially with the composition functors) to "strip" data from a sequence before performing the remainder of an algorithm.

The `operator()` of the `project1st` functor takes two arbitrary arguments and returns the first one, while `project2nd` returns the second one. They are extensions provided by SGI.

These three functors are each constructed from a single arbitrary variable/value. Later, their `operator()s` completely ignore any arguments passed, and return the stored value.

- `constant_void_fun's` `operator()` takes no arguments
- `constant_unary_fun's` `operator()` takes one argument (ignored)
- `constant_binary_fun's` `operator()` takes two arguments (ignored)

The helper creator functions `constant0`, `constant1`, and `constant2` each take a "result" argument and construct variables of the appropriate functor type.

## Function Documentation

template<typename Type, typename Compare>
const Type& __median | ( | const Type & | a,
|  | const Type & | __b,
|  | const Type & | c,
|  | Compare | comp
| ) | `[inline]`

Find the median of three values using a predicate for comparison.

Parameters:

  | a | A value.
  | b | A value.
  | c | A value.
  | comp | A binary predicate.

Returns:
  One of `a`, `b` or `c`.

If `{l`,m,n} is some convolution of `{a`,b,c} such that `comp(l,m)` and `comp(m,n)` are both true then the value returned will be `m`. This is an SGI extension.

Definition at line 120 of file stl_algo.h.

template<typename Type>
const Type& __median | ( | const Type & | a,
|  | const Type & | __b,
|  | const Type & | c
| ) | `[inline]`

Find the median of three values.

Parameters:

  | a | A value.
  | b | A value.
  | c | A value.

Returns:
  One of `a`, `b` or `c`.

If `{l`,m,n} is some convolution of `{a`,b,c} such that `l<=m<=n` then the value returned will be `m`. This is an SGI extension.

Definition at line 86 of file stl_algo.h.

template<class Operation1, class Operation2>
unary_compose<Operation1,Operation2> compose1 | ( | const Operation1 & | __fn1,
|  | const Operation2 & | __fn2
| ) | `[inline]`

| An SGI extension . Definition at line 144 of file ext/functional.

template<class Operation1, class Operation2, class Operation3>
binary_compose<Operation1, Operation2, Operation3> compose2 | ( | const Operation1 & | __fn1,
|  | const Operation2 & | __fn2,
|  | const Operation3 & | __fn3
| ) | `[inline]`

| An SGI extension . Definition at line 171 of file ext/functional.

template<class Result>
constant_void_fun<Result> constant0 | ( | const Result & | __val | ) | `[inline]`

| An SGI extension . Definition at line 306 of file ext/functional.

template<class Result>
constant_unary_fun<Result,Result> constant1 | ( | const Result & | __val | ) | `[inline]`

| An SGI extension . Definition at line 313 of file ext/functional.

template<class Result>
constant_binary_fun<Result,Result,Result> constant2 | ( | const Result & | __val | ) | `[inline]`

| An SGI extension . Definition at line 321 of file ext/functional.

template<typename InputIterator, typename Size, typename OutputIterator>
pair<InputIterator, OutputIterator> copy_n | ( | InputIterator | first,
|  | Size | count,
|  | OutputIterator | __result
| ) | `[inline]`

Copies the range [first,first+count) into [result,result+count).

Parameters:

  | first | An input iterator.
  | count | The number of elements to copy.
  | result | An output iterator.

Returns:
  A std::pair composed of first+count and result+count.

This is an SGI extension. This inline function will boil down to a call to `memmove` whenever possible. Failing that, if random access iterators are passed, then the loop count will be known (and therefore a candidate for compiler optimizations such as unrolling).

Definition at line 122 of file ext/algorithm.

template<typename InputIterator, typename Distance>
void distance | ( | InputIterator | first,
|  | InputIterator | last,
|  | Distance & | n
| ) | `[inline]`

This is an SGI extension.

Todo:
  Doc me! See docs/doxygen/TODO and http://gcc.gnu.org/ml/libstdc++/2002-02/msg00003.html for more.

Definition at line 105 of file ext/iterator.

template<size_t Nb>
size_t std::bitset< Nb >::Find_first | ( |  | ) | const`[inline, inherited]`

Finds the index of the first "on" bit.

Returns:
  The index of the first bit set, or size() if not found.

See also:
  Find_next

Definition at line 1111 of file bitset.

template<size_t Nb>
size_t std::bitset< Nb >::Find_next | ( | size_t | __prev | ) | const`[inline, inherited]`

Finds the index of the next "on" bit after prev.

Returns:
  The index of the next bit set, or size() if not found.

Parameters:

  | prev | Where to start searching.

See also:
  Find_first

Definition at line 1122 of file bitset.

template<class Type>
Type identity_element | ( | std::multiplies< Type > |  | ) | `[inline]`

| An SGI extension . Definition at line 92 of file ext/functional.

template<class Type>
Type identity_element | ( | std::plus< Type > |  | ) | `[inline]`

| An SGI extension . Definition at line 88 of file ext/functional.

template<typename ForwardIter, typename Type>
void iota | ( | ForwardIter | first,
|  | ForwardIter | last,
|  | Type | value
| ) |

This is an SGI extension.

Todo:
  Doc me! See docs/doxygen/TODO and http://gcc.gnu.org/ml/libstdc++/2002-02/msg00003.html for more.

Definition at line 138 of file ext/numeric.

template<typename RandomAccessIterator, typename StrictWeakOrdering>
bool is_heap | ( | RandomAccessIterator | first,
|  | RandomAccessIterator | last,
|  | StrictWeakOrdering | comp
| ) | `[inline]`

This is an SGI extension.

Todo:
  Doc me! See docs/doxygen/TODO and http://gcc.gnu.org/ml/libstdc++/2002-02/msg00003.html for more.

Definition at line 451 of file ext/algorithm.

template<typename RandomAccessIterator>
bool is_heap | ( | RandomAccessIterator | first,
|  | RandomAccessIterator | last
| ) | `[inline]`

This is an SGI extension.

Todo:
  Doc me! See docs/doxygen/TODO and http://gcc.gnu.org/ml/libstdc++/2002-02/msg00003.html for more.

Definition at line 432 of file ext/algorithm.

template<typename ForwardIterator, typename StrictWeakOrdering>
bool is_sorted | ( | ForwardIterator | first,
|  | ForwardIterator | last,
|  | StrictWeakOrdering | comp
| ) |

This is an SGI extension.

Todo:
  Doc me! See docs/doxygen/TODO and http://gcc.gnu.org/ml/libstdc++/2002-02/msg00003.html for more.

Definition at line 504 of file ext/algorithm.

template<typename ForwardIterator>
bool is_sorted | ( | ForwardIterator | first,
|  | ForwardIterator | last
| ) |

This is an SGI extension.

Todo:
  Doc me! See docs/doxygen/TODO and http://gcc.gnu.org/ml/libstdc++/2002-02/msg00003.html for more.

Definition at line 476 of file ext/algorithm.

template<typename InputIterator1, typename InputIterator2>
int lexicographical_compare_3way | ( | InputIterator1 | first1,
|  | InputIterator1 | last1,
|  | InputIterator2 | first2,
|  | InputIterator2 | last2
| ) |

`memcmp` on steroids.

Parameters:

  | first1 | An input iterator.
  | last1 | An input iterator.
  | first2 | An input iterator.
  | last2 | An input iterator.

Returns:
  An int, as with `memcmp`.

The return value will be less than zero if the first range is "lexigraphically less than" the second, greater than zero if the second range is "lexigraphically less than" the first, and zero otherwise. This is an SGI extension.

Definition at line 201 of file ext/algorithm.

template<typename Type, typename Integer>
Type power | ( | Type | x,
|  | Integer | n
| ) | `[inline]`

This is an SGI extension.

Todo:
  Doc me! See docs/doxygen/TODO and http://gcc.gnu.org/ml/libstdc++/2002-02/msg00003.html for more.

Definition at line 126 of file ext/numeric.

template<typename Type, typename Integer, typename MonoidOperation>
Type power | ( | Type | x,
|  | Integer | n,
|  | MonoidOperation | __monoid_op
| ) | `[inline]`

This is an SGI extension.

Todo:
  Doc me! See docs/doxygen/TODO and http://gcc.gnu.org/ml/libstdc++/2002-02/msg00003.html for more.

Definition at line 115 of file ext/numeric.

template<typename InputIterator, typename RandomAccessIterator, typename RandomNumberGenerator>
RandomAccessIterator random_sample | ( | InputIterator | first,
|  | InputIterator | last,
|  | RandomAccessIterator | out_first,
|  | RandomAccessIterator | out_last,
|  | RandomNumberGenerator & | __rand
| ) | `[inline]`

This is an SGI extension.

Todo:
  Doc me! See docs/doxygen/TODO and http://gcc.gnu.org/ml/libstdc++/2002-02/msg00003.html for more.

Definition at line 408 of file ext/algorithm.

template<typename InputIterator, typename RandomAccessIterator>
RandomAccessIterator random_sample | ( | InputIterator | first,
|  | InputIterator | last,
|  | RandomAccessIterator | out_first,
|  | RandomAccessIterator | out_last
| ) | `[inline]`

This is an SGI extension.

Todo:
  Doc me! See docs/doxygen/TODO and http://gcc.gnu.org/ml/libstdc++/2002-02/msg00003.html for more.

Definition at line 385 of file ext/algorithm.

template<typename ForwardIterator, typename OutputIterator, typename Distance, typename RandomNumberGenerator>
OutputIterator random_sample_n | ( | ForwardIterator | first,
|  | ForwardIterator | last,
|  | OutputIterator | out,
|  | const Distance | n,
|  | RandomNumberGenerator & | __rand
| ) |

This is an SGI extension.

Todo:
  Doc me! See docs/doxygen/TODO and http://gcc.gnu.org/ml/libstdc++/2002-02/msg00003.html for more.

Definition at line 299 of file ext/algorithm.

References std::distance().

template<typename ForwardIterator, typename OutputIterator, typename Distance>
OutputIterator random_sample_n | ( | ForwardIterator | first,
|  | ForwardIterator | last,
|  | OutputIterator | out,
|  | const Distance | n
| ) |

This is an SGI extension.

Todo:
  Doc me! See docs/doxygen/TODO and http://gcc.gnu.org/ml/libstdc++/2002-02/msg00003.html for more.

Definition at line 265 of file ext/algorithm.

References std::distance().

template<size_t Nb>
bitset<Nb>& std::bitset< Nb >::Unchecked_flip | ( | size_t | position | ) | `[inline, inherited]`

| These versions of single-bit set, reset, flip, and test are extensions from the SGI version. They do no range checking. Definition at line 881 of file bitset.

template<size_t Nb>
bitset<Nb>& std::bitset< Nb >::Unchecked_reset | ( | size_t | position | ) | `[inline, inherited]`

| These versions of single-bit set, reset, flip, and test are extensions from the SGI version. They do no range checking. Definition at line 874 of file bitset.

template<size_t Nb>
bitset<Nb>& std::bitset< Nb >::Unchecked_set | ( | size_t | position,
|  | int | __val
| ) | `[inline, inherited]`

| These versions of single-bit set, reset, flip, and test are extensions from the SGI version. They do no range checking. Definition at line 864 of file bitset.

template<size_t Nb>
bitset<Nb>& std::bitset< Nb >::Unchecked_set | ( | size_t | position | ) | `[inline, inherited]`

| These versions of single-bit set, reset, flip, and test are extensions from the SGI version. They do no range checking. Definition at line 857 of file bitset.

template<size_t Nb>
bool std::bitset< Nb >::Unchecked_test | ( | size_t | position | ) | const`[inline, inherited]`

| These versions of single-bit set, reset, flip, and test are extensions from the SGI version. They do no range checking. Definition at line 888 of file bitset.

template<typename InputIter, typename Size, typename ForwardIter>
pair<InputIter, ForwardIter> uninitialized_copy_n | ( | InputIter | first,
|  | Size | count,
|  | ForwardIter | __result
| ) | `[inline]`

Copies the range [first,last) into result.

Parameters:

  | first | An input iterator.
  | last | An input iterator.
  | result | An output iterator.

Returns:
  result + (first - last)

Like copy(), but does not require an initialized output range.

Definition at line 129 of file ext/memory.