A. Koenig, "Templates and Generic Algorithms," Journal of Object-Oriented Programming, June 1994, pp

Transcription

1 References BM95 BFM95 GLA96 HOR95 KAS96 KEF95 KOE94a KOE94b KOE94c LAR88 MUS87 J. Barreiro and D. Musser, An STL Hash Table Implementation with Gradual Resizing, Computer Science Dept., Rensselaer Polytechnic Institute, Troy, NY, 1995, included in HP distribution (STE95). J. Barreiro, R. Fraley, and D. Musser, Hash Tables for the Standard Template Library, Doc. No. X3Jl6/ WG21IN0605, included in HP distribution (STE95). G. Glass, "STL in Action: Helper Algorithms," c++ Report, Vol. 8, No.1, Jan. 1996, pp C. Horstmann, Safe STL, URL: /faculty/horstman/safestl.html. L. Kasparek, "Processing Variant Records with STL," C/C++ Users Journal, Vol. 14, No.9, Sept. 1996, pp T. Keffer, "Programming with the Standard Template Library," Dr. Dobb's Sourcebook, Vol. 20, No. 15, July/August 1995, pp A. Koenig, "Templates and Generic Algorithms," Journal of Object-Oriented Programming, June 1994, pp A. Koenig, "Generic Iterators," Journal of Object-Oriented Programming, Sept. 1994, pp A. Koenig, "File Iterators," Journal of Object-Oriented Programming, Nov.-Dec. 1994, pp P. Larson, "Dynamic Hash Tables," Communications of the ACM, Vol. 31, No.4, April 1988, pp D. Musser and A. Stepanov, "A Library of Generic Algorithms in Ada", in Proc. ACM SigAda International Conference, Boston, December, 1987.

2 314 References MUS88 MUS89 MUS89a MUS94 MUS95 MUS95a NEW95 NEL95 PLA96 STE95 STE95a STE95b STR91 STR94 D. Musser and A. Stepanov, "Generic Programming," First International Joint Conference of ISSAC-88 and AAECC-6, Rome, Italy, July 4-8, D. Musser and A. Stepanov, The Ada Generic Library: Linear List Processing Packages, Springer-Verlag, D. Musser and A. Stepanov, "Generic Programming," in Symbolic and Algebraic Computation Proceedings, P. Gianni (ed), Lecture Notes in Computer Science, Springer-Verlag, D. Musser and A. Stepanov, "Algorithm-oriented Generic Libraries," Software - Practice and Experience, Vol. 24, No.7, July 1994, pp D. Musser, STL Home Page, URL: I-musserlstl.html. D. Musser, Rationale for Adding Hash Tables to the C++ Standard Template Library, Computer Science Dept., Rensselaer Polytechnic Institute, Troy, NY, 1995, included in HP distribution (see STE95). STL Newbie Guide, URL: l-khanlsoftware/stvstl.newbie.html. M. Nelson, C++ Programmer's Guide to the Standard Template Library, IDG Books, Forest City, CA, P. 1. Plauger, "Standard C/C++: Introduction to <algorithm>," C/C++ Users Journal, Vol. 14, No.9, Sept. 1996, pp A. Stepanov and M. Lee, The Standard Template Library, Hewlett-Packard Laboratories, Palo Alto, CA, 1995, URL: ftp://butler.hpl.hp.com/stl. A. Stevens, "Alexander Stepanov and STL," Dr. Dobb's Journal, Vol. 20, No.3, March 1995, pp A. Stepanov, "The Standard Template Library," Byte, Vol. 20, No. 10, Oct. 1995, pp B. Stroustrop, The C++ Programming Language, Second Edition, Addison-Wesley, Reading, MA, B. Stroustrop, The Design and Evolution of C++, Addison-Wesley, Reading, MA, 1994.

3 References 315 STR94a VIL94 VIL95 ZIG95 B. Stroustrop, "Making a Vector Fit for a Standard," c++ Report, Vol. 6, No.8, Oct. 1994, pp M. Vilot, "An Introduction to the Standard Template Library," c++ Report, Vol. 6, No.8, Oct. 1994, pp M. Vilot, "The C++ Standard Library," Dr. Dobb's Journal, Vol. 20, No.8, August 1995, pp D. Zigmond, "Generic Programming and the C++ STL," Dr. Dobb 's Journal, Vo120, No.8, August 1995, pp

4 A The STL Reference This appendix is a reference to all of the types, functions, and containers in the Standard Template Library. It is designed to be used in conjunction with the main text as a handy reference for the working programmer. The descriptions in this reference are much briefer than those provided in the main text, which should be consulted when a more detailed discussion is required. The reference is organized in a purely alphabetical fashion without regard for whether an object is a function or container. This will make it easier to find things since there are no sections within the reference.

5 318 AppendixA: STL Reference accumulate TIME: linear HEADER: algo.h template <class Inputlterator, T accumulate(inputlterator Inputlterator T template <class Inputlterator, BinaryOperation> T accumulate(inputlterator Inputlterator T BinaryOperation class T> first, last, init) ; class T, class first, last, init, binary _ op) ; DESCRIPTION: the first fonn sums the values fromjirst up to, but not including, last, adds the value of init, and returns the result. The second fonn allows the user to supply any binary operation that will be used in place of addition. adjacent_difference TIME: linear HEADER: algo.h template <class Inputlterator, class Outputlterator> Outputlterator adjacent_difference( Inputlterator first, Inputlterator last, Outputlterator resul t) ; template <class Inputlterator, class Outputlterator, class BinaryOperation> Outputlterator adjacent_difference( Inputlterator first, Inputlterator last, Outputlterator result, BinaryOperation binary_op);

6 Appendix A: STL Reference 319 DESCRIPTION: calculates the difference between each pair of elements in the sequence from first up to last. The result is of the same length as the input sequence. Since the number of differences is one less than the number of elements in the input sequence a zero is inserted at the front of the result to make the sequences the same length. Thus, the difference between the first two elements in the input sequence is in the second position of the output sequence. The second form of the function allows the specification of an operation other than the default operator-. adjacent_find TIME: linear HEADER: algo.h template <class Inputlterator> Inputlterator adjacent_find(inputlterator Inputlterator first, last); template <class Inputlterator, class Inputlterator adjacent_find( Inputlterator Inputlterator BinaryPredicate BinaryPredicate> first, last, binary _pred) ; DESCRIPTION: these functions find the first pair of duplicate elements in the range first to last. If a duplicate is found then the functions return an iterator referring to the first element in the duplicate. If no duplicate is found, an iterator equal to las t is returned In the first form of the function, operator== is used to compare elements. The second form allows the user to specify an arbitrary binary predicate function to use to compare elements. advance TIME: linear HEADER: algobase.h template <class Inputlterator, class Distance> inline void advance(inputlterator& i, Distance n);

7 320 Appendix A: STL Reference DESCRIPTION: moves the iterator i by n positions by repeated application of operator++ or operator--. The iterator must be an input, forward, bidirectional, or random access iterator. The distance can be negative only if the iterator is bidirectional or random access. This function is usually used with input, forward, and bidirectional operators where it takes linear time. When used with random access iterators, operator+ or operator- are used yielding a constant time operation. Public Members TYPE: adaptor HEADER: iterator.h template <class Container> class back_insert_iterator : public output iterator; DESCRIPTION: unlike other iterators, when assigned a value the insert iterators insert a new value into a container rather than overwriting an existing value. They accomplish this by invoking push_back () on the underlying container. Of course, this means that the underlying container must support the push_backo operation. Insert iterators are useful with the STL algortihms to copy values to a container without having to worry if sufficient space exists. SEE ALSO: back_inserter, front_insert_iterator, insert_iterator back insert iterator<container>& back=insert=iterator<container>::operator=( const Container::value_type& value); inserts the value at the end of the container by invoking push _back (). back insert iterator<container>& back=insert=iterator<container>::operator++(); does nothing but is provided for compatibility with other iterators. back insert iterator<container>& back_insert_iterator<container>::operator++(int); does nothing but is provided for compatibility with other iterators.

8 Appendix A: STL Reference 321 back insert iterator<container>& back=insert=iterator<container>::operator*(}; dereference operator to return a reference to the back insert iterator itself. back_insert_iterator::back_insert_iterator( Container& x}; constructor to create a back insert operator for a container. HEADER: iterator.h template <class Container> back insert iterator<container> back=inserter(container& x}; DESCRIPTION: creates and returns a back_insert iterator for the container passed to it. This is a convenience function that is easier than creating the iteraor yourself. SEE ALSO: back insert iterator - - bidirectional_iterator Operators TYPE: structure HEADER: iterator.h template <class T, class Distance> struct bidirectional_iterator; DESCRIPTION: bidirectional iterators can both assign and retrieve values as well as being able to move in both the forward and reverse directions. T bidirectional_iterator<t, Distance>::operator=( const bidirectional iterator& x}; assigns the value of one iterator to another. bool bidirectional_iterator<t, Distance>::operator==( const bidirectional iterator& x};

9 322 Appendix A: STL Reference returns true if the two iterators are equal, otherwise returns false. boo 1 bidirectional_iterator<t, Distance>::operator!=( const bidirectional iterator& x); returns true if the two iterators are unequal, otherwise returns false. bidirectional iterator& bidirectional_iterator<t, Distance>::operator++(); increments the iterator and returns a reference to the new value. bidirectional_iterator<t, Distance>::operator++(int); returns the current value ofthe iterator and then increments the iterator. bidirectional iterator& bidirectional iterator<t, Distance>::operator--(); decrements the iterator and returns a reference to the new value. bidirectional_iterator<t, Distance>::operator--(int); returns the current value of the iterator and then decrements the iterator. T bidirectional_iterator<t, Distance>::operator*(); dereferences the iterator and allows a value to be assigned to it. TIME: logarithmic HEADER: algo.h template <class Forwardlterator, class T> bool binary_search(forwardlterator first, Forwardlterator last, const T& value); template <class Forwardlterator, class T,

10 Appendix A: STL Reference 323 class Compare> bool binary_search(forwardlterator Forwardlterator canst T& Compare first, last, value, camp); DESCRIPTION: this performs a binary search of the range from first to last for value. It returns a boolean TRUE ifvalue is found, otherwise FALSE. bind1st TYPE: adaptor HEADER: function.h template <class Operation, class T> binderlst<operation> bindlst( canst Operation& op, canst T& x); DESCRIPTION: this creates a new function object that is identical to op, but has x bound as the first parameter of the function object op. bind2nd TYPE: adaptor HEADER: function.h template <class Operation, class T> binder2nd<operation> bind2nd( canst Operation& op, canst T& x); DESCRIPTION: this creates and returns a function object that accepts two parameters. When invoked, this function object will apply op to the first parameter,using x as the second parameter, and return the result. compose1 TYPE: adaptor HEADER: function.h template <class Operationl, class Operation2> unary compose<operationl, Operation2> coaposel(const Operationl& opl, canst Operation2& op2);

11 324 Appendix A: STL Reference DESCRIPTION: returns a new function object which is the combination of the two function objects passed as parameters. The effect is to first apply op2 and then apply opl to the result of the first function object. SEE ALSO: compose2 compose2 TYPE: adaptor HEADER: function.h template <class Operationl, class Operation2, class Operation3> binary compose<operationl, Operation2, Operation3> compose2(const Operationl& opl, const Operation2& op2, const Operation3& op3); DESCRIPTION: this combines the three separate function objects into a single function object. The resultant function applies the parameter functions in the order opl (op2 (x), op2 (x) ). SEE ALSO: compose! const_iterator TYPE: typedef REQUIRED BY: all containers DESCRIPTION: a typedefprovided by all containers defining a constant iterator for the container. SEE ALSO: iterator const_reference TYPE: typedef REQUIRED BY: all containers DESCRIPTION: a typedefprovided by all containers which is a constant reference to the object type stored in the container. SEE ALSO: reference

12 Appendix A: STL Reference 325 copy TIME: linear HEADER: algobase.h template <class Inputlterator, class Outputlterator> Outputlterator copy(inputlterator first, Inputlterator last, Outputlterator result); DESCRIPTION: this copies all of elements from first up to, but not including, last to the location referred to by result. It returns an iterator which referrs to the location one past the end of the destination. The source and destination ranges may overlap only if resul t <= first. copy_backward TIME: linear HEADER: algobase.h template <class Bidirectionallteratorl, class Bidirectionallterator2> Bidirectionallterator2 copy_backward (Bidirectionallteratorl Bidirectionallteratorl Bidirectionallterator2 first, last, result); DESCRIPTION: this copies the sequence from first up to, but not including, last to a location whose upper end is indicated by resul t. It returns an iterator that references the last element copied, which will be the start of the sequence in the destination. The source and destination ranges may overlap only if resul t >= last. count TIME: linear HEADER: algo.h template <class Inputlterator, class T, class Size> void coun~(inputlterator first, Inputlterator last, const T& value, Size& n);

13 326 Appendix A: STL Reference DESCRIPTION: searches the range from first up to last and produces a count of all elements equal to value. The count is returned in the parameter n. No order of the elements is assumed and the entire range is searched. TIME: linear HEADER: algo.h template <class Inputlterator, class Predicate, class Size> void count_if(inputlterator first, Inputlterator last, Predicate pred, Size& n) ; DESCRIPTION: counts all the elements in the range first up to last that satisty the predicate pred. The number of elements satistying the predicate is returned in n. No order of the elements is assumed and the entire range is searched. deque Public Methods: TYPE: class template <class T> class deque; HEADER: deque.h DESCRIPTION: a deque is a container that can store a sequence of objects. It provides constant time insertion and deletion at the beginning and end of the sequence. Linear time insertion and deletion are provided for elements in the interiour of the sequence. Deques support random access iterators so that you can access the contents in a non-sequential fashion. Deques are optimized for insertion and deletion at either end of the sequence and should be used in applications requiring this behaviour. SEE ALSO: list, vector reference deque<t>::back(); const reference deque<t>::back();

14 Appendix A: STL Reference 327 returns the last element in the deque (not a reference to it). iterator deque<t>::begin(); const_iterator deque<t>::begin(); returns an iterator that references the first element in the deque. deque<t>::deque(); deque<t>::deque(size_type n, const T& value = T()); deque<t>::deqae(const T* first, const T* last); deque<t>: :deque(const deque<t>& x); the first form constructs an empty deque. The second form constructs a deque containing n copies of value. The third form constructs a deque containing the elements from first up to last. The fourth form is the copy constructor. deque<t>::-deque(); destroys the deque and its contents. bool deque<t>::emp y(); returns a Boolean value indicating if the deque is empty. iterator deque<t>::end(); const_iterator deque<t>::end(); returns an iterator that is one past the last element in the deque. void deque<t>::erase(iterator position); void deque<t>::erase(iterator first, iterator last); deletes the element at the indicated position from the deque. The second form deletes all elements in the range from first up to last. reference deque<t>::fron (); const_reference deque<t>::fron (); returns the first element in the deque (not a reference to it).

15 328 Appendix A: STL Reference iterator deque<t>::idser~(iterator x) ; void void void deque<t>::inser~(iterator const iterator const-iterator deque<t>::inser~(iterator const T* const T* deque<t>::idser~(iterator size_type const T& position, const T& position, n, x) ; position, first, last); position, first, last); inserts the element x just before position. The first fonn returns an iterator that references the element just inserted. The second and third fonns insert the elements from first up to last just before posi tion. The fourth fonn inserts n copies ofthe element x just before posi tion. size_type deque<t>::bax_size(); returns the maximum number of elements which can be stored in the deque. void deque<t>::pop_hack(); deletes the last element in the deque. void deque<t>::pop_eron~(); deletes the first element in the deque. void deque<t>::push_back(const T& x); appends the element x to the end of the deque. void deque<t>::push_eron~(const T& x); inserts the element x at the beginning of the deque. reverse_iterator deque<t>::rbegin(); const_reverse_iterator deque<t>::rbegin(); returns an iterator that is one past the end of the deque and can be used as the starting value for a reverse iterator.

16 Appendix A: STL Reference 329 Non-member Functions: reverse iterator deque<t>::rend(); const_reverse_iterator deque<t>::rend(); returns an iterator that can be used to find the end for a reverse iteration. size_type deque<t>::size(); returns the number of elements currently stored in the deque. void deque<t>::swap(deque<t>& x); swaps the contents of the object deque with the deque x so that each has the contents of the other. template <class T> bool operator==(const deque<t>& x, const deque<t>& y); returns a Boolean indicating if the two lists are equal or not. template <class T> bool operator«const deque<t>& x, const deque<t>& y); performs a lexicographical comparison to determine if the first deque is less than the second. difference_type TYPE: typedef REQUIRED BY: all containers DESCRIPTION: a typedef provided by all containers defining the type for the difference of two iterators. distance TIME: linear HEADER: algobase.h template <class Inputlterator, class Distance>

17 330 Appendix A: STL Reference inline void distance(inputlterator Inputlterator Distance& first, last, n) ; DESCRIPTION: detennines the distance between the iterators first and last and returns this as n. n is the number of times the iterator first must be incremented to become equal to last. The function uses operator+ and operator- for random access iterators yielding a constant time implementation. Input, forward, and bidirectional iterators use operator++ and operator--, yielding a linear time implementation. TIME: constant HEADER: iterator.h template <class T, class Distance> inline Distance* distance_type( const input_iterator<t, Distance>&); template <class T, class Distance> inline Distance* distance_type ( const forward_iterator<t, Distance>&); template <class T, class Distance> inline Distance* distance_type( const bidirectional_iterator<t, Distance>&); template <class T, class Distance> inline Distance* distance_type( const random_access_iterator<t, Distance>&); template <class T> inline ptrdiff_t* distance_type(const T*); DESCRIPTION: when an iterator is passed to this function, it returns a pointer to the type that the iterator uses to represent the difference between pointers. The value of this pointer is always zero and is not intended to be used-only the type is important. This function is used to specialize algorithms to take advantage of the capabilities of specific iterator categories. SEE ALSO: iterator_category, value_type

18 Appendix A: STL Reference 331 divides object TIME: constant HEADER: function.h template <class T> struct divides: binary_function<t, T, T> { T operator() (const T& x, const T& y); } ; DESCRIPTION: a function object which can be passed to another function as a substitute for operator/. It applies operator/ to its two parameters and returns the result. SEE ALSO: minus, times, plus, modulus equal TIME: linear HEADER: algobase.h template <class Inputlteratorl, class Inputlterator2> inline bool equal(inputlteratorl firstl, Inputlteratorl lastl, Inputlterator2 first2); template <class Inputlteratorl, class BinaryPredicate> inline bool equal(inputlteratorl Inputlteratorl Inputlterator2 BinaryPredicate class Inputlterator2, firstl, lastl, first2, binary_pred) ; DESCRIPTION: compares two ranges and returns a boolean indicating if they are equal on an element-by-element basis or not. The first range begins with fir s t 1 and continues up to las t 1. The second range begins at fir s t 2 and has the same length as the first range. The first form performs the comparison using operator==, while the second allows the specification of an alternate comparison operator.

19 332 Appendix A: STL Reference HEADER: algo.h TIME: logarithmic template <class Forwardlterator, class T> inline pair<forwardlterator,forwardlterator> equal_range (Forwardlterator first, Forwardlterator last, const T& value); template <class Forwardlterator, class T, class Compare> inline pair<forwardlterator,forwardlterator> equal_range (Forwardlterator first, Forwardlterator last, const T& value, Compare comp); DESCRIPTION: searches the range from first to last looking for a range of elements all of which are equal to value. It returns a pair of iterators that indicate the start and end of the range meeting the requirements. If no such range exists, the pair contains two iterators equal to first. The sequence being searched is assumed to be sorted into ascending order. The second form allows you to specify a comparison operator other than the default, operator<. fill constant HEADER: algobase.h TIME: linear template <class Forwardlterator, class T> void Fill (Forwardlterator first, Forwardlterator last, const T& value); SPACE: DESCRIPTION: assigns all elements in the range from first up to last the value. TIME: linear HEADER: algobase.h

20 Appendix A: STL Reference 333 template <class Outputlterator, class Size, class T> void fill_n(outputlterator first, Size n, const T& value); DESCRIPTION: assigns value to the next n elements beginning with first. find TIME: linear HEADER: algo.h template <class Inputlterator, class T> Inputlterator find(inputlterator first, Inputlterator last, const T& value); DESCRIPTION: searches the range from first up to last for value. If found, it returns an iterator referring to the first occurrence of value. Ifnot found, it returns an iterator equal to last. No assumptions about the order of the sequence are made. TIME: linear HEADER: algo.h template <class Inputlterator, class Predicate> Inputlterator find_if(inputlterator first, Inputlterator last, Predicate pred); DESCRIPTION: searches the range from first up to last for an element that satisfies the predicate. If found, it returns an iterator referring to the first element satisfying the predicate. If not found, it returns an iterator equal to last. No assumptions about the order of the sequence are made. TIME: linear HEADER: algo.h

21 334 Appendix A: STL Reference template <class Inputlterator, class Function> Function for_each(inputlterator first, Inputlterator last, Function f); DESCRIPTION: this traverses the sequence from first up to last, applying the function f to each member of the sequence. It returns the function f which was passed to it. forward_iterator Operators TYPE: structure HEADER: iterator.h template <class T, class Distance> struct forward_iterator; DESCRIPTION: forward iterators can both assign and retrieve values but are restricted in that they can only move in the forward direction. T forward_iterator<t, Distance>::operator=( const forward_iterator& x); assigns the value of one iterator to another. bool forward_iterator<t, Distance>::operator==( const forward_iterator& x); returns true if the two iterators are equal, otherwise returns false. boo 1 forward_iterator<t, Distance>::operator!=( const forward_iterator& x); returns true if the two iterators are unequal, otherwise returns false. forward iterator& forward_iterator<t, Distance>::operator++(); increments the iterator and returns a reference to the new value. forward_iterator<t, Distance>::operator++(int);

22 Appendix A: STL Reference 335 returns the current value of the iterator and then increments the iterator. T forward_iterator<t, Distance>::operator*(); dereferences the iterator and allows a value to be assigned to it. front_insert iterator Public Members TYPE: adaptor HEADER: iterator.h template <class Container> class t"ront_insert_iterator : public output_iterator; DESCRIPTION: the insert operators differ from other iterators in that when assigned a value, they insert a new object into the container rather than overwriting an existing object. This adaptor uses the push_front () method of the underlying class to insert values at the front of a container. It is therefore restricted to use with classes which provide the push_front () method. The insert iterators are particularly useful as output iterators when used in conjunction with the STL algorithms so that results can be written to a container that does not have sufficient space currently allocated. SEE ALSO: back_insert_iterator, insert_iterator, front_inserter front insert_iterator::t"ront_insert_iterator(container & x); constructor to create a front insert iterator for the given container. front insert iterator<container>& front=insert=iterator<container>::operator=( const Container::value_type& value); assignment operator that uses push_front () to insert a new value into the container. front insert iterator<container>& front=insert=iterator<container>::operator++(); does nothing but is provided for compatibility with other iterators.

23 336 Appendix A: STL Reference front insert iterator<container>& front=insert=iterator<container>::operator++(int); does nothing but is provided for compatibility with other iterators. front insert iterator<container>& front=insert=iterator<container>::operator*(); dereference operator to return a reference to the iterator itself. front_i nserter HEADER: iterator.h template <class Container> front insert iterator<container> Cront=inserter(Container& x); DESCRIPTION: convenience function which creates and returns a front_insert_iterator for the given container. SEE ALSO: fronunseruterator generate TIME: linear HEADER: algo.h template <class Forwardlterator, class Generator> void generate (Forwardlterator first, Forwardlterator last, Generator gen); DESCRIPTION: fills the object referenced by the iterators with the successive values returned by gen. The range to be filled goes from first to last inclusive. generate_n TIME: linear HEADER: algo.h template <class Outputlterator, class Size,

24 Appendix A: STL Reference 337 class Generator> void generate_n(outputlterator Size Generator first, n, gen) ; DESCRIPTION: fills n locations of the output iterator with the values obtained by n successive calls to gen. greater object TIME: constant HEADER: function.h template <class T> struct greater: binary_function<t, T, bool> { boo 1 operator () (const T& x, const T& y); } ; DESCRIPTION: a function object which can be used as a substitite for operator>. and passed as a parameter to functions expecting a function object. It compares its two parameters using operator> and returns the result. greater_equal object TIME: constant HEADER: function.h template <class T> struct greater_equal: binary_function<t, T, bool> bool operator () (const T& x, const T& y); } ; DESCRIPTION: a function object which can be used as a substitite for operator>=. and passed as a parameter to functions expecting a function object. It compares its two parameters using operator>= and returns the result. SEE ALSO: equal_to, not_equal_to, less, less_equal, greater

25 338 Appendix A: STL Reference includes TIME: linear HEADER: algo.h template <class Inputlteratorl, class Inputlterator2> bool includes(inputlteratorl firstl, Inputlteratorl lastl, Inputlterator2 first2, Inputlterator2 last2); template <class Inputlteratorl, class Inputlterator2, class Compare> bool includes(inputlteratorl firstl, Inputlteratorl lastl, Inputlterator2 first2, Inputlterator2 last2, Compare comp) ; DESCRIPTION: returns true if the multi set represented by the sequence fir s t 1 up to 1 a s t 1 is a subset of the multiset represented by the sequence from first2 up to last2. Each of the sequences must be in ascending order and may contain duplicate values. The first sequence is a subset of the second if the number of occurences of each element in the first set is less than or equal to the number of occurences in the second sequence. The second form of the function allows the specification of a comparison operator other than the default, operator<. SEE ALSO: set_intersection, set_difference, set_symmetric_difference, set union TIME: linear HEADER: algo.h template <class Inputlteratorl, class Inputlterator2,

26 Appendix A: STL Reference 339 class T> T inner_produc~(inputlteratorl Inputlteratorl Inputlterator2 T firstl, lastl, first2, init); template <class Inputlteratorl, class class T, class BinaryOperationl, class BinaryOperation2> T inner_produc~(inputlteratorl Inputlteratorl Inputlterator2 T BinaryOperationl BinaryOperation2 firstl, lastl, first2, init, binary opl, binary::::op2); Inputlterator2, DESCRIPTION: computes the inner product of two ranges. The first range goes from fir s t 1 up to las t 1 while the second range starts with fir s t 2 and is of the same length as the first range. The first form computes the inner product by multiplying the ranges on an element-by-element basis, summing the results, and adding the value ini t. The second form allows the substitution of other operations where opl replaces operator+ and op2 replaces operator*. inplace_merge TIME: linear HEADER: algo.h template <class Bidirectionallterator> inline void inplace_merge( Bidirectionallterator first, Bidirectionallterator middle, Bidirectionallterator last); template <class Bidirectionallterator, class Compare> inline void inplace_aerge( Bidirectionallterator first, Bidirectionallterator middle, Bidirectionallterator last, Compare comp); DESCRIPTION: merges the sequence from first up to middle with the sequence from middle up to last. The result is placed at first. It is assumed that the input sequences are sorted. The second form allows the specification of a comparison operator other than the default, ope rat 0 r<.

27 340 Appendix A: STL Reference input_iterator Operators TYPE: structure HEADER: iterator.h template <class T, class Distance> struct input_iterator; DESCRIPTION: input iterators are used only to obtain values from an input source. One of their main uses is to implement stream iterators for the reading of values from streams. They only move in the forward direction and can only be dereferenced to obtain the value associated with the iterator, never to set it. bool input_iterator<t, Distance>::operator==( const input iterator& xl; returns true if the two iterators are equal, otherwise returns false. bool input_iterator<t, Distance>::operator!=( const input iterator& xl; returns true if the two iterators are not equal, otherwise returns false. input iterator& input iterator<t, Distance>::operator++(l; increments the iterator and returns a reference to the new value. input_iterator<t, Distance>::operator++(intl; returns the current value of the iterator and then increments the iterator. T input_iterator<t, Distance>::operator*(l; dereferences the iterator and returns the value associated with it. inserter HEADER: iterator.h template <class Container, class Iterator> insert_iterator<container> inserter (

28 Appendix A: STL Reference 341 Container& x, Iterator i); DESCRIPTION: convenience function to create an insert i tera tor and position it at the location of i. SEE ALSO: inseruterator insert_iterator Public Members TYPE: adaptor HEADER: iterator.h template <class Container> class insert_iterator : public output_iterator; DESCRIPTION: the insert iterators differ from other iterators in that when a value is assigned to them, they insert a new value into the container rather than overwriting an existing value. An insert iterator is positioned within a container and all values assigned to it are inserted in front of this position.. This is particularly useful when used as an output iterator for one of the STL algorithms to write output to a container that does not have a sufficient number of values already allocated. SEE ALSO: inserter, front_insert_iterator, back_insert_iterator insert iterator::insert_iterator( - Container& x, Container::iterator i); constructor that initializes an insert iterator at the given position in the container. insert iterator<container>& insert=iterator<container>::operator=( const Container::value_type& value); assignment operator that uses insert () on the underlying container to insert an object into the container. The iterator is then advanced so that the next value inserted will be after the one just inserted. insert iterator<container>& insert=iterator<container>::operator++(); does nothing but is provided for compatibility with the other iterators.

29 342 Appendix A: STL Reference insert iterator<container>& insert_iterator<container>::opera~or++(int); does nothing but is provided for compatibility with the other iterators. insert iterator<container>& insert=iterator<container>::opera~or*(); dereference operator to return a reference to the iterator itself. lotagen TYPE: class TIME: constant HEADER: iota.h template <class T> class IouGen { public: IotaGen(const T& init); T operator() (); } ; DESCRIPTION: IotaGen is a generator that is given an initial value and returns successive values, starting with the initial value, each time operator () is invoked. The successive values are obtained by applying operator++ to type T. (NOTE: this is distributed by RPI as a convenience function to be used with their examples and is not part of the STL) iterator TYPE: typedef REQUIRED BY: all containers DESCRIPTION: a typedefprovided by all containers that defines the type of an iterator for the container. SEE ALSO: consuterator iterator _category TIME: constant HEADER: iterator.h

30 Appendix A: STL Reference 343 template <class T, class Distance> inline input_iterator_tag iterator_category( const input_iterator<t, Distance>&); inline output_iterator_tag iterator_category(const output_iterator&); template <class T, class Distance> inline torward_iterator_tag iterator_category( const torward_iterator<t, Distance>&); template <class T, class Distance> inline bidirectional_iterator_tag iterator_category( const bidirectional iterator<t, Distance>&); template <class T, class Distance> inline random access iterator tag iterator_category( const randorn_access_iterator<t, Distance>&); template <class T> inline random access iterator_tag iterator_category(const T*); DESCRIPTION: each of the iterator categories has an iterator tag associated with it which can be used to identify the category to which an iterator belongs. An instance of an iterator is passed to this function which returns the iterator tag for the iterator. The main use of this function is to allow algorithms to be specialized to take advantage of the capabilities of specific iterator categories. iterator _tag TYPE: structure HEADER: iterator.h struct input_iterator_tag {}; struct output_iterator_tag {}; struct Porward_iterator_tag {}; struct bidirectional_iterator_tag {}; struct random_access_iterator_tag {};

31 344 Appendix A: STL Reference DESCRIPTION: the iterator tags are a series of empty structures used to identify the category to which an iterator belongs. When the function iterator_category () is passed an iterator, it returns the iterator tag associated with it, identifying the category to which it belongs. No values are contained within the iterator tags since their type alone is suficient to identify the iterator category. SEE ALSO: iterator_category TYPE: class TIME: constant HEADER: algobase.h template <class Forwardlteratorl, class Forwardlterator2> void iter_swap(forwardlteratorl a, Forwardlterator2 b); DESCRIPTION: swaps the contents of the two iterators a and b. SEE ALSO: swap, swap_ranges TYPE: typedef REQUIRED BY: associative containers DESCRIPTION: this is a typedefprovided by all associative containers that returns the function object used by the container to compare keys. SEE ALSO: key_type, value_compare TYPE: typedef REQUIRED BY: associative containers DESCRIPTION: a type defined by all associative containers that is the type of the key used by the container. SEE ALSO: key_compare, value_type

32 Appendix A: STL Reference 345 less object TIME: constant HEADER: function.h template <class T> struct less : binary function<t, T, bool> { bool operator () (const T& x, const T& y); } ; DESCRIPTION: a function object which can be used as a substitite for operator<. and passed as a parameter to functions expecting a function object. It compares its two parameters using operator< and returns the result. object TIME: constant HEADER: function.h template <class T> struct less_equal : binary_function<t, T, bool> bool operator () (const T& x, const T& y); } ; DESCRIPTION: a function object which can be used as a substitite for operator<=. and passed as a parameter to functions expecting a function object. It compares its two parameters using operator<= and returns the result. SEE ALSO: equal_to, not_equal_to, greater, less, greater_equal lexicographical_compare TIME: linear HEADER: algobase.h template <class Inputlteratorl, class Inputlterator2> bool lexicographical_compare (

33 346 Appendix A: STL Reference InputIteratorl InputIteratorl InputIterator2 InputIterator2 firstl, lastl, first2, last2); template <class InputIteratorl, class InputIterator2, class Compare> bool lexicographical_compare ( InputIteratorl InputIteratorl InputIterator2 InputIterator2 Compare firstl, lastl, first2, last2, comp) ; DESCRIPTION: perfonns a lexicographical comparison (similar to alphabetical order) on the sequence from firstl up to lastl and from first2 up to last2. It returns true if the first sequence is less than the second. The second fonn allows the specification of a comparison operator other than operator<. list Public Methods: TYPE: class HEADER: list.h template <class T> class list; DESCRIPTION: a doubly linked list of elements of arbitrary type T. The list is a sequence container that provides constant time insertion and deletion at any point in the list. Only linear access to the elements is supported via bidirectional iterators. Lists should be used when large numbers of insertions and deletions will be made at any point in the sequence. SEE ALSO: deque, vector reference list<t>::back(); const reference list<t>::back(); returns the last element in the list (not a reference to it). iterator list<t>::begin(); const iterator list<t>::begin();

34 Appendix A: STL Reference 347 returns an iterator that references the first element in the list. boollist<t>::empty(); returns a Boolean value indicating if the list is empty. iterator list<t>::end(); const iterator list<t>::end(); returns an iterator that is one past the last element in the list. void list<t>::erase(iterator position); void list<t>::erase(iterator first, iterator last); deletes the element at the indicated position from the list. The second form deletes all elements in the range from first up to last. reference list<t>::front(); const_reference list<t>::front(); returns the first element in the list (not a reference to it). iterator list<t>::insert(iterator position, const T& x); void list<t>::insert(iterator const T* const T* void list<t>::insert(iterator const iterator const iterator void list<t>::insert(lterator size_type const T& position, first, last); position, first, last) ; position, n, x) ; inserts the element x just before position. The first form returns an iterator that references the element just inserted. The second and third forms insert the elements from first up to last just before posi tion. The fourth form inserts n copies ofthe element x just before posi tion. list<t>: :list(); list<t>::list(size type n, const T& value = T(»; list<t>::list(const T* first, const T* last); list<t>::list(const list<t>& x);

35 348 Appendix A: STL Reference the first fonn constructs an empty list. The second fonn constructs a list containing n copies of value. The third fonn constructs a list containing the elements from first up to last. The fourth fonn is the copy constructor. list<t>::-list(); destroys the list and its contents. size_type list<t>::max_size(); returns the maximum nulilber of elements which can be stored in the list. void list<t>::merge(list<t>& x); merges the sorted list x into the current list, which is assumed to be sorted. After the merge, the list x has no elements and its length is reduced to zero. The merge operation does not remove duplicates. void list<t>::pop_back(); deletes the last element in the list. void list<t>::pop_cront(); deletes the first element in the list. void list<t>::push_back(const T& x); appends the element x to the end of the list. void list<t>::push_cront(const T& x); inserts the element x at the beginning of the list. reverse_iterator list<t>::rbegin(); const_reverse_iterator list<t>::rbegin(); returns an iterator that is one past the end of the list and can be used as the starting value for a reverse iterator. void list<t>::remove(const T& value); removes all elements equal to value from the list.

36 Appendix A: STL Reference 349 reverse iterator list<t>::rend(); const reverse_iterator list<t>::rend(); returns an iterator that can be used to find the end for a reverse iteration. void list<t>::reverse(); reverses the order of the elements in the list. size_type list<t>::size(); returns the number of elements currently stored in the list. void list<t>::sort(); sorts the elements of the list into ascending order. This is an order n log n sort. void list<t>::splice(iterator void list<t>::splice(iterator iterator i); void list<t>::splice(iterator list<t>& iterator iterator position, list<t>& x); position, list<t>& x, position, x, first, last) ; inserts the entire list x into the list so that it is placed immediately before po s i - tion. The second form inserts the element from the list x referenced by i just before posi tion. It also removes the element referenced by i from the list x. The third form places the elements from first up to last from the list x just before po sit ion and removes them from the list x. void list<t>::swap(list<t>& x); swaps the contents of the object list with the list x so that each has the contents ofthe other. void list<t>::unique(); if the list is sorted, then it will remove adjacent duplicates so that only a single copy of each element remains.

37 350 Appendix A: STL Reference Non-member Functions: template <class T> bool operator==(const list<t>& x, const list<t>& y); returns a boolean indicating ifthe two lists are equal or not. template <class T> boo 1 operator«const list<t>& x, const list<t>& y); perfonns a lexicographical comparison to detennine if the first list is less than the second. object TIME: constant HEADER: function.h template <class T> struct logical_and : binary_function<t, T, bool> { bool operator () (const T& x, const T& y) const; } ; DESCRIPTION: a function object which can be passed to any function expecting a function object as a substitute for operator&&. It perfonns operator&& on its two parameters and returns the result. SEE ALSO: logical_or, logical_not object TIME: constant HEADER: function.h template <class T> struct logical_or: binary_function<t, T, bool> { boo 1 operator () (const T& x, const T& y) const; } ; DESCRIPTION: a function object which can be passed to any function expecting a function object as a substitute for operator 1 I. It perfonns operator lion its two parameters and returns the result. SEE ALSO: logicacand, logical_not

38 Appendix A: STL Reference 351 object TIME: constant HEADER: function.h template <class T> struct logical_not: binary_function<t, T, bool> ( bool operator () (const T& x) const; } ; DESCRIPTION: a function object which can be passed to any function expecting a function object as a substitute for operator!. It performs operator! on its parameter and returns the result. SEE ALSO: logical_and, logical_or TIME: logarithmic HEADER: algo.h template <class Forwardlterator, class T> inline Forwardlterator lower_bound ( Forwardlterator first, Forwardlterator last, const T& value) ; template <class Forwardlterator, class T, class Compare> inline Forwardlterator lower_bound ( Forwardlterator Forwardlterator const T& Compare first, last, value, comp) ; DESCRIPTION: returns an iterator that references the first element in the range from first up to, but not including, last that is >= value. Ifno such element exists, it returns an iterator that references the element after last. The elements in the range fir s t to 1 a stare assumed to be sorted in ascending order. The second form allows the specification of a comparison function other than the default, opera tor<.

39 352 Appendix A: STL Reference TIME: linear TYPE: heap.h template <class RandomAccesslterator> inline void make_heap(randomaccesslterator RandomAccesslterator first, last) ; template <class RandomAccesslterator, class inline void make~heap(randomaccesslterator RandomAccesslterator Compare Compare> first, last, comp) ; DESCRIPTION: rearranges the elements in the sequence from first up to last so that they form a heap. A heap is a data structure that looks like a binary tree and is sorted so that the parent of every node is greater than the node itself. This function must be used to create a heap from a sequence before any of the other heap functions can be used. TIME: constant HEADER: pair.h template<class Tl, class T2> pair<tl, T2> make_pair(const Tl& x, const T2& y); DESCRIPTION: converts the two values x and y into a pair. A pair is simply a structure containing the two values. SEE ALSO: pair map TYPE: class HEADER: map.h template <class Key, class T, class Compare> class map;

40 Appendix A: STL Reference 353 Public Methods DESCRIPTION: the map stores and retrieves objects based upon a key provided when the object is inserted. The key can be of any type and it does not have to be conatined within the object. The keys for the map must be unique, but the multimap supports duplicate keys. The map allows you to insert objects and provides fast retrieval using a comparison function to determine the equality of objects. The objects are actually stored in a tree so that insertion and retrieval take logarithmic time. The map is useful for applications that want to implement the concept of associative arrays. Internally, the objects in the map are always ordered so that an iterator will retrieve the objects in sorted order. SEE ALSO: multiset, set, multimap iterator map<key, T, Compare>::begin(); const_iterator map<key, T, Compare>::begin() const; returns an iterator referencing the first value in the map. size_type map<key, T, Compare>::count( const key_type& x) const; returns a count of the number of object equal to x. For a map this will be 0 or 1. bool map<key, T, Compare>::empty() const; returns a Boolean indicating if the map is empty or not. iterator map<key, T, Compare>::end(); const_iterator map<key, T, Compare>::end() const; returns a past-the-end iterator for the map. void map<key, T, Compare>::erase(iterator position); deletes the object referenced by the iterator posi tion. size_type map<key, T, Compare>::erase( const key_type& x); deletes all occurrences of the object x and returns the number of objects deleted.

41 354 Appendix A: STL Reference void map<key, T, Compare>::erase( iterator first, iterator last); deletes all the objects in the range from first up to last. pair iterator iterator map<key, T, Compare>::equal_range(const key_type& x) const; pair citerator citerator map<key, T, Compare>::equal_range(const key_type& x) const; returns a pair of iterators delimiting a range of values equal to x. iterator map<key, T, Compare>::Cind( const key type& x); const_iterator map<key, T, Compare>: :Cind( const key_type& x) const; finds the first object equal to x and returns an iterator referencing it. If not found it returns a past-the-end iterator. pair_iterator_bool map<key, T, Compare>::insert( const value_type& x); inserts a new value into the map. It returns a pai r whose second member is a bool indicating if the insertion was successful. An insertion can fail if the object being inserted is already in the map. The first member is an iterator referencing the newly inserted object or the existing object if the object being inserted is a duplicate. void map<key, T, Compare>::insert( const value type* const value=type* first, last); inserts the series of values from first up to last. key_compare map<key, T, Compare>::key_comp() const; returns the comparison function for the map.

42 Appendix A: STL Reference 355 iterator map<key, T, Compare>::lower_bound( const key_type& x) const; returns an iterator referencing the lower bound on a range of values equal to x. map<key, T, Compare>::map( const Compare& comp = Compare()); map<key, T, Compare>::map( const value_type* first, const value_type* last, const Compare& comp Compare()); map<key, T, Compare>::map( const map<key, T, Compare>& x); these are the map constructors. Two of these allow the specification of an alternate comparison function other than the one specified in the template parameters. The first form constructs an empty map while the second constructs a map and inserts the values from the range of the interators first up to last. The third form is the copy constructor. size type map<key, T, Compare>::max_size() const; returns the maximum size of the container. map<key, T, Compare>& map<key, T, Compare>::operator=( const map<key, T, Compare>& x); assignment operator to assign the value of one map to another. Allocator<T>::reference map<key, T, Compare>::operator[] ( const key_type& k); returns a reference to the object in the container which matches the given key. reverse_iterator map<key, T, Compare>::rbegin(); const reverse iterator map<key, T, Compare>::rbegin() const; returns a reverse iterator referencing the last object in the map.