standard template library quick reference...standard template library quick reference containers...

Standard Template Library Quick Reference

Containers

Containers are general-purpose template classes that are designed to storeobjects of almost any type. They are useful by themselves, but become evenmore powerful when combined with other concepts such as iterators andalgorithms.

Standard Containers

Name Header Description

vector<T, Alloc> <vector> or<vector.h>

Acts very similar to a standard array thatcan grow to accommodate additionalelements.

deque<T, Alloc> <deque> or<deque.h>

This is a double-ended queue which isefficient at adding or removing elementsfrom either the beginning or end of thequeue.

list<T, Alloc> <list> or <list.h> A doubly-link list container that usespointers to nodes. One pointer stores thelocation of the next node and the secondpointer stores the location of the previousnode. Faster than the vector and dequecontainers at some operations, notablyadding or removing elements from themiddle of the container.

NOTE: The Alloc parameter allows you to define your own custom memoryallocator if needed. A custom memory allocator is useful is some situations suchas when working with embedded systems which do not have general-purposemalloc/free or new/delete operators.

Container Operation Costs

Operation C-Array vector deque list

Insert/erase at start N/A linear constant constant

Insert/erase at end N/A constant constant constant

Insert/erase in middle N/A linear linear constant

Access first element constant constant constant constant

Access last element constant constant constant constant

Access middle element constant constant constant linear

Operation C-Array vector deque list

Overhead none low medium high

Vector Advantages

– Vectors can be dynamically resized; when you run out of space it automaticallygrows

– Elements of a vector can be added or removed from the interior without needingto write custom code

– You can quickly access the start the or end of the vector, without knowing itsize in advance

– You can iterate forward or backward through a vector– It is a simple matter to add bounds checking for both operator[] and pointer

dereferencing– Objects in a vector can be stored in any kind of memory with the help of a

custom allocator– Unlike standard arrays, vector have usable assignment and comparison

operators.

Vector Disadvantages

– Most implementations have to store a total of 3 memory pointers, compared toone pointer for a standard C-style dynamically allocated array. This does useup very much extra memory, so it is usually not a great burden.

– A vector will never release memory, even when the number of elements in thevector is reduced.

Deque Advantages

– Since a deque acts a lot like a vector, it has the same advantages as using avector when compared to standard C-style arrays

– It can grow in either direction (front or back) equally well– It is often faster than a vector when the container needs to grow to hold new

elements

Deque Disadvantages

– The operator[] is not as fast as vector's operator[], although it is still pretty fast– Iterating over a deque is also slower than iterating over a vector

List Advantages

– Very fast element insertion/removal in the middle of the list– Implements its own memory management system which actually can be helpful

on some platforms

List Disadvantages

– No random access iterator (which means no operator[])– Uses extra memory to track next/previous node pointers (lists are best used for

large structure, not small data elements list a character)

General Guideline

Use a vector<> whenever possible since it has the lowest overhead and bestoverall performance. However, if you are going to add and removing items fromthe middle of the collection often, then consider using a list<>. Use a deque<>whenever you will be inserting elements at the head or end most of the time, butvery seldom from the middle of the collection.

Container Adapters

The following containers are specialized containers that use one of the standardcontainers to actually store the elements they manage. Basically they arewrappers around one of the standard container templates that provide a restrictedset of operations.

Container Header Description

stack<T,Sequence>

<stack> or <stack.h> Implements a standard LIFO (Last-In, First-Out) container. You willprobably use the push() and pop()members most often.

Queue<T,Sequence>

<queue> or <queue.h> Implements a standard FIFO (First-In, First-Out) container. Thiscontainer does not allow iteration.You will probably use the push() andtop()/pop() members most often.

priority_queue <queue> or <stack.h> This container implements a FIFO,with one small difference. Thelargest element is always the firstitem returned by the top() and pop()methods.

Associative Containers

An associative containers stores objects based on key values.

Container Header Description

set<Key, Compare,Alloc>

<set> or <set.h> This container holds a uniquecollection of objects in sortedsequence. The Compareparameter defines thefunction/functor to use forcomparing the objects (default isless<Key>) and the Allocparameter is for a custom memoryallocator.

multiset<Key,Compare, Alloc>

<set> or <multiset.h> This container holds a collectionof objects in sorted sequence.Unlike a standard set<>, this typeof container allows duplicate keys.

map<Key, Data,Compare, Alloc>

<map> or <map.h> Similar to a set<> container,except the key is distinct from thedata being stored. Internally amap stores pair<const Key, Data>elements, organized by Keyvalues. The pair<> is a helpertemplate. All Key values must beunique.

map<Key, Data,Compare, Alloc>

<map> or <multimap.h> Works like the standard map<>template, except duplicate Keyvalues are allowed.

Iterators

The standard template library makes heavy use of iterators, which basically actslike pointers. They are used to indicate a position within a collection of elementsand are most often used to process a range of elements.

Iterator Categories

Iterator Category Description

Input Iterator This type of iterator allows you to read the elementit references. It does not allow you to change theelement.

Output Iterator This type of iterator grants permission to write anelement, but does not guarantee read access isavailable (although it may allow reading theelement also.)

Forward Iterator A forward iterator generally supports both Input andOutput operations, unless the iterator is constant,which restricts its usage to reading only. Thedifference between a Forward iterator and an Inputor Output iterator is that Forward iterators canusually be used with multi-pass algorithms.

Bidirectional Iterator This is very similar to a Forward iterator, except itcan be both incremented and decremented. Not allof the container templates support Bidirectionaliterators.

Random Access Iterators This type of iterator supports incrementing,decrementing and also adding and subtractingarbitrary offsets, subscripting and more. They actmuch more like traditional pointers than the otheriterators.

Concrete Iterator Template Classes

Iterator Class Description

istream_iterator<T,Distance> Reads objects of type T from an input stream(such as cin). Stops when it reaches the end ofthe stream. Used often with the copy()algorithm.

ostream_iterator<T> Writes objects of type T to an output streams(such as cout). Used often with the copy()algorithm.

Iterator Class Description

reverse_iterator<RandomAccessIterator, T, Reference,Distance>

This iterator reverses the meaning of theincrement (++) and decrement (--) operators.

insert_iterator<Container> This iterator is used to insert objects into acontainer. It will track of the next point ofinsertion and advance automatically whenever anew element is inserted.

front_insert_iterator<FronInsertionSequence>

This iterator class is an output iterator thatalways inserts new elements at the front of thecontainer. The FrontInsertSequence means youcan only use this type of iterator with containersthat have the front(), push_front() andpop_front() methods. Primarily this includesthe deque<> and list<> template classes.

back_insert_iterator<BackInsertionSequence>

This iterator class is an output iterator thatalways appends new elements at the end of acontainer. The BackInsertionSequence meansyou can only use this type of iterator withcontainers that have the back(), push_back()and pop_back() methods. Primarily thisincludes the vector<>, list<> and deque<>template classes.

Algorithms

The Standard Template Library also includes a large number of template functionscollectively referred to as algorithms. The combination of the container classeswith the algorithm template functions provides C++ with many advanced andpowerful constructs.

Algorithm Types

Algorithm Type Description

Non-mutating Algorithms in this category are used to processand/or search a container, but never modify thecontainer's elements.

Mutating Algorithms in this category are used to modifycontainers in some way.

Sorting There are a number of algorithms available forsorting, searching and merging containers and theirelements.

Generalized Numeric These types of algorithms are used to perform somekind of mathematical operation against elements in acontainer.

Non-Mutating Algorithms

Remember, the non-mutating algorithms never modify the containers they areworking on.

Algorithm Description

UnaryFunction

for_each( InputIterator first,

InputIterator last,

UnaryFunction f)

Iterates all of the elements fromfirst to last and calls function fonce per element. The returnvalue is sometimes useful whendealing with functors.

InputIterator

find( InputIterator first,

InputIterator last,

const EqualityComparable& value)

Attempts to locate value in theelements pointed to by first andlast. The value is usually thesame type as the elements in thecontainer, but conversions areperformed if needed. Returns aniterator that points to the firstmatch if found. Returns last if theitem cannot be found.


InputIterator

find_if(InputIterator first,

InputIterator last,

Predicate pred)

Similar to the find() algorithm,except instead of comparingvalues directly, it passes eachelement in the range to a helperfunction (or functor) that tests theobject in some way and returns aboolean value. If the helperfunction returns true, the searchstops and an iterator to theelement is returned, otherwise lastis returned.

ForwardIterator

adjacent_find( ForwardIterator first,

ForwardIterator last)

ForwardIterator

adjacent_find( ForwardIterator first,

ForwardIterator last,

BinaryPredicate binary_pred )

This function iterates over thecontainer's elements to locate thefirst of 2 iterators that are valid.The first version is not very useful,the second works like find_if() soyou can call a custom function (orfunctor) that tests adjacentelements and returns a boolean.

InputIterator

find_first_of( InputIterator first1,

InputIterator last1,

ForwardIterator first2,

ForwardIterator last2)

InputIterator

find_first_of( InputIterator first1,


ForwardIterator first2,

ForwardIterator last2,

BinaryPredicate comp)

Similar to using find(), except thisalgorithm searches the firstsequence to find any element thatis also in a second sequence.

The second version of the functionallows you to use a customfunction (or functor) instead of thestandard operator==().


iterator_traits<InputIterator>::difference_type

count( InputIterator first,

InputIterator last,

const EqualityComparable& value)

void

count( InputIterator first,

InputIterator last,

const EqualityComparable& value,

Size& n )

This algorithm iterators over asequence and counts the numberof elements that match the givenvalue.

The first version returns thenumber of matches found, whilethe second version adds thenumber of matches to the valuereferenced by n.

The second version is deprecatedand may be removed later.

iterator_traits<InputIterator>::difference_type

count_if( InputIterator first,

InputIterator last,

Predicate pred)

void

count_if( InputIterator first,

InputIterator last,

Predicate pred,

Size& n)

Similar to the count() algorithm,but instead of comparing theelements to some value, passeseach element to a helper function(or functor) and only countselements where the helperfunction returns true.

The second version is deprecatedand may be removed later.

pair<InputIterator1, InputIterator2>

mismatch( InputIterator1 first1,

InputIterator1 last1,

InputIterator2 first2 )

pair<InputIterator1, InputIterator2>

mismatch( InputIterator1 first1,


InputIterator2 first2,


Searches the sequencereferences by first1 and last1 tofind an element that does notmatch the elements in first2. Inother words, finds the firstdifference between 2 containers.

The second versions of thealgorithm allows you to use acustom function (or functor) tocompare the elements in thecontainers.


bool

equals( InputIterator first1,


InputIterator2 first2 )

bool

equals( InputIterator first1,




Similar to the mismatch()algorithm, except this algorithmsimply returns true or false toindicate whether the 2 sequencesare equal or not.

Can also be done using:

mismatch(f1,l1,f2).first == l1

ForwardIterator1

search( ForwardIterator1 first1,

ForwardIterator1 last1,

ForwardIterator2 first2,

ForwardIterator2 last2 )

ForwardIterator1

search( ForwardIterator1 first1,





These algorithms attempt to findthe sequence first2->last2somewhere instead the sequencefirst1->last1.

This works a bit like searching fora substring within a larger string,except of course the elements canbe of any type, not just characters.

ForwardIterator

search_n( ForwardIterator first,


Integer count,

const T& value )

ForwardIterator

search_n( ForwardIterator first,


Integer count,

const T& value,


Attempts to find the position in thesequence where value is repeatedcount times in a row. Useful fortesting for repeated elements.

NOTE: Using 0 for count willalways succeed, no matter thevalue, since there will be nocomparisons performed.


ForwardIterator1

find_end( ForwardIterator1 first1,



ForwardIterator2 last2 )

ForwardIterator1

find_end( ForwardIterator1 first1,





Works similar to search().Probably should be namedsearch_end().

Instead of returning the first matchin the search, this algorithmreturns an iterator that points tothe last match instead.

Mutating Algorithms

The mutating algorithms are used to make changes to containers or the elementsinside a container.


OutputIterator

copy( InputIterator first,

InputIterator last,

OutputIterator result )

This algorithm copies theelements referenced by first->lastby overwriting the elements inresult.

NOTE; The output container mustbe large enough to hold all thecopied elements, since thisalgorithm assigns the copiedelements, it does not push them.

BidirectionalIterator2

copy_backward( BidirectionalIterator1 first,

BidirectionalIterator1 last,

BidirectionalIterator2 result )

Also copies the elements fromfirst->last into the container atresult, but copies from last to firstin backward sequence.

NOTE: result must point to theend of the sequence, not thebeginning.

void swap( Assignable& a, Assignable& b ) Assigns a to b and b to a.


void swap_iter( ForwardIterator1 a,

ForwardIterator2 b )

Same as swap( *a, *b ).

ForwardIterator2

swap_ranges( ForwardIterator1 first1,


ForwardIterator2 first2 )

Swaps all the elements pointed toby first1->last1 with the elementspointed to by first2.

OutputIterator

transform( InputIterator first,

InputIterator last,

OutputIterator result,

UnaryFunction op )

OutputIterator

transform( InputIterator1 first1,




BinaryFunction binary_op )

This is similar to the copy()algorithm, except before theelements are copied into the newcontainer, a helper function (orfunctor) is called that can change(transform) the elements in someway.

The second version allows you todo that same thing, except in thiscase you are extracting elementsfrom 2 different containers andcombining them into one resultcontainer, by calling a helperfunction that receives oneelement from each inputcontainer.

void

replace( ForwardIterator first,


const T& old_value,

const T& new_value )

Replaces every element withvalue old_value, with the valuenew_value in the sequence first->last.

void

replace_if( ForwardIterator first,


Predicate pred,


Similar to replace(), exceptinstead of comparing each inputelement against a value, calls ahelper function (or functor). If thehelper function returns true, theelement will be replaced bynew_value.


void

replace_copy( InputIterator first,

InputIterator last,


const T& old_value,


Copies all the elements into anew container, but replaces anyelements with old_value withnew_value if found during thecopy process.

void

replace_copy_if( InputIterator first,

InputIterator last,


Predicate pred,


Works like replace_copy(),except only replaces elementswith new_value if the helperfunction (or functor) returns true.

void

fill( ForwardIterator first,


const T& value )

Use this algorithm to quicklyassign value to the elementsreferenced by first->last.

OutputIterator

fill_n( OutputIterator first,

Size n,

const T& value )

This algorithm also assigns valueto the elements referenced byfirst. It does this n times.

void

generate( ForwardIterator first,


Generator gen )

This algorithm calls the helperfunction (or functor) gen andstores the results in eachelement referenced by first->last.

void

generate_n( OutputIterator first,

Size n,

Generator gen )

Calls the helper function (orfunctor) gen and assigns theresults to the iterator first, exactlyn times.


ForwardIterator

remove( ForwardIterator first,


const T& value )

Removes all elements with valuefrom the sequence referenced byfirst->last.

ForwardIterator

remove_if( ForwardIterator first,


Predicate pred )

Same as remove(), except callsthe helper function (or functor)pred to determine whether or notto remove the item. The helperfunction returns true when theelement should be removed.

OutputIterator

remove_copy( InputIterator first,

InputIterator last,


const T& value )

Copies elements in first->last toresult if they do not equal value.

OutputIterator

remove_copy_if( InputIterator first,

InputIterator last,

OuputIterator result,

Predicate pred )

Calls the helper function (orfunctor) pred for each element infirst->last and copies the elementto result if pred returns false. Inother words, true elements arenot copied.

ForwardIterator

unique( ForwardIterator first,

ForwardIterator last )

ForwardIterator

unique( ForwardIterator first,



Removes duplicate elementsfrom the sequence first->last sowhen completed, only uniqueelements remain. The secondflavor uses a helper function (orfunctor) to decide if elements areunique or not.


OutputIterator

unique_copy( InputIterator first,

InputIterator last,


OutputIterator

unique_copy( InputIterator first,

InputIterator last,



Copies only unique elements(skips consecutive duplicates)from first->last into result. Worksbest when the input container issorted.

void

reverse( BidirectionalIterator first,

BidirectionalIterator last )

Reverses a container so the lastelement becomes the first andthe first element becomes thelast and so on.

OutputIterator

reverse_copy( BidirectionalIterator first,

BidirectionalIterator last,


Copies elements first->last intocontainer result, in reversesequence.

ForwardIterator

rotate( ForwardIterator first,


ForwardIterator middle )

Rearranges the container somiddle becomes first and lastbecomes middle. This meansfirst also becomes middle+1.Acts like rotating a circle.

OutputIterator

rotate_copy( ForwardIterator first,

ForwardIterator middle,



Works like rotate(), exceptcopies the rotated elements intoresult. Faster then doing a copy() followed by a rotate().

void

random_shuffle( RandomAccessIterator first,

RandomAccessIterator last )

void

random_shuffle( RandomAccessIterator first,

RandomAccessIterator last,

RandomNumberGenerator& rand )

Randomly rearranges all theelements in first->last. Thesecond version allows you to usea custom random numbergenerator functor.


RandomAccessIterator

random_sample( InputIterator first,

InputIterator last,

RandomAccessIterator ofirst,

RandomAccessIterator olast )


random_sample( InputIterator first,

InputIterator last,

RandomAccessIterator ofirst,

RandomAccessIterator olast,


Works like the random_shuffle()algorithm, except instead ofrearranging the input container,copies the elements randomlyinto another container. Eachinput element will only appearonce in the output, in randomsequence.

Again a custom random numbergenerator can be used if needed.

OutputIterator

random_sample_n( ForwardIterator first,


OutputIterator out,

Distance n )

OutputIterator

random_sample_n( ForwardIterator first,


OutputIterator out,

Distance n,


Similar to random_sample(),except this algorithm stops aftercopying n elements. Thisalgorithm preserves the relativeorder of the copied elements.

ForwardIterator

partition( ForwardIterator first,


Predicate pred )

This algorithm rearranges theelements in first->last by callingthe helper function (or functor)pred against each element. Allelements where pred returns trueare placed before the elementsthat return false. The returnediterator will point to the middle.(i.e. The first false element.)


ForwardIterator

stable_partition( ForwardIterator first,


Predicate pred )

Same as partition(), except theelements will maintain theirrelative order within thesequence.

Sorting Algorithms

This group of algorithm are used to fully or partially sort the elements in acontainer.


void

sort( RandomAccessIterator first,


void

sort( RandomAccessIterator first,


Compare comp )

Rearranges the container so theelements are in sorted sequence.By default, it uses operator<() tocompare elements.

The second version allows you touse a helper function (or function)to get custom sort sequences.

void

stable_sort( RandomAccessIterator first,


void

stable_sort( RandomAccessIterator first,


Compare comp )

Also sorts elements in acontainer, but unlike the standardsort(), this one preserves therelative order of duplicateelements. This means thatstable_sort() is less efficientthan standard sort().


void

partial_sort( RandomAccessIterator first,

RandomAccessIterator middle,


void

partial_sort( RandomAccessIterator first,

RandomAccessIterator middle,


Compare comp )

This algorithm also sortselements in containers, but in thiscase only elements from first->middle are sorted and placed atthe beginning of the container.The elements from middle->lastare unsorted (and probablyrearranged).


partial_sort_copy( InputIterator first,

InputIterator last,

RandomAccessIterator result_first,

RandomAccessIterator result_last )


partial_sort_copy( InputIterator first,

InputIterator last,

RandomAccessIterator result_first,

RandomAccessIterator result_last,

Compare comp )

This algorithm combines partialsorting with copying of theelements. It will stop whenever itprocesses (last-first) or(result_last-result_first) elements,whichever is smaller.

Useful for extracting X number ofitems (perhaps the smallest orlargest values) from a largecontainer into a smaller one.

bool

is_sorted( ForwardIterator first,

ForwardIterator last )

bool

is_sorted( ForwardIterator first,


Compare comp )

Returns true if the range isalready sorted, false otherwise.


void

nth_element( RandomAccessIterator first,

RanomAccessIterator nth,


void

nth_element( RandomAccessIterator first,

RandomAccessIterator nth,


Compare comp )

This is a special kind of partialsort that ensures elements to theleft of nth are less than allelements to the right of nth. Theleft side may or may not besorted. The same applies to theright side. However, all items tothe left will be less than the itemsto the right, with nth used as asplit point.

Searching Algorithms


ForwardIterator

lower_bound( ForwardIterator first,


const T& value )

ForwardIterator

lower_bound( ForwardIterator first,


const T& value,

Compare comp )

This algorithm performs a fastbinary search of a sortedcontainer and returns the iteratorwhere a new element of valuecan be inserted to maintain theproper order of elements.

Uses operator<() by default, butthe second version can be usedto customize the comparison.

NOTE: The first version requiresvalue to be comparable with a T.

ForwardIterator

upper_bound( ForwardIterator first,


const T& value )

ForwardIterator

upper_bound( ForwardIterator first,


const T& value,

Compare comp )

This algorithm also performs afast binary search of a sortedcontainer. The difference is in thereturned iterator. This onereturns a reference to the firstelement greater than value.

By comparison the lower_bound() algorithm returns a reference tothe first element greater than orequal to value.


pair<ForwardIterator, ForwardIterator>

equal_range( ForwardIterator first,


const T& value )

pair<ForwardIterator, ForwardIterator>

equal_range( ForwardIterator first,


const T& value,

Compare comp )

Combines using lower_bound()and upper_bound() into a singlealgorithm that returns bothiterators in a single function call.

NOTE: The first version onlyrequires that value becomparable to elements of typeT.

bool

binary_search( ForwardIterator first,


const T& value )

bool

binary_search( ForwardIterator first,


const T& value,

Compare comp )

Compares each element in first->last against value using eitherthe default comparison operatoror a custom comparison function(or functor) comp and returnstrue if found, false otherwise.

NOTE: Since you will often needto know the position of theelement, most of the time youshould consider usinglower_bound(), upper_bound(),or equal_range() instead.

Merging Algorithms

There are a couple of algorithms you can use for combining and merging sortedcontainers together.


OutputIterator

merge( InputIterator1 first1,





OutputIterator

merge( InputIterator1 first1,





Compare comp )

Combines 2 sorted containers(first1->last1 and first2->last2)into another container (result) sothat the output container is alsosorted. The merge is stable,which means the relative order ofduplicate elements is preserved.

void

inplace_merge( BidirectionalIterator first,

BidirectionalIterator middle,


void

inplace_merge( BidirectionalIterator first,

BidirectionalIterator middle,


Compare comp )

This algorithm takes a containerthat has been partially sorted(split around middle) andcompletes the sort so the entirecontainer is now sorted.

Set Algorithms

There are also a set of algorithms designed specifically for performing setoperations. Most of these algorithms do not require a set<> container, but theymay be used to implement the set<> template class.


bool

includes( InputIterator1 first1,



InputIterator2 last2 )

bool

includes( InputIterator1 first1,




Compare comp )

Tests 2 sorted ranges todetermine if all of the elements infirst2->last2 are also found infirst1->last1. Returns true only ifall of the elements in the secondcontainer can be found in the firstcontainer.

Both input containers must besorted for this algorithm to workproperly.

OutputIterator

set_union( InputIterator1 first1,





OutputIterator

set_union( InputIterator1 first1,





Compare comp )

Copies all the sorted elementsthat are in either first1->last1 orfirst2->last2 into a new container(result), while preserving the sortsequence.


NOTE: If the same valueelements appear in bothcontainers, then this algorithmcopies the elements from thecontainer where the value isrepeated the most often.


OutputIterator

set_intersection( InputIterator1 first1,





OutputIterator

set_intersect( InputIterator1 first1,





Compare comp )

Copies all the sorted elementsthat are found in both first1->last1 and first2->last2 into anew container (result), whilepreserving the sort sequence.


NOTE: If the same valueelements appear in bothcontainers, then this algorithmcopies the elements from thecontainer where the value isrepeated the least often.

OutputIterator

set_difference( InputIterator1 first1,





OutputIterator

set_difference( InputIterator1 first1,





Compare comp )

Copies all the sorted elementsthat are in first1->last1 but arenot in first2->last2 into a newcontainer (result), preserving thesort sequence.



OutputIterator

set_symmetric_difference(






OutputIterator

set_symmetric_difference(






Compare comp )

Copies all the sorted elementsthat are in first1->last1 but not infirst2->last2 as well as all theelement in first2->last2 that arenot in first1->last1 into a newcontainer (result), preserving thesort sequence. After using thisalgorithm the output container willhave the set of elements that arenot found in both inputcontainers.


Heap Operations

A heap is data structure similar to a tree, but normally stores its elements as anarray (including vector and deque). The difference is that in a heap not everyelement has to be perfectly sorted. Instead the elements have to arranged so thehighest value is always above the lower values. This is used by thepriority_queue<> template internally to arrange elements by value.


Void

make_heap( RandomAccessIterator first,

RandomAccessIterator last)

void

make_heap( RandomAccessIterator first,


Compare comp )

Turns the container first->last into aheap. Typically the underlyingcontainer will be a C-style array,vector<> or deque<> object.


void

push_heap( RandomAccessIterator first,


void

push_heap( RandomAccessIterator first,


Compare comp )

This function moves an elementthat has already been added to theend of a container into its properlocation within the heap structure.You must add the element to theunderlying container yourself,perhaps by using the push_back()function.

void

pop_heap( RandomAccessIterator first,


void

pop_heap( RandomAccessIterator first,


Compare comp )

This method removes the largestelement from the heap structure(the largest element is normally thefirst element). It does not actuallyremove the element, but insteadmoves it to the end of theunderlying container andreorganizes the remainingelements so the heap is still valid.

void

sort_heap( RandomAccessIterator first,


void

sort_heap( RandomAccessIterator first,


Compare comp )

Returns the heap's underlyingheap sequence back into a sortedsequence. The relative order ofthe elements is not guaranteed tobe preserved.

bool

is_heap( RandomAccessIterator first,


bool

is_heap( RandomAccessIterator first,


Compare comp )

Tests a container to determine if itis already organized into thesequence needed to be treated asa heap structure.

Miscellaneous Algorithms

Here are several general-purpose algorithms.


const T&

min( const T& a,

const T& b )

const T&

min( const T& a,

const T& b,

Compare comp )

Compares a to b and returns theone with the lesser value (returns aif they are equal). Uses operator<by default.

const T&

max( const T& a,

const T& b )

const T&

max( const T& a,

const T& b,

Compare comp )

Compares a to b and returns theone with the greater value (returnsa if they are equal). Usesoperator< by default.

ForwardIterator

min_element( ForwardIterator first,

ForwardIterator1 last )

ForwardIterator

min_element( ForwardIterator first,


Compare comp )

Finds the smallest element in thecontainer and returns an iteratorthat references that element.

ForwardIterator

max_element( ForwardIterator first,

ForwardIterator1 last )

ForwardIterator

max_element( ForwardIterator first,


Compare comp )

Finds the largest element in thecontainer and returns an iteratorthat references that element.


bool

lexicographical_compare(




InputIterator2 last2 )

bool

lexicographical_compare(





Compare comp )

While this algorithm's name isawkward, the job it performs issimple. It compares elements oneby one from both containers until iteither reaches the end or findselements that do not match. If bothcontainers stored exactly the sameelements in the same sequence, itreturns true, otherwise it returnsfalse.

bool

next_permutation( BidirectionalIterator first,


bool

next_permutation( BidirectionalIterator first,


Compare comp )

This algorithm is used to rearrangethe elements in a sorted containerin every other possible sequence(or permutation). Every time youcall this algorithm, the elements willbe reordered and it will return true.Once all the permutations havebeen generated, the elements arereturned to the original sortedsequence and false is returned.

bool

prev_permutation( BidirectionalIterator first,


bool

prev_permutation( BidirectionalIterator first,


Compare comp )

This algorithm is the mirror imageof next_permutation().


T

accumulate( InputIterator first,

InputIterator last,

T init )

T

accumulate( InputIterator first,

InputIterator last,

T init,

BinaryFunction binary_op )

Adds all the elements from first->last to init and returns the sum.

The second version allows you touse a function (or functor) that willbe called with the previous result(initially the same as init) and thenext element in the container. Thefunction will return a value of type Tthat will be added to the nextresult.

NOTE: Defined in the header<numeric>.

T

inner_product( InputIterator1 first1,



T init )

T

inner_product( InputIterator1 first1,



T init,

BinaryFunction1 binary_op1,

BinaryFunction2 binary_op2 )

This algorithm takes each elementin the first container (first1->last1)and multiplies it by eachcorresponding element in thesecond container (first2) andreturns the sum of all of the results+ the value in init. Think of it as acrude matrix multiply and addoperation.

NOTE: Defined in the header<numeric>.

OutputIterator

partial_sum( InputIterator first,

InputIterator last,


OutputIterator

partial_sum( InputIterator first,

InputIterator last,


BinaryOperator binary_op )

This algorithm visits each elementin a container and adds theelement's value to the nextelement's value and stores theresult in the output container. Thefirst element is always just copiedto the output.

Output[0] = Input[0]

Output[i] = Input[i-1] + Input[i]


OutputIterator

adjacent_difference( InputIterator first,

InputIterator last,


OutputIterator

adjacent_difference( InputIterator first,

InputIterator last,


Copies the first element from firstto result. Next, subtracts allelements from the previouselement and stores the result inresult.

Output[0] = Input[0]

Output[i] = Input[i] – Input[i-1]

Function Objects (aka Functors)

A function object or functor is any object that can be used as if it were a plain oldfunction. A class can used as a functor if it defines operator(), which issometimes referred to as the default operator. So a functor is really either apointer to a static function, or a pointer to an object that defines operator(). Theadvantages of using a function object should become apparent soon.

Many of the algorithms in the Standard Template Library will accept a functor touse instead of the default functor defined by the template class. This allows theuser of the algorithm to adapt the algorithm to their specific needs. You can usethe predefined function objects that are included with the STL, or you can roll yourown as long as your functors have the required function signatures.

There are 3 major types of function objects and several other less commonly usedfunction objects.

Major Functor Types

Functor Type Used By Description

Predicate (Unaryor Binary)

Unary: remove_if, find_if,count_if, replace_if,replace_copy_if, remove_if, andremove_copy_if

Binary: adjacent_find,find_first_of, mismatch, equal,search, search_n, find_end,unique, and unique_copy

A predicate function objectreturns a bool value of trueor false. Generally they willreceive one argument oftype T, but some algorithmswill require a binarypredicate function whichtakes in two arguments oftype T and returns a bool.

ComparisonFunctions

sort, stable_sort, partial_sort,partial_sort_copy, is_sorted,nth_element, lower_bound,upper_bound, equal_range,binary_search, merge,inplace_merge, includes,set_union, set_intersection,set_difference,set_symmetric_difference,make_heap, push_heap,pop_heap, sort_heap, is_heap,min, max, min_element,max_element,lexicographical_compare,next_permutation andprev_permutation

This kind of function objecttakes two arguments of typeT and return true or falseafter the items have beencompared. The operator<is an example of this kind offunction and is generally thedefault used when you donot supply your ownfunction object.

Functor Type Used By Description

NumericFunctions (Unaryor Binary)

Unary: for_each and transform

Binary: transform, accumulate,and inner_product

This kind of function willgenerally accept either oneor two arguments of type Tand returns the results ofsome sort of mathematicaloperation. The accumulatealgorithm uses operator+as its default numericfunction.

Here is an example of an algorithm that uses a function.

#include <iostream>#include <iterator>#include <vector>#include <algorithm>

using namespace std;

bool failingGrade( int score ){

return score < 70;}

int main( int argc, char *argv[] ){

vector<int> scores;

scores.push_back( 69 );scores.push_back( 70 );scores.push_back( 85 );scores.push_back( 80 );

cout << “Scores Before: “ << endl;copy( scores.begin(), scores.end(), ostream_iterator<int>(cout,

“\n”) );

vector<int>::iterator new_end;

new_end = remove_if( scores.begin(), scores.end(), failingGrade );scores.remove( new_end, scores.end() );

cout << “Scores After: “ << endlcopy( scores.begin(), scores.end(), ostream_iterator<int>(cout,

“\n”) );

return 0;}

The only problem with this example is that the failingGrade function is not veryflexible. It uses a hard-coded cutoff of 70.

Here is a better version that uses a function object (object of a class with anoperator() defined).



class Failing{private: int cutoff;public: Failing( int below ) : cutoff(below) {} bool operator()( int score ) { return score < cutoff; }};


vector<int> scores;


cout << "Scores Before: " << endl;copy( scores.begin(), scores.end(), ostream_iterator<int>(cout,

"\n") );

vector<int>::iterator new_end;new_end = remove_if( scores.begin(), scores.end(), Failing(75) );scores.erase( new_end, scores.end() );

cout << "Scores After: " << endl;copy( scores.begin(), scores.end(), ostream_iterator<int>(cout,

"\n") );

return 0;}

This can also be achieved using a class template instead as follows:



template <typename T>

class Failing{private: T cutoff;public: Failing( T below ) : cutoff(below) {} bool operator()( T const& score ) { return score < cutoff; }};


vector<int> scores;


cout << "Scores Before: " << endl;copy( scores.begin(), scores.end(), ostream_iterator<int>(cout,

"\n") );

vector<int>::iterator new_end;new_end = remove_if( scores.begin(), scores.end(), Failing<int>

(81) );scores.erase( new_end, scores.end() );

cout << "Scores After: " << endl;copy( scores.begin(), scores.end(), ostream_iterator<int>(cout,

"\n") );

return 0;}

Predefined Function Objects

Since using function objects with algorithms is so common, a number ofpredefined function objects are available for you to use in your code.

Arithmetic Function Objects

Functor Type Description

plus<T> Binary Adds two elements together to calculate asum.

minus<T> Binary Subtracts two elements to calculate thedifference.

multiplies<T>*

* times<T> in olderversions of STL

Binary Multiples two elements to calculate aproduct.

divides<T> Binary Divides one element by another to calculatea dividend.

modulus<T> Binary Performs a modulo operation against twoelements and calculates the remainder.

negate<T> Unary Negates the element so positive valuesbecome negative and vice-versa.

Comparison Function Objects


equal_to<T> Binary Compares two elements for equality usingoperator==.

not_equal_to<T> Binary Compares two elements for inequality usingoperator==.

less<T> Binary Compares two elements using operator<.

greater<T> Binary Compares two elements using operator>.

less_equal<T> Binary Compares two elements using operator<=.

greater_equal<T> Binary Compares two elements using operator>=.

Logical Function Objects


logical_and<T> Binary Performs an AND operation with two otherconditions.


logical_or<T> Binary Performs an OR operation with two otherconditions.

logical_not<T> Unary Inverts boolean logic.

Function Object Adapters

Alas the function objects listed above are quite useful, but limited in scope. Thereis no apparent way you can use functors like less<T> with any algorithm thatrequires a unary function, or is there?

This is the concept of a Function Object Adapter. They can be used to convertbinary functors into unary functors or to do other conversions such as converting aplain function into a function object or converting a class member function backinto a standard function so it can be used with the algorithms.

Adapter Description Notes

binder1st Adapts a unaryfunction/functor and aconstant into a binaryfunctor, where the constantwill be used as the firstargument to the functor.

Don't use directly. Insteaduse the bind1st() function,which creates a binder1stobject internally.

binder2nd Adapts a unaryfunction/functor and aconstant into a binaryfunctor, where the constantwill be used as the secondargument to the functor.

Don't use directly. Instead,use the bind2nd() function,which creates a binder2ndobject internally.

ptr_fun Converts a pointer to astandard function into afunction object. Neededwhen trying to customizethe container templates(such as set<>) whichrequire a functor class anddo not support functionobjects.

Can be used to convert bothunary and binary functionsinto function objects.

unary_negate Converts a unary predicatefunction object by invertingthe logical return value.

Don't use directly. Use thenot1() function instead.

binary_negate Converts a binary predicatefunction object by invertingthe logical return value.

Don't use directly. Use thenot2() helper functioninstead.

Adapter Description Notes

unary_compose Combines multiple functionobjects into a single objectby calling the first functionand passing the results tothe next function. In otherwords, allows you to chainfunction calls together.

Don't use directly. Use thecompose1() helper functioninstead.

binary_compose Combines multiple functionobjects into a single objectin the same manner asunary_compose, exceptworks on binary functions.

Don't use directly. Use thecompose2() helper functioninstead.

mem_fun Converts a memberfunction of a class (orstruct) into a plain functionso it can be used withalgorithms. It performsopposite from the sameway ptr_fun() does.

Use this helper functionwhen you are storingpointers to objects in acontainer and want to call amember function of the classin an algorithm.

mem_fun_ref Converts a memberfunction of a class (ortemplate) into a functionobject just like themem_fun() functionadapter does.

Use this helper functionwhen you are storing objects(not pointers) in a containerand need to access theobject by reference.

standard template library quick reference...standard template library quick reference containers...

Documents