# STL extensions from SGI

## Compounds

class | binary_compose
| An SGI extension . More...
struct | constant_binary_fun
| An SGI extension . More...
struct | constant_unary_fun
| An SGI extension . More...
struct | constant_void_fun
| An SGI extension . More...
class | hash_map
class | hash_multimap
class | hash_multiset
class | hash_set
struct | project1st
| An SGI extension . More...
struct | project2nd
| An SGI extension . More...
struct | rb_tree
class | rope
struct | select1st
| An SGI extension . More...
struct | select2nd
| An SGI extension . More...
class | slist
class | subtractive_rng
struct | temporary_buffer
class | unary_compose
| An SGI extension . More...

## [NOHEADER]

bitset< _Nb > & | _Unchecked_set (size_t __pos)
bitset< _Nb > & | _Unchecked_set (size_t __pos, int __val)
bitset< _Nb > & | _Unchecked_reset (size_t __pos)
bitset< _Nb > & | _Unchecked_flip (size_t __pos)
bool | _Unchecked_test (size_t __pos) const

## Functions

template<typename _Tp> const _Tp & | __median (const _Tp &__a, const _Tp &__b, const _Tp &__c)
| Find the median of three values.
template<typename _Tp, typename _Compare> const _Tp & | __median (const _Tp &__a, const _Tp &__b, const _Tp &__c, _Compare __comp)
| Find the median of three values using a predicate for comparison.
size_t | _Find_first () const
| Finds the index of the first "on" bit.
size_t | _Find_next (size_t __prev) const
| Finds the index of the next "on" bit after prev.
template<typename _InputIter, typename _Size, typename _OutputIter> pair< _InputIter, _OutputIter > | copy_n (_InputIter __first, _Size __count, _OutputIter __result)
| Copies the range [first,first+count) into [result,result+count).
template<typename _InputIter1, typename _InputIter2> int | lexicographical_compare_3way (_InputIter1 __first1, _InputIter1 __last1, _InputIter2 __first2, _InputIter2 __last2)
| `memcmp` on steroids.
template<typename _ForwardIter, typename _OutputIter, typename _Distance> _OutputIter | random_sample_n (_ForwardIter __first, _ForwardIter __last, _OutputIter __out, const _Distance __n)
template<typename _ForwardIter, typename _OutputIter, typename _Distance, typename _RandomNumberGenerator> _OutputIter | random_sample_n (_ForwardIter __first, _ForwardIter __last, _OutputIter __out, const _Distance __n, _RandomNumberGenerator &__rand)
template<typename _InputIter, typename _RandomAccessIter> _RandomAccessIter | random_sample (_InputIter __first, _InputIter __last, _RandomAccessIter __out_first, _RandomAccessIter __out_last)
template<typename _InputIter, typename _RandomAccessIter, typename _RandomNumberGenerator> _RandomAccessIter | random_sample (_InputIter __first, _InputIter __last, _RandomAccessIter __out_first, _RandomAccessIter __out_last, _RandomNumberGenerator &__rand)
template<typename _RandomAccessIter> bool | is_heap (_RandomAccessIter __first, _RandomAccessIter __last)
template<typename _RandomAccessIter, typename _StrictWeakOrdering> bool | is_heap (_RandomAccessIter __first, _RandomAccessIter __last, _StrictWeakOrdering __comp)
template<typename _ForwardIter> bool | is_sorted (_ForwardIter __first, _ForwardIter __last)
template<typename _ForwardIter, typename _StrictWeakOrdering> bool | is_sorted (_ForwardIter __first, _ForwardIter __last, _StrictWeakOrdering __comp)
template<class _Tp> _Tp | identity_element (std::plus< _Tp >)
| An SGI extension .
template<class _Tp> _Tp | identity_element (std::multiplies< _Tp >)
| An SGI extension .
template<class _Operation1, class _Operation2> unary_compose< _Operation1, _Operation2 > | compose1 (const _Operation1 &__fn1, const _Operation2 &__fn2)
| An SGI extension .
template<class _Operation1, class _Operation2, class _Operation3> binary_compose< _Operation1, _Operation2, _Operation3 > | compose2 (const _Operation1 &__fn1, const _Operation2 &__fn2, const _Operation3 &__fn3)
| An SGI extension .
template<class _Result> constant_void_fun< _Result > | constant0 (const _Result &__val)
| An SGI extension .
template<class _Result> constant_unary_fun< _Result, _Result > | constant1 (const _Result &__val)
| An SGI extension .
template<class _Result> constant_binary_fun< _Result, _Result, _Result > | constant2 (const _Result &__val)
| An SGI extension .
template<typename _InputIterator, typename _Distance> void | distance (_InputIterator __first, _InputIterator __last, _Distance &__n)
template<typename _InputIter, typename _Size, typename _ForwardIter> pair< _InputIter, _ForwardIter > | uninitialized_copy_n (_InputIter __first, _Size __count, _ForwardIter __result)
| Copies the range [first,last) into result.
template<typename _Tp, typename _Integer, typename _MonoidOperation> _Tp | power (_Tp __x, _Integer __n, _MonoidOperation __monoid_op)
template<typename _Tp, typename _Integer> _Tp | power (_Tp __x, _Integer __n)
template<typename _ForwardIter, typename _Tp> void | iota (_ForwardIter __first, _ForwardIter __last, _Tp __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 _Tp, typename _Compare>
const _Tp& __median | ( | const _Tp & | __a,
|  | const _Tp & | __b,
|  | const _Tp & | __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 _Tp>
const _Tp& __median | ( | const _Tp & | __a,
|  | const _Tp & | __b,
|  | const _Tp & | __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.

Referenced by std::nth_element().

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 1091 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 1102 of file bitset.

template<size_t _Nb>
bitset<_Nb>& std::bitset< _Nb >::_Unchecked_flip | ( | size_t | __pos | ) | `[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 867 of file bitset. Referenced by std::bitset< _Nb >::flip().

template<size_t _Nb>
bitset<_Nb>& std::bitset< _Nb >::_Unchecked_reset | ( | size_t | __pos | ) | `[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 860 of file bitset. Referenced by std::bitset< _Nb >::reset().

template<size_t _Nb>
bitset<_Nb>& std::bitset< _Nb >::_Unchecked_set | ( | size_t | __pos,
|  | 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 850 of file bitset.

template<size_t _Nb>
bitset<_Nb>& std::bitset< _Nb >::_Unchecked_set | ( | size_t | __pos | ) | `[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 843 of file bitset. Referenced by std::bitset< _Nb >::set().

template<size_t _Nb>
bool std::bitset< _Nb >::_Unchecked_test | ( | size_t | __pos | ) | 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 874 of file bitset. Referenced by std::bitset< _Nb >::operator[](), and std::bitset< _Nb >::test().

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

| An SGI extension . Definition at line 143 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 170 of file ext/functional.

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

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

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

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

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

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

template<typename _InputIter, typename _Size, typename _OutputIter>
pair<_InputIter, _OutputIter> copy_n | ( | _InputIter | __first,
|  | _Size | __count,
|  | _OutputIter | __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 121 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 103 of file ext/iterator.

Referenced by std::list< _Tp, _Alloc >::size().

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

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

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

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

template<typename _ForwardIter, typename _Tp>
void iota | ( | _ForwardIter | __first,
|  | _ForwardIter | __last,
|  | _Tp | __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 137 of file ext/numeric.

template<typename _RandomAccessIter, typename _StrictWeakOrdering>
bool is_heap | ( | _RandomAccessIter | __first,
|  | _RandomAccessIter | __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 465 of file ext/algorithm.

template<typename _RandomAccessIter>
bool is_heap | ( | _RandomAccessIter | __first,
|  | _RandomAccessIter | __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 448 of file ext/algorithm.

template<typename _ForwardIter, typename _StrictWeakOrdering>
bool is_sorted | ( | _ForwardIter | __first,
|  | _ForwardIter | __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 514 of file ext/algorithm.

template<typename _ForwardIter>
bool is_sorted | ( | _ForwardIter | __first,
|  | _ForwardIter | __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 488 of file ext/algorithm.

template<typename _InputIter1, typename _InputIter2>
int lexicographical_compare_3way | ( | _InputIter1 | __first1,
|  | _InputIter1 | __last1,
|  | _InputIter2 | __first2,
|  | _InputIter2 | __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 200 of file ext/algorithm.

template<typename _Tp, typename _Integer>
_Tp power | ( | _Tp | __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 125 of file ext/numeric.

template<typename _Tp, typename _Integer, typename _MonoidOperation>
_Tp power | ( | _Tp | __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 _InputIter, typename _RandomAccessIter, typename _RandomNumberGenerator>
_RandomAccessIter random_sample | ( | _InputIter | __first,
|  | _InputIter | __last,
|  | _RandomAccessIter | __out_first,
|  | _RandomAccessIter | __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 393 of file ext/algorithm.

template<typename _InputIter, typename _RandomAccessIter>
_RandomAccessIter random_sample | ( | _InputIter | __first,
|  | _InputIter | __last,
|  | _RandomAccessIter | __out_first,
|  | _RandomAccessIter | __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 373 of file ext/algorithm.

template<typename _ForwardIter, typename _OutputIter, typename _Distance, typename _RandomNumberGenerator>
_OutputIter random_sample_n | ( | _ForwardIter | __first,
|  | _ForwardIter | __last,
|  | _OutputIter | __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 289 of file ext/algorithm.

References std::distance(), and std::min().

template<typename _ForwardIter, typename _OutputIter, typename _Distance>
_OutputIter random_sample_n | ( | _ForwardIter | __first,
|  | _ForwardIter | __last,
|  | _OutputIter | __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 257 of file ext/algorithm.

References std::distance(), and std::min().

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 128 of file ext/memory.