Book: Standard Template Library Programmer`s Guide
Introduction to the Standard Template Library
The Standard Template Library, or STL, is a C++ library of container classes, algorithms, and iterators; it provides many of the basic algorithms and data structures of computer science. The STL is a generic library, meaning that its components are heavily parameterized: almost every component in the STL is a template. You should make sure that you understand how templates work in C++ before you use the STL.
Like many class libraries, the STL includes container classes: classes whose purpose is to contain other objects. The STL includes the classes vector, list, deque, set, multiset, map, multimap, hash_set, hash_multiset, hash_map, and hash_multimap. Each of these classes is a template, and can be instantiated to contain any type of object. You can, for example, use a vector<int> in much the same way as you would use an ordinary C array, except that vector eliminates the chore of managing dynamic memory allocation by hand.
vector<int> v(3); // Declare a vector of 3 elements.
v[0] = 7;
v[1] = v[0] + 3;
v[2] = v[0] + v[1]; // v[0] == 7, v[1] == 10, v[2] == 17
The STL also includes a large collection of algorithms that manipulate the data stored in containers. You can reverse the order of elements in a vector , for example, by using the reverse algorithm.
reverse(v.begin(), v.end()); // v[0] == 17, v[1] == 10, v[2] == 7
There are two important points to notice about this call to reverse . First, it is a global function, not a member function. Second, it takes two arguments rather than one: it operates on a range of elements, rather than on a container. In this particular case the range happens to be the entire container v.
The reason for both of these facts is the same: reverse, like other STL algorithms, is decoupled from the STL container classes. This means that reverse can be used not only to reverse elements in vectors, but also to reverse elements in lists, and even elements in C arrays. The following program is also valid.
double A[6] = { 1.2, 1.3, 1.4, 1.5, 1.6, 1.7 };
reverse(A, A + 6);
for (int i = 0; i < 6; ++i) cout << "A[" << i << "] = " << A[i];
This example uses a range , just like the example of reversing a vector: the first argument to reverse is a pointer to the beginning of the range, and the second argument points one element past the end of the range. This range is denoted [A, A + 6); the asymmetrical notation is a reminder that the two endpoints are different, that the first is the beginning of the range and the second is one past the end of the range.
In the example of reversing a C array, the arguments to reverse are clearly of type double*. What are the arguments to reverse if you are reversing a vector, though, or a list? That is, what exactly does reverse declare its arguments to be, and what exactly do v.begin() and v.end() return?
The answer is that the arguments to reverse are iterators , which are a generalization of pointers. Pointers themselves are iterators, which is why it is possible to reverse the elements of a C array. Similarly, vector declares the nested types iterator and const_iterator. In the example above, the type returned by v.begin() and v.end() is vector<int>::iterator. There are also some iterators, such as istream_iterator and ostream_iterator, that aren't associated with containers at all.
Iterators are the mechanism that makes it possible to decouple algorithms from containers: algorithms are templates, and are parameterized by the type of iterator, so they are not restricted to a single type of container. Consider, for example, how to write an algorithm that performs linear search through a range. This is the STL's find algorithm.
template <class InputIterator, class T>
InputIterator find(InputIterator first, InputIterator last, const T& value) {
while (first != last && *first != value) ++first;
return first;
}
Find takes three arguments: two iterators that define a range, and a value to search for in that range. It examines each iterator in the range [first, last), proceeding from the beginning to the end, and stops either when it finds an iterator that points to value or when it reaches the end of the range.
First and last are declared to be of type InputIterator , and InputIterator is a template parameter. That is, there isn't actually any type called InputIterator: when you call find, the compiler substitutes the actual type of the arguments for the formal type parameters InputIterator and T. If the first two arguments to find are of type int* and the third is of type int , then it is as if you had called the following function.
int* find(int* first, int* last, const int& value) {
while (first != last && *first != value) ++first;
return first;
}
One very important question to ask about any template function, not just about STL algorithms, is what the set of types is that may correctly be substituted for the formal template parameters. Clearly, for example, int* or double* may be substituted for find 's formal template parameter InputIterator . Equally clearly, int or double may not: find uses the expression *first , and the dereference operator makes no sense for an object of type int or of type double . The basic answer, then, is that find implicitly defines a set of requirements on types, and that it may be instantiated with any type that satisfies those requirements. Whatever type is substituted for InputIterator must provide certain operations: it must be possible to compare two objects of that type for equality, it must be possible to increment an object of that type, it must be possible to dereference an object of that type to obtain the object that it points to, and so on.
Find isn't the only STL algorithm that has such a set of requirements; the arguments to for_each and count, and other algorithms, must satisfy the same requirements. These requirements are sufficiently important that we give them a name: we call such a set of type requirements a concept , and we call this particular concept Input Iterator. we say that a type conforms to a concept , or that it is a model of a concept , if it satisfies all of those requirements. We say that int* is a model of Input Iterator because int* provides all of the operations that are specified by the Input Iterator requirements.
Concepts are not a part of the C++ language; there is no way to declare a concept in a program, or to declare that a particular type is a model of a concept. Nevertheless, concepts are an extremely important part of the STL. Using concepts makes it possible to write programs that cleanly separate interface from implementation: the author of find only has to consider the interface specified by the concept Input Iterator, rather than the implementation of every possible type that conforms to that concept. Similarly, if you want to use find , you need only to ensure that the arguments you pass to it are models of Input Iterator.this is the reason why find and reverse can be used with list s, vector s, C arrays, and many other types: programming in terms of concepts, rather than in terms of specific types, makes it possible to reuse software components and to combine components together.
Input Iterator is, in fact, a rather weak concept: that is, it imposes very few requirements. An Input Iterator must support a subset of pointer arithmetic (it must be possible to increment an Input Iterator using prefix and postfix operator++), but need not support all operations of pointer arithmetic. This is sufficient for find, but some other algorithms require that their arguments satisfy additional requirements. Reverse , for example, must be able to decrement its arguments as well as increment them; it uses the expression last. In terms of concepts, we say that reverse 's arguments must be models of Bidirectional Iterator rather than Input Iterator.
The Bidirectional Iterator concept is very similar to the Input Iterator concept: it simply imposes some additional requirements. The types that are models of Bidirectional Iterator are a subset of the types that are models ofInput Iterator: every type that is a model of Bidirectional Iterator is also a model of Input Iterator. Int*, for example, is both a model of Bidirectional Iterator and a model of Input Iterator, but istream_iterator, is only a model of Input Iterator: it does not conform to the more stringent Bidirectional Iterator requirements.
We describe the relationship between Input Iterator and Bidirectional Iterator by saying that Bidirectional Iterator is a refinement of Input Iterator. Refinement of concepts is very much like inheritance of C++ classes; the main reason we use a different word, instead of just calling it "inheritance", is to emphasize that refinement applies to concepts rather than to actual types.
There are actually three more iterator concepts in addition to the two that we have already discussed: the five iterator concepts are Output Iterator, Input Iterator, Forward Iterator, Bidirectional Iterator, and Random Access Iterator; Forward Iterator is a refinement of Input Iterator, Bidirectional Iterator is a refinement of Forward Iterator, and Random Access Iterator is a refinement of Bidirectional Iterator. (Output Iterator is related to the other four concepts, but it is not part of the hierarchy of refinement: it is not a refinement of any of the other iterator concepts, and none of the other iterator concepts are refinements of it.) The Iterator Overview has more information about iterators in general.
Container classes, like iterators, are organized into a hierarchy of concepts. All containers are models of the concept Container; more refined concepts, such as Sequence and Associative Container, describe specific types of containers.
If you understand algorithms, iterators, and containers, then you understand almost everything there is to know about the STL. The STL does, however, include several other types of components.
First, the STL includes several utilities: very basic concepts and functions that are used in many different parts of the library. The concept Assignable, for example, describes types that have assignment operators and copy constructors; almost all STL classes are models of Assignable, and almost all stl algorithms require their arguments to be models of Assignable.
Second, the STL includes some lowlevel mechanisms for allocating and deallocating memory. Allocators are very specialized, and you can safely ignore them for almost all purposes.
Finally, the STL includes a large collection of function objects, also known as functors. Just as iterators are a generalization of pointers, function objects are a generalization of functions: a function object is anything that you can call using the ordinary function call syntax. There are several different concepts relating to function objects, including Unary Function (a function object that takes a single argument, i.e. one that is called as f(x)) and Binary Function (a function object that takes two arguments, i.e. one that is called as f(x, y)). Function objects are an important part of generic programming because they allow abstraction not only over the types of objects, but also over the operations that are being performed.
How to use the STL documentation
This site documents all of the components (classes, functions, and concepts) in the SGI Standard Template Library. Each page describes a single component, and also includes links to related components.
This documentation assumes a general familiarity with C++, especially with C++ templates. Additionally, you should read Introduction to the Standard Template Library before proceeding to the pages that describe individual components: the introductory page defines several terms that are used throughout the documentation.
Classification of STL components
The STL components are divided into six broad categories on the basis of functionality: Containers, Iterators, Algorithms, Function Objects, Utilities, and Allocators; these categories are defined in the Introduction, and the Table of Contents is organized according to them.
The STL documentation contains two indices. One of them, the Main Index, lists all components in alphabetical order. The other, the Divided Index, contains a separate alphabetical listing for each category. The Divided Index includes one category that is not present in the Table of Contents: Adaptors. An adaptor is a class or a function that transforms one interface into a different one. The reason that adaptors don't appear in the Table of Contents is that no component is merely an adaptor, but always an adaptor and something else; stack, for example, is a container and an adaptor. Accordingly, stack appears in two different places in the Divided Index. There are several other components that appear in the Divided Index in more than one place.
The STL documentation classifies components in two ways.
1. Categories are a classification by functionality. The categories are:
• Container
• Iterator
• Algorithm
• Function Object
• Utility
• Adaptor
• Allocator.
2. Component types are a structural classification: one based on what kind of C++ entity (if any) a component is. The component types are:
• Type (i.e. a struct or class )
• Function
• Concept (as defined in the Introduction).
These two classification schemes are independent, and each of them applies to every STL component; vector, for example, is a type whose category is Containers, and Forward Iterator is a concept whose category is Iterators.
Both of these classification schemes appear at the top of every page that documents an STL component. The upper left corner identifies the the component's category as Containers, Iterators, Algorithms, Function Objects, Utilities, Adaptors, or Allocators, and the upper right corner identifies the component as a type, a function, or a concept.
The STL is a generic library: almost every class and function is a template. Accordingly, one of the most important purposes of the STL documentation is to provide a clear description of which types may be used to instantiate those templates. As described in the Introduction, a concept is a generic set of requirements that a type must satisfy: a type is said to be a model of a concept if it satisfies all of that concept's requirements.
Concepts are used very heavily in the STL documentation, both because they directly express type requirements, and because they are a tool for organizing types conceptually. (For example, the fact that ostream_iterator and insert_iterator are both models of Output Iterator is an important statement about what those two classes have in common.) Concepts are used for the documentation of both types and functions.
The format of a concept page
A page that documents a concept has the following sections.
• Summary: a description of the concept's purpose.
• Refinement of: a list of other concepts that this concept refines , with links to those concepts.
• Associated types: a concept is a set of requirements on some type. Frequently, however, some of those requirements involve some other type. For example, one of the Unary Function requirements is that a Unary Function must have an argument type ; if F is a type that models Unary Function and f is an object of type F, then, in the expression f(x), x must be of F 's argument type. If a concept does have any such associated types, then they are defined in this section.
• Notation: the next three sections, definitions, valid expressions, and expression semantics, present expressions involving types that model the concept being defined. This section defines the meaning of the variables and identifiers used in those expressions.
• Definitions: some concepts, such as LessThan Comparable, use specialized terminology. If a concept requires any such terminology, it is defined in this section.
• Valid Expressions: a type that models a concept is required to support certain operations. In most cases, it doesn't make sense to describe this in terms of specific functions or member functions: it doesn't make any difference, for example, whether a type that models Input Iterator uses a global function or a member function to provide operator++. This section lists the expressions that a type modeling this concept must support. It includes any special requirements (if any) on the types of the expression's operands, and the expression's return type (if any).
• Expression Semantics: the previous section, valid expressions, lists which expressions involving a type must be supported; it doesn't, however, define the meaning of those expressions. This section does: it lists the semantics, preconditions, and postconditions for the expressions defined in the previous section.
• Complexity Guarantees: in some cases, the runtime complexity of certain operations is an important part of a concept's requirements. For example, one of the most significant distinctions between a Bidirectional Iterator and a Random Access Iterator is that, for random access iterators, expressions like p + n take constant time. Any such requirements on runtime complexity are listed in this section.
• Invariants: many concepts require that some property is always true for objects of a type that models the concept being defined. For example, LessThan Comparable imposes the requirement of transitivity : if x < y and y < z, then x < z. Some such properties are "axioms" (that is, they are independent of any other requirements) and some are "theorems" (that is, they follow either from requirements in the expression semantics section or from other requirements in the invariants section).
• Models: a list of examples of types that are models of this concept. Note that this list is not intended to be complete: in most cases a complete list would be impossible, because there are an infinite number of types that could model the concept.
• Notes: footnotes (if any) that are referred to by other parts of the page.
• See Also: links to other related pages.
The format of a type page
A page that documents a type has the following sections.
• Description. a summary of the type's properties.
• Example of use: a code fragment involving the type.
• Definition: a link to the source code where the type is defined.
• Template parameters: almost all stl structs and classes are templates. This section lists the name of each template parameter, its purpose, and its default value (if any).
• Model of: a list of the concepts that this type is a model of, and links to those concepts. Note that a type may be a model of more than one concept: vector, for example, is a model of both Random Access Container and Back Insertion Sequence. if a type is a model of two different concepts, that simply means that it satisfies the requirements of both.
• Type requirements: the template parameters of a class template usually must satisfy a set of requirements. Many of these can simply be expressed by listing which concept a template parameter must conform to, but some type requirements are slightly more complicated, and involve a relationship between two different template parameters.
• Public base classes: if this class inherits from any other classes, they are listed in this section.
• Members: a list of this type's nested types, member functions, member variables, and associated nonmember functions. In most cases these members are simply listed, rather than defined: since the type is a model of some concept, detailed definitions aren't usually necessary. For example, vector is a model of Container, so the description of the member function begin() in the Container page applies to vector, and there is no need to repeat it in the vector page. Instead, the Members section provides a very brief description of each member and a link to whatever page defines that member more fully.
• New Members: a type might have some members that are not part of the requirements of any of the concepts that it models. For example, vector has a member function called capacity(), which is not part of the Random Access Container or Back Insertion Sequence requirements. these members are defined in the New members section.
• Notes: footnotes (if any) that are referred to by other parts of the page.
• See Also: links to other related pages.
The format of a function page
A page that documents a function has the following sections.
• Prototype: the function's declaration.
• Description: a summary of what the function does.
• Definition: a link to the source code where the function is defined.
• Requirements on types: most functions in the stl are function templates. This section lists the requirements that must be satisfied by the function's template parameters. Sometimes the requirements can simply be expressed by listing which concept a template parameter must conform to, but sometimes they are more complicated and involve a relationship between two different template parameters. In the case of find, for example, the requirements are that the parameter InputIterator is a model of Input Iterator, that the parameter EqualityComparable is a model of Equality Comparable, and that comparison for equality is possible between objects of type EqualityComparable and objects of InputIterator 's value types.
• Preconditions: functions usually aren't guaranteed to yield a welldefined result for any possible input, but only for valid input; it is an error to call a function with invalid input. This section describes the conditions for validity.
• Complexity: guarantees on the function's runtime complexity. For example, find 's runtime complexity is linear in the length of the input range.
• Example of use: a code fragment that illustrates how to use the function.
• Notes: footnotes (if any) that are referred to by other parts of the page.
• See Also: links to other related pages.
Category: containers
Component type: concept
Description
A Container is an object that stores other objects (its elements), and that has methods for accessing its elements. In particular, every type that is a model of Container has an associated iterator type that can be used to iterate through the Container's elements.
There is no guarantee that the elements of a Container are stored in any definite order; the order might, in fact, be different upon each iteration through the Container. Nor is there a guarantee that more than one iterator into a Container may be active at any one time. (Specific types of Containers, such as Forward Container, do provide such guarantees.)
A Container "owns" its elements: the lifetime of an element stored in a container cannot exceed that of the Container itself. [1]
Refinement of
Assignable
Associated types
Value type  X::value_type 
The type of the object stored in a container. The value type must be Assignable, but need not be DefaultConstructible. [2] 
Iterator type  X::iterator 
The type of iterator used to iterate through a container's elements. The iterator's value type is expected to be the container's value type. A conversion from the iterator type to the const iterator type must exist. The iterator type must be an input iterator. [3] 
Const iterator type  X::const_iterator 
A type of iterator that may be used to examine, but not to modify, a container's elements. [3] [4] 
Reference type  X::reference 
A type that behaves as a reference to the container's value type. [5] 
Const reference type  X::const_reference 
A type that behaves as a const reference to the container's value type. [5] 
Pointer type  X::pointer 
A type that behaves as a pointer to the container's value type. [6] 
Distance type  X::difference_type 
A signed integral type used to represent the distance between two of the container's iterators. This type must be the same as the iterator's distance type. [2] 
Size type  X::size_type 
An unsigned integral type that can represent any nonnegative value of the container's distance type. [2] 
Notation
X
A type that is a model of Container
a, b
Object of type X
T
The value type of X
Definitions
The size of a container is the number of elements it contains. The size is a nonnegative number.
The area of a container is the total number of bytes that it occupies. More specifically, it is the sum of the elements' areas plus whatever overhead is associated with the container itself. If a container's value type T is a simple type (as opposed to a container type), then the container's area is bounded above by a constant times the container's size times sizeof(T). That is, if a is a container with a simple value type, then a 's area is O(a.size()).
A variable sized container is one that provides methods for inserting and/or removing elements; its size may vary during a container's lifetime. A fixed size container is one where the size is constant throughout the container's lifetime. In some fixedsize container types, the size is determined at compile time.
Valid expressions
In addition to the expressions defined in Assignable, EqualityComparable, and LessThanComparable, the following expressions must be valid.
Name  Expression  Return type 

Beginning of range  a.begin() 
iterator if a is mutable, const_iterator otherwise [4] [7] 
End of range  a.end() 
iterator if a is mutable, const_iterator otherwise [4] 
Size  a.size() 
size_type 
Maximum size  a.max_size() 
size_type 
Empty container  a.empty() 
Convertible to bool 
Swap  a.swap(b) 
void 
Expression semantics
Semantics of an expression is defined only where it differs from, or is not defined in, Assignable, Equality Comparable, or LessThan Comparable
Name  Expression  Semantics  Postcondition 

Copy constructor  X(a) 
X().size() == a.size(). X() contains a copy of each of a 's elements. 

Copy constructor  X b(a); 
b.size() == a.size(). b contains a copy of each of a 's elements. 

Assignment operator  b = a 
b.size() == a.size(). b contains a copy of each of a 's elements. 

Destructor  a.~X() 
Each of a 's elements is destroyed, and memory allocated for them (if any) is deallocated.  
Beginning of range  a.begin() 
Returns an iterator pointing to the first element in the container. [7]  a.begin() is either dereferenceable or pasttheend. It is pasttheend if and only if a.size() == 0. 
End of range  a.end()  Returns an iterator pointing one past the last element in the container.  a.end() is pasttheend. 
Size  a.size() 
Returns the size of the container, that is, its number of elements. [8]  a.size() >= 0 && a.size() <= max_size() 
Maximum size  a.max_size() 
Returns the largest size that this container can ever have. [8]  a.max_size() >= 0 && a.max_size() >= a.size() 
Empty container  a.empty() 
Equivalent to a.size() == 0. (But possibly faster.)  
Swap  a.swap(b) 
Equivalent to swap(a,b) [9] 
Complexity guarantees
The copy constructor, the assignment operator, and the destructor are linear in the container's size.
begin() and end() are amortized constant time.
size() is linear in the container's size. [10]max_size() and empty() are amortized constant time. If you are testing whether a container is empty, you should always write c.empty() instead of c.size() == 0. The two expressions are equivalent, but the former may be much faster.
swap() is amortized constant time. [9]
Invariants
Valid range  For any container a, [a.begin(), a.end()) is a valid range. [11] 
Range size  a.size() is equal to the distance from a.begin() to a.end(). 
Completeness  An algorithm that iterates through the range [a.begin(), a.end()) will pass through every element of a. [11] 
Models
• vector
Notes
[1] The fact that the lifetime of elements cannot exceed that of of their container may seem like a severe restriction. In fact, though, it is not. Note that pointers and iterators are objects; like any other objects, they may be stored in a container. The container, in that case, "owns" the pointers themselves, but not the objects that they point to.
[2] This expression must be a typedef , that is, a synonym for a type that already has some other name.
[3] This may either be a typedef for some other type, or else a unique type that is defined as a nested class within the class X.
[4] A container's iterator type and const iterator type may be the same: there is no guarantee that every container must have an associated mutable iterator type. For example, set and hash_set define iterator and const_iterator to be the same type.
[5] It is required that the reference type has the same semantics as an ordinary C++ reference, but it need not actually be an ordinary C++ reference. Some implementations, for example, might provide additional reference types to support nonstandard memory models. Note, however, that "smart references" (userdefined reference types that provide additional functionality) are not a viable option. It is impossible for a userdefined type to have the same semantics as C++ references, because the C++ language does not support redefining the member access operator (operator.).
[6] As in the case of references [5], the pointer type must have the same semantics as C++ pointers but need not actually be a C++ pointer. "Smart pointers," however, unlike "smart references", are possible. This is because it is possible for userdefined types to define the dereference operator and the pointer member access operator, operator* and operator>.
[7] The iterator type need only be an input iterator , which provides a very weak set of guarantees; in particular, all algorithms on input iterators must be "single pass". It follows that only a single iterator into a container may be active at any one time. This restriction is removed in Forward Container.
[8] In the case of a fixedsize container, size() == max_size().
[9] For any Assignable type, swap can be defined in terms of assignment. This requires three assignments, each of which, for a container type, is linear in the container's size. In a sense, then, a.swap(b) is redundant. It exists solely for the sake of efficiency: for many containers, such as vector and list, it is possible to implement swap such that its runtime complexity is constant rather than linear. If this is possible for some container type X , then the template specialization swap(X&, X&) can simply be written in terms of X::swap(X&). The implication of this is that X::swap(X&) should only be defined if there exists such a constanttime implementation. Not every container class X need have such a member function, but if the member function exists at all then it is guaranteed to be amortized constant time.
[10] For many containers, such as vector and deque, size is O(1). This satisfies the requirement that it be O(N).
[11] Although [a.begin(), a.end()) must be a valid range, and must include every element in the container, the order in which the elements appear in that range is unspecified. If you iterate through a container twice, it is not guaranteed that the order will be the same both times. This restriction is removed in Forward Container.
See also
The Iterator overview, Input Iterator, Sequence
Category: containers
Component type: concept
Description
A Forward Container is a Container whose elements are arranged in a definite order: the ordering will not change spontaneously from iteration to iteration. The requirement of a definite ordering allows the definition of elementbyelement equality (if the container's element type is Equality Comparable) and of lexicographical ordering (if the container's element type is LessThan Comparable).
Iterators into a Forward Container satisfy the forward iterator requirements; consequently, Forward Containers support multipass algorithms and allow multiple iterators into the same container to be active at the same time. Refinement of Container, EqualityComparable, LessThanComparable
Associated types
No additional types beyond those defined in Container. However, the requirements for the iterator type are strengthened: the iterator type must be a model of Forward Iterator.
Notation
X
A type that is a model of Forward Container
a, b
Object of type X
T
The value type of X
Valid expressions
In addition to the expressions defined in Container, EqualityComparable, and LessThanComparable, the following expressions must be valid.
Name  Expression  Type requirements  Return type 

Equality  a == b 
T is EqualityComparable  Convertible to bool 
Inequality  a != b 
T is EqualityComparable  Convertible to bool 
Less  a < b 
T is LessThanComparable  Convertible to bool 
Greater  a > b 
T is LessThanComparable  Convertible to bool 
Less or equal  a <= b 
T is LessThanComparable  Convertible to bool 
Greater or equal  a >= b 
T is LessThanComparable  Convertible to bool 
Expression semantics
Semantics of an expression is defined only where it is not defined in Container, EqualityComparable, or LessThanComparable, or where there is additional information.
Name  Expression  Semantics 

Equality  a == b 
Returns true if a.size() == b.size() and if each element of a compares equal to the corresponding element of b. Otherwise returns false. 
Less  a < b 
Equivalent to lexicographical_compare(a,b) 
Complexity guarantees
The equality and inequality operations are linear in the container's size.
Invariants
Ordering  Two different iterations through a forward container will access its elements in the same order, providing that there have been no intervening mutative operations. 
Models
• vector
• list
• slist
• deque
• set
• hash_set
• map
• hash_map
• multiset
• hash_multiset
• multimap
• hash_multimap
See also
The iterator overview, Forward Iterator, Sequence
Category: containers
Component type: concept
Description
A Reversible Container is a Forward Container whose iterators are Bidirectional Iterators. It allows backwards iteration through the container.
Refinement of
Forward Container
Associated types
Two new types are introduced. In addition, the iterator type and the const iterator type must satisfy a more stringent requirement than for a Forward Container. The iterator and reverse iterator types must be Bidirectional Iterators, not merely Forward Iterators.
Reverse iterator type  X::reverse_iterator 
A Reverse Iterator adaptor whose base iterator type is the container's iterator type. Incrementing an object of type reverse_iterator moves backwards through the container: the Reverse Iterator adaptor maps operator++ to operator. 
Const reverse iterator type  X::const_reverse_iterator 
A Reverse Iterator adaptor whose base iterator type is the container's const iterator type. [1] 
Notation
X
A type that is a model of Reversible Container
a, b
Object of type X
Valid expressions
In addition to the expressions defined in Forward Container, the following expressions must be valid.
Name  Expression  Return type 

Beginning of range  a.rbegin() 
reverse_iterator if a is mutable, const_reverse_iterator otherwise [1] 
End of range  a.rend() 
reverse_iterator if a is mutable, const_reverse_iterator otherwise [1] 
Expression semantics
Semantics of an expression is defined only where it is not defined in Forward Container, or where there is additional information.
Name  Expression  Semantics  Postcondition 

Beginning of reverse range  a.rbegin() 
Equivalent to X::reverse_iterator(a.end()). 
a.rbegin() is dereferenceable or pasttheend. It is pasttheend if and only if a.size() == 0. 
End of reverse range  a.rend() 
Equivalent to X::reverse_iterator(a.begin()). 
a.end() is pasttheend. 
Complexity guarantees
The runtime complexity of rbegin() and rend() is amortized constant time.
Invariants
Valid range  [a.rbegin(), a.rend()) is a valid range. 
Equivalence of ranges  The distance from a.begin() to a.end() is the same as the distance from a.rbegin() to a.rend(). 
Models
• vector
• list
• deque
Notes
[1] A Container's iterator type and const iterator type may be the same type: a container need not provide mutable iterators. It follows from this that the reverse iterator type and the const reverse iterator type may also be the same.
See also
The Iterator overview, Bidirectional Iterator, Sequence
Category: containers
Component type: concept
Description
A Random Access Container is a Reversible Container whose iterator type is a Random Access Iterator. It provides amortized constant time access to arbitrary elements.
Refinement of
Reversible Container
Associated types
No additional types beyond those defined in Reversible Container. However, the requirements for the iterator type are strengthened: it must be a Random Access Iterator.
Notation
X
A type that is a model of Random Access Container
a, b
Object of type X
T
The value type of X
Valid expressions
In addition to the expressions defined in Reversible Container, the following expressions must be valid.
Name  Expression  Type requirements  Return type 

Element access  a[n] 
n is convertible to size_type  reference if a is mutable, const_reference otherwise 
Expression semantics
Semantics of an expression is defined only where it is not defined in Reversible Container, or where there is additional information.
Name  Expression  Precondition  Semantics 

Element access  a[n] 
0 <= n < a.size() 
Returns the n th element from the beginning of the container. 
Complexity guarantees
The runtime complexity of element access is amortized constant time.
Invariants
Element access  The element returned by a[n] is the same as the one obtained by incrementing a.begin()n times and then dereferencing the resulting iterator. 
Models
• vector
• deque
See also
The Iterator overview, Random Access Iterator, Sequence
Category: containers
Component type: concept
Description
A Sequence is a variablesized Container whose elements are arranged in a strict linear order. It supports insertion and removal of elements.
Refinement of
Forward Container, Default Constructible
Associated types
None, except for those of Forward Container.
Notation
X
A type that is a model of Sequence
a, b
Object of type X
T
The value type of X
t
Object of type T
p, q
Object of type X::iterator
n
Object of a type convertible to X::size_type
Definitions
If a is a Sequence, then p is a valid iterator in a if it is a valid (nonsingular) iterator that is reachable from a.begin().
If a is a Sequence, then [p, q) is a valid range in a if p and q are valid iterators in a and if q is reachable from p.
Valid expressions
In addition to the expressions defined in Forward Container, the following expressions must be valid.
Name  Expression  Type requirements  Return type 

Fill constructor  X(n, t) 
X 

Fill constructor  X a(n, t); 

Default fill constructor  X(n) 
T is DefaultConstructible.  X 
Default fill constructor  X a(n); 
T is DefaultConstructible.  
Range constructor  X(i, j) 
i and j are Input Iterators whose value type is convertible to T [1]  X 
Range constructor  X a(i, j); 
i and j are Input Iterators whose value type is convertible to T [1]  
Front  a.front() 
reference if a is mutable, const_reference otherwise.  
Insert  a.insert(p, t) 
X::iterator 

Fill insert  a.insert(p, n, t) 
a is mutable  void 
Range insert  a.insert(p, i, j) 
i and j are Input Iterators whose value type is convertible to T [1]. a is mutable  void 
Erase  a.erase(p) 
a is mutable  iterator 
Range erase  a.erase(p,q) 
a is mutable  iterator 
Clear  a.clear() 
a is mutable  void 
Resize  a.resize(n, t) 
a is mutable  void 
Resize  a.resize(n) 
a is mutable  void 
Expression semantics
Semantics of an expression is defined only where it is not defined in Forward Container, or where it differs.
Name  Expression  Precondition  Semantics  Postcondition 

Fill constructor  X(n, t) 
n >= 0 
Creates a sequence with n copies of t  size() == n. Every element is a copy of t. 
Fill constructor  X a(n, t); 
n >= 0 
Creates a sequence with n copies of t  a.size() == n . Every element of a is a copy of t. 
Default fill constructor  X(n) 
n >= 0 
Creates a sequence of n elements initialized to a default value.  size() == n. Every element is a copy of T(). 
Default fill constructor  X a(n, t); 
n >= 0 
Creates a sequence with n elements initialized to a default value.  a.size() == n. Every element of a is a copy of T(). 
Default constructor  X a; or X() 
Equivalent to X(0).  size() == 0. 

Range constructor  X(i, j) 
[i,j) is a valid range.  Creates a sequence that is a copy of the range [i,j)  size() is equal to the distance from i to j. Each element is a copy of the corresponding element in the range [i,j). 
Range constructor  X a(i, j); 
[i,j) is a valid range.  Creates a sequence that is a copy of the range [i,j)  a.size() is equal to the distance from i to j. Each element in a is a copy of the corresponding element in the range [i,j). 
Front  a.front() 
!a.empty() 
Equivalent to *(a.first())  
Insert  a.insert(p, t) 
p is a valid iterator in a. a.size() < a.max_size()  A copy of t is inserted before p. [2] [3]  a.size() is incremented by 1. *(a.insert(p,t)) is a copy of t . The relative order of elements already in the sequence is unchanged. 
Fill insert  a.insert(p, n, t) 
p is a valid iterator in a. n >= 0 && a.size() + n <= a.max_size().  n copies of t are inserted before p. [2] [3] [4]  a.size() is incremented by n. The relative order of elements already in the sequence is unchanged. 
Range insert  a.insert(p, i, j) 
[i,j) is a valid range.  a.size() plus the distance from i to j does not exceed a.max_size(). Inserts a copy of the range [i,j) before p. [1] [2] [3]  a.size() is incremented by the distance from i to j. The relative order of elements already in the sequence is unchanged. 
Erase  a.erase(p) 
p is a dereferenceable iterator in a.  Destroys the element pointed to by p and removes it from a. [3]  a.size() is decremented by 1. The relative order of the other elements in the sequence is unchanged. The return value is an iterator to the element immediately following the one that was erased. 
Range erase  a.erase(p,q) 
[p,q) is a valid range in a.  Destroys the elements in the range [p,q) and removes them from a. [3]  a.size() is decremented by the distance from i to j. The relative order of the other elements in the sequence is unchanged. The return value is an iterator to the element immediately following the ones that were erased. 
Clear  a.clear() 
Equivalent to a.erase(a.begin(), a.end())  
Resize  a.resize(n, t) 
n <= a.max_size() 
Modifies the container so that it has exactly n elements, inserting elements at the end or erasing elements from the end if necessary. If any elements are inserted, they are copies of t. If n > a.size() , this expression is equivalent to a.insert(a.end(), n – size(), t). If n < a.size() , it is equivalent to a.erase(a.begin() + n, a.end()).  a.size() == n 
Resize  a.resize(n) 
n <= a.max_size() 
Equivalent to a.resize(n, T()).  a.size() == n 
Complexity guarantees
The fill constructor, default fill constructor, and range constructor are linear.
Front is amortized constant time.
Fill insert, range insert, and range erase are linear.
The complexities of singleelement insert and erase are sequence dependent.
Models
• vector [5]
• deque
• list
• slist
Notes
[1] At present (early 1998), not all compilers support "member templates". If your compiler supports member templates then i and j may be of any type that conforms to the Input Iterator requirements. If your compiler does not yet support member templates, however, then i and j must be of type const T* or of type X::const_iterator.
[2] Note that p equal to a.begin() means to insert something at the beginning of a (that is, before any elements already in a ), and p equal to a.end() means to append something to the end of a.
[3] Warning: there is no guarantee that a valid iterator ona is still valid after an insertion or an erasure. In some cases iterators do remain valid, and in other cases they do not. The details are different for each sequence class.
[4] a.insert(p, n, t) is guaranteed to be no slower then calling a.insert(p, t)n times. In some cases it is significantly faster.
[5] Vector is usually preferable to deque and list. Deque is useful in the case of frequent insertions at both the beginning and end of the sequence, and list and slist are useful in the case of frequent insertions in the middle of the sequence. In almost all other situations, vector is more efficient.
See also
Container, Forward Container, Associative Container, Front Insertion Sequence, Back Insertion Sequence, vector, deque, list, slist
Category: containers
Component type: concept
Description
A Front Insertion Sequence is a Sequence where it is possible to insert an element at the beginning, or to access the first element, in amortized constant time. Front Insertion Sequences have special member functions as a shorthand for those operations.
Refinement of
Sequence
Associated types
None, except for those of Sequence.
Notation
X
A type that is a model of Front Insertion Sequence
a
Object of type X
T
The value type of X
t
Object of type T
Valid expressions
In addition to the expressions defined in Sequence, the following expressions must be valid.
Name  Expression  Type requirements  Return type 

Front  a.front() [1] 
reference if a is mutable, otherwise const_reference.  
Push front  a.push_front(t) 
a is mutable.  void 
Pop front  a.pop_front() 
a is mutable.  void 
Expression semantics
Name  Expression  Precondition  Semantics  Postcondition 

Front  a.front() [1] 
!a.empty()  Equivalent to *(a.begin()).  
Push front  a.push_front(t)  Equivalent to a.insert(a.begin(), t) a.size is incremented by 1.  a.front() is a copy of t.  
Pop front  a.pop_front() 
!a.empty() 
Equivalent to a.erase(a.begin())  a.size() is decremented by 1. 
Complexity guarantees
Front, push front, and pop front are amortized constant time. [2]
Invariants
Symmetry of push and pop  push_front() followed by pop_front() is a null operation. 
Models
• list
• deque
Notes
[1] Front is actually defined in Sequence, since it is always possible to implement it in amortized constant time. Its definition is repeated here, along with push front and pop front, in the interest of clarity.
[2] This complexity guarantee is the only reason that front(), push_front(), and pop_front() are defined: they provide no additional functionality. Not every sequence must define these operations, but it is guaranteed that they are efficient if they exist at all.
See also
Container, Sequence, Back Insertion Sequence, deque, list, slist
Category: containers
Component type: concept
Description
A Back Insertion Sequence is a Sequence where it is possible to append an element to the end, or to access the last element, in amortized constant time. Back Insertion Sequences have special member functions as a shorthand for those operations.
Refinement of
Sequence
Associated types
None, except for those of Sequence.
Notation
X
A type that is a model of Back Insertion Sequence
a
Object of type X
T
The value type of X
t
Object of type T
Valid expressions
In addition to the expressions defined in Sequence, the following expressions must be valid.
Name  Expression  Type requirements  Return type 

Back  a.back() 
reference if a is mutable, otherwise const_reference.  
Push back  a.push_back(t) 
a is mutable.  void 
Pop back  a.pop_back() 
a is mutable.  void 
Expression semantics
Name  Expression  Precondition  Semantics  Postcondition 

Back  a.back() 
!a.empty() 
Equivalent to *(a.end()).  
Push back  a.push_back(t) 
Equivalent to a.insert(a.end(), t) a.size is incremented by 1.  a.back() is a copy of t.  
Pop back  a.pop_back() 
!a.empty() 
Equivalent to a.erase(a.end())  a.size() is decremented by 1. 
Complexity guarantees
Back, push back, and pop back are amortized constant time. [1]
Invariants
Symmetry of push and pop  push_back() followed by pop_back() is a null operation. 
Models
vector
list
deque
Notes
[1] This complexity guarantee is the only reason that back(), push_back(), and pop_back() are defined: they provide no additional functionality. Not every sequence must define these operations, but it is guaranteed that they are efficient if they exist at all.
See also
Container, Sequence, Front Insertion Sequence, vector, deque, list
Category: containers
Component type: concept
Description
An Associative Container is a variablesized Container that supports efficient retrieval of elements (values) based on keys. It supports insertion and removal of elements, but differs from a Sequence in that it does not provide a mechanism for inserting an element at a specific position. [1]
As with all containers, the elements in an Associative Container are of type value_type. Additionally, each element in an Associative Container has a key, of type key_type. In some Associative Containers, Simple Associative Containers, the value_type and key_type are the same: elements are their own keys. In others, the key is some specific part of the value. Since elements are stored according to their keys, it is essential that the key associated with each element is immutable. In Simple Associative Containers this means that the elements themselves are immutable, while in other types of Associative Containers, such as Pair Associative Containers, the elements themselves are mutable but the part of an element that is its key cannot be modified. This means that an Associative Container's value type is not Assignable.
The fact that the value type of an Associative Container is not Assignable has an important consequence: associative containers cannot have mutable iterators. This is simply because a mutable iterator (as defined in the Trivial Iterator requirements) must allow assignment. That is, if i is a mutable iterator and t is an object of i 's value type, then *i = t must be a valid expression.
In Simple Associative Containers, where the elements are the keys, the elements are completely immutable; the nested types iterator and const_iterator are therefore the same. Other types of associative containers, however, do have mutable elements, and do provide iterators through which elements can be modified. Pair Associative Containers, for example, have two different nested types iterator and const_iterator . Even in this case, iterator is not a mutable iterator: as explained above, it does not provide the expression *i = t. It is, however, possible to modify an element through such an iterator: if, for example, i is of type map<int, double> , then (*i).second = 3 is a valid expression.
In some associative containers, Unique Associative Containers, it is guaranteed that no two elements have the same key. [2] In other associative containers, Multiple Associative Containers, multiple elements with the same key are permitted.
Refinement of
Forward Container, Default Constructible
Associated types
One new type is introduced, in addition to the types defined in the Forward Container requirements.
Key type  X::key_type 
The type of the key associated with X::value_type . Note that the key type and value type might be the same. 
Notation
X
A type that is a model of Associative Container
a
Object of type X
t
Object of type X::value_type
k
Object of type X::key_type
p, q
Object of type X::iterator
Definitions
If a is an associative container, then p is a valid iterator in a if it is a valid iterator that is reachable from a.begin().
If a is an associative container, then [p, q) is a valid range in a if [p, q) is a valid range and p is a valid iterator in a.
Valid expressions
In addition to the expressions defined in Forward Container, the following expressions must be valid.
Name  Expression  Return type 

Default constructor  X() X a; 

Erase key  a.erase(k) 
size_type 
Erase element  a.erase(p) 
void 
Erase range  a.erase(p, q) 
void 
Clear  a.clear() 
void 
Find  a.find(k) 
iterator if a is mutable, otherwise const_iterator 
Count  a.count(k) 
size_type 
Equal range  a.equal_range(k) 
pair<iterator, iterator> if a is mutable, otherwise pair<const_iterator, const_iterator>. 
Expression semantics
Name  Expression  Precondition  Semantics  Postcondition 

Default constructor  X() X a; 
Creates an empty container.  The size of the container is 0.  
Erase key  a.erase(k) 
Destroys all elements whose key is the same as k, and removes them from a. [2] The return value is the number of elements that were erased, i.e. the old value of a.count(k).  a.size() is decremented by a.count(k). a contains no elements with key k.  
Erase element  a.erase(p) 
p is a dereferenceable iterator in a.  Destroys the element pointed to by p, and removes it from a.  a.size() is decremented by 1. 
Erase range  a.erase(p, q) 
[p, q) is a valid range in a.  Destroys the elements in the range [p,q) and removes them from a.  a.size() is decremented by the distance from i to j. 
Clear  a.clear() 
Equivalent to a.erase(a.begin(), a.end())  
Find  a.find(k)  Returns an iterator pointing to an element whose key is the same as k, or a.end() if no such element exists.  Either the return value is a.end(), or else the return value has a key that is the same as k.  
Count  a.count(k) 
Returns the number of elements in a whose keys are the same as k.  
Equal range  a.equal_range(k)  Returns a pair P such that [P.first, P.second) is a range containing all elements in a whose keys are the same as k. [3] If no elements have the same key as k, the return value is an empty range.  The distance between P.first and P.second is equal to a.count(k) . If p is a dereferenceable iterator in a, then either p lies in the range [P.first, P.second), or else *p has a key that is not the same as k. 
Complexity guarantees
Average complexity for erase key is at most O(log(size()) + count(k)).
Average complexity for erase element is constant time.
Average complexity for erase range is at most O(log(size()) + N), where N is the number of elements in the range.
Average complexity for count is at most O(log(size()) + count(k)).
Average complexity for find is at most logarithmic.
Average complexity for equal range is at most logarithmic.
Invariants
Contiguous storage  All elements with the same key are adjacent to each other. That is, if p and q are iterators that point to elements that have the same key, and if p precedes q , then every element in the range [p, q) has the same key as every other element. 
Immutability of keys  Every element of an Associative Container has an immutable key. Objects may be inserted and erased, but an element in an Associative Container may not be modified in such a way as to change its key. 
Models
• set
• multiset
• hash_set
• hash_multiset
• map
• multimap
• hash_map
• hash_multimap
Notes
[1] The reason there is no such mechanism is that the way in which elements are arranged in an associative container is typically a class invariant; elements in a Sorted Associative Container, for example, are always stored in ascending order, and elements in a Hashed Associative Container are always stored according to the hash function. It would make no sense to allow the position of an element to be chosen arbitrarily.
[2] Keys are not required to be Equality Comparable: associative containers do not necessarily use operator== to determine whether two keys are the same. In Sorted Associative Containers, for example, where keys are ordered by a comparison function, two keys are considered to be the same if neither one is less than the other.
[3] Note the implications of this member function: it means that if two elements have the same key, there must be no elements with different keys in between them. The requirement that elements with the same key be stored contiguously is an associative container invariant.
See also
Simple Associative Container, Pair Associative Container, Unique Associative Container, Multiple Associative Container, Sorted Associative Container, Unique Sorted Associative Container, Multiple Sorted Associative Container, Hashed Associative Container, Unique Hashed Associative Container, Multiple Hashed Associative Container.
Category: containers
Component type: concept
Description
A Simple Associative Container is an Associative Container where elements are their own keys. A key in a Simple Associative Container is not associated with any additional value.
Refinement of
Associative Container
Associated types
None, except for those described in the Associative Container requirements. Simple Associative Container, however, introduces two new type restrictions.
Key type  X::key_type 
The type of the key associated with X::value_type. The types key_type and value_type must be the same type. 
Iterator  X::iterator 
The type of iterator used to iterate through a Simple Associative Container's elements. The types X::iterator and X::const_iterator must be the same type. That is, a Simple Associative Container does not provide mutable iterators. [1] 
Notation
X
A type that is a model of Simple Associative Container
a
Object of type X
k
Object of type X::key_type
p, q
Object of type X::iterator
Valid expressions
None, except for those defined in the Associative Container requirements.
Invariants
Immutability of Elements  Every element of a Simple Associative Container is immutable. Objects may be inserted and erased, but not modified. [1] 
Models
• set
• multiset
• hash_set
• hash_multiset
Notes
[1] This is a consequence of the Immutability of Keys invariant of Associative Container. Keys may never be modified; values in a Simple Associative Container are themselves keys, so it immediately follows that values in a Simple Associative Container may not be modified.
See also
Associative Container, Pair Associative Container
Category: containers
Component type: concept
Description
A Pair Associative Container is an Associative Container that associates a key with some other object. The value type of a Pair Associative Container is pair<const key_type, data_type>. [1]
Refinement of
Associative Container
Associated types
One new type is introduced, in addition to the types defined in the Associative Container requirements. Additionally, Pair Associative Container introduces one new type restriction
Key type  X::key_type 
The type of the key associated with X::value_type. 
Data type  X::data_type 
The type of the data associated with X::value_type. A Pair Associative Container can be thought of as a mapping from key_type to data_type. 
Value type  X::value_type 
The type of object stored in the container. The value type is required to be pair<const key_type, data_type>. 
Notation
X
A type that is a model of Pair Associative Container
a
Object of type X
t
Object of type X::value_type
d
Object of type X::data_type
k
Object of type X::key_type
p, q
Object of type X::iterator
Valid expressions
None, except for those defined in the Associative Container requirements.
Models
• map
• multimap
• hash_map
• hash_multimap
Notes
[1] The value type must be pair<const key_type, data_type>, rather than pair<key_type, data_type>, because of the Associative Container invariant of key immutability. The data_type part of an object in a Pair Associative Container may be modified, but the key_type part may not be. Note the implication of this fact: a Pair Associative Container cannot provide mutable iterators (as defined in the Trivial Iterator requirements), because the value type of a mutable iterator must be Assignable, and pair<const key_type, data_type> is not Assignable. However, a Pair Associative Container can provide iterators that are not completely constant: iterators such that the expression (*i).second = d is valid.
See also
Associative Container, Simple Associative Container
Category: containers
Component type: concept
Description
A Sorted Associative Container is a type of Associative Container. Sorted Associative Containers use an ordering relation on their keys; two keys are considered to be equivalent if neither one is less than the other. (If the ordering relation is caseinsensitive string comparison, for example, then the keys "abcde" and "aBcDe" are equivalent.)
Sorted Associative Containers guarantee that the complexity for most operations is never worse than logarithmic [1], and they also guarantee that their elements are always sorted in ascending order by key.
Refinement of
Reversible Container, Associative Container
Associated types
Two new types are introduced, in addition to the types defined in the Associative Container and Reversible Container requirements.
X::key_compare 
The type of a Strict Weak Ordering used to compare keys. Its argument type must be X::key_type. 
X::value_compare 
The type of a Strict Weak Ordering used to compare values. Its argument type must be X::value_type, and it compares two objects of value_type by passing the keys associated with those objects to a function object of type key_compare. 
Notation
X
A type that is a model of Sorted Associative Container
a
Object of type X
t
Object of type X::value_type
k
Object of type X::key_type
p, q
Object of type X::iterator
c
Object of type X::key_compare
Valid expressions
In addition to the expressions defined in Associative Container and Reversible Container, the following expressions must be valid.
Name  Expression  Return type 

Default constructor  X() X a; 

Constructor with compare  X(c) X a(c); 

Key comparison  a.key_comp() 
X::key_compare 
Value comparison  a::value_compare() 
X::value_compare 
Lower bound  a.lower_bound(k) 
iterator if a is mutable, otherwise const_iterator. 
Upper bound  a.upper_bound(k) 
iterator if a is mutable, otherwise const_iterator. 
Equal range  a.equal_range(k) 
pair<iterator, iterator> if a is mutable, otherwise pair<const_iterator, const_iterator>. 
Expression semantics
Name  Expression  Semantics  Postcondition 

Default constructor  X() X a; 
Creates an empty container, using key_compare() as the comparison object.  The size of the container is 0. 
Constructor with compare  X(c) X a(c); 
Creates an empty container, using c as the comparison object.  The size of the container is 0. key_comp() returns a function object that is equivalent to c. 
Key comparison  a.key_comp() 
Returns the key comparison object used by a.  
Value comparison  a::value_compare() 
Returns the value comparison object used by a.  If t1 and t2 are objects of type value_type, and k1 and k2 are the keys associated with them, then a.value_comp()(t1, t2) is equivalent to a.key_comp()(k1, k2). 
Lower bound  a.lower_bound(k) 
Returns an iterator pointing to the first element whose key is not less than k. Returns a.end() if no such element exists.  If a contains any elements that have the same key as k, then the return value of lower_bound points to the first such element. 
Upper bound  a.upper_bound(k) 
Returns an iterator pointing to the first element whose key is greater than k.  Returns a.end() if no such element exists. If a contains any elements that have the same key as k, then the return value of upper_bound points to one past the last such element. 
Equal range  a.equal_range(k) 
Returns a pair whose first element is a.lower_bound(k) and whose second element is a.upper_bound(k). 
Complexity guarantees
key_comp() and value_comp() are constant time.
Erase element is constant time.
Erase key is O(log(size()) + count(k)). [1]
Erase range is O(log(size()) + N), where N is the length of the range. [1]
Find is logarithmic. [1]
Count is O(log(size()) + count(k)). [1]
Lower bound, upper bound, and equal range are logarithmic. [1]
Invariants
Definition of value_comp  If t1 and t2 are objects of type X::value_type and k1 and k2 are the keys associated with those objects, then a.value_comp() returns a function object such that a.value_comp()(t1, t2) is equivalent to a.key_comp()(k1, k2). 
Ascending order  The elements in a Sorted Associative Container are always arranged in ascending order by key. That is, if a is a Sorted Associative Container, then is_sorted(a.begin(), a.end(), a.value_comp()) is always true. 
Models
• set
• multiset
• map
• multimap
Notes
[1] This is a much stronger guarantee than the one provided by Associative Container. The guarantees in Associative Container only apply to average complexity; worst case complexity is allowed to be greater. Sorted Associative Container, however, provides an upper limit on worst case complexity.
[2] This definition is consistent with the semantics described in Associative Container. It is a stronger condition, though: if a contains no elements with the key k , then a.equal_range(k) returns an empty range that indicates the position where those elements would be if they did exist. The Associative Container requirements, however, merely state that the return value is an arbitrary empty range.
See also
Associative Container, Hashed Associative Container
Category: containers
Component type: concept
Description
A Hashed Associative Container is an Associative Container whose implementation is a hash table. [1] The elements of a Hashed Associative Container are not guaranteed to be in any meaningful order; in particular, they are not sorted. The worst case complexity of most operations on Hashed Associative Containers is linear in the size of the container, but the average case complexity is constant time; this means that for applications where values are simply stored and retrieved, and where ordering is unimportant, Hashed Associative Containers are usually much faster than Sorted Associative Containers.
Refinement of
Associative Container
Associated types
The following new types are introduced, in addition to the types defined in the Associative Container requirements.
Hash function  X::hasher 
A type that is a model of Hash Function. X::hasher 's argument type must be X::key_type. 
Key equal  X::key_equal 
A Binary Predicate whose argument type is X::key_type . An object of type key_equal returns true if its arguments are the same key, and false otherwise. X::key_equal must be an equivalence relation. 
Notation
X
A type that is a model of Hashed Associative Container
a
Object of type X
t
Object of type X::value_type
k
Object of type X::key_type
p, q
Object of type X::iterator
n
Object of type X::size_type
h
Object of type X::hasher
c
Object of type X::key_equal
Definitions
A hash function for a Hashed Associative Container X is a Unary Function whose argument type is X::key_type and whose return type is size_t. A hash function must be deterministic (that is, it must always return the same value whenever it is called with the same argument), but return values of the hash function should be as uniform as possible: ideally, no two keys will hash to the same value. [2]
Elements in a Hashed Associative Container are organized into buckets. A Hashed Associative Container uses the value of the hash function to determine which bucket an element is assigned to.
The number of elements in a Hashed Associative Container divided by the number of buckets is called the load factor. A Hashed Associative Container with a small load factor is faster than one with a large load factor.
Valid expressions
In addition to the expressions defined in Associative Container, the following expressions must be valid.
Name  Expression  Return type 

Default constructor  X() X a; 

Constructor with bucket count  X(n) X a(n); 

Constructor with hash function  X(n, h) X a(n, h); 

Constructor with key equal  X(n, h, k) X a(n, h, k); 

Hash function  a.hash_funct() 
X::hasher 
Key equal  a.key_eq() 
X::key_equal 
Erase key  a.erase(k) 
size_type 
Erase element  a.erase(p) 
void 
Erase range  a.erase(p, q) 
void 
Find  a.find(k) 
iterator if a is mutable, otherwise const_iterator 
Count  a.count(k) 
size_type 
Equal range  a.equal_range(k) 
pair<iterator, iterator> if a is mutable, otherwise pair<const_iterator, const_iterator>. 
Bucket count  a.bucket_count() 
X::size_type 
Resize  a.resize(n) 
void 
Expression semantics
Name  Expression  Precondition  Semantics  Postcondition 

Default constructor  X() X a; 
Creates an empty container, using hasher() as the hash function and key_equal() as the key equality function.  The size of the container is 0. The bucket count is an unspecified default value. The hash function is hasher(), and the key equality function is key_equal().  
Constructor with bucket count  X(n) X a(n); 
Creates an empty container with at least n buckets, using hasher() as the hash function and key_equal() as the key equality function.  The size of the container is 0. The bucket count is greater than or equal to n. The hash function is hasher(), and the key equality function is key_equal().  
Constructor with hash function  X(n, h) X a(n, h); 
Creates an empty container with at least n buckets, using h as the hash function and key_equal() as the key equality function.  The size of the container is 0. The bucket count is greater than or equal to n. The hash function is h, and the key equality function is key_equal().  
Constructor with key equal  X(n, h, k) X a(n, h, k); 
Creates an empty container with at least n buckets, using h as the hash function and k as the key equality function. The size of the container is 0.  The bucket count is greater than or equal to n. The hash function is h, and the key equality function is k.  
Hash function  a.hash_funct() 
Returns the hash function used by a.  
Key equal  a.key_eq() 
Returns the key equal function used by a.  
Erase key  a.erase(k) 
Destroys all elements whose key is the same as k, and removes them from a. [2]The return value is the number of elements that were erased, i.e. the old value of a.count(k).  a.size() is decremented by a.count(k). a contains no elements with key k.  
Erase element  a.erase(p) 
p is a dereferenceable iterator in a.  Destroys the element pointed to by p, and removes it from a.  a.size() is decremented by 1. 
Erase range  a.erase(p, q) 
[p, q) is a valid range in a.  Destroys the elements in the range [p,q) and removes them from a.  a.size() is decremented by the distance from i to j. 
Find  a.find(k) 
Returns an iterator pointing to an element whose key is the same as k, or a.end() if no such element exists.  Either the return value is a.end(), or else the return value has a key that is the same as k.  
Count  a.count(k) 
Returns the number of elements in a whose keys are the same as k.  
Equal range  a.equal_range(k) 
Returns a pair P such that [P.first, P.second) is a range containing all elements in a whose keys are the same as k. [3] If no elements have the same key as k , the return value is an empty range.  The distance between P.first and P.second is equal to a.count(k). If p is a dereferenceable iterator in a, then either a lies in the range [P.first, P.second), or else *a has a key that is not the same as k.  
Bucket count  a.bucket_count() 
Returns the number of buckets in a.  
Resize  a.resize(n) 
Increases the bucket count of a.  The bucket count of a will be at least n. All iterators pointing to element in a will remain valid. [3] 
Complexity guarantees
The default constructor, constructor with bucket count, constructor with hash function, and constructor with key equal, are all amortized constant time.
Hash Function and Key Equal are amortized constant time.
Average complexity for Erase Key is O(count(k)). Worst case is linear in the size of the container.
Erase Element is amortized constant time.
Average complexity for Erase Range is O(N), where N is the length of the range being erased. Worse case is linear in the size of the container.
Average complexity for Find is constant time. Worst case is linear in the size of the container.
Average complexity for Equal Range is O(count(k)). Worst case is linear in the size of the container.
Average complexity for Count is O(count(k)). Worst case is linear in the size of the container.
Bucket Count is amortized constant time.
Resize is linear in the size of the container.
Models
• hash_set
• hash_map
• hash_multiset
• hash_multimap
Notes
[1] There is an extensive literature dealing with hash tables. See, for example, section 6.4 of Knuth. (D. E. Knuth, The Art of Computer Programming. Volume 3: Sorting and Searching. AddisonWesley, 1975.)
[2] If the hash function is poor (that is, if many different keys hash to the same value) then this will hurt performance. The worst case is where every key hashes to the same value; in this case, runtime complexity of most Hashed Associative Container operations will be linear in the size of the container.
[3] Resizing does not invalidate iterators; however, it does not necessarily preserve the ordering relation between iterators. That is, if i and j are iterators that point into a Hashed Associative Container such that i comes immediately before j, then there is no guarantee that i will still come immediately before j after the container is resized. The only guarantee about about the ordering of elements is the contiguous storage invariant: elements with the same key are always adjacent to each other.
See also
Associative Container, Sorted Associative Container, Unique Hashed Associative Container, Multiple Hashed Associative Container
Categories: containers, functors
Component type: concept
Description
A Hash Function is a Unary Function that is used by Hashed Associative Containers: it maps its argument to a result of type size_t. A Hash Function must be deterministic and stateless. That is, the return value must depend only on the argument, and equal arguments must yield equal results.
The performance of a Hashed Associative Container depends crucially on its hash function. It is important for a Hash Function to minimize collisions, where a collision is defined as two different arguments that hash to the same value. It is also important that the distribution of hash values be uniform; that is, the probability that a Hash Function returns any particular value of type size_t should be roughly the same as the probability that it returns any other value. [1]
Refinement of
Unary Function
Associated types
Result type  The type returned when the Hash Function is called. The result type must be size_t. 
Valid expressions
None, except for those described in the Unary Function requirements.
Invariants
Deterministic function  The return value depends only on the argument, as opposed to the past history of the Hash Function object. The return value is always the same whenever the argument is the same. 
Models
• hash
Notes
[1] Note that both of these requirements make sense only in the context of some specific distribution of input values. To take a simple example, suppose that the values being hashed are the six strings "aardvark", "trombone", "history", "diamond", "forthright", and "solitude". In this case, one reasonable (and efficient) hash function would simply be the first character of each string. On the other hand, suppose that the values being hashed are "aaa0001", "aaa0010", "aaa0011", "aaa0100", "aaa0101", and "aaa0110". In that case, a different hash function would be more appropriate. This is why Hashed Associative Containers are parameterized by the hash function: no one hash function is best for all applications.
See also
Hashed Associative Container, hash
Category: containers
Component type: concept
Description
A Unique Associative Container is an Associative Container with the property that each key in the container is unique: no two elements in a Unique Associative Container have the same key.
Refinement of
Associative Container
Associated types
None, except for those defined by Associative Container.
Notation
X
A type that is a model of Unique Associative Container
a
Object of type X
t
Object of type X::value_type
k
Object of type X::key_type
p, q
Object of type X::iterator
Valid expressions
In addition to the expressions defined in Associative Container, the following expressions must be valid.
Name  Expression  Type requirements  Return type 

Range constructor  X(i, j) X a(i, j); 
i and j are Input Iterators whose value type is convertible to T [1]  
Insert element  a.insert(t) 
pair<X::iterator, bool> 

Insert range  a.insert(i, j) 
i and j are Input Iterators whose value type is convertible to X::value_type. [1]  void 
Count  a.count(k) 
size_type 
Expression semantics
Name  Expression  Precondition  Semantics  Postcondition 

Range constructor  X(i, j) X a(i, j); 
[i,j) is a valid range.  Creates an associative container that contains all of the elements in the range [i,j) that have unique keys.  size() is less than or equal to the distance from i to j. 
Insert element  a.insert(t) 
Inserts t into a if and only if a does not already contain an element whose key is the same as the key of t. The return value is a pair P. P.first is an iterator pointing to the element whose key is the same as the key of t. P.second is a bool: it is true if t was actually inserted into a, and false if t was not inserted into a, i.e. if a already contained an element with the same key as t.  P.first is a dereferenceable iterator. *(P.first) has the same key as t. The size of a is incremented by 1 if and only if P.second is true.  
Insert range  a.insert(i, j) 
[i, j) is a valid range.  Equivalent to a.insert(t) for each object t that is pointed to by an iterator in the range [i, j). Each element is inserted into a if and only if a does not already contain an element with the same key.  The size of a is incremented by at most j – i. 
Count  a.count(k) 
Returns the number of elements in a whose keys are the same as k.  The return value is either 0 or 1. 
Complexity guarantees
Average complexity for insert element is at most logarithmic.
Average complexity for insert range is at most O(N * log(size() + N)), where N is j – i.
Invariants
Uniqueness  No two elements have the same key. Equivalently, this means that for every object k of type key_type, a.count(k) returns either 0 or 1. 
Models
• set
• map
• hash_set
• hash_map
Notes
[1] At present (early 1998), not all compilers support "member templates". If your compiler supports member templates then i and j may be of any type that conforms to the Input Iterator requirements. If your compiler does not yet support member templates, however, then i and j must be of type const T* or of type X::const_iterator.
See also
Associative Container, Multiple Associative Container, Unique Sorted Associative Container, Multiple Sorted Associative Container
Multiple Associative Container
Category: containers
Component type: concept
Description
A Multiple Associative Container is an Associative Container in which there may be more than one element with the same key. That is, it is an Associative Container that does not have the restrictions of a Unique Associative Container.
Refinement of
Associative Container
Associated types
None, except for those defined by Associative Container
Notation
X
A type that is a model of Multiple Associative Container
a
Object of type X
t
Object of type X::value_type
k
Object of type X::key_type
p, q
Object of type X::iterator
Valid expressions
In addition to the expressions defined in Associative Container, the following expressions must be valid.
Name  Expression  Type requirements  Return type 

Range constructor  X(i, j) X a(i, j); 
i and j are Input Iterators whose value type is convertible to T [1]  
Insert element  a.insert(t) 
X::iterator 

Insert range  a.insert(i, j) 
i and j are Input Iterators whose value type is convertible to X::value_type.  void 
Expression semantics
Name  Expression  Precondition  Semantics  Postcondition 

Range constructor  X(i, j) X a(i, j); 
[i,j) is a valid range.  Creates an associative container that contains all elements in the range [i,j).  size() is equal to the distance from i to j. Each element in [i, j) is present in the container. 
Insert element  a.insert(t) 
Inserts t into a.  The size of a is incremented by 1. The value of a.count(t) is incremented by a.  
Insert range  a.insert(i, j) 
[i, j) is a valid range.  Equivalent to a.insert(t) for each object t that is pointed to by an iterator in the range [i, j) . Each element is inserted into a.  The size of a is incremented by j – i. 
Complexity guarantees
Average complexity for insert element is at most logarithmic.
Average complexity for insert range is at most O(N * log(size() + N)), where N is j – i.
Models
• multiset
• multimap
• hash_multiset
• hash_multimap
Notes
[1] At present (early 1998), not all compilers support "member templates". If your compiler supports member templates then i and j may be of any type that conforms to the Input Iterator requirements. If your compiler does not yet support member templates, however, then i and j must be of type const T* or of type X::const_iterator.
See also
Associative Container, Unique Associative Container, Unique Sorted Associative Container, Multiple Sorted Associative Container
Unique Sorted Associative Container
Category: containers
Component type: concept
Description
A Unique Sorted Associative Container is a Sorted Associative Container that is also a Unique Associative Container. That is, it is a Sorted Associative Container with the property that no two elements in the container have the same key.
Refinement of
Sorted Associative Container, Unique Associative Container
Associated types
None, except for those described in the Sorted Associative Container and Unique Associative Container requirements.
Notation
X
A type that is a model of Unique Sorted Associative Container
a
Object of type X
t
Object of type X::value_type
k
Object of type X::key_type
p, q
Object of type X::iterator
c
Object of type X::key_compare
Valid expressions
In addition to the expressions defined in Sorted Associative Container and Unique Associative Container, the following expressions must be valid.
Name  Expression  Type requirements  Return type 

Range constructor  X(i, j) X a(i, j); 
i and j are Input Iterators whose value type is convertible to T [1].  
Range constructor with compare  X(i, j, c) X a(i, j, c); 
i and j are Input Iterators whose value type is convertible to T [1]. c is an object of type key_compare.  
Insert with hint  a.insert(p, t) 
iterator 

Insert range  a.insert(i, j) 
i and j are Input Iterators whose value type is convertible to X::value_type. [1]  void 
Expression semantics
Name  Expression  Precondition  Semantics  Postcondition 

Range constructor  X(i, j) X a(i, j); 
[i,j) is a valid range.  Creates an associative container that contains all of the elements in the range [i,j) that have unique keys. The comparison object used by the container is key_compare().  size() is less than or equal to the distance from i to j. 
Range constructor with compare  X(i, j, c) X a(i, j, c); 
[i,j) is a valid range.  Creates an associative container that contains all of the elements in the range [i,j) that have unique keys. The comparison object used by the container is c.  size() is less than or equal to the distance from i to j. 
Insert with hint  a.insert(p, t) 
p is a nonsingular iterator in a.  Inserts t into a if and only if a does not already contain an element whose key is equivalent to t's key. The argument p is a hint: it points to the location where the search will begin. The return value is a dereferenceable iterator that points to the element with a key that is equivalent to that of t.  a contains an element whose key is the same as that of t. The size of a is incremented by either 1 or 0. 
Insert range  a.insert(i, j) 
[i, j) is a valid range.  Equivalent to a.insert(t) for each object t that is pointed to by an iterator in the range [i, j) . Each element is inserted into a if and only if a does not already contain an element with an equivalent key.  The size of a is incremented by at most j – i. 
Complexity guarantees
The range constructor, and range constructor with compare, are in general O(N * log(N)), where N is the size of the range. However, they are linear in N if the range is already sorted by value_comp().
Insert with hint is logarithmic in general, but it is amortized constant time if t is inserted immediately before p.
Insert range is in general O(N * log(N)), where N is the size of the range. However, it is linear in N if the range is already sorted by value_comp().
Invariants
Strictly ascending order  The elements in a Unique Sorted Associative Container are always arranged in strictly ascending order by key. That is, if a is a Unique Sorted Associative Container, then is_sorted(a.begin(), a.end(), a.value_comp()) is always true . Furthermore, if i and j are dereferenceable iterators in a such that i precedes j, then a.value_comp()(*i, *j) is always true. [2] 
Models
• map
• set
Notes
[1] At present (early 1998), not all compilers support "member templates". If your compiler supports member templates then i and j may be of any type that conforms to the Input Iterator requirements. If your compiler does not yet support member templates, however, then i and j must be of type const T* or of type X::const_iterator.
[2] This is a more stringent invariant than that of Sorted Associative Container. In a Sorted Associative Container we merely know that every element is less than or equal to its successor; in a Unique Sorted Associative Container, however, we know that it must be less than its successor.
See also
Associative Container, Sorted Associative Container, Multiple Sorted Associative Container, Hashed Associative Container
Multiple Sorted Associative Container
Category: containers
Component type: concept
Description
A Multiple Sorted Associative Container is a Sorted Associative Container that is also a Multiple Associative Container. That is, it is a Sorted Associative Container
with the property that any number of elements in the container may have equivalent keys.
Refinement of
Sorted Associative Container, Multiple Associative Container
Associated types
None, except for those described in the Sorted Associative Container and Multiple Associative Container requirements.
Notation
X
A type that is a model of Multiple Sorted Associative Container
a
Object of type X
t
Object of type X::value_type
k
Object of type X::key_type
p, q
Object of type X::iterator
c
Object of type X::key_compare
Valid expressions
In addition to the expressions defined in Sorted Associative Container and Multiple Associative Container, the following expressions must be valid.
Name  Expression  Type requirements  Return type 

Range constructor  X(i, j) X a(i, j); 
i and j are Input Iterators whose value type is convertible to T [1].  X 
Range constructor with compare  X(i, j, c) X a(i, j, c); 
i and j are Input Iterators whose value type is convertible to T [1]. c is an object of type key_compare.  X 
Insert with hint  a.insert(p, t) 
iterator 

Insert range  a.insert(i, j) 
i and j are Input Iterators whose value type is convertible to X::value_type. [1]  void 
Expression semantics
Name  Expression  Precondition  Semantics  Postcondition 

Range constructor  X(i, j) X a(i, j); [i,j) is a valid range. 
Creates an associative container that contains all of the elements in the range [i,j). The comparison object used by the container is key_compare().  size() is equal to the distance from i to j.  
Range constructor with compare  X(i, j, c) X a(i, j, c); 
[i,j) is a valid range.  Creates an associative container that contains all of the elements in the range [i,j) . The comparison object used by the container is c.  size() is equal to the distance from i to j. 
Insert with hint  a.insert(p, t) 
p is a nonsingular iterator in a.  Inserts t into a. The argument p is a hint: it points to the location where the search will begin. The return value is a dereferenceable iterator that points to the element that was just inserted.  a contains an element whose key is the same as that of t. The size of a is incremented by 1. 
Insert range  a.insert(i, j) 
[i, j) is a valid range.  Equivalent to a.insert(t) for each object t that is pointed to by an iterator in the range [i, j). Each element is inserted into a.  The size of a is incremented by j – i. 
Complexity guarantees
The range constructor, and range constructor with compare, are in general O(N * log(N)), where N is the size of the range. However, they are linear in N if the range is already sorted by value_comp().
Insert with hint is logarithmic in general, but it is amortized constant time if t is inserted immediately before p.
Insert range is in general O(N * log(N)) , where N is the size of the range. However, it is linear in N if the range is already sorted by value_comp().
Models
• multimap
• multiset
Notes
[1] At present (early 1998), not all compilers support "member templates". If your compiler supports member templates then i and j may be of any type that conforms to the Input Iterator requirements. If your compiler does not yet support member templates, however, then i and j must be of type const T* or of type X::const_iterator.
See also
Associative Container, Sorted Associative Container, Unique Sorted Associative Container Hashed Associative Container
Unique Hashed Associative Container
Category: containers
Component type: concept
Description
A Unique Hashed Associative Container is a Hashed Associative Container that is also a Unique Associative Container. That is, it is a Hashed Associative Container with the property that no two elements in the container have the same key.
Refinement of
Hashed Associative Container, Unique Associative Container
Associated types
None, except for those described in the Hashed Associative Container and Unique Associative Container requirements.
Notation
X
A type that is a model of Hashed Associative Container
a
Object of type X
t
Object of type X::value_type
k
Object of type X::key_type
p, q
Object of type X::iterator
n
Object of type X::size_type
h
Object of type X::hasher
c
Object of type X::key_equal
Valid expressions
In addition to the expressions defined in Hashed Associative Container and Unique Associative Container, the following expressions must be valid.
Name  Expression  Type requirements  Return type 

Range constructor  X(i, j) X a(i, j); 
i and j are Input Iterators whose value type is convertible to T [1].  X 
Range constructor with bucket count  X(i, j, n) X a(i, j, n); 
i and j are Input Iterators whose value type is convertible to T [1].  X 
Range constructor with hash function  X(i, j, n, h) X a(i, j, n, h); 
i and j are Input Iterators whose value type is convertible to T [1].  X 
Range constructor with key equal  X(i, j, n, h, k) X a(i, j, n, h, k); 
i and j are Input Iterators whose value type is convertible to T [1].  X 
Expression semantics
Name  Expression  Precondition  Semantics  Postcondition 

Range constructor  X(i, j) X a(i, j); 
[i,j) is a valid range.  Creates an associative container that contains all of the elements in the range [i,j) that have unique keys, using hasher() as the hash function and key_equal() as the key equality function.  size() is less than or equal to the distance from i to j. The bucket count is an unspecified default value. The hash function is hasher(), and the key equality function is key_equal(). 
Range constructor with bucket count  X(i, j, n) X a(i, j, n); 
[i,j) is a valid range.  Creates an associative container that contains all of the elements in the range [i,j) that have unique keys, using at least n buckets, and using hasher() as the hash function and key_equal() as the key equality function.  size() is less than or equal to the distance from i to j. The bucket count is greater than or equal to n. The hash function is hasher(), and the key equality function is key_equal(). 
Range constructor with hash function  X(i, j, n, h) X a(i, j, n, h); 
[i,j) is a valid range.  Creates an associative container that contains all of the elements in the range [i,j) that have unique keys, using at least n buckets, and using h as the hash function and key_equal() as the key equality function.  size() is less than or equal to the distance from i to j. The bucket count is greater than or equal to n. The hash function is h, and the key equality function is key_equal(). 
Range constructor with key equal  X(i, j, n, h, k) X a(i, j, n, h, k); 
[i,j) is a valid range.  Creates an associative container that contains all of the elements in the range [i,j) that have unique keys, using at least n buckets, and using h as the hash function and k as the key equality function.  size() is less than or equal to the distance from i to j. The bucket count is greater than or equal to n. The hash function is h , and the key equality function is k. 
Complexity guarantees
The range constructor, range constructor with bucket count, range constructor with hash function, and range constructor with key equal, are all linear in j – i.
Models
• hash_set
• hash_map
Notes
[1] At present (early 1998), not all compilers support "member templates". If your compiler supports member templates then i and j may be of any type that conforms to the Input Iterator requirements. If your compiler does not yet support member templates, however, then i and j must be of type const T* or of type X::const_iterator.
See also
Associative Container, Hashed Associative Container, Multiple Hashed Associative Container Sorted Associative Container
Multiple Hashed Associative Container
Category: containers
Component type: concept
Description
A Multiple Hashed Associative Container is a Hashed Associative Container that is also a Multiple Associative Container. That is, it is a Hashed Associative Container
with the property that any number of elements in the container may have the same key
Refinement of
Hashed Associative Container, Multiple Associative Container
Associated types
None, except for those described in the Hashed Associative Container and Multiple Associative Container requirements.
Notation
X
A type that is a model of Hashed Associative Container
a
Object of type X
t
Object of type X::value_type
k
Object of type X::key_type
p, q
Object of type X::iterator
n
Object of type X::size_type
h
Object of type X::hasher
c
Object of type X::key_equal
Valid expressions
In addition to the expressions defined in Hashed Associative Container and and Multiple Associative Container, the following expressions must be valid.
Name  Expression  Type requirements  Return type 

Range constructor  X(i, j) X a(i, j); 
i and j are Input Iterators whose value type is convertible to T [1].  X 
Range constructor with bucket count  X(i, j, n) X a(i, j, n); 
i and j are Input Iterators whose value type is convertible to T [1].  X 
Range constructor with hash function  X(i, j, n, h) X a(i, j, n, h); 
i and j are Input Iterators whose value type is convertible to T [1].  X 
Range constructor with key equal  X(i, j, n, h, k) X a(i, j, n, h, k); 
i and j are Input Iterators whose value type is convertible to T [1].  X 
Expression semantics
Name  Expression  Precondition  Semantics  Postcondition 

Range constructor  X(i, j) X a(i, j); 
[i,j) is a valid range.  Creates an associative container that contains all elements in the range [i,j), using hasher() as the hash function and key_equal() as the key equality function.  size() is equal to the distance from i to j. The bucket count is an unspecified default value. The hash function is hasher(), and the key equality function is key_equal(). 
Range constructor with bucket count  X(i, j, n) X a(i, j, n); 
[i,j) is a valid range.  Creates an associative container that contains all elements in the range [i,j), using at least n buckets, and using hasher() as the hash function and key_equal() as the key equality function.  size() is equal to the distance from i to j. The bucket count is greater than or equal to n. The hash function is hasher(), and the key equality function is key_equal(). 
Range constructor with hash function  X(i, j, n, h) X a(i, j, n, h); 
[i,j) is a valid range.  Creates an associative container that contains all elements in the range [i,j), using at least n buckets, and using h as the hash function and key_equal() as the key equality function. size() is equal to the distance from i to j.  The bucket count is greater than or equal to n. The hash function is h, and the key equality function is key_equal(). 
Range constructor with key equal  X(i, j, n, h, k) X a(i, j, n, h, k); 
[i,j) is a valid range.  Creates an associative container that contains all elements in the range [i,j) , using at least n buckets, and using h as the hash function and k as the key equality function.  size() is equal to the distance from i to j. The bucket count is greater than or equal to n. The hash function is h , and the key equality function is k. 
Complexity guarantees
The range constructor, range constructor with bucket count, range constructor with hash function, and range constructor with key equal, are all linear in j – i.
Models
• hash_multiset
• hash_multimap
Notes
[1] At present (early 1998), not all compilers support "member templates". If your compiler supports member templates then i and j may be of any type that conforms to the Input Iterator requirements. If your compiler does not yet support member templates, however, then i and j must be of type const T* or of type X::const_iterator.
See also
Associative Container, Hashed Associative Container, Unique Hashed Associative Container, Sorted Associative Container
Category: containers
Component type: type
Description
A vector is a Sequence that supports random access to elements, constant time insertion and removal of elements at the end, and linear time insertion and removal of elements at the beginning or in the middle. The number of elements in a vector may vary dynamically; memory management is automatic. Vector is the simplest of the STL container classes, and in many cases the most efficient.
Example
vector<int> V;
V.insert(V.begin(), 3);
assert(V.size() == 1 && V.capacity() >= 1 && V[0] == 3);
Definition
Defined in the standard header vector, and in the nonstandard backwardcompatibility header vector.h.
Template parameters
Parameter  Description  Default 

T 
The vector's value type: the type of object that is stored in the vector.  
Alloc 
The vector 's allocator, used for all internal memory management.  alloc 
Model of
Random Access Container, Back Insertion Sequence.
Type requirements
None, except for those imposed by the requirements of Random Access Container and Back Insertion Sequence.
Public base classes
None.
Members
Member  Where defined  Description 

value_type 
Container  The type of object, T, stored in the vector. 
pointer 
Container  Pointer to T. 
reference 
Container  Reference to T 
const_reference 
Container  Const reference to T 
size_type 
Container  An unsigned integral type. 
difference_type 
Container  A signed integral type. 
iterator 
Container  Iterator used to iterate through a vector. 
const_iterator 
Container  Const iterator used to iterate through a vector. 
reverse_iterator 
Reversible Container  Iterator used to iterate backwards through a vector. 
const_reverse_iterator 
Reversible Container  Const iterator used to iterate backwards through a vector. 
iterator begin() 
Container  Returns an iterator pointing to the beginning of the vector. 
iterator end() 
Container  Returns an iterator pointing to the end of the vector. 
const_iterator begin() const 
Container  Returns a const_iterator pointing to the beginning of the vector. 
const_iterator end() const 
Container  Returns a const_iterator pointing to the end of the vector. 
reverse_iterator rbegin() 
Reversible Container  Returns a reverse_iterator pointing to the beginning of the reversed vector. 
reverse_iterator rend() 
Reversible Container  Returns a reverse_iterator pointing to the end of the reversed vector. 
const_reverse_iterator rbegin() const 
Reversible Container  Returns a const_reverse_iterator pointing to the beginning of the reversed vector. 
const_reverse_iterator rend() const 
Reversible Container  Returns a const_reverse_iterator pointing to the end of the reversed vector. 
size_type size() const 
Container  Returns the size of the vector. 
size_type max_size() const 
Container  Returns the largest possible size of the vector. 
size_type capacity() const 
vector 
See below. 
bool empty() const 
Container  true if the vector 's size is 0. 
reference operator[](size_type n) 
Random Access Container  Returns the n'th element. 
const_reference operator[](size_type n) const 
Random Access Container  Returns the n'th element. 
vector() 
Container  Creates an empty vector. 
vector(size_type n) 
Sequence  Creates a vector with n elements. 
vector(size_type n, const T& t) 
Sequence  Creates a vector with n copies of t. 
vector(const vector&) 
Container  The copy constructor. 
template <class InputIterator> vector(InputIterator, InputIterator) [1] 
Sequence  Creates a vector with a copy of a range. 
~vector() 
Container  The destructor. 
vector& operator=(const vector&) 
Container  The assignment operator 
void reserve(size_t) 
vector 
See below. 
vector reference front() 
Sequence  Returns the first element. 
const_reference front() const 
Sequence  Returns the first element. 
reference back() 
Back Insertion Sequence  Returns the last element. 
const_reference back() const 
Back Insertion Sequence  Returns the last element. 
void push_back(const T&) 
Back Insertion Sequence  Inserts a new element at the end. 
void pop_back() 
Back Insertion Sequence  Removes the last element. 
void swap(vector&) 
Container  Swaps the contents of two vectors. 
iterator insert(iterator pos, const T& x) 
Sequence  Inserts x before pos. 
template <class InputIterator> void insert(iterator pos, InputIterator f, InputIterator l) [1] 
Sequence  Inserts the range [first, last) before pos. 
void insert(iterator pos, size_type n, const T& x) 
Sequence  Inserts n copies of x before pos. 
iterator erase(iterator pos) 
Sequence  Erases the element at position pos. 
iterator erase(iterator first, iterator last) 
Sequence  Erases the range [first, last) 
void clear() 
Sequence  Erases all of the elements. 
void resize(n, t = T()) 
Sequence  Inserts or erases elements at the end such that the size becomes n. 
bool operator==(const vector&, const vector&) 
Forward Container  Tests two vectors for equality. This is a global function, not a member function. 
bool operator<(const vector&, const vector&) 
Forward Container  Lexicographical comparison. This is a global function, not a member function. 
New members
These members are not defined in the Random Access Container and Back Insertion Sequence requirements, but are specific to vector.
Member  Description 

size_type capacity() const 
Number of elements for which memory has been allocated. capacity() is always greater than or equal to size(). [2] [3] 
void reserve(size_type n) 
If n is less than or equal to capacity(), this call has no effect. Otherwise, it is a request for allocation of additional memory. If the request is successful, then capacity() is greater than or equal to n; otherwise, capacity() is unchanged. In either case, size() is unchanged. [2] [4] 
Notes
[1] This member function relies on member template functions, which at present (early 1998) are not supported by all compilers. If your compiler supports member templates, you can call this function with any type of input iterator. If your compiler does not yet support member templates, though, then the arguments must be of type const value_type*.
[2] Memory will be reallocated automatically if more than capacity() – size() elements are inserted into the vector. Reallocation does not change size(), nor does it change the values of any elements of the vector. It does, however, increase capacity(), and it invalidates [5] any iterators that point into the vector.
[3] When it is necessary to increase capacity(), vector usually increases it by a factor of two. It is crucial that the amount of growth is proportional to the current capacity() , rather than a fixed constant: in the former case inserting a series of elements into a vector is a linear time operation, and in the latter case it is quadratic.
[4] Reserve() causes a reallocation manually. The main reason for using reserve() is efficiency: if you know the capacity to which your vector must eventually grow, then it is usually more efficient to allocate that memory all at once rather than relying on the automatic reallocation scheme. The other reason for using reserve() is so that you can control the invalidation of iterators. [5]
[5] A vector's iterators are invalidated when its memory is reallocated. Additionally, inserting or deleting an element in the middle of a vector invalidates all iterators that point to elements following the insertion or deletion point. It follows that you can prevent a vector's iterators from being invalidated if you use reserve() to preallocate as much memory as the vector will ever use, and if all insertions and deletions are at the vector's end.
See also
deque, list, slist
Category: containers
Component type: type
Description
A deque [1] is very much like a vector: like vector, it is a sequence that supports random access to elements, constant time insertion and removal of elements at the end of the sequence, and linear time insertion and removal of elements in the middle.
The main way in which deque differs from vector is that deque also supports constant time insertion and removal of elements at the beginning of the sequence [2]. Additionally, deque does not have any member functions analogous to vector 's capacity() and reserve(), and does not provide any of the guarantees on iterator validity that are associated with those member functions. [3]
Example
deque<int> Q;
Q.push_back(3);
Q.push_front(1);
Q.insert(Q.begin() + 1, 2);
Q[2] = 0;
copy(Q.begin(), Q.end(), ostream_iterator<int>(cout, " "));
// The values that are printed are 1 2 0
Definition
Defined in the standard header deque, and in the nonstandard backwardcompatibility header deque.h.
Template parameters
Parameter  Description  Default 

T 
The deque's value type: the type of object that is stored in the deque.  
Alloc 
The deque 's allocator, used for all internal memory management.  alloc 
Model of
Random access container, Front insertion sequence, Back insertion sequence.
Type requirements
None, except for those imposed by the requirements of Random access container, Front insertion sequence, and Back insertion sequence.
Public base classes
None.
Members
Member  Where defined  Description 

value_type 
Container  The type of object, T, stored in the deque. 
pointer 
Container  Pointer to T. 
reference 
Container  Reference to T 
const_reference 
Container  Const reference to T 
size_type 
Container  An unsigned integral type. 
difference_type 
Container  A signed integral type. 
iterator 
Container  Iterator used to iterate through a deque. 
const_iterator 
Container  Const iterator used to iterate through a deque. 
reverse_iterator 
Reversible Container  Iterator used to iterate backwards through a deque. 
const_reverse_iterator 
Reversible Container  Const iterator used to iterate backwards through a deque. 
iterator begin() 
Container  Returns an iterator pointing to the beginning of the deque. 
iterator end() 
Container  Returns an iterator pointing to the end of the deque. 
const_iterator begin() const 
Container  Returns a const_iterator pointing to the beginning of the deque. 
const_iterator end() const 
Container  Returns a const_iterator pointing to the end of the deque. 
reverse_iterator rbegin() 
Reversible Container  Returns a reverse_iterator pointing to the beginning of the reversed deque. 
reverse_iterator rend() 
Reversible Container  Returns a reverse_iterator pointing to the end of the reversed deque. 
const_reverse_iterator rbegin() const 
Reversible Container  Returns a const_reverse_iterator pointing to the beginning of the reversed deque. 
const_reverse_iterator rend() const 
Reversible Container  Returns a const_reverse_iterator pointing to the end of the reversed deque. 
size_type size() const 
Container  Returns the size of the deque. 
size_type max_size() const 
Container  Returns the largest possible size of the deque. 
bool empty() const 
Container  true if the deque 's size is 0. 
reference operator[](size_type n) 
Random Access Container  Returns the n 'th element. 
const_reference operator[](size_type n) const 
Random Access Container  Returns the n'th element. 
deque() 
Container  Creates an empty deque. 
deque(size_type n) 
Sequence  Creates a deque with n elements. 
deque(size_type n, const T& t) 
Sequence  Creates a deque with n copies of t. 
deque(const deque&) 
Container  The copy constructor 
template <class InputIterator> deque(InputIterator f, InputIterator l) [4] 
Sequence  Creates a deque with a copy of a range. 
~deque() 
Container  The destructor. 
deque& operator=(const deque&) 
Container  The assignment operator 
reference front() 
Front Insertion Sequence  Returns the first element. 
const_reference front() const 
Front Insertion Sequence  Returns the first element. 
reference back() 
Back Insertion Sequence  Returns the last element. 
const_reference back() const 
Back Insertion Sequence  Returns the last element. 
void push_front(const T&) 
Front Insertion Sequence  Inserts a new element at the beginning. 
void push_back(const T&) 
Back Insertion Sequence  Inserts a new element at the end. 
void pop_front() 
Front Insertion Sequence  Removes the first element. 
void pop_back() 
Back Insertion Sequence  Removes the last element. 
void swap(deque&) 
Container  Swaps the contents of two deques. 
iterator insert(iterator pos, const T& x) 
Sequence  Inserts x before pos. 
template <class InputIterator> void insert(iterator pos, InputIterator f, InputIterator l) [4] 
Sequence  Inserts the range [f, l) before pos. 
void insert(iterator pos, size_type n, const T& x) 
Sequence  Inserts n copies of x before pos. 
iterator erase(iterator pos) 
Sequence  Erases the element at position pos. 
iterator erase(iterator first, iterator last) 
Sequence  Erases the range [first, last) 
void clear() 
Sequence  Erases all of the elements. 
void resize(n, t = T()) 
Sequence  Inserts or erases elements at the end such that the size becomes n. 
bool operator==(const deque&, const deque&) 
Forward Container  Tests two deques for equality. This is a global function, not a member function. 
bool operator<(const deque&, const deque&) 
Forward Container  Lexicographical comparison. This is a global function, not a member function. 
New members
All of deque's members are defined in the Random access container, Front insertion sequence, and Back insertion sequence requirements. Deque does not introduce any new members.
Notes
[1] The name deque is pronounced "deck", and stands for "doubleended queue." Knuth (section 2.6) reports that the name was coined by E. J. Schweppe. See section 2.2.1 of Knuth for more information about deques. (D. E. Knuth, The Art of Computer Programming. Volume 1: Fundamental Algorithms, second edition. AddisonWesley, 1973.)
[2] Inserting an element at the beginning or end of a deque takes amortized constant time. Inserting an element in the middle is linear in n, where n is the smaller of the number of elements from the insertion point to the beginning, and the number of elements from the insertion point to the end.
[3] The semantics of iterator invalidation for deque is as follows. Insert (including push_front and push_back) invalidates all iterators that refer to a deque. Erase in the middle of a deque invalidates all iterators that refer to the deque. Erase at the beginning or end of a deque (including pop_front and pop_back) invalidates an iterator only if it points to the erased element.
[4] This member function relies on member template functions, which at present (early 1998) are not supported by all compilers. If your compiler supports member templates, you can call this function with any type of input iterator. If your compiler does not yet support member templates, though, then the arguments must either be of type const value_type* or of type deque::const_iterator.
See also
vector, list, slist
Category: containers
Component type: type
Description
A list is a doubly linked list. That is, it is a Sequence that supports both forward and backward traversal, and (amortized) constant time insertion and removal of elements at the beginning or the end, or in the middle. Lists have the important property that insertion and splicing do not invalidate iterators to list elements, and that even removal invalidates only the iterators that point to the elements that are removed. The ordering of iterators may be changed (that is, list<T>::iterator might have a different predecessor or successor after a list operation than it did before), but the iterators themselves will not be invalidated or made to point to different elements unless that invalidation or mutation is explicit. [1]
Note that singly linked lists, which only support forward traversal, are also sometimes useful. If you do not need backward traversal, then slist may be more efficient than list. Definition Defined in the standard header list, and in the nonstandard backwardcompatibility header list.h.
Example
list<int> L;
L.push_back(0);
L.push_front(1);
L.insert(++L.begin(), 2);
copy(L.begin(), L.end(), ostream_iterator<int>(cout, " "));
// The values that are printed are 1 2 0
Template parameters
Parameter  Description  Default 

T 
The list 's value type: the type of object that is stored in the list.  
Alloc 
The list 's allocator, used for all internal memory management.  alloc 
Model of
Reversible Container, Front Insertion Sequence, Back Insertion Sequence.
Type requirements
None, except for those imposed by the requirements of Reversible Container, Front Insertion Sequence, and Back Insertion Sequence.
Public base classes
None.
Members
Member  Where defined  Description 

value_type 
Container  The type of object, T, stored in the list. 
pointer 
Container  Pointer to T. 
reference 
Container  Reference to T 
const_reference 
Container  Const reference to T 
size_type 
Container  An unsigned integral type. 
difference_type 
Container  A signed integral type. 
iterator 
Container  Iterator used to iterate through a list. 
const_iterator 
Container  Const iterator used to iterate through a list. 
reverse_iterator 
Reversible Container  Iterator used to iterate backwards through a list. 
const_reverse_iterator 
Reversible Container  Const iterator used to iterate backwards through a list. 
iterator begin() 
Container  Returns an iterator pointing to the beginning of the list. 
iterator end() 
Container  Returns an iterator pointing to the end of the list. 
const_iterator begin() const 
Container  Returns a const_iterator pointing to the beginning of the list. 
const_iterator end() const 
Container  Returns a const_iterator pointing to the end of the list. 
reverse_iterator rbegin() 
Reversible  Container Returns a reverse_iterator pointing to the beginning of the reversed list. 
reverse_iterator rend() 
Reversible Container  Returns a reverse_iterator pointing to the end of the reversed list. 
const_reverse_iterator rbegin() const 
Reversible Container  Returns a const_reverse_iterator pointing to the beginning of the reversed list. 
const_reverse_iterator rend() const 
Reversible Container  Returns a const_reverse_iterator pointing to the end of the reversed list. 
size_type size() const 
Container  Returns the size of the list. Note: you should not assume that this function is constant time. It is permitted to be O(N ), where N is the number of elements in the list . If you wish to test whether a list is empty, you should write L.empty() rather than L.size() == 0. 
size_type max_size() const 
Container  Returns the largest possible size of the list. 
bool empty() const 
Container  true if the list 's size is 0. 
list() 
Container  Creates an empty list. 
list(size_type n) 
Sequence  Creates a list with n elements, each of which is a copy of T(). 
list(size_type n, const T& t) 
Sequence  Creates a list with n copies of t. 
list(const list&) 
Container  The copy constructor. 
template <class InputIterator> list(InputIterator f, InputIterator l) [2] 
Sequence  Creates a list with a copy of a range. 
~list() 
Container  The destructor. 
list& operator=(const list&) 
Container  The assignment operator 
reference front() 
Front Insertion Sequence  Returns the first element. 
const_reference front() const 
Front Insertion Sequence  Returns the first element. 
reference back() 
Sequence  Returns the last element. 
const_reference back() const 
Back Insertion Sequence  Returns the last element. 
void push_front(const T&) 
Front Insertion Sequence  Inserts a new element at the beginning. 
void push_back(const T&) 
Back Insertion Sequence  Inserts a new element at the end. 
void pop_front() 
Front Insertion Sequence  Removes the first element. 
void pop_back() 
Back Insertion Sequence  Removes the last element. 
void swap(list&) 
Container  Swaps the contents of two lists. 
iterator insert(iterator pos, const T& x) 
Sequence  Inserts x before pos. 
template <class InputIterator> void insert(iterator pos, InputIterator f, InputIterator l) [2] 
Sequence  Inserts the range [f, l) before pos. 
void insert(iterator pos, size_type n, const T& x) 
Sequence  Inserts n copies of x before pos. 
iterator erase(iterator pos) 
Sequence  Erases the element at position pos. 
iterator erase(iterator first, iterator last) 
Sequence  Erases the range [first, last) 
void clear() 
Sequence  Erases all of the elements. 
void resize(n, t = T()) 
Sequence  Inserts or erases elements at the end such that the size becomes n. 
void splice(iterator pos, list& L) 
list 
See below. 
void splice(iterator pos, list& L, iterator i) 
list 
See below. 
void splice(iterator pos, list& L, iterator f, iterator l) 
list 
See below. 
void remove(const T& value) 
list 
See below. 
void unique() 
list 
See below. 
void merge(list& L) 
list 
See below. 
void sort() 
list 
See below. 
bool operator==(const list&, const list&) 
Forward Container  Tests two lists for equality. This is a global function, not a member function. 
bool operator<(const list&, const list&) 
Forward Container  Lexicographical comparison. This is a global function, not a member function. 
New members
These members are not defined in the Reversible Container, Front Insertion Sequence, and Back Insertion Sequence requirements, but are specific to list.
Function  Description 

void splice(iterator position, list<T, Alloc>& x); 
position must be a valid iterator in *this, and x must be a list that is distinct from *this. (That is, it is required that &x != this.) All of the elements of x are inserted before position and removed from x. All iterators remain valid, including iterators that point to elements of x. [3] This function is constant time. 
void splice(iterator position, list<T, Alloc>& x, iterator i); 
position must be a valid iterator in *this, and i must be a dereferenceable iterator in x. Splice moves the element pointed to by i from x to *this, inserting it before position. All iterators remain valid, including iterators that point to elements of x. [3] If position == i or position == ++i, this function is a null operation. This function is constant time. 
void splice(iterator position, list<T, Alloc>& x, iterator f, iterator l); 
position must be a valid iterator in *this, and [first, last) must be a valid range in x. position may not be an iterator in the range [first, last). Splice moves the elements in [first, last) from x to *this , inserting them before position. All iterators remain valid, including iterators that point to elements of x. [3] This function is constant time. 
void remove(const T& val); 
Removes all elements that compare equal to val. The relative order of elements that are not removed is unchanged, and iterators to elements that are not removed remain valid. This function is linear time: it performs exactly size() comparisons for equality. 
template<class Predicate> void remove_if( Predicate p); [4] 
Removes all elements *i such that p(*i) is true. The relative order of elements that are not removed is unchanged, and iterators to elements that are not removed remain valid. This function is linear time: it performs exactly size() applications of p. 
void unique(); 
Removes all but the first element in every consecutive group of equal elements. The relative order of elements that are not removed is unchanged, and iterators to elements that are not removed remain valid. This function is linear time: it performs exactly size() – 1 comparisons for equality. 
template<class BinaryPredicate> void unique( BinaryPredicate p); [4] 
Removes all but the first element in every consecutive group of equivalent elements, where two elements *i and *j are considered equivalent if p(*i, *j) is true. The relative order of elements that are not removed is unchanged, and iterators to elements that are not removed remain valid. This function is linear time: it performs exactly size() – 1 comparisons for equality. 
void merge(list<T, Alloc>& x); 
Both *this and x must be sorted according to operator<, and they must be distinct. (That is, it is required that &x != this.) This function removes all of x's elements and inserts them in order into *this. The merge is stable; that is, if an element from *this is equivalent to one from x, then the element from *this will precede the one from x. All iterators to elements in *this and x remain valid. This function is linear time: it performs at most size() + x.size() – 1 comparisons. 
template<class BinaryPredicate> void merge(list<T, Alloc>& x, BinaryPredicate Comp); [4] 
Comp must be a comparison function that induces a strict weak ordering (as defined in the LessThan Comparable requirements) on objects of type T, and both *this and x must be sorted according to that ordering. The lists x and *this must be distinct. (That is, it is required that &x != this.) This function removes all of x's elements and inserts them in order into *this. The merge is stable; that is, if an element from *this is equivalent to one from x, then the element from *this will precede the one from x. All iterators to elements in *this and x remain valid. This function is linear time: it performs at most size() + x.size() – 1 applications of Comp. 
void reverse(); 
Reverses the order of elements in the list. All iterators remain valid and continue to point to the same elements. [5] This function is linear time. 
void sort(); 
Sorts *this according to operator< . The sort is stable, that is, the relative order of equivalent elements is preserved. All iterators remain valid and continue to point to the same elements. [6] The number of comparisons is approximately N log N , where N is the list 's size. 
template<class BinaryPredicate> void sort(BinaryPredicate comp); [4] 
Comp must be a comparison function that induces a strict weak ordering (as defined in the LessThan Comparable requirements on objects of type T. This function sorts the list *this according to Comp. The sort is stable, that is, the relative order of equivalent elements is preserved. All iterators remain valid and continue to point to the same elements. [6] The number of comparisons is approximately N log N, where N is the list's size. 
Notes
[1] A comparison with vector is instructive. Suppose that i is a valid vector<T>::iterator. If an element is inserted or removed in a position that precedes i, then this operation will either result in i pointing to a different element than it did before, or else it will invalidate i entirely. (A vector<T>::iterator will be invalidated, for example, if an insertion requires a reallocation.) However, suppose that i and j are both iterators into a vector , and there exists some integer n such that i == j + n. In that case, even if elements are inserted into the vector and i and j point to different elements, the relation between the two iterators will still hold. A list is exactly the opposite: iterators will not be invalidated, and will not be made to point to different elements, but, for list iterators, the predecessor/successor relationship is not invariant.
[2] This member function relies on member template functions, which at present (early 1998) are not supported by all compilers. If your compiler supports member templates, you can call this function with any type of input iterator. If your compiler does not yet support member templates, though, then the arguments must either be of type const value_type* or of type list::const_iterator.
[3] A similar property holds for all versions of insert() and erase(). List<T, Alloc>::insert() never invalidates any iterators, and list<T, Alloc>::erase() only invalidates iterators pointing to the elements that are actually being erased.
[4] This member function relies on member template functions, which at present (early 1998) are not supported by all compilers. You can only use this member function if your compiler supports member templates.
[5] If L is a list, note that L.reverse() and reverse(L.begin(), L.end()) are both correct ways of reversing the list. They differ in that L.reverse() will preserve the value that each iterator into L points to but will not preserve the iterators' predecessor/successor relationships, while reverse(L.begin(), L.end()) will not preserve the value that each iterator points to but will preserve the iterators' predecessor/successor relationships. Note also that the algorithm reverse (L.begin(), L.end()) will use T 's assignment operator, while the member function L.reverse() will not.
[6] The sort algorithm works only for random access iterators . In principle, however, it would be possible to write a sort algorithm that also accepted bidirectional iterators. Even if there were such a version of sort, it would still be useful for list to have a sort member function. That is, sort is provided as a member function not only for the sake of efficiency, but also because of the property that it preserves the values that list iterators point to.
See also
Bidirectional Iterator, Reversible Container, Sequence, slist, vector.
Category: containers
Component type: type
Description
An slist is a singly linked list: a list where each element is linked to the next element, but not to the previous element. [1] That is, it is a Sequence that supports forward but not backward traversal, and (amortized) constant time insertion and removal of elements. Slists, like lists, have the important property that insertion and splicing do not invalidate iterators to list elements, and that even removal invalidates only the iterators that point to the elements that are removed. The ordering of iterators may be changed (that is, slist<T>::iterator might have a different predecessor or successor after a list operation than it did before), but the iterators themselves will not be invalidated or made to point to different elements unless that invalidation or mutation is explicit. [2]
The main difference between slist and list is that list's iterators are bidirectional iterators, while slist's iterators are forward iterators. This means that slist is less versatile than list; frequently, however, bidirectional iterators are unnecessary. You should usually use slist unless you actually need the extra functionality of list, because singly linked lists are smaller and faster than double linked lists.
Important performance note: like every other Sequence, slist defines the member functions insert and erase. Using these member functions carelessly, however, can result in disastrously slow programs. The problem is that insert 's first argument is an iterator pos , and that it inserts the new element(s) beforepos . This means that insert must find the iterator just before pos; this is a constanttime operation for list, since list has bidirectional iterators, but for slist it must find that iterator by traversing the list from the beginning up to pos . In other words: insert and erase are slow operations anywhere but near the beginning of the slist.
Slist provides the member functions insert_after and erase_after, which are constant time operations: you should always use insert_after and erase_after whenever possible. If you find that insert_after and erase_after aren't adequate for your needs, and that you often need to use insert and erase in the middle of the list, then you should probably use list instead of slist.
Definition
Defined in the header slist, and in the backwardcompatibility header slist.h. The slist class, and the slist header, are an SGI extension; they are not part of the C++ standard.
Example
int main() {
slist<int> L;
L.push_front(0);
L.push_front(1);
L.insert_after(L.begin(), 2);
copy(L.begin(), L.end(), // The output is 1 2 0
ostream_iterator<int>(cout, " "));
cout << endl;
slist<int>::iterator back = L.previous(L.end());
back = L.insert_after(back, 3);
back = L.insert_after(back, 4);
back = L.insert_after(back, 5);
copy(L.begin(), L.end(), // The output is 1 2 0 3 4 5
ostream_iterator<int>(cout, " "));
cout << endl;
}
Template parameters
Parameter  Description  Default 

T 
The slist 's value type: the type of object that is stored in the list.  
Alloc 
The slist 's allocator, used for all internal memory management.  alloc 
Model of
Front Insertion Sequence
Type requirements
None, except for those imposed by the requirements of Front Insertion Sequence.
Public base classes
None.
Members
Member  Where defined  Description 

value_type 
Container  The type of object, T, stored in the slist. 
pointer 
Container  Pointer to T. 
reference 
Container  Reference to T 
const_reference 
Container  Const reference to T 
size_type 
Container  An unsigned integral type. 
difference_type 
Container  A signed integral type. 
iterator 
Container  Iterator used to iterate through an slist. 
const_iterator 
Container  Const iterator used to iterate through an slist. 
iterator begin() 
Container  Returns an iterator pointing to the beginning of the slist. 
iterator end() 
Container  Returns an iterator pointing to the end of the slist. 
const_iterator begin() const 
Container  Returns a const_iterator pointing to the beginning of the slist. 
const_iterator end() const 
Container  Returns a const_iterator pointing to the end of the slist. 
size_type size() const 
Container  Returns the size of the slist. Note: you should not assume that this function is constant time. It is permitted to be O(N), where N is the number of elements in the slist. If you wish to test whether an slist is empty, you should write L.empty() rather than L.size() == 0. 
size_type max_size() const 
Container  Returns the largest possible size of the slist. 
bool empty() const 
Container  true if the slist's size is 0. 
slist() 
Container  Creates an empty slist. 
slist(size_type n) 
Sequence  Creates an slist with n elements, each of which is a copy of T(). 
slist(size_type n, const T& t) 
Sequence  Creates an slist with n copies of t. 
slist(const slist&) 
Container  The copy constructor. 
template <class InputIterator> slist(InputIterator f, InputIterator l) [3] 
Sequence  Creates an slist with a copy of a range. 
~slist() 
Container  The destructor. 
slist& operator=(const slist&) 
Container  The assignment operator 
void swap(slist&) 
Container  Swaps the contents of two slists. 
reference front() 
Front Insertion Sequence  Returns the first element. 
const_reference front() const 
Front Insertion Sequence  Returns the first element. 
void push_front(const T&) 
Front Insertion Sequence  Inserts a new element at the beginning. 
void pop_front() 
Front Insertion Sequence  Removes the first element. 
iterator previous(iterator pos) 
slist 
See below 
const_iterator previous(const_iterator pos) 
slist 
See below 
iterator insert(iterator pos, const T& x) 
Sequence  Inserts x before pos. 
template<class InputIterator> void insert(iterator pos, InputIterator f, InputIterator l) [3] 
Sequence  Inserts the range [first, last) before pos. 
void insert(iterator pos, size_type n, const value_type& x) 
Sequence  Inserts n copies of x before pos. 
iterator erase(iterator pos) 
Sequence  Erases the element at position pos. 
iterator erase(iterator first, iterator last) 
Sequence  Erases the range [first, last) 
void clear() 
Sequence  Erases all of the elements. 
void resize(n, t = T()) 
Sequence  Inserts or erases elements at the end such that the size becomes n. 
iterator insert_after(iterator pos) 
slist 
See below. 
iterator insert_after(iterator pos, const value_type& x) 
slist 
See below. 
template<class InputIterator> void insert_after(iterator pos, InputIterator f, InputIterator l) 
slist 
See below. 
void insert_after(iterator pos, size_type n, const value_type& x) 
slist 
See below. 
iterator erase_after(iterator pos) 
slist 
See below. 
iterator erase_after(iterator before_first, iterator last) 
slist 
See below. 
void splice(iterator position, slist& L) 
slist 
See below. 
void splice(iterator position, slist& L, iterator i) 
slist 
See below. 
void splice(iterator position, slist& L, iterator f, iterator l) 
slist 
See below. 
void splice_after(iterator pos, iterator prev) 
slist 
See below. 
void splice_after(iterator pos, iterator before_first, iterator before_last) 
slist 
See below. 
void remove(const T& value) 
slist 
See below. 
void unique() 
slist 
See below. 
void merge(slist& L) 
slist 
See below. 
void sort() 
slist 
See below. 
bool operator==(const slist&, const slist&) 
Forward Container  Tests two slists for equality. This is a global function, not a member function. 
bool operator<(const slist&, const slist&) 
Forward Container  Lexicographical comparison. This is a global function, not a member function. 
New members
These members are not defined in the Front Insertion Sequence requirements, but are specific to slist:
Function  Description 

iterator previous(iterator pos) 
pos must be a valid iterator in *this. The return value is an iterator prev such that ++prev == pos. Complexity: linear in the number of iterators in the range [begin(), pos). 
const_iterator previous(const_iterator pos) 
pos must be a valid iterator in *this. The return value is an iterator prev such that ++prev == pos. Complexity: linear in the number of iterators in the range [begin(), pos). 
iterator insert_after(iterator pos) 
pos must be a dereferenceable iterator in *this. (That is, pos may not be end().) Inserts a copy of T() immediately followingpos. The return value is an iterator that points to the new element. Complexity: constant time. 
iterator insert_after(iterator pos, const value_type& x) 
pos must be a dereferenceable iterator in *this. (That is, pos may not be end().) Inserts a copy of x immediately followingpos. The return value is an iterator that points to the new element. Complexity: constant time. 
template<class InputIterator> void insert_after(iterator pos, InputIterator f, InputIterator l) 
Inserts elements from the range [f, l) immediately followingpos. Complexity: linear in last – first. 
void insert_after(iterator pos, size_type n, const value_type& x) 
Inserts n copies of x immediately followingpos. Complexity: linear in n. 
iterator erase_after(iterator pos) 
Erases the element pointed to by the iterator followingpos. Complexity: constant time. 
iterator erase_after(iterator before_first, iterator last) 
Erases all elements in the range [before_first + 1, last). Complexity: linear in last – (before_first + 1). 
void splice(iterator position, slist<T, Alloc>& x); 
position must be a valid iterator in *this, and x must be an slist that is distinct from *this. (That is, it is required that &x != this.) All of the elements of x are inserted before position and removed from x. All iterators remain valid, including iterators that point to elements of x. [4] Complexity: proportional to c1 (position – begin()) + c2(x.size()), where c1 and c2 are unknown constants. 
void splice(iterator position, slist<T, Alloc>& x, iterator i); 
position must be a valid iterator in *this, and i must be a dereferenceable iterator in x. Splice moves the element pointed to by i from x to *this, inserting it before position . All iterators remain valid, including iterators that point to elements of x. [4] If position == i or position == ++i, this function is a null operation. Complexity: proportional to c1(position – begin()) + c2(i – x.begin()), where c1 and c2 are unknown constants. 
void splice(iterator position, slist<T, Alloc>& x, iterator f, iterator l); 
position must be a valid iterator in *this , and [first, last) must be a valid range in x. position may not be an iterator in the range [first, last). Splice moves the elements in [first, last) from x to *this, inserting them before position. All iterators remain valid, including iterators that point to elements of x. [4] Complexity: proportional to c1(position – begin()) + c2(f – x.begin()) + c3(l – f) , where c1, c2, and c3 are unknown constants. 
void remove(const T& val); 
Removes all elements that compare equal to val. The relative order of elements that are not removed is unchanged, and iterators to elements that are not removed remain valid. This function is linear time: it performs exactly size() comparisons for equality. 
void splice_after(iterator pos, iterator prev) 
pos must be a dereferenceable iterator in *this, and prev must be a dereferenceable iterator either in *this or in some other slist. (Note: "dereferenceable iterator" implies that neither pos nor prev may be an offtheend iterator.) Moves the element followingprev to *this, inserting it immediately afterpos. Complexity: constant time. 
void splice_after(iterator pos, iterator before_first, iterator before_last) 
pos must be a dereferenceable iterator in *this, and before_first and before_last must be dereferenceable iterators either in *this or in some other slist. (Note: "dereferenceable iterator" implies that none of these iterators may be offtheend iterators.) Moves the elements in the range [before_first + 1, before_last + 1) to *this, inserting them immediately afterpos. Complexity: constant time. 
template<class Predicate> void remove_if(Predicate p); [5] 
Removes all elements *i such that p(*i) is true. The relative order of elements that are not removed is unchanged, and iterators to elements that are not removed remain valid. This function is linear time: it performs exactly size() applications of p. 
void unique(); 
Removes all but the first element in every consecutive group of equal elements. The relative order of elements that are not removed is unchanged, and iterators to elements that are not removed remain valid. This function is linear time: it performs exactly size() – 1 comparisons for equality. 
template<class BinaryPredicate> void unique(BinaryPredicate p); [5] 
Removes all but the first element in every consecutive group of equivalent elements, where two elements *i and *j are considered equivalent if p(*i, *j) is true. The relative order of elements that are not removed is unchanged, and iterators to elements that are not removed remain valid. This function is linear time: it performs exactly size() – 1 comparisons for equality. 
void merge(slist<T, Alloc>& x); 
Both *this and x must be sorted according to operator<, and they must be distinct. (That is, it is required that &x != this.) This function removes all of x 's elements and inserts them in order into *this. The merge is stable; that is, if an element from *this is equivalent to one from x, then the element from *this will precede the one from x. All iterators to elements in *this and x remain valid. This function is linear time: it performs at most size() + x.size() – 1 comparisons. 
template<class BinaryPredicate> void merge(slist<T, Alloc>& x, BinaryPredicate Comp); [5] 
Comp must be a comparison function that induces a strict weak ordering (as defined in the LessThan Comparable requirements) on objects of type T, and both *this and x must be sorted according to that ordering. The slists x and *this must be distinct. (That is, it is required that &x != this.) This function removes all of x 's elements and inserts them in order into *this. The merge is stable; that is, if an element from *this is equivalent to one from x, then the element from *this will precede the one from x. All iterators to elements in *this and x remain valid. This function is linear time: it performs at most size() + x.size() – 1 applications of Comp. 
void reverse(); 
Reverses the order of elements in the slist. All iterators remain valid and continue to point to the same elements. [6] This function is linear time. 
void sort(); 
Sorts *this according to operator<. The sort is stable, that is, the relative order of equivalent elements is preserved. All iterators remain valid and continue to point to the same elements. [7] The number of comparisons is approximately N log N, where N is the slist 's size. 
template<class BinaryPredicate> void sort(BinaryPredicate comp); [5] 
Comp must be a comparison function that induces a strict weak ordering (as defined in the LessThan Comparable requirements) on objects of type T. This function sorts the slist *this according to Comp. The sort is stable, that is, the relative order of equivalent elements is preserved. All iterators remain valid and continue to point to the same elements. [7] The number of comparisons is approximately N log N, where N is the slist 's size. 
Notes
[1] The lists in such languages as Common Lisp, Scheme, and ML are singly linked lists. In some programming languages, almost all data structures are represented as singly linked lists.
[2] A comparison with vector is instructive. Suppose that i is a valid vector<T>::iterator . If an element is inserted or removed in a position that precedes i , then this operation will either result in i pointing to a different element than it did before, or else it will invalidate i entirely. (A vector<T>::iterator will be invalidated, for example, if an insertion requires a reallocation.) However, suppose that i and j are both iterators into a vector, and there exists some integer n such that i == j + n. In that case, even if elements are inserted into the vector and i and j point to different elements, the relation between the two iterators will still hold. An slist is exactly the opposite: iterators will not be invalidated, and will not be made to point to different elements, but, for slist iterators, the predecessor/successor relationship is not invariant.
[3] This member function relies on member template functions, which at present (early 1998) are not supported by all compilers. If your compiler supports member templates, you can call this function with any type of input iterator. If your compiler does not yet support member templates, though, then the arguments must either be of type const value_type* or of type slist::const_iterator.
[4] A similar property holds for all versions of insert() and erase(). Slist<T, Alloc>::insert() never invalidates any iterators, and slist<T, Alloc>::erase() only invalidates iterators pointing to the elements that are actually being erased.
[5] This member function relies on member template functions, which at present (early 1998) are not supported by all compilers. You can only use this member function if your compiler supports member templates.
[6] The reverse algorithm works only for bidirectional iterators. Even if reverse were extended to work with forward iterators, however, it would still be useful to have the reverse member function: it has different iterator invalidation semantics. That is, the reverse member function preserves the value that each iterator points to. Note also that the algorithm reverse(L.begin(), L.end()) uses T 's assignment operator, but the member function L.reverse() does not.
[7] The sort algorithm works only for random access iterators. In principle, however, it would be possible to write a sort algorithm that also accepted forward iterators. Even if there were such a version of sort, it would still be useful for slist to have a sort member function. That is, sort is provided as a member function not only for the sake of efficiency, but also because of the property that it preserves the values that list iterators point to.
See also
Bidirectional Iterator, Reversible Container, Sequence, list, vector
Category: containers
Component type: type
Description
A bit_vector is essentially a vector<bool>: it is a Sequence that has the same interface as vector. The main difference is that bit_vector is optimized for space efficiency. A vector always requires at least one byte per element, but a bit_vector only requires one bit per element.
Warning: the name bit_vector will be removed in a future release of the STL. The only reason that bit_vector is a separate class, instead of a template specialization of vector<bool>, is that this would require partial specialization of templates. On compilers that support partial specialization, bit_vector is a specialization of vector<bool>. The name bit_vector is a typedef. This typedef is not defined in the C++ standard, and is retained only for backward compatibility.
Example
bit_vector V(5);
V[0] = true;
V[1] = false;
V[2] = false;
V[3] = true;
V[4] = false;
for (bit_vector::iterator i = V.begin(); i < V.end(); ++i) cout << (*i ? '1' : '0');
cout << endl;
Definition
Defined in the standard header vector, and in the nonstandard backwardcompatibility header bvector.h.
Template parameters
None. Bit_vector is not a class template.
Model of
Random access container, Back insertion sequence.
Type requirements
None.
Public base classes
None.
Members
Member  Where defined  Description 

value_type 
Container  The type of object stored in the bit_vector: bool 
reference 
bit_vector 
A proxy class that acts as a reference to a single bit. See below for details. 
const_reference  Container  Const reference to value_type. In bit_vector this is simply defined to be bool. 
size_type 
Container  An unsigned integral type. 
difference_type 
Container  A signed integral type. 
iterator 
Container  Iterator used to iterate through a bit_vector. 
const_iterator 
Container  Const iterator used to iterate through a bit_vector. 
reverse_iterator 
Reversible Container  Iterator used to iterate backwards through a bit_vector. 
const_reverse_iterator 
Reversible Container  Const iterator used to iterate backwards through a bit_vector. 
iterator begin() 
Container  Returns an iterator pointing to the beginning of the bit_vector. 
iterator end() 
Container  Returns an iterator pointing to the end of the bit_vector. 
const_iterator begin() const 
Container  Returns a const_iterator pointing to the beginning of the bit_vector. 
const_iterator end() const 
Container  Returns a const_iterator pointing to the end of the bit_vector. 
reverse_iterator rbegin() 
Reversible Container  Returns a reverse_iterator pointing to the beginning of the reversed bit_vector. 
reverse_iterator rend() 
Reversible Container  Returns a reverse_iterator pointing to the end of the reversed bit_vector. 
const_reverse_iterator rbegin() const 
Reversible  Container Returns a const_reverse_iterator pointing to the beginning of the reversed bit_vector. 
const_reverse_iterator rend() const 
Reversible Container  Returns a const_reverse_iterator pointing to the end of the reversed bit_vector. 
size_type size() const 
Container  Returns the number of elements in the bit_vector. 
size_type max_size() const 
Container  Returns the largest possible size of the bit_vector. 
size_type capacity() const 
bit_vector 
See below. 
bool empty() const 
Container  true if the bit_vector 's size is 0. 
reference operator[](size_type n) 
Random Access Container  Returns the n'th element. 
const_reference operator[](size_type n) const 
Random Access Container  Returns the n'th element. 
bit_vector() 
Container  Creates an empty bit_vector. 
bit_vector(size_type n) 
Sequence  Creates a bit_vector with n elements. 
bit_vector(size_type n, bool t) 
Sequence  Creates a bit_vector with n copies of t. 
bit_vector(const bit_vector&) 
Container  The copy constructor. 
template <class InputIterator> bit_vector(InputIterator, InputIterator) [1] 
Sequence  Creates a bit_vector with a copy of a range. 
~bit_vector() 
Container  The destructor. 
bit_vector& operator=(const bit_vector&) 
Container  The assignment operator 
void reserve(size_t) 
bit_vector 
See below. 
reference front() 
Sequence  Returns the first element. 
const_reference front() const 
Sequence  Returns the first element. 
reference back() 
Back Insertion  Sequence Returns the last element. 
const_reference back() const 
Back Insertion Sequence  Returns the last element. 
void push_back(const T&) 
Back Insertion Sequence  Inserts a new element at the end. 
void pop_back() 
Back Insertion Sequence  Removes the last element. 
void swap(bit_vector&) 
Container  Swaps the contents of two bit_vectors. 
void swap(bit_vector::reference x, bit_vector::reference y) 
bit_vector 
See below. 
iterator insert(iterator pos, bool x) 
Sequence  Inserts x before pos. 
template <class InputIterator> void insert(iterator pos, InputIterator f, InputIterator l) [1] 
Sequence  Inserts the range [f, l) before pos. 
void insert(iterator pos, size_type n, bool x) 
Sequence  Inserts n copies of x before pos. 
void erase(iterator pos) 
Sequence  Erases the element at position pos. 
void erase(iterator first, iterator last) 
Sequence  Erases the range [first, last) 
void clear() 
Sequence  Erases all of the elements. 
bool operator==(const bit_vector&, const bit_vector&) 
Forward Container  Tests two bit_vectors for equality. This is a global function, not a member function. 
bool operator<(const bit_vector&, const bit_vector&) 
Forward Container  Lexicographical comparison. This is a global function, not a member function. 
New members
These members are not defined in the Random access container and Back insertion sequence requirements, but are specific to vector.
Member  Description 

reference 
A proxy class that acts as a reference to a single bit; the reason it exists is to allow expressions like V[0] = true. (A proxy class like this is necessary, because the C++ memory model does not include independent addressing of objects smaller than one byte.) The public member functions of reference are operator bool() const, reference& operator=(bool), and void flip(). That is, reference acts like an ordinary reference: you can convert a reference to bool, assign a bool value through a reference, or flip the bit that a reference refers to. 
size_type capacity() const 
Number of bits for which memory has been allocated. capacity() is always greater than or equal to size(). [2] [3] 
void reserve(size_type n) 
If n is less than or equal to capacity(), this call has no effect. Otherwise, it is a request for the allocation of additional memory. If the request is successful, then capacity() is greater than or equal to n; otherwise, capacity() is unchanged. In either case, size() is unchanged. [2] [4] 
void swap(bit_vector::reference x, bit_vector::reference y) 
Swaps the bits referred to by x and y. This is a global function, not a member function. It is necessary because the ordinary version of swap takes arguments of type T&, and bit_vector::reference is a class, not a builtin C++ reference. 
Notes
[1] This member function relies on member template functions, which at present (early 1998) are not supported by all compilers. If your compiler supports member templates, you can call this function with any type of input iterator. If your compiler does not yet support member templates, though, then the arguments must either be of type const bool* or of type bit_vector::const_iterator.
[2] Memory will be reallocated automatically if more than capacity() – size() bits are inserted into the bit_vector. Reallocation does not change size(), nor does it change the values of any bits of the bit_vector. It does, however, increase capacity(), and it invalidates [5] any iterators that point into the bit_vector.
[3] When it is necessary to increase capacity(), bit_vector usually increases it by a factor of two. It is crucial that the amount of growth is proportional to the current capacity(), rather than a fixed constant: in the former case inserting a series of bits into a bit_vector is a linear time operation, and in the latter case it is quadratic.
[4] reserve() is used to cause a reallocation manually. The main reason for using reserve() is efficiency: if you know the capacity to which your bit_vector must eventually grow, then it is probably more efficient to allocate that memory all at once rather than relying on the automatic reallocation scheme. The other reason for using reserve() is to control the invalidation of iterators. [5]
[5] A bit_vector's iterators are invalidated when its memory is reallocated. Additionally, inserting or deleting a bit in the middle of a bit_vector invalidates all iterators that point to bits following the insertion or deletion point. It follows that you can prevent a bit_vector's iterators from being invalidated if you use reserve() to preallocate as much storage as the bit_vector will ever use, and if all insertions and deletions are at the bit_vector's end.
See also
vector
Category: containers
Component type: type
Description
Set is a Sorted Associative Container that stores objects of type Key. Set is a Simple Associative Container, meaning that its value type, as well as its key type, is Key. It is also a Unique Associative Container, meaning that no two elements are the same.
Set and multiset are particularly well suited to the set algorithms includes, set_union, set_intersection, set_difference, and set_symmetric_difference. The reason for this is twofold. First, the set algorithms require their arguments to be sorted ranges, and, since set and multiset are Sorted Associative Containers, their elements are always sorted in ascending order. Second, the output range of these algorithms is always sorted, and inserting a sorted range into a set or multiset is a fast operation: the Unique Sorted Associative Container and Multiple Sorted Associative Container requirements guarantee that inserting a range takes only linear time if the range is already sorted.
Set has the important property that inserting a new element into a set does not invalidate iterators that point to existing elements. Erasing an element from a set also does not invalidate any iterators, except, of course, for iterators that actually point to the element that is being erased.
Example
struct ltstr {
bool operator()(const char* s1, const char* s2) const {
return strcmp(s1, s2) < 0;
}
};
int main() {
const int N = 6;
const char* a[N] = {"isomer", "ephemeral", "prosaic", "nugatory", "artichoke", "serif"};
const char* b[N] = {"flat", "this", "artichoke", "frigate", "prosaic", "isomer"};
set<const char*, ltstr> A(a, a + N);
set<const char*, ltstr> B(b, b + N);
set<const char*, ltstr> C;
cout << "Set A: ";
copy(A.begin(), A.end(), ostream_iterator<const char*>(cout, " "));
cout << endl;
cout << "Set B: ";
copy(B.begin(), B.end(), ostream_iterator<const char*>(cout, " "));
cout << endl;
cout << "Union: ";
set_union(A.begin(), A.end(), B.begin(), B.end(), ostream_iterator<const char*>(cout, " "), ltstr());
cout << endl;
cout << "Intersection: ";
set_intersection(A.begin(), A.end(), B.begin(), B.end(), ostream_iterator<const char*>(cout, " "), ltstr());
cout << endl;
set_difference(A.begin(), A.end(), B.begin(), B.end(), inserter(C, C.begin()), ltstr());
cout << "Set C (difference of A and B): ";
copy(C.begin(), C.end(), ostream_iterator <const char*>(cout, " "));
cout << endl;
}
Definition
Defined in the standard header set, and in the nonstandard backwardcompatibility header set.h.
Template parameters
Parameter  Description  Default 

Key 
The set's key type and value type. This is also defined as set::key_type and set::value_type  
Compare 
The key comparison function, a Strict Weak Ordering whose argument type is key_type; it returns true if its first argument is less than its second argument, and false otherwise. This is also defined as set::key_compare and set::value_compare.  less<Key> 
Alloc 
The set 's allocator, used for all internal memory management.  alloc 
Model of
Unique Sorted Associative Container, Simple Associative Container
Type requirements
• Key is Assignable.
• Compare is a Strict Weak Ordering whose argument type is Key.
• Alloc is an Allocator.
Public base classes
None.
Members
Member  Where defined  Description 

value_type 
Container  The type of object, T, stored in the set. 
key_type 
Associative Container  The key type associated with value_type. 
key_compare 
Sorted Associative  Container Function object that compares two keys for ordering. 
value_compare 
Sorted Associative  Container Function object that compares two values for ordering. 
pointer 
Container  Pointer to T. 
reference 
Container  Reference to T 
const_reference 
Container  Const reference to T 
size_type 
Container  An unsigned integral type. 
difference_type 
Container  A signed integral type. 
iterator 
Container  Iterator used to iterate through a set. 
const_iterator 
Container  Const iterator used to iterate through a set. (Iterator and const_iterator are the same type.) 
reverse_iterator 
Reversible Container  Iterator used to iterate backwards through a set. 
const_reverse_iterator 
Reversible Container  Const iterator used to iterate backwards through a set. (Reverse_iterator and const_reverse_iterator are the same type.) 
iterator begin() const 
Container  Returns an iterator pointing to the beginning of the set. 
iterator end() const 
Container  Returns an iterator pointing to the end of the set. 
reverse_iterator rbegin() const 
Reversible Container  Returns a reverse_iterator pointing to the beginning of the reversed set. 
reverse_iterator rend() const 
Reversible Container  Returns a reverse_iterator pointing to the end of the reversed set. 
size_type size() const 
Container  Returns the size of the set. 
size_type max_size() const 
Container  Returns the largest possible size of the set. 
bool empty() const 
Container  true if the set 's size is 0. 
key_compare key_comp() const 
Sorted Associative Container  Returns the key_compare object used by the set. 
value_compare value_comp() const 
Sorted Associative Container  Returns the value_compare object used by the set. 
set() 
Container  Creates an empty set. 
set(const key_compare& comp) 
Sorted Associative Container  Creates an empty set, using comp as the key_compare object. 
template <class InputIterator> set(InputIterator f, InputIterator l) [1] 
Unique Sorted Associative Container  Creates a set with a copy of a range. 
template <class InputIterator> set(InputIterator f, InputIterator l, const key_compare& comp) [1] 
Unique Sorted Associative Container  Creates a set with a copy of a range, using comp as the key_compare object. 
set(const set&) 
Container  The copy constructor. 
set& operator=(const set&) 
Container  The assignment operator 
void swap(set&) 
Container  Swaps the contents of two sets. 
pair<iterator, bool> insert(const value_type& x) 
Unique Associative Container  Inserts x into the set. 
iterator insert(iterator pos, const value_type& x) 
Unique Sorted Associative Container  Inserts x into the set , using pos as a hint to where it will be inserted. 
template <class InputIterator> void insert(InputIterator, InputIterator) [1] 
Unique Sorted Associative Container  Inserts a range into the set. 
void erase(iterator pos) 
Associative Container  Erases the element pointed to by pos. 
size_type erase(const key_type& k) 
Associative Container  Erases the element whose key is k. 
void erase(iterator first, iterator last) 
Associative Container  Erases all elements in a range. 
void clear() 
Associative Container  Erases all of the elements. 
iterator find(const key_type& k) const 
Associative Container  Finds an element whose key is k. 
size_type count(const key_type& k) const 
Unique Associative Container  Counts the number of elements whose key is k. 
iterator lower_bound(const key_type& k) const 
Sorted Associative Container  Finds the first element whose key is not less than k. 
iterator upper_bound(const key_type& k) const 
Sorted Associative Container  Finds the first element whose key greater than k. 
pair<iterator, iterator> equal_range(const key_type& k) const 
Sorted Associative Container  Finds a range containing all elements whose key is k. 
bool operator==(const set&, const set&) 
Forward Container  Tests two sets for equality. This is a global function, not a member function. 
bool operator<(const set&, const set&) 
Forward Container  Lexicographical comparison. This is a global function, not a member function. 
New members
All of set 's members are defined in the Unique Sorted Associative Container and Simple Associative Container requirements. Set does not introduce any new members.
Notes
[1] This member function relies on member template functions, which at present (early 1998) are not supported by all compilers. If your compiler supports member templates, you can call this function with any type of input iterator. If your compiler does not yet support member templates, though, then the arguments must either be of type const value_type* or of type set::const_iterator.
See also
Associative Container, Sorted Associative Container, Simple Associative Container, Unique Sorted Associative Container, map, multiset, multimap, hash_set, hash_map, hash_multiset, hash_multimap
map<Key, Data, Compare, Alloc>
Category: containers
Component type: type
Description
Map is a Sorted Associative Container that associates objects of type Key with objects of type Data. Map is a Pair Associative Container, meaning that its value type is pair<const Key, Data>. It is also a Unique Associative Container, meaning that no two elements have the same key.
Map has the important property that inserting a new element into a map does not invalidate iterators that point to existing elements. Erasing an element from a map also does not invalidate any iterators, except, of course, for iterators that actually point to the element that is being erased.
Example
struct ltstr {
bool operator()(const char* s1, const char* s2) const {
return strcmp(s1, s2) < 0;
}
};
int main() {
map<const char*, int, ltstr> months;
months["january"] = 31;
months["february"] = 28;
months["march"] = 31;
months["april"] = 30;
months["may"] = 31;
months["june"] = 30;
months["july"] = 31;
months["august"] = 31;
months["september"] = 30;
months["october"] = 31;
months["november"] = 30;
months["december"] = 31;
cout << "june –> " << months["june"] << endl;
map<const char*, int, ltstr>::iterator cur = months.find("june");
map<const char*, int, ltstr>::iterator prev = cur;
map<const char*, int, ltstr>::iterator next = cur;
++next;
prev;
cout << "Previous (in alphabetical order) is " << (*prev).first << endl;
cout << "Next (in alphabetical order) is " << (*next).first << endl;
}
Definition
Defined in the standard header map, and in the nonstandard backwardcompatibility header map.h.
Template parameters
Parameter  Description  Default 

Key 
The map's key type. This is also defined as map::key_type.  
Data 
The map's data type. This is also defined as map::data_type.  
Compare 
The key comparison function, a Strict Weak Ordering whose argument type is key_type; it returns true if its first argument is less than its second argument, and false otherwise. This is also defined as map::key_compare.  less<Key> 
Alloc 
The map 's allocator, used for all internal memory management.  alloc 
Model of
Unique Sorted Associative Container, Pair Associative Container
Type requirements
• Data is Assignable.
• Compare is a Strict Weak Ordering whose argument type is Key.
• Alloc is an Allocator.
Public base classes
None.
Members
Member  Where defined  Description 

key_type 
Associative Container  The map 's key type, Key. 
data_type 
Pair Associative Container  The type of object associated with the keys. 
value_type 
Pair Associative Container  The type of object, pair<const key_type, data_type>, stored in the map. 
key_compare 
Sorted Associative Container  Function object that compares two keys for ordering. 
value_compare 
Sorted Associative Container  Function object that compares two values for ordering. 
pointer 
Container  Pointer to T. 
reference 
Container  Reference to T 
const_reference 
Container  Const reference to T 
size_type 
Container  An unsigned integral type. 
difference_type 
Container  A signed integral type. 
iterator 
Container  Iterator used to iterate through a map. [1] 
const_iterator 
Container  Const iterator used to iterate through a map. 
reverse_iterator 
Reversible Container  Iterator used to iterate backwards through a map. [1] 
const_reverse_iterator 
Reversible Container  Const iterator used to iterate backwards through a map. 
iterator begin() 
Container  Returns an iterator pointing to the beginning of the map. 
iterator end() 
Container  Returns an iterator pointing to the end of the map. 
const_iterator begin() const 
Container  Returns a const_iterator pointing to the beginning of the map. 
const_iterator end() const 
Container  Returns a const_iterator pointing to the end of the map. 
reverse_iterator rbegin() 
Reversible Container  Returns a reverse_iterator pointing to the beginning of the reversed map. 
reverse_iterator rend() 
Reversible Container  Returns a reverse_iterator pointing to the end of the reversed map. 
const_reverse_iterator rbegin() const 
Reversible Container  Returns a const_reverse_iterator pointing to the beginning of the reversed map. 
const_reverse_iterator rend() const 
Reversible Container  Returns a const_reverse_iterator pointing to the end of the reversed map. 
size_type size() const 
Container  Returns the size of the map. 
size_type max_size() const 
Container  Returns the largest possible size of the map. 
bool empty() const 
Container  true if the map 's size is 0. 
key_compare key_comp() const 
Sorted Associative Container  Returns the key_compare object used by the map. 
value_compare value_comp() const 
Sorted Associative Container  Returns the value_compare object used by the map. 
map() 
Container  Creates an empty map. 
map(const key_compare& comp) 
Sorted Associative Container  Creates an empty map , using comp as the key_compare object. 
template <class InputIterator> map(InputIterator f, InputIterator l) [2] 
Unique Sorted Associative Container  Creates a map with a copy of a range. 
template <class InputIterator> map(InputIterator f, InputIterator l, const key_compare& comp) [2] 
Unique Sorted Associative Container  Creates a map with a copy of a range, using comp as the key_compare object. 
map(const map&) 
Container  The copy constructor. 
map& operator=(const map&) 
Container  The assignment operator 
void swap(map&) 
Container  Swaps the contents of two maps. 
pair<iterator, bool> insert(const value_type& x) 
Unique Associative Container  Inserts x into the map. 
iterator insert(iterator pos, const value_type& x) 
Unique Sorted Associative Container  Inserts x into the map, using pos as a hint to where it will be inserted. 
template <class InputIterator> void insert(InputIterator, InputIterator) [2] 
Unique Sorted Associative Container  Inserts a range into the map. 
void erase(iterator pos) 
Associative Container  Erases the element pointed to by pos. 
size_type erase(const key_type& k) 
Associative Container  Erases the element whose key is k. 
void erase(iterator first, iterator last) 
Associative Container  Erases all elements in a range. 
void clear() 
Associative Container  Erases all of the elements. 
iterator find(const key_type& k) 
Associative Container  Finds an element whose key is k. 
const_iterator find(const key_type& k) const 
Associative Container  Finds an element whose key is k. 
size_type count(const key_type& k) 
Unique Associative Container  Counts the number of elements whose key is k. 
iterator lower_bound(const key_type& k) 
Sorted Associative Container  Finds the first element whose key is not less than k. 
const_iterator lower_bound(const key_type& k) const 
Sorted Associative Container  Finds the first element whose key is not less than k. 
iterator upper_bound(const key_type& k) 
Sorted Associative Container  Finds the first element whose key greater than k. 
const_iterator upper_bound(const key_type& k) const 
Sorted Associative Container  Finds the first element whose key greater than k. 
pair<iterator, iterator> equal_range(const key_type& k) 
Sorted Associative Container  Finds a range containing all elements whose key is k. 
pair<const_iterator, const_iterator> equal_range(const key_type& k) const 
Sorted Associative Container  Finds a range containing all elements whose key is k. 
data_type& operator[](const key_type& k) [3] 
map  See below. 
bool operator==(const map&, const map&) 
Forward Container  Tests two maps for equality. This is a global function, not a member function. 
bool operator<(const map&, const map&) 
Forward Container  Lexicographical comparison. This is a global function, not a member function. 
New members
These members are not defined in the Unique Sorted Associative Container and Pair Associative Container requirements, but are unique to map:
Member function  Description 

data_type& operator[](const key_type& k) [3] 
Returns a reference to the object that is associated with a particular key. If the map does not already contain such an object, operator[] inserts the default object data_type(). [3] 
Notes
[1] Map::iterator is not a mutable iterator, because map::value_type is not Assignable. That is, if i is of type map::iterator and p is of type map::value_type, then *i = p is not a valid expression. However, map::iterator isn't a constant iterator either, because it can be used to modify the object that it points to. Using the same notation as above, (*i).second = p is a valid expression. The same point applies to map::reverse_iterator.
[2] This member function relies on member template functions, which at present (early 1998) are not supported by all compilers. If your compiler supports member templates, you can call this function with any type of input iterator. If your compiler does not yet support member templates, though, then the arguments must either be of type const value_type* or of type map::const_iterator.
[3] Since operator[] might insert a new element into the map, it can't possibly be a const member function. Note that the definition of operator[] is extremely simple: m[k] is equivalent to (*((m.insert(value_type(k, data_type()))).first)).second. Strictly speaking, this member function is unnecessary: it exists only for convenience.
See also
Associative Container, Sorted Associative Container, Pair Associative Container, Unique Sorted Associative Container, set multiset, multimap, hash_set, hash_map, hash_multiset, hash_multimap
Category: containers
Component type: type
Description
Multiset is a Sorted Associative Container that stores objects of type Key. Multiset is a Simple Associative Container, meaning that its value type, as well as its key type, is Key. It is also a Multiple Associative Container, meaning that two or more elements may be identical.
Set and multiset are particularly well suited to the set algorithms includes, set_union, set_intersection, set_difference, and set_symmetric_difference. The reason for this is twofold. First, the set algorithms require their arguments to be sorted ranges, and, since set and multiset are Sorted Associative Containers, their elements are always sorted in ascending order. Second, the output range of these algorithms is always sorted, and inserting a sorted range into a set or multiset is a fast operation: the Unique Sorted Associative Container and Multiple Sorted Associative Container requirements guarantee that inserting a range takes only linear time if the range is already sorted.
Multiset has the important property that inserting a new element into a multiset does not invalidate iterators that point to existing elements. Erasing an element from a multiset also does not invalidate any iterators, except, of course, for iterators that actually point to the element that is being erased.
Example
int main() {
const int N = 10;
int a[N] = {4, 1, 1, 1, 1, 1, 0, 5, 1, 0};
int b[N] = {4, 4, 2, 4, 2, 4, 0, 1, 5, 5};
multiset<int> A(a, a + N);
multiset<int> B(b, b + N);
multiset<int> C;
cout << "Set A: ";
copy(A.begin(), A.end(), ostream_iterator<int>(cout, " "));
cout << endl;
cout << "Set B: ";
copy(B.begin(), B.end(), ostream_iterator<int>(cout, " "));
cout << endl;
cout << "Union: ";
set_union(A.begin(), A.end(), B.begin(), B.end(), ostream_iterator<int>(cout, " "));
cout << endl;
cout << "Intersection: ";
set_intersection(A.begin(), A.end(), B.begin(), B.end(), ostream_iterator<int>(cout, " "));
cout << endl;
set_difference(A.begin(), A.end(), B.begin(), B.end(), inserter(C, C.begin()));
cout << "Set C (difference of A and B): ";
copy(C.begin(), C.end(), ostream_iterator<int>(cout, " "));
cout << endl;
}
Definition
Defined in the standard header set, and in the nonstandard backwardcompatibility header multiset.h.
Template parameters
Parameter  Description  Default 

Key 
The set's key type and value type. This is also defined as multiset::key_type and multiset::value_type  
Compare 
The key comparison function, a Strict Weak Ordering whose argument type is key_type; it returns true if its first argument is less than its second argument, and false otherwise. This is also defined as multiset::key_compare and multiset::value_compare.  less<Key> 
Alloc 
The multiset 's allocator, used for all internal memory management.  alloc 
Model of
Multiple Sorted Associative Container, Simple Associative Container
Type requirements
• Key is Assignable.
• Compare is a Strict Weak Ordering whose argument type is Key.
• Alloc is an Allocator.
Public base classes
None.
Members
Member  Where defined  Description 

value_type 
Container  The type of object, T, stored in the multiset. 
key_type 
Associative Container  The key type associated with value_type. 
key_compare 
Sorted Associative Container  Function object that compares two keys for ordering. 
value_compare 
Sorted Associative Container  Function object that compares two values for ordering. 
pointer 
Container  Pointer to T. 
reference 
Container  Reference to T 
const_reference 
Container  Const reference to T 
size_type 
Container  An unsigned integral type. 
difference_type 
Container  A signed integral type. 
iterator 
Container  Iterator used to iterate through a multiset. 
const_iterator 
Container  Const iterator used to iterate through a multiset. (Iterator and const_iterator are the same type.) 
reverse_iterator 
Reversible Container  Iterator used to iterate backwards through a multiset. 
const_reverse_iterator 
Reversible Container  Const iterator used to iterate backwards through a multiset. (Reverse_iterator and const_reverse_iterator are the same type.) 
iterator begin() const 
Container  Returns an iterator pointing to the beginning of the multiset. 
iterator end() const 
Container  Returns an iterator pointing to the end of the multiset. 
reverse_iterator rbegin() const 
Reversible Container  Returns a reverse_iterator pointing to the beginning of the reversed multiset. 
reverse_iterator rend() const 
Reversible Container  Returns a reverse_iterator pointing to the end of the reversed multiset. 
size_type size() const 
Container  Returns the size of the multiset. 
size_type max_size() const 
Container  Returns the largest possible size of the multiset. 
bool empty() const 
Container  true if the multiset 's size is 0. 
key_compare key_comp() const 
Sorted Associative Container  Returns the key_compare object used by the multiset. 
value_compare value_comp() const 
Sorted Associative Container  Returns the value_compare object used by the multiset. 
multiset() 
Container  Creates an empty multiset. 
multiset(const key_compare& comp) 
Sorted Associative Container  Creates an empty multiset, using comp as the key_compare object. 
template <class InputIterator> multiset(InputIterator f, InputIterator l) [1] 
Multiple Sorted Associative Container  Creates a multiset with a copy of a range. 
template <class InputIterator> multiset(InputIterator f, InputIterator l, const key_compare& comp) [1] 
Multiple Sorted Associative Container  Creates a multiset with a copy of a range, using comp as the key_compare object. 
multiset(const multiset&) 
Container  The copy constructor. 
multiset& operator=(const multiset&) 
Container  The assignment operator 
void swap(multiset&) 
Container  Swaps the contents of two multisets. 
iterator insert(const value_type& x) 
Multiple Associative Container  Inserts x into the multiset. 
iterator insert(iterator pos, const value_type& x) 
Multiple Sorted Associative Container  Inserts x into the multiset, using pos as a hint to where it will be inserted. 
template <class InputIterator> void insert(InputIterator, InputIterator) [1] 
Multiple Sorted Associative Container  Inserts a range into the multiset. 
void erase(iterator pos) 
Associative Container  Erases the element pointed to by pos. 
size_type erase(const key_type& k) 
Associative Container  Erases the element whose key is k. 
void erase(iterator first, iterator last) 
Associative Container  Erases all elements in a range. 
void clear() 
Associative Container  Erases all of the elements. 
iterator find(const key_type& k) const 
Associative Container  Finds an element whose key is k. 
size_type count(const key_type& k) const 
Associative Container  Counts the number of elements whose key is k. 
iterator lower_bound(const key_type& k) const 
Sorted Associative Container  Finds the first element whose key is not less than k. 
iterator upper_bound(const key_type& k) const 
Sorted Associative Container  Finds the first element whose key greater than k. 
pair<iterator, iterator> equal_range(const key_type& k) const 
Sorted Associative Container  Finds a range containing all elements whose key is k. 
bool operator==(const multiset&, const multiset&) 
Forward Container  Tests two multisets for equality. This is a global function, not a member function. 
bool operator<(const multiset&, const multiset&) 
Forward Container  Lexicographical comparison. This is a global function, not a member function. 
New members
All of multiset's members are defined in the Multiple Sorted Associative Container and Simple Associative Container requirements. Multiset does not introduce any new members.
Notes
[1] This member function relies on member template functions, which at present (early 1998) are not supported by all compilers. If your compiler supports member templates, you can call this function with any type of input iterator. If your compiler does not yet support member templates, though, then the arguments must either be of type const value_type* or of type multiset::const_iterator.
See also
Associative Container, Sorted Associative Container, Simple Associative Container, Multiple Sorted Associative Container, set, map, multimap, hash_set, hash_map, hash_multiset, hash_multimap
multimap<Key, Data, Compare, Alloc>
Category: containers
Component type: type
Description
Multimap is a Sorted Associative Container that associates objects of type Key with objects of type Data. multimap is a Pair Associative Container, meaning that its value type is pair<const Key, Data>. It is also a Multiple Associative Container, meaning that there is no limit on the number of elements with the same key.
Multimap has the important property that inserting a new element into a multimap does not invalidate iterators that point to existing elements. Erasing an element from a multimap also does not invalidate any iterators, except, of course, for iterators that actually point to the element that is being erased.
Example
struct ltstr {
bool operator()(const char* s1, const char* s2) const {
return strcmp(s1, s2) < 0;
}
};
int main() {
multimap<const char*, int, ltstr> m;
m.insert(pair<const char* const, int>("a", 1));
m.insert(pair<const char* const, int>("c", 2));
m.insert(pair<const char* const, int>("b", 3));
m.insert(pair<const char* const, int>("b", 4));
m.insert(pair<const char* const, int>("a", 5));
m.insert(pair<const char* const, int>("b", 6));
cout << "Number of elements with key a: " << m.count("a") << endl;
cout << "Number of elements with key b: " << m.count("b") << endl;
cout << "Number of elements with key c: " << m.count("c") << endl;
cout << "Elements in m: " << endl;
for (multimap<const char*, int, ltstr>::iterator it = m.begin(); it != m.end(); ++it)
cout << " [" << (*it).first << ", " << (*it).second << "]" << endl;
}
Definition
Defined in the standard header map, and in the nonstandard backwardcompatibility header multimap.h.
Template parameters
Parameter  Description  Default 

Key 
The multimap's key type. This is also defined as multimap::key_type.  
Data 
The multimap's data type. This is also defined as multimap::data_type.  
Compare 
The key comparison function, a Strict Weak Ordering whose argument type is key_type; it returns true if its first argument is less than its second argument, and false otherwise. This is also defined as multimap::key_compare.  less<Key> 
Alloc 
The multimap 's allocator, used for all internal memory management.  alloc 
Model of
Multiple Sorted Associative Container, Pair Associative Container
Type requirements
• Data is Assignable.
• Compare is a Strict Weak Ordering whose argument type is Key.
• Alloc is an Allocator.
Public base classes
None.
Members
Member  Where defined  Description 

key_type 
Associative Container  The multimap 's key type, Key. 
data_type 
Pair Associative Container  The type of object associated with the keys. 
value_type 
Pair Associative Container  The type of object, pair<const key_type, data_type>, stored in the multimap. 
key_compare 
Sorted Associative Container  Function object that compares two keys for ordering. 
value_compare 
Sorted Associative Container  Function object that compares two values for ordering. 
pointer 
Container  Pointer to T. 
reference 
Container  Reference to T 
const_reference 
Container  Const reference to T 
size_type 
Container  An unsigned integral type. 
difference_type 
Container  A signed integral type. 
iterator 
Container  Iterator used to iterate through a multimap. [1] 
const_iterator 
Container  Const iterator used to iterate through a multimap. 
reverse_iterator 
Reversible Container  Iterator used to iterate backwards through a multimap. [1] 
const_reverse_iterator 
Reversible Container  Const iterator used to iterate backwards through a multimap. 
iterator begin() 
Container  Returns an iterator pointing to the beginning of the multimap. 
iterator end() 
Container  Returns an iterator pointing to the end of the multimap. 
const_iterator begin() const 
Container  Returns a const_iterator pointing to the beginning of the multimap. 
const_iterator end() const 
Container  Returns a const_iterator pointing to the end of the multimap. 
reverse_iterator rbegin() 
Reversible Container  Returns a reverse_iterator pointing to the beginning of the reversed multimap. 
reverse_iterator rend() 
Reversible Container  Returns a reverse_iterator pointing to the end of the reversed multimap. 
const_reverse_iterator rbegin() const 
Reversible Container  Returns a const_reverse_iterator pointing to the beginning of the reversed multimap. 
const_reverse_iterator rend() const 
Reversible Container  Returns a const_reverse_iterator pointing to the end of the reversed multimap. 
size_type size() const 
Container  Returns the size of the multimap. 
size_type max_size() const 
Container  Returns the largest possible size of the multimap. 
bool empty() const 
Container  true if the multimap 's size is 0. 
key_compare key_comp() const 
Sorted Associative Container  Returns the key_compare object used by the multimap. 
value_compare value_comp() const 
Sorted Associative Container  Returns the value_compare object used by the multimap. 
multimap() 
Container  Creates an empty multimap. 
multimap(const key_compare& comp) 
Sorted Associative Container  Creates an empty multimap, using comp as the key_compare object. 
template <class InputIterator> multimap(InputIterator f, InputIterator l) [2] 
Multiple Sorted Associative Container  Creates a multimap with a copy of a range. 
template <class InputIterator> multimap(InputIterator f, InputIterator l, const key_compare& comp) [2] 
Multiple Sorted Associative Container  Creates a multimap with a copy of a range, using comp as the key_compare object. 
multimap(const multimap&) 
Container  The copy constructor. 
multimap& operator=(const multimap&) 
Container  The assignment operator 
void swap(multimap&) 
Container  Swaps the contents of two multimaps. 
iterator insert(const value_type& x) 
Multiple Associative Container  Inserts x into the multimap. 
iterator insert(iterator pos, const value_type& x) 
Multiple Sorted Associative Container  Inserts x into the multimap, using pos as a hint to where it will be inserted. 
template <class InputIterator> void insert(InputIterator, InputIterator) [2] 
Multiple Sorted Associative Container  Inserts a range into the multimap. 
void erase(iterator pos) 
Associative Container  Erases the element pointed to by pos. 
size_type erase(const key_type& k) 
Associative Container  Erases the element whose key is k. 
void erase(iterator first, iterator last) 
Associative Container  Erases all elements in a range. 
void clear() 
Associative Container  Erases all of the elements. 
iterator find(const key_type& k) 
Associative Container  Finds an element whose key is k. 
const_iterator find(const key_type& k) const 
Associative Container  Finds an element whose key is k. 
size_type count(const key_type& k) 
Associative Container  Counts the number of elements whose key is k. 
iterator lower_bound(const key_type& k) 
Sorted Associative Container  Finds the first element whose key is not less than k. 
const_iterator lower_bound(const key_type& k) const 
Sorted Associative Container  Finds the first element whose key is not less than k. 
iterator upper_bound(const key_type& k) 
Sorted Associative Container  Finds the first element whose key greater than k. 
const_iterator upper_bound(const key_type& k) const 
Sorted Associative Container  Finds the first element whose key greater than k. 
pair<iterator, iterator> equal_range(const key_type& k) 
Sorted Associative Container  Finds a range containing all elements whose key is k. 
pair<const_iterator, const_iterator> equal_range(const key_type& k) const 
Sorted Associative Container  Finds a range containing all elements whose key is k. 
bool operator==(const multimap&, const multimap&) 
Forward Container  Tests two multimaps for equality. This is a global function, not a member function. 
bool operator<(const multimap&, const multimap&) 
Forward Container  Lexicographical comparison. This is a global function, not a member function. 
New members
All of multimap 's members are defined in the Multiple Sorted Associative Container and Pair Associative Container requirements. Multimap does not introduce any new members.
Notes
[1] Multimap::iterator is not a mutable iterator, because multimap::value_type is not Assignable. That is, if i is of type multimap::iterator and p is of type multimap::value_type, then *i = p is not a valid expression. However, multimap::iterator isn't a constant iterator either, because it can be used to modify the object that it points to. Using the same notation as above, (*i).second = p is a valid expression. The same point applies to multimap::reverse_iterator.
[2] This member function relies on member template functions, which at present (early 1998) are not supported by all compilers. If your compiler supports member templates, you can call this function with any type of input iterator. If your compiler does not yet support member templates, though, then the arguments must either be of type const value_type* or of type multimap::const_iterator.
See also
Associative Container, Sorted Associative Container, Pair Associative Container, Multiple Sorted Associative Container, set, map, multiset, hash_set, hash_map, hash_multiset, hash_multimap
hash_set<Key, HashFcn, EqualKey, Alloc>
Category: containers
Component type: type
Description
Hash_set is a Hashed Associative Container that stores objects of type Key. Hash_set is a Simple Associative Container, meaning that its value type, as well as its key type, is Key. It is also a Unique Associative Container, meaning that no two elements compare equal using the Binary Predicate EqualKey.
Hash_set is useful in applications where it is important to be able to search for an element quickly. If it is important for the elements to be in a particular order, however, then set is more appropriate.
Example
struct eqstr {
bool operator()(const char* s1, const char* s2) const {
return strcmp(s1, s2) == 0;
}
};
void lookup(const hash_set<const char*, hash<const char*>, eqstr>& Set, const char* word) {
hash_set<const char*, hash<const char*>, eqstr>::const_iterator it = Set.find(word);
cout << word << ": " << (it != Set.end() ? "present" : "not present") << endl;
}
int main() {
hash_set<const char*, hash<const char*>, eqstr> Set;
Set.insert("kiwi");
Set.insert("plum");
Set.insert("apple");
Set.insert("mango");
Set.insert("apricot");
Set.insert("banana");
lookup(Set, "mango");
lookup(Set, "apple");
lookup(Set, "durian");
}
Definition
Defined in the header hash_set, and in the backwardcompatibility header hash_set.h. This class is an SGI extension; it is not part of the C++ standard.
Template parameters
Parameter  Description  Default 

Key 
The hash_set's key type and value type. This is also defined as hash_set::key_type and hash_set::value_type  
HashFcn 
The Hash Function used by the hash_set. This is also defined as hash_set::hasher.  hash<Key> 
EqualKey 
The hash_set's key equality function: a binary predicate that determines whether two keys are equal. This is also defined as hash_set::key_equal.  equal_to<Key> 
Alloc 
The hash_set 's allocator, used for all internal memory management.  alloc 
Model of
Unique Hashed Associative Container, Simple Associative Container
Type requirements
• Key is Assignable.
• EqualKey is a Binary Predicate whose argument type is Key.
• EqualKey is an equivalence relation.
• Alloc is an Allocator.
Public base classes
None.
Members
Member  Where defined  Description 

value_type 
Container  The type of object, T, stored in the hash_set. 
key_type 
Associative Container  The key type associated with value_type. 
hasher 
Hashed Associative Container  The hash_set's Hash Function. 
key_equal 
Hashed Associative Container  Function object that compares keys for equality. 
pointer 
Container  Pointer to T. 
reference 
Container  Reference to T 
const_reference 
Container  Const reference to T 
size_type 
Container  An unsigned integral type. 
difference_type 
Container  A signed integral type. 
iterator 
Container  Iterator used to iterate through a hash_set. 
const_iterator 
Container  Const iterator used to iterate through a hash_set. (Iterator and const_iterator are the same type.) 
iterator begin() const 
Container  Returns an iterator pointing to the beginning of the hash_set. 
iterator end() const 
Container  Returns an iterator pointing to the end of the hash_set. 
size_type size() const 
Container  Returns the size of the hash_set. 
size_type max_size() const 
Container  Returns the largest possible size of the hash_set. 
bool empty() const 
Container  true if the hash_set 's size is 0. 
size_type bucket_count() const 
Hashed Associative Container  Returns the number of buckets used by the hash_set. 
void resize(size_type n) 
Hashed Associative Container  Increases the bucket count to at least n. 
hasher hash_funct() const 
Hashed Associative Container  Returns the hasher object used by the hash_set. 
key_equal key_eq() const 
Hashed Associative Container  Returns the key_equal object used by the hash_set. 
hash_set() 
Container  Creates an empty hash_set. 
hash_set(size_type n) 
Hashed Associative Container  Creates an empty hash_set with at least n buckets. 
hash_set(size_type n, const hasher& h) 
Hashed Associative Container  Creates an empty hash_set with at least n buckets, using h as the hash function. 
hash_set(size_type n, const hasher& h, const key_equal& k) 
Hashed Associative Container  Creates an empty hash_set with at least n buckets, using h as the hash function and k as the key equal function. 
template <class InputIterator> hash_set(InputIterator f, InputIterator l) [1] 
Unique Hashed Associative Container  Creates a hash_set with a copy of a range. 
template <class InputIterator> hash_set(InputIterator f, InputIterator l, size_type n) [1] 
Unique Hashed Associative Container  Creates a hash_set with a copy of a range and a bucket count of at least n. 
template <class InputIterator> hash_set(InputIterator f, InputIterator l, size_type n, const hasher& h) [1] 
Unique Hashed Associative Container  Creates a hash_set with a copy of a range and a bucket count of at least n, using h as the hash function. 
hash_set(InputIterator f, InputIterator l, size_type n, const hasher& h, const key_equal& k) [1] 
Unique Hashed Associative Container  Creates a hash_set with a copy of a range and a bucket count of at least n, using h as the hash function and k as the key equal function. 
hash_set(const hash_set&) 
Container  The copy constructor. 
hash_set& operator=(const hash_set&) 
Container  The assignment operator 
void swap(hash_set&) 
Container  Swaps the contents of two hash_sets. 
pair<iterator, bool> insert(const value_type& x) 
Unique Associative Container  Inserts x into the hash_set. 
template <class InputIterator> void insert(InputIterator f, InputIterator l) [1] 
Unique Associative Container  Inserts a range into the hash_set. 
void erase(iterator pos) 
Associative Container  Erases the element pointed to by pos. 
size_type erase(const key_type& k) 
Associative Container  Erases the element whose key is k. 
void erase(iterator first, iterator last) 
Associative Container  Erases all elements in a range. 
void clear() 
Associative Container  Erases all of the elements. 
iterator find(const key_type& k) const 
Associative Container  Finds an element whose key is k. 
size_type count(const key_type& k) const 
Unique Associative Container  Counts the number of elements whose key is k. 
pair<iterator, iterator> equal_range(const key_type& k) const 
Associative Container  Finds a range containing all elements whose key is k. 
bool operator==(const hash_set&, const hash_set&) 
Hashed Associative Container  Tests two hash_sets for equality. This is a global function, not a member function. 
New members
All of hash_set's members are defined in the Unique Hashed Associative Container and Simple Associative Container requirements. Hash_set does not introduce any new members.
Notes
[1] This member function relies on member template functions, which at present (early 1998) are not supported by all compilers. If your compiler supports member templates, you can call this function with any type of input iterator. If your compiler does not yet support member templates, though, then the arguments must either be of type const value_type* or of type hash_set::const_iterator.
See also
Associative Container, Hashed Associative Container, Simple Associative Container, Unique Hashed Associative Container, set, map, multiset, multimap, hash_map, hash_multiset, hash_multimap
hash_map<Key, Data, HashFcn, EqualKey, Alloc>
Category: containers
Component type: type
Description
Hash_map is a Hashed Associative Container that associates objects of type Key with objects of type Data. Hash_map is a Pair Associative Container, meaning that its value type is pair<const Key, Data>. It is also a Unique Associative Container, meaning that no two elements have keys that compare equal using EqualKey.
Looking up an element in a hash_map by its key is efficient, so hash_map is useful for "dictionaries" where the order of elements is irrelevant. If it is important for the elements to be in a particular order, however, then map is more appropriate.
Example
struct eqstr {
bool operator()(const char* s1, const char* s2) const {
return strcmp(s1, s2) == 0;
}
};
int main() {
hash_map<const char*, int, hash<const char*>, eqstr> months;
months["january"] = 31;
months["february"] = 28;
months["march"] = 31;
months["april"] = 30;
months["may"] = 31;
months["june"] = 30;
months["july"] = 31;
months["august"] = 31;
months["september"] = 30;
months["october"] = 31;
months["november"] = 30;
months["december"] = 31;
cout << "september –> " << months["september"] << endl;
cout << "april –> " << months["april"] << endl;
cout << "june –> " << months["june"] << endl;
cout << "november –> " << months["november"] << endl;
}
Definition
Defined in the header hash_map, and in the backwardcompatibility header hash_map.h. This class is an SGI extension; it is not part of the C++ standard.
Template parameters
Parameter  Description  Default 

Key 
The hash_map's key type. This is also defined as hash_map::key_type.  
Data 
The hash_map's data type. This is also defined as hash_map::data_type.  
HashFcn 
The hash function used by the hash_map. This is also defined as hash_map::hasher.  hash<Key> 
EqualKey 
The hash_map key equality function: a binary predicate that determines whether two keys are equal. This is also defined as hash_map::key_equal.  equal_to<Key> 
Alloc 
The hash_map's allocator, used for all internal memory management.  alloc 
Model of
Unique Hashed Associative Container, Pair Associative Container
Type requirements
• Key is Assignable.
• EqualKey is a Binary Predicate whose argument type is Key.
• EqualKey is an equivalence relation.
• Alloc is an Allocator.
Public base classes
None.
Members
Member  Where defined  Description 

key_type 
Associative Container  The hash_map's key type, Key. 
data_type 
Pair Associative Container  The type of object associated with the keys. 
value_type 
Pair Associative Container  The type of object, pair<const key_type, data_type>, stored in the hash_map. 
hasher 
Hashed Associative Container  The hash_map's hash function. 
key_equal 
Hashed Associative Container  Function object that compares keys for equality. 
pointer 
Container  Pointer to T. 
reference 
Container  Reference to T 
const_reference 
Container  Const reference to T 
size_type 
Container  An unsigned integral type. 
difference_type 
Container  A signed integral type. 
iterator 
Container  Iterator used to iterate through a hash_map. [1] 
const_iterator 
Container  Const iterator used to iterate through a hash_map. 
iterator begin() 
Container  Returns an iterator pointing to the beginning of the hash_map. 
iterator end() 
Container  Returns an iterator pointing to the end of the hash_map. 
const_iterator begin() const 
Container  Returns an const_iterator pointing to the beginning of the hash_map. 
const_iterator end() const 
Container  Returns an const_iterator pointing to the end of the hash_map. 
size_type size() const 
Container  Returns the size of the hash_map. 
size_type max_size() const 
Container  Returns the largest possible size of the hash_map. 
bool empty() const 
Container  true if the hash_map's size is 0. 
size_type bucket_count() const 
Hashed Associative Container  Returns the number of buckets used by the hash_map. 
void resize(size_type n) 
Hashed Associative Container  Increases the bucket count to at least n. 
hasher hash_funct() const 
Hashed Associative Container  Returns the hasher object used by the hash_map. 
key_equal key_eq() const 
Hashed Associative Container  Returns the key_equal object used by the hash_map. 
hash_map() 
Container  Creates an empty hash_map. 
hash_map(size_type n) 
Hashed Associative Container  Creates an empty hash_map with at least n buckets. 
hash_map(size_type n, const hasher& h) 
Hashed Associative Container  Creates an empty hash_map with at least n buckets, using h as the hash function. 
hash_map(size_type n, const hasher& h, const key_equal& k) 
Hashed Associative Container  Creates an empty hash_map with at least n buckets, using h as the hash function and k as the key equal function. 
template <class InputIterator> hash_map(InputIterator f, InputIterator l) [2] 
Unique Hashed Associative Container  Creates a hash_map with a copy of a range. 
template <class InputIterator> hash_map(InputIterator f, InputIterator l, size_type n) [2] 
Unique Hashed Associative Container  Creates a hash_map with a copy of a range and a bucket count of at least n. 
template <class InputIterator> hash_map(InputIterator f, InputIterator l, size_type n, const hasher& h) [2] 
Unique Hashed Associative Container  Creates a hash_map with a copy of a range and a bucket count of at least n , using h as the hash function. 
template <class InputIterator> hash_map(InputIterator f, InputIterator l, size_type n, const hasher& h, const key_equal& k) [2] 
Unique Hashed Associative Container  Creates a hash_map with a copy of a range and a bucket count of at least n , using h as the hash function and k as the key equal function. 
hash_map(const hash_map&) 
Container  The copy constructor. 
hash_map& operator=(const hash_map&) 
Container  The assignment operator 
void swap(hash_map&) 
Container  Swaps the contents of two hash_maps. 
pair<iterator, bool> insert(const value_type& x) 
Unique Associative Container  Inserts x into the hash_map. 
template <class InputIterator> void insert(InputIterator f, InputIterator l) [2] 
Unique Associative Container  Inserts a range into the hash_map. 
void erase(iterator pos) 
Associative Container  Erases the element pointed to by pos. 
size_type erase(const key_type& k) 
Associative Container  Erases the element whose key is k. 
void erase(iterator first, iterator last) 
Associative Container  Erases all elements in a range. 
void clear() 
Associative Container  Erases all of the elements. 
const_iterator find(const key_type& k) const 
Associative Container  Finds an element whose key is k. 
iterator find(const key_type& k) 
Associative Container  Finds an element whose key is k. 
size_type count(const key_type& k) const 
Unique Associative Container  Counts the number of elements whose key is k. 
pair<const_iterator, const_iterator> equal_range(const key_type& k) const 
Associative Container  Finds a range containing all elements whose key is k. 
pair<iterator, iterator> equal_range(const key_type& k) 
Associative Container  Finds a range containing all elements whose key is k. 
data_type& operator[](const key_type& k) [3] 
hash_map 
See below. 
bool operator==(const hash_map&, const hash_map&) 
Hashed Associative Container  Tests two hash_maps for equality. This is a global function, not a member function. 
New members
These members are not defined in the Unique Hashed Associative Container and Pair Associative Container requirements, but are specific to hash_map.
Member  Description 

data_type& operator[](const key_type& k) [3] 
Returns a reference to the object that is associated with a particular key. If the hash_map does not already contain such an object, operator[] inserts the default object data_type(). [3] 
Notes
[1] Hash_map::iterator is not a mutable iterator, because hash_map::value_type is not Assignable. That is, if i is of type hash_map::iterator and p is of type hash_map::value_type, then *i = p is not a valid expression. However, hash_map::iterator isn't a constant iterator either, because it can be used to modify the object that it points to. Using the same notation as above, (*i).second = p is a valid expression.
[2] This member function relies on member template functions, which at present (early 1998) are not supported by all compilers. If your compiler supports member templates, you can call this function with any type of input iterator. If your compiler does not yet support member templates, though, then the arguments must either be of type const value_type* or of type hash_map::const_iterator.
[3] Since operator[] might insert a new element into the hash_map, it can't possibly be a const member function. Note that the definition of operator[] is extremely simple: m[k] is equivalent to (*((m.insert(value_type(k, data_type()))).first)).second. Strictly speaking, this member function is unnecessary: it exists only for convenience.
See also
Associative Container, Hashed Associative Container, Pair Associative Container, Unique Hashed Associative Container, set, map, multiset, multimap, hash_set, hash_multiset, hash_multimap
hash_multiset<Key, HashFcn, EqualKey, Alloc>
Category: containers
Component type: type
Description
Hash_multiset is a Hashed Associative Container that stores objects of type Key. Hash_multiset is a simple associative container, meaning that its value type, as well as its key type, is Key. It is also a Multiple Associative Container, meaning that two or more elements may compare equal using the Binary Predicate EqualKey.
Hash_multiset is useful in applications where it is important to be able to search for an element quickly. If it is important for the elements to be in a particular order, however, then multiset is more appropriate.
Example
struct eqstr {
bool operator()(const char* s1, const char* s2) const {
return strcmp(s1, s2) == 0;
}
};
void lookup(const hash_multiset<const char*, hash<const char*>, eqstr>& Set, const char* word) {
int n_found = Set.count(word);
cout << word << ": " << n_found << " " << (n_found == 1 ? "instance" : "instances") << endl;
}
int main() {
hash_multiset<const char*, hash<const char*>, eqstr> Set;
Set.insert("mango");
Set.insert("kiwi");
Set.insert("apple");
Set.insert("kiwi");
Set.insert("mango");
Set.insert("mango");
Set.insert("apricot");
Set.insert("banana");
Set.insert("mango");
lookup(Set, "mango");
lookup(Set, "apple");
lookup(Set, "durian");
}
Definition
Defined in the header hash_set, and in the backwardcompatibility header hash_set.h. This class is an SGI extension; it is not part of the C++ standard.
Template parameters
Parameter  Description  Default 

Key 
The hash_multiset's key type and value type. This is also defined as hash_multiset::key_type and hash_multiset::value_type  
HashFcn 
The Hash Function used by the hash_multiset. This is also defined as hash_multiset::hasher.  hash<Key> 
EqualKey  The hash_multiset's key equality function: a binary predicate that determines whether two keys are equal. This is also defined as hash_multiset::key_equal.  equal_to<Key> 
Alloc 
The hash_multiset's allocator, used for all internal memory management.  alloc 
Model of
Multiple Hashed Associative Container, Simple Associative Container
Type requirements
• Key is assignable.
• EqualKey is a Binary Predicate whose argument type is Key.
• EqualKey is an equivalence relation.
• Alloc is an Allocator.
Public base classes
None.
Members
Member  Where defined  Description 

value_type 
Container  The type of object, T, stored in the hash_multiset. 
key_type 
Associative Container  The key type associated with value_type. 
hasher 
Hashed Associative Container  The hash_multiset's Hash Function. 
key_equal 
Hashed Associative Container  Function object that compares keys for equality. 
pointer 
Container  Pointer to T. 
reference 
Container  Reference to T 
const_reference 
Container  Const reference to T 
size_type 
Container  An unsigned integral type. 
difference_type 
Container  A signed integral type. 
iterator 
Container  Iterator used to iterate through a hash_multiset. 
const_iterator 
Container  Const iterator used to iterate through a hash_multiset. (Iterator and const_iterator are the same type.) 
iterator begin() const 
Container  Returns an iterator pointing to the beginning of the hash_multiset. 
iterator end() const 
Container  Returns an iterator pointing to the end of the hash_multiset. 
size_type size() const 
Container  Returns the size of the hash_multiset. 
size_type max_size() const 
Container  Returns the largest possible size of the hash_multiset. 
bool empty() const 
Container  true if the hash_multiset's size is 0. 
size_type bucket_count() const 
Hashed Associative Container  Returns the number of buckets used by the hash_multiset. 
void resize(size_type n) 
Hashed Associative Container  Increases the bucket count to at least n. 
hasher hash_funct() const 
Hashed Associative Container  Returns the hasher object used by the hash_multiset. 
key_equal key_eq() const 
Hashed Associative Container  Returns the key_equal object used by the hash_multiset. 
hash_multiset() 
Container  Creates an empty hash_multiset. 
hash_multiset(size_type n) 
Hashed Associative Container  Creates an empty hash_multiset with at least n buckets. 
hash_multiset(size_type n, const hasher& h) 
Hashed Associative Container  Creates an empty hash_multiset with at least n buckets, using h as the hash function. 
hash_multiset(size_type n, const hasher& h, const key_equal& k) 
Hashed Associative Container  Creates an empty hash_multiset with at least n buckets, using h as the hash function and k as the key equal function. 
template <class InputIterator> hash_multiset(InputIterator, InputIterator) [1] 
Multiple Hashed Associative Container  Creates a hash_multiset with a copy of a range. 
template <class InputIterator> hash_multiset(InputIterator, InputIterator, size_type n) [1] 
Multiple Hashed Associative Container  Creates a hash_multiset with a copy of a range and a bucket count of at least n. 
template <class InputIterator> hash_multiset(InputIterator, InputIterator, size_type n, const hasher& h) [1] 
Multiple Hashed Associative Container  Creates a hash_multiset with a copy of a range and a bucket count of at least n, using h as the hash function. 
template <class InputIterator> hash_multiset(InputIterator, InputIterator, size_type n, const hasher& h, const key_equal& k) [1] 
Multiple Hashed Associative Container  Creates a hash_multiset with a copy of a range and a bucket count of at least n, using h as the hash function and k as the key equal function. 
hash_multiset(const hash_multiset&) 
Container  The copy constructor. 
hash_multiset& operator=(const hash_multiset&) 
Container  The assignment operator 
void swap(hash_multiset&) 
Container  Swaps the contents of two hash_multisets. 
iterator insert(const value_type& x) 
Multiple Associative Container  Inserts x into the hash_multiset. 
template <class InputIterator> void insert(InputIterator, InputIterator) [1] 
Multiple Associative Container  Inserts a range into the hash_multiset. 
void erase(iterator pos) 
Associative Container  Erases the element pointed to by pos. 
size_type erase(const key_type& k) 
Associative Container  Erases the element whose key is k. 
void erase(iterator first, iterator last) 
Associative Container  Erases all elements in a range. 
void clear() 
Associative Container  Erases all of the elements. 
iterator find(const key_type& k) const 
Associative Container  Finds an element whose key is k. 
size_type count(const key_type& k) const 
Associative Container  Counts the number of elements whose key is k. 
pair<iterator, iterator> equal_range(const key_type& k) const 
Associative Container  Finds a range containing all elements whose key is k. 
bool operator==(const hash_multiset&, const hash_multiset&) 
Hashed Associative Container  Tests two hash_multisets for equality. This is a global function, not a member function. 
New members
All of hash_multiset's members are defined in the Multiple Hashed Associative Container and Simple Associative Container requirements. Hash_multiset does not introduce any new members.
Notes
[1] This member function relies on member template functions, which at present (early 1998) are not supported by all compilers. If your compiler supports member templates, you can call this function with any type of input iterator. If your compiler does not yet support member templates, though, then the arguments must either be of type const value_type* or of type hash_multiset::const_iterator.
See also
Associative Container, Hashed Associative Container, Simple Associative Container, Multiple Hashed Associative Container, set, map, multiset, multimap, hash_set, hash_map, hash_multimap
hash_multimap<Key, Data, HashFcn, EqualKey, Alloc>
Category: containers
Component type: type
Description
Hash_multimap is a Hashed Associative Container that associates objects of type Key with objects of type Data. Hash_multimap is a Pair Associative Container, meaning that its value type is pair<const Key, Data>. It is also a Multiple Associative Container, meaning that there is no limit on the number of elements whose keys may compare equal using EqualKey.
Looking up an element in a hash_multimap by its key is efficient, so hash_multimap is useful for "dictionaries" where the order of elements is irrelevant. If it is important for the elements to be in a particular order, however, then multimap is more appropriate.
Example
struct eqstr {
bool operator()(const char* s1, const char* s2) const {
return strcmp(s1, s2) == 0;
}
};
typedef hash_multimap<const char*, int, hash<const char*>, eqstr> map_type;
void lookup(const map_type& Map, const char* str) {
cout << str << ": ";
pair<map_type::const_iterator, map_type::const_iterator> p = Map.equal_range(str);
for (map_type::const_iterator i = p.first; i != p.second; ++i) cout << (*i).second << " ";
cout << endl;
}
int main() {
map_type M;
M.insert(map_type::value_type("H", 1));
M.insert(map_type::value_type("H", 2));
M.insert(map_type::value_type("C", 12));
M.insert(map_type::value_type("C", 13));
M.insert(map_type::value_type("O", 16));
M.insert(map_type::value_type("O", 17));
M.insert(map_type::value_type("O", 18));
M.insert(map_type::value_type("I", 127));
lookup(M, "I");
lookup(M, "O");
lookup(M, "Rn");
}
Definition
Defined in the header hash_map, and in the backwardcompatibility header hash_map.h. This class is an SGI extension; it is not part of the C++ standard.
Template parameters
Parameter  Description  Default 

Key 
The hash_multimap's key type. This is also defined as hash_multimap::key_type.  
Data 
The hash_multimap's data type. This is also defined as hash_multimap::data_type.  
HashFcn 
The hash function used by the hash_multimap. This is also defined as hash_multimap::hasher.  hash<Key> 
EqualKey 
The hash_multimap's key equality function: a binary predicate that determines whether two keys are equal. This is also defined as hash_multimap::key_equal.  equal_to<Key> 
Alloc 
The hash_set's allocator, used for all internal memory management.  alloc 
Model of
Multiple Hashed Associative Container, Pair Associative Container
Type requirements
• Key is Assignable.
• EqualKey is a Binary Predicate whose argument type is Key.
• EqualKey is an equivalence relation.
• Alloc is an Allocator.
Public base classes
None.
Members
Member  Where defined  Description 

key_type 
Associative Container  The hash_multimap's key type, Key. 
data_type 
Pair Associative Container  The type of object associated with the keys. 
value_type 
Pair Associative Container  The type of object, pair<const key_type, data_type>, stored in the hash_multimap. 
hasher 
Hashed Associative Container  The hash_multimap's hash function. 
key_equal 
Hashed Associative Container  Function object that compares keys for equality. 
pointer 
Container  Pointer to T. 
reference 
Container  Reference to T 
const_reference 
Container  Const reference to T 
size_type 
Container  An unsigned integral type. 
difference_type 
Container  A signed integral type. 
iterator 
Container  Iterator used to iterate through a hash_multimap. [1] 
const_iterator 
Container  Const iterator used to iterate through a hash_multimap. 
iterator begin() 
Container  Returns an iterator pointing to the beginning of the hash_multimap. 
iterator end() 
Container  Returns an iterator pointing to the end of the hash_multimap. 
const_iterator begin() const 
Container  Returns an const_iterator pointing to the beginning of the hash_multimap. 
const_iterator end() const 
Container  Returns an const_iterator pointing to the end of the hash_multimap. 
size_type size() const 
Container  Returns the size of the hash_multimap. 
size_type max_size() const 
Container  Returns the largest possible size of the hash_multimap. 
bool empty() const 
Container  true if the hash_multimap's size is 0. 
size_type bucket_count() const 
Hashed Associative Container  Returns the number of buckets used by the hash_multimap. 
void resize(size_type n) 
Hashed Associative Container  Increases the bucket count to at least n. 
hasher hash_funct() const 
Hashed Associative Container  Returns the hasher object used by the hash_multimap. 
key_equal key_eq() const 
Hashed Associative Container  Returns the key_equal object used by the hash_multimap. 
hash_multimap() 
Container  Creates an empty hash_multimap. 
hash_multimap(size_type n) 
Hashed Associative Container  Creates an empty hash_multimap with at least n buckets. 
hash_multimap(size_type n, const hasher& h) 
Hashed Associative Container  Creates an empty hash_multimap with at least n buckets, using h as the hash function. 
hash_multimap(size_type n, const hasher& h, const key_equal& k) 
Hashed Associative Container  Creates an empty hash_multimap with at least n buckets, using h as the hash function and k as the key equal function. 
template <class InputIterator> hash_multimap(InputIterator, InputIterator) [2] 
Multiple Hashed Associative Container  Creates a hash_multimap with a copy of a range. 
template <class InputIterator> hash_multimap(InputIterator, InputIterator, size_type n) [2] 
Multiple Hashed Associative Container  Creates a hash_multimap with a copy of a range and a bucket count of at least n. 
template <class InputIterator> hash_multimap(InputIterator, InputIterator, size_type n, const hasher& h) [2] 
Multiple Hashed Associative Container  Creates a hash_multimap with a copy of a range and a bucket count of at least n, using h as the hash function. 
template <class InputIterator> hash_multimap(InputIterator, InputIterator, size_type n, const hasher& h, const key_equal& k) [2] 
Multiple Hashed Associative Container  Creates a hash_multimap with a copy of a range and a bucket count of at least n, using h as the hash function and k as the key equal function. 
hash_multimap(const hash_multimap&) 
Container  The copy constructor. 
hash_multimap& operator=(const hash_multimap&) 
Container  The assignment operator 
void swap(hash_multimap&) 
Container  Swaps the contents of two hash_multimaps. 
iterator insert(const value_type& x) 
Multiple Associative Container  Inserts x into the hash_multimap. 
template <class InputIterator> void insert(InputIterator, InputIterator) [2] 
Multiple Associative Container  Inserts a range into the hash_multimap. 
void erase(iterator pos) 
Associative Container  Erases the element pointed to by pos. 
size_type erase(const key_type& k) 
Associative Container  Erases the element whose key is k. 
void erase(iterator first, iterator last) 
Associative Container  Erases all elements in a range. 
void clear() 
Associative Container  Erases all of the elements. 
const_iterator find(const key_type& k) const 
Associative Container  Finds an element whose key is k. 
iterator find(const key_type& k) 
Associative Container  Finds an element whose key is k. 
size_type count(const key_type& k) const 
Associative Container  Counts the number of elements whose key is k. 
pair<const_iterator, const_iterator> equal_range(const key_type& k) const 
Associative Container  Finds a range containing all elements whose key is k. 
pair<iterator, iterator> equal_range(const key_type& k) 
Associative Container  Finds a range containing all elements whose key is k. 
bool operator==(const hash_multimap&, const hash_multimap&) 
Hashed Associative Container  Tests two hash_multimaps for equality. This is a global function, not a member function. 
New members
All of hash_multimap's members are defined in the Multiple Hashed Associative Container and Pair Associative Container requirements. Hash_multimap does not introduce any new members.
Notes
[1] Hash_multimap::iterator is not a mutable iterator, because hash_multimap::value_type is not Assignable. That is, if i is of type hash_multimap::iterator and p is of type hash_multimap::value_type, then *i = p is not a valid expression. However, hash_multimap::iterator isn't a constant iterator either, because it can be used to modify the object that it points to. Using the same notation as above, (*i).second = p is a valid expression.
[2] This member function relies on member template functions, which at present (early 1998) are not supported by all compilers. If your compiler supports member templates, you can call this function with any type of input iterator. If your compiler does not yet support member templates, though, then the arguments must either be of type const value_type* or of type hash_multimap::const_iterator.
See also
Associative Container, Hashed Associative Container, Pair Associative Container, Multiple Hashed Associative Container, set, map, multiset, multimap, hash_set, hash_map, hash_multiset
Categories: containers, functors
Component type: type
Description
The function object hash<T> is a Hash Function; it is used as the default hash function by all of the Hashed Associative Containers that are included in the STL.
The hash<T> template is only defined for template arguments of type char*, const char*, crope, wrope, and the builtin integral types. [1] If you need a Hash Function with a different argument type, you must either provide your own template specialization or else use a different Hash Function.
Example
int main() {
hash<const char*> H;
cout << "foo –> " << H("foo") << endl;
cout << "bar –> " << H("bar") << endl;
}
Definition
Defined in the headers hash_map and hash_set, and in the backwardcompatibility headers hash_map.h and hash_set.h. This class is an SGI extension; it is not part of the C++ standard.
Template parameters
Parameter  Description 

T 
The argument type. That is, the type of object that is being hashed. 
Model of
Hash Function
Type requirements
T must be a type for which a specialization of hash has been defined. The STL defines the following specializations:
• char*
• const char*
• crope
• wrope
• char
• signed char
• unsigned char
• short
• unsigned short
• int
• unsigned int
• long
• unsigned long
Public base classes
None.
Members
Member  Where defined  Description 

size_t operator()(const T& x) 
Hash Function  Returns x's hash value. 
New members
All of hash's members are defined in the Hash Function requirements. Hash does not introduce any new members.
Notes
[1] Technically, what this means is that the actual template hash<T> is an empty class; the member function operator() is defined only in the various specializations.
See also
Hashed Associative Container, Hash Function
Category: utilities
Component type: concept
Description
Several library components, including strings, need to perform operations on characters. A Character Traits class is similar to a function object: it encapsulates some information about a particular character type, and some operations on that type.
Note that every member of a Character Traits class is static. There is never any need to create a Character Traits object, and, in fact, there is no guarantee that creating such objects is possible.
Refinement of
Character Traits is not a refinement of any other concept.
Associated types
Value type  X::char_type 
The character type described by this Character Traits type. 
Int type  X::int_type 
A type that is capable of representing every valid value of type char_type, and, additionally an endoffile value. For char, for example, the int type may be int, and for wchar_t it may be wint_t. 
Position type  X::pos_type 
A type that can represent the position of a character of type char_type within a file. This type is usually streampos. 
Offset type  X::off_type 
An integer type that can represent the difference between two pos_type values. This type is usually streamoff. 
State type  X::state_type 
A type that can represent a state in a multibyte encoding scheme. This type, if used at all, is usually mbstate_t. 
Notation
X
A type that is a model of Character Traits.
c, c1, c2
A value of X's value type, X::char_type.
e, e1, e2
A value of X's int type, X::int_type.
n
A value of type size_t.
p, p1, p2
A nonnull pointer of type const X::char_type*.
s
A nonnull pointer of type X::char_type*.
Valid Expressions
Name  Expression  Type requirements  Return type 

Character assignment  X::assign(c1, c2) 
c1 is a modifiable lvalue.  void 
Character equality  X::eq(c1, c2) 
bool 

Character comparison  X::lt(c1, c2) 
bool 

Range comparison  X::compare(p1, p2, n) 
int 

Length  X::length(p) 
size_t 

Find  X::find(p, n, c) 
const X::char_type* 

Move  X::move(s, p, n) 
X::char_type* 

Copy  X::copy(s, p, n) 
X::char_type* 

Range assignment  X::assign(s, n, c) 
X::char_type* 

EOF value  X::eof() 
X::int_type 

Not EOF  X::not_eof(e) 
X::int_type 

Convert to value type  X::to_char_type(e) 
X::char_type 

Convert to int type  X::to_int_type(c) 
X::int_type 

Equal int type values  X::eq_int_type(e1, e2) 
bool 
Expression semantics
Name  Expression  Precondition  Semantics  Postcondition 

Character assignment  X::assign(c1, c2) 
Performs the assignment c1 = c2  X::eq(c1, c2) is true.  
Character equality  X::eq(c1, c2) 
Returns true if and only if c1 and c2 are equal.  
Character comparison  X::lt(c1, c2) 
Returns true if and only if c1 is less than c2 . Note that for any two value values c1 and c2 , exactly one of X::lt(c1, c2), X::lt(c2, c1) , and X::eq(c1, c2) should be true.  
Range comparison  X::compare(p1, p2, n) 
[p1, p1+n) and [p2, p2+n) are valid ranges.  Generalization of strncmp. Returns 0 if every element in [p1, p1+n) is equal to the corresponding element in [p2, p2+n), a negative value if there exists an element in [p1, p1+n) less than the corresponding element in [p2, p2+n) and all previous elements are equal, and a positive value if there exists an element in [p1, p1+n) greater than the corresponding element in [p2, p2+n) and all previous elements are equal.  
Length  X::length(p) 
Generalization of strlen. Returns the smallest nonnegative number n such that X::eq(p+n, X::char_type()) is true. Behavior is undefined if no such n exists.  
Find  X::find(p, n, c) 
[p, p+n) is a valid range.  Generalization of strchr. Returns the first pointer q in [p, p+n) such that X::eq(*q, c) is true. Returns a null pointer if no such pointer exists. (Note that this method for indicating a failed search differs from that is find.)  
Move  X::move(s, p, n) 
[p, p+n) and [s, s+n) are valid ranges (possibly overlapping).  Generalization of memmove. Copies values from the range [p, p+n) to the range [s, s+n), and returns s.  
Copy  X::copy(s, p, n) 
[p, p+n) and [s, s+n) are valid ranges which do not overlap.  Generalization of memcpy. Copies values from the range [p, p+n) to the range [s, s+n), and returns s.  
Range assignment  X::assign(s, n, c) 
[s, s+n) is a valid range.  Generalization of memset. Assigns the value c to each pointer in the range [s, s+n), and returns s.  
EOF value  X::eof() 
Returns a value that can represent EOF.  X::eof() is distinct from every valid value of type X::char_type. That is, there exists no value c such that X::eq_int_type(X::to_int_type(c), X::eof()) is true.  
Not EOF  X::not_eof(e) 
Returns e if e represents a valid char_type value, and some nonEOF value if e is X::eof().  
Convert to value type  X::to_char_type(e) 
Converts e to X's int type. If e is a representation of some char_type value then it returns that value; if e is X::eof() then the return value is unspecified.  
Convert to int type  X::to_int_type(c) 
Converts c to X's int type.  X::to_char_type(X::to_int_type(c)) is a null operation.  
Equal int type values  X::eq_int_type(e1, e2) 
Compares two int type values. If there exist values of type X::char_type such that e1 is X::to_int_type(c1)) and e2 is X::to_int_type(c2)), then X::eq_int_type(e1, e2) is the same as X::eq(c1, c2). Otherwise, eq_int_type returns true if e1 and e2 are both EOF and false if one of e1 and e2 is EOF and the other is not. 
Complexity guarantees
length, find, move, copy, and the range version of assign are linear in n.
All other operations are constant time.
Models
• char_traits<char>
• char_traits<wchar_t>
See also
string
Category: utilities
Component type: type
Description
The char_traits class is the default Character Traits class used by the library; it is the only predefined Character Traits class.
Example
The char_traits class is of no use by itself. It is used as a template parameter of other classes, such as the basic_string template.
Definition
Defined in the standard header string.
Template parameters
Parameter  Description 

charT  char_traits 's value type, i.e.char_traits<>::char_type. 
Model of
Character Traits
Type requirements
charT is either char or wchar_t.
(All of char_traits 's member functions are defined for arbitrary types, but some of char_traits 's members must be explicitly specialized if char_traits is to be useful for other types than char and wchar_t.)
Public base classes
None.
Members
All of char_traits 's members are static. There is never any reason to create an object of type char_traits.
Member  Where defined  Description 

char_type 
Character Traits  char_traits's value type: charT. 
int_type 
Character Traits  char_traits's int type. 
pos_type 
Character Traits  char_traits's position type. 
off_type 
Character Traits  char_traits's offset type 
state_type 
Character Traits  char_traits's state type. 
static void assign(char_type& c1, const char_type& c2) 
Character Traits  Assigns c2 to c1. 
static bool eq(const char_type& c1, const char_type& c2) 
Character Traits  Character equality. 
static bool lt(const char_type& c1, const char_type& c2) 
Character Traits  Returns true if c1 is less than c2. 
static int compare(const char_type* p1, const char_type* p2, size_t n) 
Character Traits  Threeway lexicographical comparison, much like strncmp. 
static size_t length(const char* p) 
Character Traits  Returns length of a nullterminated array of characters. 
static const char_type* find(const char_type* p, size_t n, const char_type& c) 
Character Traits  Finds c in [p, p+n) , returning 0 if not found. 
static char_type* move(char_type* s, const char_type* p, size_t n) 
Character Traits  Copies characters from [p, p+n) to the (possibly overlapping) range [s, s+n). 
static char_type* copy(char_type* s, const char_type* p, size_t n) 
Character Traits  Copies characters from [p, p+n) to the (nonoverlapping) range [s, s+n). 
static char_type* assign(char_type* s, size_t n, char_type c) 
Character Traits  Assigns the value c to every element in the range [s, s+n). 
static int_type eof() 
Character Traits  Returns the value used as an EOF indicator. 
static int_type not_eof(const int_type& c) 
Character Traits  Returns a value that is not equal to eof() . Returns c unless c is equal to eof(). 
static char_type to_char_type(const int_type& c) 
Character Traits  Returns the char_type value corresponding to c, if such a value exists. 
static int_type to_int_type(const char_type& c) 
Character Traits  Returns a int_type representation of c. 
static bool eq_int_type(cosnt int_type& c1, const int_type& c1) 
Character Traits  Tests whether two int_type values are equal. If the values can also be represented as char_type, then eq and eq_int_type must be consistent with each other. 
New members
None. All of char_traits's members are defined in the Character Traits requirements.
See also
Character Traits, string
basic_string<charT, traits, Alloc>
Category: containers
Component type: type
Description
The basic_string class represents a Sequence of characters. It contains all the usual operations of a Sequence, and, additionally, it contains standard string operations such as search and concatenation.
The basic_string class is parameterized by character type, and by that type's Character Traits. Most of the time, however, there is no need to use the basic_string template directly. The types string and wstring are typedefs for, respectively, basic_string<char> and basic_string<wchar_t>.
Some of basic_string's member functions use an unusual method of specifying positions and ranges. In addition to the conventional method using iterators, many of basic_string's member functions use a single value pos of type size_type to represent a position (in which case the position is begin() + pos, and many of basic_string's member functions use two values, pos and n, to represent a range. In that case pos is the beginning of the range and n is its size. That is, the range is [begin() + pos, begin() + pos + n).
Note that the C++ standard does not specify the complexity of basic_string operations. In this implementation, basic_string has performance characteristics very similar to those of vector: access to a single character is O(1), while copy and concatenation are O(N). By contrast, rope has very different performance characteristics: most rope operations have logarithmic complexity.
Note also that, according to the C++ standard, basic_string has very unusual iterator invalidation semantics. Iterators may be invalidated by swap, reserve, insert , and erase (and by functions that are equivalent to insert and/or erase , such as clear, resize, append , and replace). Additionally, however, the first call to any nonconst member function, including the nonconst version of begin() or operator[], may invalidate iterators. (The intent of these iterator invalidation rules is to give implementors greater freedom in implementation techniques.) In this implementation, begin(), end(), rbegin(), rend(), operator[], c_str(), and data() do not invalidate iterators. In this implementation, iterators are only invalidated by member functions that explicitly change the string's contents.
Example
int main() {
string s(10u, ' '); // Create a string of ten blanks.
const char* A = "this is a test";
s += A;
cout << "s = " << (s + '\n');
cout << "As a nullterminated sequence: " << s.c_str() << endl;
cout << "The sixteenth character is " << s[15] << endl;
reverse(s.begin(), s.end());
s.push_back('\n');
cout << s;
}
Definition
Defined in the standard header string.
Template parameters
Parameter  Description  Default 

charT 
The string's value type: the type of character it contains.  
traits 
The Character Traits type, which encapsulates basic character operations.  char_traits<charT> 
Alloc 
The string's allocator, used for internal memory management.  alloc 
Model of
Random Access Container, Sequence.
Type requirements
In addition to the type requirements imposed by Random Access Container and Sequence:
• charT is a POD ("plain ol' data") type.
• traits is a Character Traits type whose value type is charT
Public base classes
None.
Members
Member  Where defined  Description 

value_type 
Container  The type of object, CharT, stored in the string. 
pointer 
Container  Pointer to CharT. 
reference 
Container  Reference to CharT 
const_reference 
Container  Const reference to CharT 
size_type 
Container  An unsigned integral type. 
difference_type 
Container  A signed integral type. 
static const size_type npos 
basic_string 
The largest possible value of type size_type. That is, size_type(1). 
iterator 
Container  Iterator used to iterate through a string. A basic_string supplies Random Access Iterators. 
const_iterator 
Container Const  iterator used to iterate through a string. 
reverse_iterator 
Reversible Container  Iterator used to iterate backwards through a string. 
const_reverse_iterator 
Reversible Container  Const iterator used to iterate backwards through a string. 
iterator begin() 
Container  Returns an iterator pointing to the beginning of the string. 
iterator end() 
Container  Returns an iterator pointing to the end of the string. 
const_iterator begin() 
const 
Container Returns a const_iterator pointing to the beginning of the string. 
const_iterator end() const 
Container  Returns a const_iterator pointing to the end of the string. 
reverse_iterator rbegin() 
Reversible Container  Returns a reverse_iterator pointing to the beginning of the reversed string. 
reverse_iterator rend() 
Reversible Container  Returns a reverse_iterator pointing to the end of the reversed string. 
const_reverse_iterator rbegin() const 
Reversible Container  Returns a const_reverse_iterator pointing to the beginning of the reversed string. 
const_reverse_iterator rend() const 
Reversible Container  Returns a const_reverse_iterator pointing to the end of the reversed string. 
size_type size() const 
Container  Returns the size of the string. 
size_type length() const 
basic_string 
Synonym for size(). 
size_type max_size() const 
Container  Returns the largest possible size of the string. 
size_type capacity() const 
basic_string 
See below. 
bool empty() const 
Container  true if the string's size is 0. 
reference operator[](size_type n) 
Random Access Container  Returns the n'th character. 
const_reference operator[](size_type n) const 
Random Access Container  Returns the n'th character. 
const charT* c_str() const 
basic_string 
Returns a pointer to a nullterminated array of characters representing the string's contents. 
const charT* data() const 
basic_string 
Returns a pointer to an array of characters (not necessarily nullterminated) representing the string's contents. 
basic_string() 
Container  Creates an empty string. 
basic_string(const basic_string& s, size_type pos = 0, size_type n = npos) 
Container, basic_string  Generalization of the copy constructor. 
basic_string(const charT*) 
basic_string 
Construct a string from a nullterminated character array. 
basic_string(const charT* s, size_type n) 
basic_string 
Construct a string from a character array and a length. 
basic_string(size_type n, charT c) 
Sequence  Create a string with n copies of c. 
template <class InputIterator> basic_string(InputIterator first, InputIterator last) 
Sequence  Create a string from a range. 
~basic_string() 
Container  The destructor. 
basic_string& operator=(const basic_string&) 
Container  The assignment operator 
basic_string& operator=(const charT* s) 
basic_string 
Assign a nullterminated character array to a string. 
basic_string& operator=(charT c) 
basic_string 
Assign a single character to a string. 
void reserve(size_t) 
basic_string 
See below. 
void swap(basic_string&) 
Container  Swaps the contents of two strings. 
iterator insert(iterator pos, const T& x) 
Sequence  Inserts x before pos. 
template <class InputIterator > void insert(iterator pos, InputIterator f, InputIterator l) [1] 
Sequence  Inserts the range [first, last) before pos. 
void insert(iterator pos, size_type n, const T& x) 
Sequence  Inserts n copies of x before pos. 
basic_string& insert(size_type pos, const basic_string& s) 
basic_string 
Inserts s before pos. 
basic_string& insert(size_type pos, const basic_string& s, size_type pos1, size_type n) 
basic_string 
Inserts a substring of s before pos. 
basic_string& insert(size_type pos, const charT* s) 
basic_string 
Inserts s before pos. 
basic_string& insert(size_type pos, const charT* s, size_type n) 
basic_string 
Inserts the first n characters of s before pos. 
basic_string& insert(size_type pos, size_type n, charT c) 
basic_string 
Inserts n copies of c before pos. 
basic_string& append(const basic_string& s) 
basic_string 
Append s to *this. 
basic_string& append(const basic_string& s, size_type pos, size_type n) 
basic_string 
Append a substring of s to *this. 
basic_string& append(const charT* s) 
basic_string 
Append s to *this. 
basic_string& append(const charT* s, size_type n) 
basic_string 
Append the first n characters of s to *this. 
basic_string& append(size_type n, charT c) 
basic_string 
Append n copies of c to *this. 
template <class InputIterator> basic_string& append(InputIterator first, InputIterator last) 
basic_string 
Append a range to *this. 
void push_back(charT c) 
basic_string 
Append a single character to *this. 
basic_string& operator+=(const basic_string& s) 
basic_string 
Equivalent to append(s). 
basic_string& operator+=(const charT* s) 
basic_string 
Equivalent to append(s) 
basic_string& operator+=(charT c) 
basic_string 
Equivalent to push_back(c) 
iterator erase(iterator p) 
Sequence  Erases the character at position p 
iterator erase(iterator first, iterator last) 
Sequence  Erases the range [first, last) 
basic_string& erase(size_type pos = 0, size_type n = npos) 
basic_string 
Erases a range. 
void clear() 
Sequence  Erases the entire container. 
void resize(size_type n, charT c = charT()) 
Sequence  Appends characters, or erases characters from the end, as necessary to make the string's length exactly n characters. 
basic_string& assign(const basic_string&) 
basic_string 
Synonym for operator= 
basic_string& assign(const basic_string& s, size_type pos, size_type n) 
basic_string 
Assigns a substring of s to *this 
basic_string& assign(const charT* s, size_type n) 
basic_string 
Assigns the first n characters of s to *this. 
basic_string& assign(const charT* s) 
basic_string 
Assigns a nullterminated array of characters to *this. 
basic_string& assign(size_type n, charT c) 
Sequence  Erases the existing characters and replaces them by n copies of c. 
template <class InputIterator> basic_string& assign(InputIterator first, InputIterator last) 
Sequence  Erases the existing characters and replaces them by [first, last) 
basic_string& replace(size_type pos, size_type n, const basic_string& s) 
basic_string 
Replaces a substring of *this with the string s. 
basic_string& replace(size_type pos, size_type n, const basic_string& s, size_type pos1, size_type n1) 
basic_string 
Replaces a substring of *this with a substring of s. 
basic_string& replace(size_type pos, size_type n, const charT* s, size_type n1) 
basic_string 
Replaces a substring of *this with the first n1 characters of s. 
basic_string& replace(size_type pos, size_type n, const charT* s) 
basic_string 
Replaces a substring of *this with a nullterminated character array. 
basic_string& replace(size_type pos, size_type n, size_type n1, charT c) 
basic_string 
Replaces a substring of *this with n1 copies of c. 
basic_string& replace(iterator first, iterator last, const basic_string& s) 
basic_string 
Replaces a substring of *this with the string s. 
basic_string& replace(iterator first, iterator last, const charT* s, size_type n) 
basic_string 
Replaces a substring of *this with the first n characters of s. 
basic_string& replace(iterator first, iterator last, const charT* s) 
basic_string 
Replaces a substring of *this with a nullterminated character array. 
basic_string& replace(iterator first, iterator last, size_type n, charT c) 
basic_string 
Replaces a substring of *this with n copies of c. 
template <class InputIterator> basic_string& replace(iterator first, iterator last, InputIterator f, InputIterator l) 
basic_string 
Replaces a substring of *this with the range [f, l) 
size_type copy(charT* buf, size_type n, size_type pos = 0) const 
basic_string 
Copies a substring of *this to a buffer. 
size_type find(const basic_string& s, size_type pos = 0) const 
basic_string 
Searches for s as a substring of *this, beginning at character pos of *this. 
size_type find(const charT* s, size_type pos, size_type n) const 
basic_string 
Searches for the first n characters of s as a substring of *this, beginning at character pos of *this. 
size_type find(const charT* s, size_type pos = 0) const 
basic_string 
Searches for a nullterminated character array as a substring of *this, beginning at character pos of *this. 
size_type find(charT c, size_type pos = 0) const 
basic_string 
Searches for the character c, beginning at character position pos. 
size_type rfind(const basic_string& s, size_type pos = npos) const 
basic_string 
Searches backward for s as a substring of *this, beginning at character position min(pos, size()) 
size_type rfind(const charT* s, size_type pos, size_type n) const 
basic_string 
Searches backward for the first n characters of s as a substring of *this, beginning at character position min(pos, size()) 
size_type rfind(const charT* s, size_type pos = npos) const 
basic_string 
Searches backward for a nullterminated character array as a substring of *this, beginning at character min(pos, size()) 
size_type rfind(charT c, size_type pos = npos) const 
basic_string 
Searches backward for the character c, beginning at character position min(pos, size(). 
size_type find_first_of(const basic_string& s, size_type pos = 0) const 
basic_string 
Searches within *this, beginning at pos, for the first character that is equal to any character within s. 
size_type find_first_of(const charT* s, size_type pos, size_type n) const 
basic_string 
Searches within *this, beginning at pos, for the first character that is equal to any character within the first n characters of s. 
size_type find_first_of(const charT* s, size_type pos = 0) const 
basic_string 
Searches within *this, beginning at pos, for the first character that is equal to any character within s. 
size_type find_first_of(charT c, size_type pos = 0) const 
basic_string 
Searches within *this, beginning at pos, for the first character that is equal to c. 
size_type find_first_not_of(const basic_string& s, size_type pos = 0) const 
basic_string 
Searches within *this, beginning at pos, for the first character that is not equal to any character within s. 
size_type find_first_not_of(const charT* s, size_type pos, size_type n) const 
basic_string 
Searches within *this, beginning at pos, for the first character that is not equal to any character within the first n characters of s. 
size_type find_first_not_of(const charT* s, size_type pos = 0) const 
basic_string 
Searches within *this, beginning at pos, for the first character that is not equal to any character within s. 
size_type find_first_not_of(charT c, size_type pos = 0) const 
basic_string 
Searches within *this, beginning at pos, for the first character that is not equal to c. 
size_type find_last_of(const basic_string& s, size_type pos = npos) const 
basic_string 
Searches backward within *this, beginning at min(pos, size()), for the first character that is equal to any character within s. 
size_type find_last_of(const charT* s, size_type pos, size_type n) const 
basic_string 
Searches backward within *this, beginning at min(pos, size()), for the first character that is equal to any character within the first n characters of s. 
size_type find_last_of(const charT* s, size_type pos = npos) const 
basic_string 
Searches backward *this, beginning at min(pos, size()), for the first character that is equal to any character within s. 
size_type find_last_of(charT c, size_type pos = npos) const 
basic_string 
Searches backward *this, beginning at min(pos, size()), for the first character that is equal to c. 
size_type find_last_not_of(const basic_string& s, size_type pos = npos) const 
basic_string 
Searches backward within *this, beginning at min(pos, size()), for the first character that is not equal to any character within s. 
size_type find_last_not_of(const charT* s, size_type pos, size_type n) const 
basic_string 
Searches backward within *this, beginning at min(pos, size()), for the first character that is not equal to any character within the first n characters of s. 
size_type find_last_not_of(const charT* s, size_type pos = npos) const 
basic_string 
Searches backward *this, beginning at min(pos, size()), for the first character that is not equal to any character within s. 
size_type find_last_not_of(charT c, size_type pos = npos) const 
basic_string 
Searches backward *this, beginning at min(pos, size()), for the first character that is not equal to c. 
basic_string substr(size_type pos = 0, size_type n = npos) const 
basic_string 
Returns a substring of *this. 
int compare(const basic_string& s) const 
basic_string 
Threeway lexicographical comparison of s and *this. 
int compare(size_type pos, size_type n, const basic_string& s) const 
basic_string 
Threeway lexicographical comparison of s and a substring of *this. 
int compare(size_type pos, size_type n, const basic_string& s, size_type pos1, size_type n1) const 
basic_string 
Threeway lexicographical comparison of a substring of s and a substring of *this 
int compare(const charT* s) const 
basic_string 
Threeway lexicographical comparison of s and *this. 
int compare(size_type pos, size_type n, const charT* s, size_type len = npos) const 
basic_string 
Threeway lexicographical comparison of the first min(len, traits::length(s)) characters of s and a substring of *this. 
template<class charT, class traits, class Alloc> basic_string<charT, traits, Alloc> operator+(const basic_string<charT, traits, Alloc>& s1, const basic_string<charT, traits, Alloc>& s2) 
basic_string 
String concatenation. A global function, not a member function. 
template<class charT, class traits, class Alloc> basic_string<charT, traits, Alloc> operator+(const charT* s1, const basic_string<charT, traits, Alloc>& s2) 
basic_string 
String concatenation. A global function, not a member function. 
template<class charT, class traits, class Alloc> basic_string<charT, traits, Alloc> operator+(const basic_string<charT, traits, Alloc>& s1, const charT* s2) 
basic_string 
String concatenation. A global function, not a member function. 
template<class charT, class traits, class Alloc> basic_string<charT, traits, Alloc> operator+(charT c, const basic_string<charT, traits, Alloc>& s2) 
basic_string 
String concatenation. A global function, not a member function. 
template<class charT, class traits, class Alloc> basic_string<charT, traits, Alloc> operator+(const basic_string<charT, traits, Alloc>& s1, charT c) 
basic_string 
String concatenation. A global function, not a member function. 
template<class charT, class traits, class Alloc> bool operator==(const basic_string<charT, traits, Alloc>& s1, const basic_string<charT, traits, Alloc>& s2) 
Container  String equality. A global function, not a member function. 
template<class charT, class traits, class Alloc> bool operator==(const charT* s1, const basic_string<charT, traits, Alloc>& s2) 
basic_string 
String equality. A global function, not a member function. 
template<class charT, class traits, class Alloc> bool operator==(const basic_string<charT, traits, Alloc>& s1, const charT* s2) 
basic_string 
String equality. A global function, not a member function. 
template<class charT, class traits, class Alloc> bool operator!=(const basic_string<charT, traits, Alloc>& s1, const basic_string<charT, traits, Alloc>& s2) 
Container  String inequality. A global function, not a member function. 
template<class charT, class traits, class Alloc> bool operator!=(const charT* s1, const basic_string<charT, traits, Alloc>& s2) 
basic_string 
String inequality. A global function, not a member function. 
template<class charT, class traits, class Alloc> bool operator!=(const basic_string<charT, traits, Alloc>& s1, const charT* s2) 
basic_string 
String inequality. A global function, not a member function. 
template<class charT, class traits, class Alloc> bool operator<(const basic_string<charT, traits, Alloc>& s1, const basic_string<charT, traits, Alloc>& s2) 
Container  String comparison. A global function, not a member function. 
template<class charT, class traits, class Alloc> bool operator<(const charT* s1, const basic_string<charT, traits, Alloc>& s2) 
basic_string 
String comparison. A global function, not a member function. 
template<class charT, class traits, class Alloc> bool operator<(const basic_string<charT, traits, Alloc>& s1, const charT* s2) 
basic_string 
String comparison. A global function, not a member function. 
template<class charT, class traits, class Alloc> void swap(basic_string<charT, traits, Alloc>& s1, basic_string<charT, traits, Alloc>& s2) 
Container  Swaps the contents of two strings. 
template<class charT, class traits, class Alloc> basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, basic_string<charT, traits, Alloc>& s) 
basic_string 
Reads s from the input stream is 
template<class charT, class traits, class Alloc> basic_ostream<charT, traits>& operator<<(basic_istream<charT, traits>& os, const basic_string<charT, traits, Alloc>& s) 
basic_string 
Writes s to the output stream os 
template<class charT, class traits, class Alloc> basic_istream<charT, traits>& getline(basic_istream<charT, traits>& is, basic_string<charT, traits, Alloc>& s, charT delim) 
basic_string 
Reads a string from the input stream is, stopping when it reaches delim 
template<class charT, class traits, class Alloc> basic_istream<charT, traits>& getline(basic_istream<charT, traits>& is, basic_string<charT, traits, Alloc>& s) 
basic_string 
Reads a single line from the input stream is 
New members
These members are not defined in the Random Access Container and Sequence: requirements, but are specific to basic_string.
Member  Description 

static const size_type npos 
The largest possible value of type size_type. That is, size_type(1). 
size_type length() const 
Equivalent to size(). 
size_type capacity() const  Number of elements for which memory has been allocated. That is, the size to which the string can grow before memory must be reallocated. capacity() is always greater than or equal to size(). 
const charT* c_str() const 
Returns a pointer to a nullterminated array of characters representing the string's contents. For any string s it is guaranteed that the first s.size() characters in the array pointed to by s.c_str() are equal to the character in s, and that s.c_str()[s.size()] is a null character. Note, however, that it not necessarily the first null character. Characters within a string are permitted to be null. 
const charT* data() const 
Returns a pointer to an array of characters, not necessarily nullterminated, representing the string's contents. data() is permitted, but not required, to be identical to c_str(). The first size() characters of that array are guaranteed to be identical to the characters in *this. The return value of data() is never a null pointer, even if size() is zero. 
basic_string(const basic_string& s, size_type pos = 0, size_type n = npos) 
Constructs a string from a substring of s. The substring begins at character position pos and terminates at character position pos + n or at the end of s, whichever comes first. This constructor throws out_of_range if pos > s.size(). Note that when pos and n have their default values, this is just a copy constructor. 
basic_string(const charT* s) 
Equivalent to basic_string(s, s + traits::length(s)). 
basic_string(const charT* s, size_type n) 
Equivalent to basic_string(s, s + n). 
basic_string& operator=(const charT* s) 
Equivalent to operator=(basic_string(s)). 
basic_string& operator=(charT c) 
Assigns to *this a string whose size is 1 and whose contents is the single character c. 
void reserve(size_t n) 
Requests that the string's capacity be changed; the postcondition for this member function is that, after it is called, capacity() >= n. You may request that a string decrease its capacity by calling reserve() with an argument less than the current capacity. (If you call reserve() with an argument less than the string's size, however, the capacity will only be reduced to size(). A string's size can never be greater than its capacity.) reserve() throws length_error if n > max_size(). 
basic_string& insert(size_type pos, const basic_string& s) 
If pos > size(), throws out_of_range. Otherwise, equivalent to insert(begin() + pos, s.begin(), s.end()). 
basic_string& insert(size_type pos, const basic_string& s, size_type pos1, size_type n) 
If pos > size() or pos1 > s.size(), throws out_of_range. Otherwise, equivalent to insert(begin() + pos, s.begin() + pos1, s.begin() + pos1 + min(n, s.size() – pos1)). 
basic_string& insert(size_type pos, const charT* s) 
If pos > size(), throws out_of_range. Otherwise, equivalent to insert(begin() + pos, s, s + traits::length(s)) 
basic_string& insert(size_type pos, const charT* s, size_type n) 
If pos > size(), throws out_of_range. Otherwise, equivalent to insert(begin() + pos, s, s + n). 
basic_string& insert(size_type pos, size_type n, charT c) 
If pos > size(), throws out_of_range. Otherwise, equivalent to insert(begin() + pos, n, c). 
basic_string& append(const basic_string& s) 
Equivalent to insert(end(), s.begin(), s.end()). 
basic_string& append(const basic_string& s, size_type pos, size_type n) 
If pos > s.size(), throws out_of_range. Otherwise, equivalent to insert(end(), s.begin() + pos, s.begin() + pos + min(n, s.size() – pos)). 
basic_string& append(const charT* s) 
Equivalent to insert(end(), s, s + traits::length(s)). 
basic_string& append(const charT* s, size_type n) 
Equivalent to insert(end(), s, s + n). 
basic_string& append(size_type n, charT c) 
Equivalent to insert(end(), n, c). 
template<class InputIterator> basic_string& append(InputIterator first, InputIterator last) 
Equivalent to insert(end(), first, last). 
void push_back(charT c) 
Equivalent to insert(end(), c) 
basic_string& operator+=(const basic_string& s) 
Equivalent to append(s). 
basic_string& operator+=(const charT* s) 
Equivalent to append(s) 
basic_string& operator+=(charT c) 
Equivalent to push_back(c) 
basic_string& erase(size_type pos = 0, size_type n = npos) 
If pos > size(), throws out_of_range. Otherwise, equivalent to erase(begin() + pos, begin() + pos + min(n, size() – pos)). 
basic_string& assign(const basic_string& s) 
Synonym for operator= 
basic_string& assign(const basic_string& s, size_type pos, size_type n) 
Equivalent to (but probably faster than) clear() followed by insert(0, s, pos, n). 
basic_string& assign(const charT* s, size_type n) 
Equivalent to (but probably faster than) clear() followed by insert(0, s, n). 
basic_string& assign(const charT* s) 
Equivalent to (but probably faster than) clear() followed by insert(0, s). 
basic_string& replace(size_type pos, size_type n, const basic_string& s) 
Equivalent to erase(pos, n) followed by insert(pos, s). 
basic_string& replace(size_type pos, size_type n, const basic_string& s, size_type pos1, size_type n1) 
Equivalent to erase(pos, n) followed by insert(pos, s, pos1, n1). 
basic_string& replace(size_type pos, size_type n, const charT* s, size_type n1) 
Equivalent to erase(pos, n) followed by insert(pos, s, n1). 
basic_string& replace(size_type pos, size_type n, const charT* s) 
Equivalent to erase(pos, n) followed by insert(pos, s). 
basic_string& replace(size_type pos, size_type n, size_type n1, charT c) 
Equivalent to erase(pos, n) followed by insert(pos, n1, c). 
basic_string& replace(iterator first, iterator last, const basic_string& s) 
Equivalent to insert(erase(first, last), s.begin(), s.end()). 
basic_string& replace(iterator first, iterator last, const charT* s, size_type n) 
Equivalent to insert(erase(first, last), s, s + n). 
basic_string& replace(iterator first, iterator last, const charT* s) 
Equivalent to insert(erase(first, last), s, s + traits::length(s)). 
basic_string& replace(iterator first, iterator last, size_type n, charT c)  Equivalent to insert(erase(first, last), n, c). 
template<class InputIterator> basic_string& replace(iterator first, iterator last, InputIterator f, InputIterator l) 
Equivalent to insert(erase(first, last), f, l). 
size_type copy(charT* buf, size_type n, size_type pos = 0) const 
Copies at most n characters from *this to a character array. Throws out_of_range if pos > size(). Otherwise, equivalent to copy(begin() + pos, begin() + pos + min(n, size()), buf). Note that this member function does nothing other than copy characters from *this to buf; in particular, it does not terminate buf with a null character. 
size_type find(const basic_string& s, size_type pos = 0) const 
Searches for s as a substring of *this, beginning at character position pos. It is almost the same as search, except that search tests elements for equality using operator== or a userprovided function object, while this member function uses traits::eq. Returns the lowest character position N such that pos <= N and pos + s.size() <= size() and such that, for every i less than s.size(), (*this)[N + i] compares equal to s[i]. Returns npos if no such position N exists. Note that it is legal to call this member function with arguments such that s.size() > size() – pos, but such a search will always fail. 
size_type find(const charT* s, size_type pos, size_type n) const 
Searches for the first n characters of s as a substring of *this, beginning at character pos of *this. This is equivalent to find(basic_string(s, n), pos). 
size_type find(const charT* s, size_type pos = 0) const 
Searches for a nullterminated character array as a substring of *this, beginning at character pos of *this. This is equivalent to find(basic_string(s), pos). 
size_type find(charT c, size_type pos = 0) const 
Searches for the character c, beginning at character position pos. That is, returns the first character position N greater than or equal to pos, and less than size(), such that (*this)[N] compares equal to c. Returns npos if no such character position N exists. 
size_type rfind(const basic_string& s, size_type pos = npos) const 
Searches backward for s as a substring of *this. It is almost the same as find_end, except that find_end tests elements for equality using operator== or a userprovided function object, while this member function uses traits::eq. This member function returns the largest character position N such that N <= pos and N + s.size() <= size(), and such that, for every i less than s.size(), (*this)[N + i] compares equal to s[i]. Returns npos if no such position N exists. Note that it is legal to call this member function with arguments such that s.size() > size(), but such a search will always fail. 
size_type rfind(const charT* s, size_type pos, size_type n) const 
Searches backward for the first n characters of s as a substring of *this. Equivalent to rfind(basic_string(s, n), pos). 
size_type rfind(const charT* s, size_type pos = npos) const 
Searches backward for a nullterminated character array as a substring of *this. Equivalent to rfind(basic_string(s), pos). 
size_type rfind(charT c, size_type pos = npos) const 
Searches backward for the character c. That is, returns the largest character position N such that N <= pos and N < size(), and such that (*this)[N] compares equal to c. Returns npos if no such character position exists. 
size_type find_first_of(const basic_string& s, size_type pos = 0) const 
Searches within *this, beginning at pos, for the first character that is equal to any character within s. This is similar to the standard algorithm find_first_of, but differs because find_first_of compares characters using operator== or a userprovided function object, while this member function uses traits::eq. Returns the smallest character position N such that pos <= N < size(), and such that (*this)[N] compares equal to some character within s. Returns npos if no such character position exists. 
size_type find_first_of(const charT* s, size_type pos, size_type n) const 
Searches within *this, beginning at pos, for the first character that is equal to any character within the range [s, s+n). That is, returns the smallest character position N such that pos <= N < size(), and such that (*this)[N] compares equal to some character in [s, s+n). Returns npos if no such character position exists. 
size_type find_first_of(const charT* s, size_type pos = 0) const 
Equivalent to find_first_of(s, pos, traits::length(s)). 
size_type find_first_of(charT c, size_type pos = 0) const 
Equivalent to find(c, pos). 
size_type find_first_not_of(const basic_string& s, size_type pos = 0) const 
Searches within *this, beginning at pos, for the first character that is not equal to any character within s. Returns the smallest character position N such that pos <= N < size(), and such that (*this)[N] does not compare equal to any character within s. Returns npos if no such character position exists. 
size_type find_first_not_of(const charT* s, size_type pos, size_type n) const 
Searches within *this, beginning at pos, for the first character that is not equal to any character within the range [s, s+n). That is, returns the smallest character position N such that pos <= N < size(), and such that (*this)[N] does not compare equal to any character in [s, s+n). Returns npos if no such character position exists. 
size_type find_first_not_of(const charT* s, size_type pos = 0) const 
Equivalent to find_first_not_of(s, pos, traits::length(s)). 
size_type find_first_not_of(charT c, size_type pos = 0) const 
Returns the smallest character position N such that pos <= N < size(), and such that (*this)[N] does not compare equal to c. Returns npos if no such character position exists. 
size_type find_last_of(const basic_string& s, size_type pos = npos) const 
Searches backward within *this for the first character that is equal to any character within s. That is, returns the largest character position N such that N <= pos and N < size(), and such that (*this)[N] compares equal to some character within s. Returns npos if no such character position exists. 
size_type find_last_of(const charT* s, size_type pos, size_type n) const 
Searches backward within *this for the first character that is equal to any character within the range [s, s+n). That is, returns the largest character position N such that N <= pos and N < size(), and such that (*this)[N] compares equal to some character within [s, s+n). Returns npos if no such character position exists. 
size_type find_last_of(const charT* s, size_type pos = npos) const 
Equivalent to find_last_of(s, pos, traits::length(s)). 
size_type find_last_of(charT c, size_type pos = npos) const 
Equivalent to rfind(c, pos). 
size_type find_last_not_of(const basic_string& s, size_type pos = npos) const  Searches backward within *this for the first character that is not equal to any character within s. That is, returns the largest character position N such that N <= pos and N < size(), and such that (*this)[N] does not compare equal to any character within s. Returns npos if no such character position exists. 
size_type find_last_not_of(const charT* s, size_type pos, size_type n) const 
Searches backward within *this for the first character that is not equal to any character within [s, s+n). That is, returns the largest character position N such that N <= pos and N < size(), and such that (*this)[N] does not compare equal to any character within [s, s+n). Returns npos if no such character position exists. 
size_type find_last_not_of(const charT* s, size_type pos = npos) const 
Equivalent to find_last_of(s, pos, traits::length(s)). 
size_type find_last_not_of(charT c, size_type pos = npos) const 
Searches backward *this for the first character that is not equal to c. That is, returns the largest character position N such that N <= pos and N < size(), and such that (*this)[N] does not compare equal to c. 
basic_string substr(size_type pos = 0, size_type n = npos) const 
Equivalent to basic_string(*this, pos, n). 
int compare(const basic_string& s) const 
Threeway lexicographical comparison of s and *this, much like strcmp. If traits::compare(data, s.data(), min(size(), s.size())) is nonzero, then it returns that nonzero value. Otherwise returns a negative number if size() < s.size(), a positive number if size() > s.size(), and zero if the two are equal. 
int compare(size_type pos, size_type n, const basic_string& s) const 
Threeway lexicographical comparison of s and a substring of *this. Equivalent to basic_string(*this, pos, n).compare(s). 
int compare(size_type pos, size_type n, const basic_string& s, size_type pos1, size_type n1) const 
Threeway lexicographical comparison of a substring of s and a substring of *this. Equivalent to basic_string(*this, pos, n).compare(basic_string(s, pos1, n1)). 
int compare(const charT* s) const 
Threeway lexicographical comparison of s and *this. Equivalent to compare(basic_string(s)). 
int compare(size_type pos, size_type n, const charT* s, size_type len = npos) const 
Threeway lexicographical comparison of the first min(len, traits::length(s) characters of s and a substring of *this. Equivalent to basic_string(*this, pos, n).compare(basic_string(s, min(len, traits::length(s)))). 
template<class charT, class traits, class Alloc> basic_string<charT, traits, Alloc> operator+(const basic_string<charT, traits, Alloc>& s1, const basic_string<charT, traits, Alloc>& s2) 
String concatenation. Equivalent to creating a temporary copy of s, appending s2, and then returning the temporary copy. 
template<class charT, class traits, class Alloc> basic_string<charT, traits, Alloc> operator+(const charT* s1, const basic_string<charT, traits, Alloc>& s2) 
String concatenation. Equivalent to creating a temporary basic_string object from s1, appending s2, and then returning the temporary object. 
template<class charT, class traits, class Alloc> basic_string<charT, traits, Alloc> operator+(const basic_string<charT, traits, Alloc>& s1, const charT* s2) 
String concatenation. Equivalent to creating a temporary copy of s, appending s2, and then returning the temporary copy. 
template<class charT, class traits, class Alloc> basic_string<charT, traits, Alloc> operator+(charT c, const basic_string<charT, traits, Alloc>& s2) 
String concatenation. Equivalent to creating a temporary object with the constructor basic_string(1, c), appending s2, and then returning the temporary object. 
template<class charT, class traits, class Alloc> basic_string<charT, traits, Alloc> operator+(const basic_string<charT, traits, Alloc>& s1, charT c) 
String concatenation. Equivalent to creating a temporary object, appending c with push_back, and then returning the temporary object. 
template<class charT, class traits, class Alloc> bool operator==(const charT* s1, const basic_string<charT, traits, Alloc>& s2) 
String equality. Equivalent to basic_string(s1).compare(s2) == 0. 
template<class charT, class traits, class Alloc> bool operator==(const basic_string<charT, traits, Alloc>& s1, const charT* s2) 
String equality. Equivalent to basic_string(s1).compare(s2) == 0. 
template<class charT, class traits, class Alloc> bool operator!=(const charT* s1, const basic_string<charT, traits, Alloc>& s2) 
String inequality. Equivalent to basic_string(s1).compare(s2) == 0. 
template<class charT, class traits, class Alloc> bool operator!=(const basic_string<charT, traits, Alloc>& s1, const charT* s2) 
String inequality. Equivalent to !(s1 == s2). 
template<class charT, class traits, class Alloc> bool operator<(const charT* s1, const basic_string<charT, traits, Alloc>& s2) 
String comparison. Equivalent to !(s1 == s2). 
template<class charT, class traits, class Alloc> bool operator<(const basic_string<charT, traits, Alloc>& s1, const charT* s2) 
String comparison. Equivalent to !(s1 == s2). 
template<class charT, class traits, class Alloc> basic_istream<charT, traits>& operator>>(basic_istream<charT, traits>& is, basic_string<charT, traits, Alloc>& s) 
Reads s from the input stream is. Specifically, it skips whitespace, and then replaces the contents of s with characters read from the input stream. It continues reading characters until it encounters a whitespace character (in which case that character is not extracted), or until endoffile, or, if is.width() is nonzero, until it has read is.width() characters. This member function resets is.width() to zero. 
template<class charT, class traits, class Alloc> basic_ostream<charT, traits>& operator>>(basic_istream<charT, traits>& is, const basic_string<charT, traits, Alloc>& s) 
Writes s to the output stream is. It writes max(s.size(), is.width()) characters, padding as necessary. This member function resets is.width() to zero. 
template<class charT, class traits, class Alloc> basic_istream<charT, traits>& getline(basic_istream<charT, traits>& is, basic_string<charT, traits, Alloc>& s, charT delim) 
Replaces the contents of s with characters read from the input stream. It continues reading characters until it encounters the character delim (in which case that character is extracted but not stored in s ), or until end of file. Note that getline , unlike operator>>, does not skip whitespace. As the name suggests, it is most commonly used to read an entire line of text precisely as the line appears in an input file. 
template<class charT, class traits, class Alloc> basic_istream<charT, traits>& getline(basic_istream<charT, traits>& is, basic_string<charT, traits, Alloc>& s) 
Equivalent to getline(is, s, is.widen('\n\)). 
See also
rope, vector, Character Traits
Category: containers
Component type: tye
Description
Ropes are a scalable string implementation: they are designed for efficient operation that involve the string as a whole. Operations such as assignment, concatenation, and substring take time that is nearly independent of the length of the string. Unlike C strings, ropes are a reasonable representation for very long strings such as edit buffers or mail messages. [1]
Though rope s can be treated as Containers of characters, and are almost Sequences, this is rarely the most efficient way to accomplish a task. Replacing an individual character in a rope is slow: each character replacement essentially consists of two substring operations followed by two concatenation operations. Rope s primarily target a more functional programming style.
They differ from vector<char> or referencecounted string implementations in the following ways.
Advantages:
• Much faster concatenation and substring operations involving long strings. Inserting a character in the middle of a 10 megabyte rope should take on the order of 10s of microseconds, even if a copy of the original is kept, e.g. as part of an edit history. In contrast, this would take on the order of a second for conventional "flat" string representation. The time required for concatenation can be viewed as constant for most applications. It is perfectly reasonable to use a rope as the representation of a file inside a text editor.
• Potentially much better space performance. Minor modifications of a rope can share memory with the original. Rope s are allocated in small chunks, significantly reducing memory fragmentation problems introduced by large blocks.
• Assignment is simply a (possibly reference counted) pointer assignment. Unlike referencecounted copyonwrite implementations, this remains largely true even if one of the copies is subsequently slightly modified. It is very inexpensive to checkpoint old versions of a string, e.g. in an edit history.
• It is possible to view a function producing characters as a rope. Thus a piece of a rope may be a 100MByte file, which is read only when that section of the string is examined. Concatenating a string to the end of such a file does not involve reading the file. (Currently the implementation of this facility is incomplete.)
Disadvantages:
• Single character replacements in a rope are expensive. A character update requires time roughly logarithmic in the length of the string. It is implemented as two substring operations followed by two concatenations.
• A rope can be examined a character at a time through a const_iterator in amortized constant time, as for vector<char>. However this is slower than for vector<char> by a significant constant factor (roughly a factor of 5 or 10 if little processing is done on each character and the string is long). Nonconst iterators involve additional checking, and are hence a bit slower still. (We expect that eventually some common algorithms will be specialized so that this cost is not encountered. Currently only output, conversion to a C string, and the singlecharacter find member function are treated in this way.)
• Iterators are on the order of a dozen words in size. This means that copying them, though not tremendously expensive, is not a trivial operation. Avoid postincrementing iterators; use preincrement whenever possible. (The interface also provides primitives for indexing into a string using integer character positions. Passing positions around is clearly much cheaper, but this makes the indexing operation expensive, again roughly logarithmic in the length of the rope.)
Experience with previous implementations for other programming languages suggests that rope s are a good choice as the normal or default representation of strings in a program. It will occasionally be necessary to use some type of character array, such as vector<char>, in places that are particularly sensitive to the performance of traversals or inplace updates. But the use of rope s minimizes the number of cases in which program running times become intolerable due to unexpectedly long string inputs.
A rope is almost, but not quite, a Sequence. It supports random access const_iterators. Forward or backward traversals take constant time per operation. Nonconstant iterators are also provided. However, assignment through a nonconst iterator is an expensive operation (basically logarithmic time, but with a large constant). It should be avoided in frequently executed code.
In order to discourage accidental use of expensive operations, the begin and end member functions on ropes return const_iterator. If nonconst iterators are desired, the member functions mutable_begin and mutable_end should be used.
Any modification of a rope invalidates const iterators referring to the rope. Mutable iterators refer to the same position in the same rope after an update. (This may be surprising if the iterators refers to a position after an insertion point.) They remain valid unless the iterator refers to a position that is more than one past the end of the resulting rope.
Definition
Defined in the header rope, and in the backwardcompatibility header rope.h. The rope class, and the rope header, are SGI extensions; they are not part of the C++ standard.
Example
crope r(1000000, 'x'); // crope is rope<char>. wrope is rope<wchar_t>
// Builds a rope containing a million 'x's.
// Takes much less than a MB, since the
// different pieces are shared.
crope r2 = r + "abc" + r; // concatenation; takes on the order of 100s
// of machine instructions; fast
crope r3 = r2.substr(1000000, 3); // yields "abc"; fast.
crope r4 = r2.substr(1000000, 1000000); // also fast.
reverse(r2.mutable_begin(), r2.mutable_end()); // correct, but slow; may take a
// minute or more.
Template parameters
Parameter  Description  Default 

T 
The rope 's value type: usually char or wchar_t. [2]  
Alloc 
The rope 's allocator, used for all internal memory management.  alloc 
Model of
Random Access Container. Almost, but not quite, a model of Front Insertion Sequence and Back Insertion Sequence.
Type requirements
None, except for those imposed by the requirements of Random Access Container.
Public base classes
None.
Members
Member  Where defined  Description 

value_type 
Container  The rope's value type T, usually char or wchar_t. 
difference_type 
Container  A signed integral type. 
size_type 
Container  An unsigned integral type. 
reference  Container  Reference to a rope element. [3] 
const_reference 
Container  Const reference to T. [3] 
pointer 
Container  Pointer to T. [3] 
const_pointer 
Container  Const pointer to T. [3] 
const_reverse_iterator 
Reversible  Container Const iterator used to iterate backwards through a rope. 
reverse_iterator 
Reversible  Container Mutable iterator used to iterate backwards through a rope. 
iterator 
Container  Mutable random access iterator used to iterate through a rope. 
const_iterator 
Container  Const random access iterator used to iterate through a rope. 
rope(const charT* s) 
rope 
Constructs a rope from a C string. 
rope(const charT* s, size_t n) 
rope 
Constructs a rope from a (not necessarily nullterminated) array of charT. 
rope(const const_iterator& f, const const_iterator& l) 
Sequence  Creates a rope with a copy of a range. 
rope(const iterator& f, const iterator& l) 
Sequence  Creates a rope with a copy of a range. 
rope(const charT* f, const charT* l) 
Sequence  Creates a rope with a copy of a range. 
rope(charT c) 
rope 
Singlecharacter constructor. 
rope() 
Container  Default constructor. 
rope(char_producer<charT>*, size_t, bool) 
rope 
See below. 
rope(const rope& x) 
Container  The copy constructor. 
~rope() 
Container  The destructor. 
rope& operator=(const rope&x) 
Container  The assignment operator. 
void swap(rope& x) 
Container  Swaps the contents of two ropes. 
size_type size() const 
Container  Returns the size of the rope. 
size_type length() const 
rope 
Same as size 
size_type max_size() const  Container  Size of longest rope guaranteed to be representable. 
bool empty() const 
Container  Equivalent to size() == 0. 
const_iterator begin() const 
Container  Returns an const_iterator pointing to the beginning of the rope. 
const_iterator end() const 
Container  Returns an const_iterator pointing to the end of the rope. 
iterator mutable_begin() 
rope 
Returns an iterator pointing to the beginning of the rope. 
iterator mutable_end() 
rope 
Returns an iterator pointing to the end of the rope. 
const_reverse_iterator rbegin() const 
Reversible Container  Returns a const_reverse_iterator pointing to the beginning of the reversed rope 
const_reverse_iterator rend() const 
Reversible Container  Returns a const_reverse_iterator pointing to the end of the reversed rope 
iterator mutable_rbegin() 
rope 
Returns a reverse_iterator pointing to the beginning of the reversed rope. 
iterator mutable_rend() 
rope 
Returns a reverse_iterator pointing to the end of the reversed rope. 
charT operator[](size_type n) const 
Random Access  Container Returns the n'th element. 
charT at(size_type pos) const 
Random Access  Container Returns the n'th element. 
reference mutable_reference_at(size_type n) 
rope 
Returns a reference to the n th element. 
int compare(const rope&) const 
rope 
Threeway comparison. See below. 
charT front() const 
Sequence  Returns the first element. 
charT back() const 
Back Insertion Sequence  Returns the last element. 
void push_front() 
Front Insertion Sequence  Inserts a new element at the front. 
void push_back(charT) 
Back Insertion Sequence  Inserts a new element at the end. 
void pop_front() 
Front Insertion Sequence  Removes the first element. 
void pop_back() 
Back Insertion Sequence  Removes the last element. 
iterator insert(const iterator& p, const rope& x) 
rope 
Inserts the contents of x before p. 
iterator insert(const iterator& p, charT c) 
Sequence  Inserts c before p. 
iterator insert(const iterator& p) 
Sequence  Inserts charT() before p. 
iterator insert(const iterator& p, size_t n, charT c) 
Sequence  Inserts n copies of c before p. 
iterator insert(const iterator& p, const charT* s) 
rope  Inserts a C string before p. 
iterator insert(const iterator& p, const charT* s, size_t n) 
rope 
Inserts a (not necessarily nullterminated) array of charT before p. 
iterator insert(const iterator& p, const charT* f, const char* l) 
Sequence  Inserts the range [f, l) before p. 
iterator insert(const iterator& p, const const_iterator& f, const const_iterator& l) 
Sequence  Inserts the range [f, l) before p. 
iterator insert(const iterator& p, const iterator& f, const iterator& l) 
Sequence  Inserts the range [f, l) before p. 
void insert(size_t i, const rope& x) 
rope 
Inserts the contents of x before the ith element. 
void insert(size_t i, charT c) 
rope 
Inserts the character c before the ith element. 
void insert(size_t i) 
rope 
Inserts the character charT() before the ith element. 
void insert(size_t i, size_t n, charT c) 
rope 
Inserts n copies of c before the ith element. 
void insert(size_t i, const charT* s) 
rope 
Inserts a C string before the ith element. 
void insert(size_t i, const charT* s, size_t n) 
rope 
Inserts a (not necessarily nullterminated) array of charT before the ith element. 
void insert(size_t i, const charT* f, const charT* l) 
rope 
Inserts the range [f, l) before the ith element. 
void insert(size_t i, const const_iterator& f, const const_iterator& l) 
rope 
Inserts the range [f, l) before the ith element. 
void insert(size_t i, const iterator& f, const iterator& l) 
rope 
Inserts the range [f, l) before the ith element. 
void erase(const iterator& p) 
Sequence  Erases the element pointed to by p. 
void erase(const iterator& f, const iterator& l) 
Sequence  Erases the range [f, l). 
void erase(size_t i, size_t n) 
rope 
Erases n elements, starting with the ith element. 
append(const charT* s) 
rope 
Appends a C string. 
append(const charT* s, size_t) 
rope 
Appends a (not necessarily nullterminated) array of charT. 
append(const charT* f, const charT* l) 
rope 
Appends a range. 
append(charT c) 
rope 
Appends the character c. 
append() 
rope 
Appends the character charT(). 
append(size_t n, charT c) 
rope 
Appends n copies of c. 
append(const rope& x) 
rope 
Appends the rope x. 
void replace(const iterator& f, const iterator& l, const rope&) 
rope 
See below. 
void replace(const iterator& f, const iterator& l, charT) 
rope 
See below. 
void replace(const iterator& f, const iterator& l, const charT* s) 
rope 
See below. 
void replace(const iterator& f, const iterator& l, const charT* s, size_t n) 
rope 
See below. 
void replace(const iterator& f1, const iterator& l1, const charT* f2, const charT* l2) 
rope 
See below. 
void replace(const iterator& f1, const iterator& l1, const const_iterator& f2, const const_iterator& l2) 
rope 
See below. 
void replace(const iterator& f1, const iterator& l1, const iterator& f2, const iterator& l2) 
rope 
See below. 
void replace(const iterator& p, const rope& x) 
rope 
See below. 
void replace(const iterator& p, charT c) 
rope 
See below. 
void replace(const iterator& p, const charT* s) 
rope 
See below. 
void replace(const iterator& p, const charT* s, size_t n) 
rope 
See below. 
void replace(const iterator& p, const charT* f, const charT* l) 
rope 
See below. 
void replace(const iterator& p, const_iterator f, const_iterator l) 
rope 
See below. 
void replace(const iterator& p, iterator f, iterator l) 
rope 
See below. 
void replace(size_t i, size_t n, const rope& x) 
rope 
See below. 
void replace(size_t i, size_t n, const charT* s, size_t n) 
rope 
See below. 
void replace(size_t i, size_t n, charT c) 
rope 
See below. 
void replace(size_t i, size_t n, const charT* s) 
rope 
See below. 
void replace(size_t i, size_t n, const charT* f, const charT* l) 
rope 
See below. 
void replace(size_t i, size_t n, const const_iterator& f, const const_iterator& l) 
rope 
See below. 
void replace(size_t i, size_t n, const iterator& f, const iterator& l) 
rope 
See below. 
void replace(size_t i, charT c) 
rope 
See below. 
void replace(size_t i, const rope& x) 
rope 
See below. 
void replace(size_t i, const charT* s) 
rope 
See below. 
void replace(size_t i, const charT* s, size_t n) 
rope 
See below. 
void replace(size_t i, const charT* f, const charT* l) 
rope 
See below. 
void replace(size_t i, const const_iterator& f, const const_iterator& l) 
rope 
See below. 
void replace(size_t i, const iterator& f, const iterator& l) 
rope 
See below. 
rope substr(iterator f) const 
rope 
See below. 
rope substr(const_iterator f) const 
rope 
See below. 
rope substr(iterator f, iterator l) const 
rope 
See below. 
rope substr(const_iterator f, const_iterator l) const 
rope 
See below. 
rope substr(size_t i, size_t n = 1) const 
rope 
See below. 
void copy(charT* buf) const 
rope 
Copies a rope into an array of charT. 
size_type copy(size_type pos, size_type n, charT* buf) 
rope 
Copies a rope into an array of charT. 
const charT* c_str() const 
rope 
See below. 
void delete_c_str() 
rope 
See below. 
rope operator+(const rope& L, const rope&R) 
rope 
Concatenates L and R. This is a global function, not a member function. 
rope& operator+=(rope& L, const rope& R) 
rope 
Appends R to L. This is a global function, not a member function. 
rope operator+(const rope& L, const charT* s) 
rope 
Concatenates L and s. This is a global function, not a member function. 
rope& operator+=(rope& L, const charT* s) 
rope 
Appends s to L. This is a global function, not a member function. 
rope operator+(const rope& L, charT c) 
rope 
Concatenates L and c. This is a global function, not a member function. 
rope& operator+=(rope& L, charT c) 
rope 
Appends c to L. This is a global function, not a member function. 
bool operator<(const rope&, const rope&) 
Forward Container  Lexicographical comparison. This is a global function, not a member function. 
bool operator==(const rope&, const rope*) 
Forward Container  Tests two ropes for equality. This is a global function, not a member function. 
ostream& operator<<(ostream& os, rope x) 
rope 
Outputs x to the stream os. This is a global function, not a member function. 
New members
These members are not defined in the Random Access Container requirements, but are specific to rope:
Function  Description 

rope(const charT* s) 
Constructs a rope from a C string. The rope consists of the sequence of characters starting with *s up to, but not including, the first null character. 
rope(const charT* s, size_t n) 
Constructs a rope from an array of charT. The rope consists of the characters in the range [s, s + n). Note that this range is permitted to contain embedded null characters. 
rope(charT c) 
Constructs a rope consisting of the single character c. 
rope(char_producer<charT>* cp, size_t n, bool destroy) 
Constructs a rope of size n, whose characters are computed as needed by cp. The object *cp must be valid as long as any reference to the resulting rope, or a rope derived from it, may be used. If destroy is true, then delete cp will be executed automatically once cp is no longer needed. Typically destroy will be true unless cp is a pointer to statically allocated storage. It is rarely safe to allocate *cp on the stack. 
size_type length() const 
Synonym for size 
iterator mutable_begin() 
Returns an iterator pointing to the beginning of the rope. This member function exists because mutable rope iterators are much more expensive than constant rope iterators. 
iterator mutable_end() 
Returns an iterator pointing to the end of the rope. This member function exists because mutable rope iterators are much more expensive than constant rope iterators. 
iterator mutable_rbegin() 
Returns a reverse_iterator pointing to the beginning of the reversed rope. This member function exists because mutable rope iterators are much more expensive than constant rope iterators. 
iterator mutable_rend() 
Returns a reverse_iterator pointing to the end of the reversed rope. This member function exists because mutable rope iterators are much more expensive than constant rope iterators. 
reference mutable_reference_at(size_type n) 
Returns a reference to the n th element. This member function exists because mutable references to rope elements have fairly high overhead. 
int compare(const rope& x) 
Threeway comparison, much like the function strcmp from the standard C library. Returns a negative number if *this is lexicographically less than x, a positive number if *this is lexicographically greater than x, and zero if neither rope is lexicographically less than the other. 
iterator insert(const iterator& p, const rope& x) 
Inserts the contents of the ropex immediately before the position p. 
iterator insert(const iterator& p, const charT* s) 
Inserts a C string immediately before the position p. The elements that are inserted are the sequence of characters starting with *s and up to, but not including, the first null character. 
iterator insert(const iterator& p, const charT* s, size_t n) 
Inserts an array of charT. The elements that are inserted are the range [s, s + n). Note that this range is permitted to contain embedded null characters. 
void insert(size_t i, const rope& x) 
Inserts the contents of the rope x immediately before the ith element. 
void insert(size_t i, size_t n, charT c) 
Inserts n copies of c immediately before the ith element. 
void insert(size_t i, const charT* s) 
Inserts a C string immediately before the ith element. The elements that are inserted are the sequence of characters starting with *s and up to, but not including, the first null character. 
void insert(size_t i, const charT* s, size_t n) 
Inserts an array of charT immediately before the ith element. The elements that are inserted are the range [s, s + n). Note that this range is permitted to contain embedded null characters. 
void insert(size_t i, charT c) 
Inserts the character c immediately before the ith element. 
void insert(size_t i) 
Inserts the character charT() immediately before the ith element. 
void insert(size_t i, const charT* f, const charT* l) 
Inserts the range [f, l) immediately before the ith element. 
void insert(size_t i, const const_iterator& f, const const_iterator& l) 
Inserts the range [f, l) immediately before the ith element. 
void insert(size_t i, const iterator& f, const iterator& l) 
Inserts the range [f, l) immediately before the ith element. 
void erase(size_t i, size_t n) 
Erases n elements, starting with the ith element. 
append(const charT* s) 
Adds a C string to the end of the rope. The elements that are inserted are the sequence of characters starting with *s and up to, but not including, the first null character. 
append(const charT* s, size_ nt) 
Adds an array of charT to the end of the rope. The elements that are inserted are the range [s, s + n). Note that this range is permitted to contain embedded null characters. 
append(const charT* f, const charT* l) 
Adds the elements in the range [f, l) to the end of the rope. 
append(charT c) 
Adds the character c to the end of the rope. 
append() 
Adds the character charT() to the end of the rope. 
append(const rope& x) 
Adds the contents of the rope x to the end of *this. 
append(size_t n, charT c) 
Adds n copies of c to the end of *this. 
void replace(const iterator& f, const iterator& l, const rope& x) 
Replaces the elements in the range [f, l) with the elements in x. 
void replace(const iterator& f, const iterator& l, charT c) 
Replaces the elements in the range [f, l) with the single character c. 
void replace(const iterator& f, const iterator& l, const charT* s) 
Replaces the elements in the range [f, l) with a C string: the sequence of characters beginning with *s and up to, but not including, the first null character. 
void replace(const iterator& f, const iterator& l, const charT* s, size_t n) 
Replaces the elements in the range [f, l) with the elements in the range [s, s + n). 
void replace(const iterator& f1, const iterator& l1, const charT* f2, const charT* l2) 
Replaces the elements in the range [f1, l1) with the elements in the range [f2, l2). 
void replace(const iterator& f1, const iterator& l1, const const_iterator& f2, const const_iterator& l2) 
Replaces the elements in the range [f1, l1) with the elements in the range [f2, l2). 
void replace(const iterator& f1, const iterator& l1, const iterator& f2, const iterator& l2) 
Replaces the elements in the range [f1, l1) with the elements in the range [f2, l2). 
void replace(const iterator& p, const rope& x) 
Replaces the element pointed to by p with the elements in x. 
void replace(const iterator& p, charT c) 
Replaces the element pointed to by p with the single character c. 
void replace(const iterator& p, const charT* s) 
Replaces the element pointed to by p with a C string: the sequence of characters beginning with *s and up to, but not including, the first null character. 
void replace(const iterator& p, const charT* s, size_t n) 
Replaces the element pointed to by p with the elements in the range [s, s + n). 
void replace(const iterator& p, const charT* f, const charT* l) 
Replaces the element pointed to by p with the elements in the range [f, l). 
void replace(const iterator& p, const_iterator f, const_iterator l) 
Replaces the element pointed to by p with the elements in the range [f, l). 
void replace(const iterator& p, iterator f, iterator l) 
Replaces the element pointed to by p with the elements in the range [f, l). 
void replace(size_t i, size_t n, const rope& x) 
Replaces the n elements beginning with the ith element with the elements in x. 
void replace(size_t i, size_t n, charT c) 
Replaces the n elements beginning with the ith element with the single character c. 
void replace(size_t i, size_t n, const charT* s) 
Replaces the n elements beginning with the ith element with an array of charT: the sequence of characters beginning with *s and up to, but not including, the first null character. 
void replace(size_t i, size_t n1, const charT* s, size_t n2) 
Replaces the n1 elements beginning with the ith element with the elements in the range [s, s + n2). 
void replace(size_t i, size_t n, const charT* f, const charT* l) 
Replaces the n elements beginning with the ith element with the characters in the range [f, l). 
void replace(size_t i, size_t n, const const_iterator& f, const const_iterator& l) 
Replaces the n elements beginning with the ith element with the characters in the range [f, l). 
void replace(size_t i, size_t n, const iterator& f, const iterator& l) 
Replaces the n elements beginning with the ith element with the characters in the range [f, l). 
void replace(size_t i, charT c) 
Replaces the ith element with the character c. 
void replace(size_t i, const rope& x) 
Replaces the ith element with elements from the rope x. 
void replace(size_t i, const charT* s) 
Replaces the ith element with a C string: the sequence of characters beginning with *s and up to, but not including, the first null character. 
void replace(size_t i, const charT* s, size_t n) 
Replaces the ith element with the elements in the range [s, s + n). 
void replace(size_t i, const charT* f, const charT* l) 
Replaces the ith element with the range [f, l). 
void replace(size_t i, const const_iterator& f, const const_iterator& l) 
Replaces the ith element with the range [f, l). 
void replace(size_t i, const iterator& f, const iterator& l) 
Replaces the ith element with the range [f, l). 
rope substr(iterator f) const 
Returns a new rope with a single element, *f. [4] 
rope substr(const_iterator f) const 
Returns a new rope with a single element, *f. [4] 
rope substr(iterator f, iterator l) const  Returns a new rope that consists of the range [f, l). [4] 
rope substr(const_iterator f, const_iterator l) const 
Returns a new rope that consists of the range [f, l). [4] 
rope substr(size_t i, size_t n = 1) const 
Returns a new rope whose elements are the n characters starting at the position i. [4]. 
void copy(charT* buf) const 
Copies the characters in a rope into buf. 
size_type copy(size_type pos, size_type n, charT* buf) 
Copies n characters, starting at position pos in the rope, into buf. If the rope contains fewer than pos + n characters, then instead it only copies size() – pos characters. 
const charT* c_str() const 
Returns a pointer to a nullterminated sequence of characters that contains all of the characters in a rope. [5] [6] The resulting sequence of characters is valid at least as long as the rope remains valid and unchanged. Note that the first invocation of this operation on long strings is slow: it is linear in the length of the rope. 
void delete_c_str() 
Reclaims the internal storage used by c_str. Note that this invalidates the pointer that c_str returns. 
rope operator+(const rope& L, const rope& R) 
Returns a new rope consisting of the concatenation of L and R. This is a global function, not a member function. 
rope& operator+=(rope& L, const rope& R) 
Modifies L by appending R, and returns L. This is a global function, not a member function. 
rope operator+(const rope& L, const charT* s) 
Returns a new rope consisting of the concatenation of L and all of the characters from s up to, but not including, the first null character. This is a global function, not a member function. 
rope& operator+=(rope& L, const charT* s) 
Modifies L by appending the characters from s up to, but not including, the first null character. The return value is L. This is a global function, not a member function. 
rope operator+(const rope& L, charT c) 
Returns a new rope consisting of L with the character c appended to it. This is a global function, not a member function. 
rope& operator+=(rope& L, charT c) 
Modifies L by appending the character c. This is a global function, not a member function. 
ostream& operator<<(ostream& os, rope x) 
Outputs x to the stream os. This is a global function, not a member function. 
Notes
[1] For a detailed discussion of the rope data structure, see H.J. Boehm, R. Atkinson, and M. Plass, "Ropes: An Alternative to Strings", Software Practice and Experience 25(12):1315, 1995.
[2] Since the value type is usually either char or wchar_t, the library introduces two abbreviations: crope is a typedef for rope<char>, and wrope is a typedef for rope<wchar_t>.
[3] Rope::reference is not value_type&, but a proxy type. In fact, reference is a typedef for the nested class charT_ref_proxy. Const_reference, however, is simply const value_type&. Similarly, const_pointer is just const value_type* but pointer is a proxy type. If r is an object of type reference, then &r is of type pointer.
[4] Note that the return value of substr is conceptually a distinct rope: the two rope s may share storage, but this is a hidden implementation detail. If you modify a rope returned by substr, this will not change the value of the original rope.
[5] The final const qualifier in the member function c_str() is conceptually slightly inaccurate in the interest of conformance to the basic_string interface in the draft C++ standard; the rope is updated to cache the converted string.
[6] Concurrent calls to c_str() are allowed; the cache is updated atomically.
See also
Random Access Container, Sequence, vector, sequence_buffer
Categories: containers, adaptors
Component type: type
Description
A stack is an adaptor that provides a restricted subset of Container functionality: it provides insertion, removal, and inspection of the element at the top of the stack. Stack is a "last in first out" (LIFO) data structure: the element at the top of a stack is the one that was most recently added. [1] Stack does not allow iteration through its elements. [2]
Stack is a container adaptor, meaning that it is implemented on top of some underlying container type. By default that underlying type is deque, but a different type may be selected explicitly.
Example
int main() {
stack<int> S;
S.push(8);
S.push(7);
S.push(4);
assert(S.size() == 3);
assert(S.top() == 4);
S.pop();
assert(S.top() == 7);
S.pop();
assert(S.top() == 8);
S.pop();
assert(S.empty());
}
Definition
Defined in the standard header stack, and in the nonstandard backwardcompatibility header stack.h.
Template parameters
Parameter  Description  Default 

T 
The type of object stored in the stack.  
Sequence 
The type of the underlying container used to implement the stack.  deque<T> 
Model of
Assignable, Default Constructible
Type requirements
• T is a model of Assignable.
• Sequence is a model of Back Insertion Sequence.
• Sequence::value_type is the same type as T.
• If operator== is used, then T is a model of Equality Comparable
• If operator< is used, then T is a model of LessThan Comparable.
Public base classes
None.
Members
Member  Where defined  Description 

value_type 
stack 
See below. 
size_type 
stack 
See below. 
stack() 
Default Constructible  The default constructor. Creates an empty stack. 
stack(const stack&) 
Assignable  The copy constructor. 
stack& operator=(const stack&) 
Assignable  The assignment operator. 
bool empty() const 
stack 
See below. 
size_type size() const 
stack 
See below. 
value_type& top() 
stack 
See below. 
const value_type& top() const 
stack 
See below. 
void push(const value_type&) 
stack 
See below. 
void pop() [3] 
stack 
See below. 
bool operator==(const stack&, const stack&) 
stack 
See below. 
bool operator<(const stack&, const stack&) 
stack 
See below. 
New members
These members are not defined in the Assignable and Default Constructible requirements, but are specific to stack.
Member  Description 

value_type 
The type of object stored in the stack. This is the same as T and Sequence::value_type. 
size_type 
An unsigned integral type. This is the same as Sequence::size_type. 
bool empty() const 
Returns true if the stack contains no elements, and false otherwise. S.empty() is equivalent to S.size() == 0. 
size_type size() const 
Returns the number of elements contained in the stack. 
value_type& top() 
Returns a mutable reference to the element at the top of the stack. Precondition: empty() is false. 
const value_type& top() const 
Returns a const reference to the element at the top of the stack. Precondition: empty() is false. 
void push(const value_type& x) 
Inserts x at the top of the stack. Postconditions: size() will be incremented by 1, and top() will be equal to x. 
void pop() 
Removes the element at the top of the stack. [3] Precondition: empty() is false. Postcondition: size() will be decremented by 1. 
bool operator==(const stack&, const stack&) 
Compares two stacks for equality. Two stacks are equal if they contain the same number of elements and if they are equal elementbyelement. This is a global function, not a member function. 
bool operator<(const stack&, const stack&) 
Lexicographical ordering of two stacks. This is a global function, not a member function. 
Notes
[1] Stacks are a standard data structure, and are discussed in all algorithm books. See, for example, section 2.2.1 of Knuth. (D. E. Knuth, The Art of Computer Programming. Volume 1: Fundamental Algorithms, second edition. AddisonWesley, 1973.)
[2] This restriction is the only reason for stack to exist at all. Note that any Front Insertion Sequence or Back Insertion Sequence can be used as a stack; in the case of vector, for example, the stack operations are the member functions back, push_back, and pop_back. The only reason to use the container adaptor stack instead is to make it clear that you are performing only stack operations, and no other operations.
[3] One might wonder why pop() returns void, instead of value_type. That is, why must one use top() and pop() to examine and remove the top element, instead of combining the two in a single member function? In fact, there is a good reason for this design. If pop() returned the top element, it would have to return by value rather than by reference: return by reference would create a dangling pointer. Return by value, however, is inefficient: it involves at least one redundant copy constructor call. Since it is impossible for pop() to return a value in such a way as to be both efficient and correct, it is more sensible for it to return no value at all and to require clients to use top() to inspect the value at the top of the stack.
See also
queue, priority_queue, Container, Sequence
Categories: containers, adaptors
Component type: type
Description
A queue is an adaptor that provides a restricted subset of Container functionality A queue is a "first in first out" (FIFO) data structure. [1] That is, elements are added to the back of the queue and may be removed from the front; Q.front() is the element that was added to the queue least recently. Queue does not allow iteration through its elements. [2]
Queue is a container adaptor, meaning that it is implemented on top of some underlying container type. By default that underlying type is deque, but a different type may be selected explicitly.
Example
int main() {
queue<int> Q;
Q.push(8);
Q.push(7);
Q.push(6);
Q.push(2);
assert(Q.size() == 4);
assert(Q.back() == 2);
assert(Q.front() == 8);
Q.pop();
assert(Q.front() == 7);
Q.pop();
assert(Q.front() == 6);
Q.pop();
assert(Q.front() == 2);
Q.pop();
assert(Q.empty());
}
Definition
Defined in the standard header queue, and in the nonstandard backwardcompatibility header stack.h.
Template parameters
Parameter  Description  Default 

T 
The type of object stored in the queue.  
Sequence 
The type of the underlying container used to implement the queue.  deque<T> 
Model of
Assignable, Default Constructible
Type requirements
• T is a model of Assignable.
• Sequence is a model of Front Insertion Sequence.
• Sequence is a model of Back Insertion Sequence.
• Sequence::value_type is the same type as T.
• If operator== is used, then T is a model of Equality Comparable
• If operator< is used, then T is a model of LessThan Comparable.
Public base classes
None.
Members
Member  Where defined  Description 

value_type 
queue 
See below. 
size_type 
queue 
See below. 
queue() 
Default Constructible  The default constructor. Creates an empty queue. 
queue(const queue&) 
Assignable  The copy constructor. 
queue& operator=(const queue&) 
Assignable  The assignment operator. 
bool empty() const 
queue 
See below. 
size_type size() const 
queue 
See below. 
value_type& front() 
queue 
See below. 
const value_type& front() const 
queue 
See below. 
value_type& back() 
queue 
See below. 
const value_type& back() const 
queue 
See below. 
void push(const value_type&) 
queue 
See below. 
void pop() [3] 
queue 
See below. 
bool operator==(const queue&, const queue&) 
queue 
See below. 
bool operator<(const queue&, const queue&) 
queue 
See below. 
New members
These members are not defined in the Assignable and Default Constructible requirements, but are specific to queue.
Member  Description 

value_type 
The type of object stored in the queue. This is the same as T and Sequence::value_type. 
size_type 
An unsigned integral type. This is the same as Sequence::size_type. 
bool empty() const 
Returns true if the queue contains no elements, and false otherwise. Q.empty() is equivalent to Q.size() == 0. 
size_type size() const  Returns the number of elements contained in the queue. 
value_type& front() 
Returns a mutable reference to the element at the front of the queue, that is, the element least recently inserted. Precondition: empty() is false. 
const value_type& front() const 
Returns a const reference to the element at the front of the queue, that is, the element least recently inserted. Precondition: empty() is false. 
value_type& back() 
Returns a mutable reference to the element at the back of the queue, that is, the element most recently inserted. Precondition: empty() is false. 
const value_type& back() const 
Returns a const reference to the element at the back of the queue, that is, the element most recently inserted. Precondition: empty() is false. 
void push(const value_type& x) 
Inserts x at the back of the queue. Postconditions: size() will be incremented by 1, and back() will be equal to x. 
void pop() 
Removes the element at the front of the queue. [3] Precondition: empty() is false. Postcondition: size() will be decremented by 1. 
bool operator==(const queue&, const queue&) 
Compares two queues for equality. Two queues are equal if they contain the same number of elements and if they are equal elementbyelement. This is a global function, not a member function. 
bool operator<(const queue&, const queue&) 
Lexicographical ordering of two queues. This is a global function, not a member function. 
Notes
[1] Queues are a standard data structure, and are discussed in all algorithm books. See, for example, section 2.2.1 of Knuth. (D. E. Knuth, The Art of Computer Programming. Volume 1: Fundamental Algorithms, second edition. AddisonWesley, 1973.)
[2] This restriction is the only reason for queue to exist at all. Any container that is both a front insertion sequence and a back insertion sequence can be used as a queue; deque, for example, has member functions front, back, push_front, push_back, pop_front, and pop_back The only reason to use the container adaptor queue instead of the container deque is to make it clear that you are performing only queue operations, and no other operations.
[3] One might wonder why pop() returns void, instead of value_type. That is, why must one use front() and pop() to examine and remove the element at the front of the queue, instead of combining the two in a single member function? In fact, there is a good reason for this design. If pop() returned the front element, it would have to return by value rather than by reference: return by reference would create a dangling pointer. Return by value, however, is inefficient: it involves at least one redundant copy constructor call. Since it is impossible for pop() to return a value in such a way as to be both efficient and correct, it is more sensible for it to return no value at all and to require clients to use front() to inspect the value at the front of the queue.
See also
stack, priority_queue, deque, Container, Sequence
priority_queue<T, Sequence, Compare>
Categories: containers, adaptors
Component type: type
Description
A priority_queue is an adaptor that provides a restricted subset of Container functionality: it provides insertion of elements, and inspection and removal of the top element. It is guaranteed that the top element is the largest element in the priority_queue, where the function object Compare is used for comparisons. [1] Priority_queue does not allow iteration through its elements. [2]
Priority_queue is a container adaptor, meaning that it is implemented on top of some underlying container type. By default that underlying type is vector, but a different type may be selected explicitly.
Example
int main() {
priority_queue<int> Q;
Q.push(1);
Q.push(4);
Q.push(2);
Q.push(8);
Q.push(5);
Q.push(7);
assert(Q.size() == 6);
assert(Q.top() == 8);
Q.pop();
assert(Q.top() == 7);
Q.pop();
assert(Q.top() == 5);
Q.pop();
assert(Q.top() == 4);
Q.pop();
assert(Q.top() == 2);
Q.pop();
assert(Q.top() == 1);
Q.pop();
assert(Q.empty());
}
Definition
Defined in the standard header queue, and in the nonstandard backwardcompatibility header stack.h.
Template parameters
Parameter  Description  Default 

T 
The type of object stored in the priority queue.  
Sequence 
The type of the underlying container used to implement the priority queue.  vector<T> 
Compare 
The comparison function used to determine whether one element is smaller than another element. If Compare(x,y) is true, then x is smaller than y. The element returned by Q.top() is the largest element in the priority queue. That is, it has the property that, for every other element x in the priority queue, Compare(Q.top(), x) is false.  less<T> 
Model of
Assignable, Default Constructible
Type requirements
• T is a model of Assignable.
• Sequence is a model of Sequence.
• Sequence is a model of Random Access Container.
• Sequence::value_type is the same type as T.
• Compare is a model of Binary Predicate.
• Compare induces a strict weak ordering, as defined in the LessThan Comparable requirements, on its argument type.
• T is convertible to Compare's argument type.
Public base classes
None.
Members
Member  Where defined  Description 

value_type 
priority_queue 
See below. 
size_type 
priority_queue 
See below. 
priority_queue() 
Default Constructible  The default constructor. Creates an empty priority_queue, using Compare() as the comparison function. 
priority_queue(const priority_queue&) 
Assignable  The copy constructor. 
priority_queue(const Compare&) 
priority_queue 
See below. 
priority_queue(const value_type*, const value_type*) 
priority_queue 
See below. 
priority_queue(const value_type*, const value_type*, const Compare&) 
priority_queue 
See below. 
priority_queue& operator=(const priority_queue&) 
Assignable  The assignment operator. 
bool empty() const 
priority_queue 
See below. 
size_type size() const 
priority_queue 
See below. 
const value_type& top() const 
priority_queue 
See below. 
void push(const value_type&) 
priority_queue 
See below. 
void pop() [3] 
priority_queue 
See below. 
New members
These members are not defined in the Assignable and Default Constructible requirements, but are specific to priority_queue.
Member  Description 

value_type 
The type of object stored in the priority_queue. This is the same as T and Sequence::value_type. 
size_type 
An unsigned integral type. This is the same as Sequence::size_type. 
priority_queue(const Compare& comp) 
The constructor. Creates an empty priority_queue, using comp as the comparison function. The default constructor uses Compare() as the comparison function. 
priority_queue(const value_type* first, const value_type* last) 
The constructor. Creates a priority_queue initialized to contain the elements in the range [first, last), and using Compare() as the comparison function. 
priority_queue(const value_type* first, const value_type* last, const Compare& comp) 
The constructor. Creates a priority_queue initialized to contain the elements in the range [first, last), and using comp as the comparison function. 
bool empty() const 
Returns true if the priority_queue contains no elements, and false otherwise. S.empty() is equivalent to S.size() == 0. 
size_type size() const 
Returns the number of elements contained in the priority_queue. 
const value_type& top() const 
Returns a const reference to the element at the top of the priority_queue. The element at the top is guaranteed to be the largest element in the priority queue, as determined by the comparison function Compare. That is, for every other element x in the priority_queue, Compare(Q.top(), x) is false. Precondition: empty() is false. 
void push(const value_type& x) 
Inserts x into the priority_queue. Postcondition: size() will be incremented by 1. 
void pop() 
Removes the element at the top of the priority_queue, that is, the largest element in the priority_queue. [3] Precondition: empty() is false. Postcondition: size() will be decremented by 1. 
Notes
[1] Priority queues are a standard concept, and can be implemented in many different ways; this implementation uses heaps. Priority queues are discussed in all algorithm books; see, for example, section 5.2.3 of Knuth. (D. E. Knuth, The Art of Computer Programming. Volume 3: Sorting and Searching. AddisonWesley, 1975.)
[2] This restriction is the only reason for priority_queue to exist at all. If iteration through elements is important, you can either use a vector that is maintained in sorted order, or a set, or a vector that is maintained as a heap using make_heap, push_heap, and pop_heap. Priority_queue is, in fact, implemented as a random access container that is maintained as a heap. The only reason to use the container adaptor priority_queue , instead of performing the heap operations manually, is to make it clear that you are never performing any operations that might violate the heap invariant.
[3] One might wonder why pop() returns void, instead of value_type. That is, why must one use top() and pop() to examine and remove the element at the top of the priority_queue, instead of combining the two in a single member function? In fact, there is a good reason for this design. If pop() returned the top element, it would have to return by value rather than by reference: return by reference would create a dangling pointer. Return by value, however, is inefficient: it involves at least one redundant copy constructor call. Since it is impossible for pop() to return a value in such a way as to be both efficient and correct, it is more sensible for it to return no value at all and to require clients to use top() to inspect the value at the top of the priority_queue.
See also
stack, queue, set, make_heap, push_heap, pop_heap, is_heap, sort, is_sorted, Container, Sorted Associative Container, Sequence
Category: containers
Component type: type
Description
Bitset is very similar to vector<bool> (also known as bit_vector): it contains a collection of bits, and provides constanttime access to each bit. There are two main differences between bitset and vector<bool>. First, the size of a bitset cannot be changed: bitset's template parameter N, which specifies the number of bits in the bitset, must be an integer constant. Second, bitset is not a Sequence; in fact, it is not an STL Container at all. It does not have iterators, for example, or begin() and end() member functions. Instead, bitset's interface resembles that of unsigned integers. It defines bitwise arithmetic operators such as &=, = , and ^=.
In general, bit 0 is the least significant bit and bit N1 is the most significant bit.
Example
int main() {
const bitset<12> mask(2730ul);
cout << "mask = " << mask << endl;
bitset<12> x;
cout << "Enter a 12bit bitset in binary: " << flush;
if (cin >> x) {
cout << "x = " << x << endl;
cout << "As ulong: " << x.to_ulong() << endl;
cout << "And with mask: " << (x & mask) << endl;
cout << "Or with mask: " << (x  mask) << endl;
}
}
Definition
Defined in the standard header bitset.
Template parameters
Parameter  Description 

N 
A nonzero constant of type size_t : the number of bits that the bitset contains. 
Model of
Assignable, Default Constructible, Equality Comparable
Type requirements
N is a constant integer expression of a type convertible to size_t, and N is a positive number.
Public base classes
None.
Members
Member  Where defined  Description 

reference 
bitset 
A proxy class that acts as a reference to a single bit. 
bitset() 
Default Constructible  The default constructor. All bits are initially zero. 
bitset(unsigned long val) 
bitset 
Conversion from unsigned long. 
bitset(const bitset&) 
Assignable  Copy constructor. 
bitset& operator=(const bitset&) 
Assignable  Assignment operator. 
template<class Char, class Traits, class Alloc> explicit bitset(const basic_string<Char,Traits,Alloc>& s, size_t pos = 0, size_t n = basic_string <Char,Traits,Alloc>::npos) 
bitset 
Conversion from string. 
bitset& operator&=(const bitset&) 
bitset 
Bitwise and. 
bitset& operator=(const bitset&) 
bitset 
Bitwise inclusive or. 
bitset& operator^=(const bitset&) 
bitset 
Bitwise exclusive or. 
bitset& operator<<=(size_t) 
bitset 
Left shift. 
bitset& operator>>=(size_t) 
bitset 
Right shift. 
bitset operator<<(size_t n) const 
bitset 
Returns a copy of *this shifted left by n bits. 
bitset operator>>(size_t n) const 
bitset 
Returns a copy of *this shifted right by n bits. 
bitset& set() 
bitset 
Sets every bit. 
bitset& flip() 
bitset 
Flips the value of every bit. 
bitset operator~() const 
bitset 
Returns a copy of *this with all of its bits flipped. 
bitset& reset() 
bitset 
Clears every bit. 
bitset& set(size_t n, int val = 1) 
bitset 
Sets bit n if val is nonzero, and clears bit n if val is zero. 
bitset& reset(size_t n) 
bitset 
Clears bit n. 
bitset flip(size_t n) 
bitset 
Flips bit n. 
size_t size() const 
bitset 
Returns N. 
size_t count() const 
bitset 
Returns the number of bits that are set. 
bool any() const 
bitset 
Returns true if any bits are set. 
bool none() const 
bitset 
Returns true if no bits are set. 
bool test(size_t n) const 
bitset 
Returns true if bit n is set. 
reference operator[](size_t n) 
bitset 
Returns a reference to bit n. 
bool operator[](size_t n) const 
bitset 
Returns true if bit n is set. 
unsigned long to_ulong() const 
bitset 
Returns an unsigned long corresponding to the bits in *this. 
template<class Char, class Traits, class Alloc> basic_string <Char,Traits,Alloc> to_string() const 
bitset 
Returns a string representation of *this. 
bool operator==(const bitset&) const 
Equality Comparable  The equality operator. 
bool operator!=(const bitset&) const 
Equality Comparable  The inequality operator. 
bitset operator&(const bitset&, const bitset&) 
bitset 
Bitwise and of two bitsets. This is a global function, not a member function. 
bitset operator(const bitset&, const bitset&) 
bitset 
Bitwise or of two bitsets. This is a global function, not a member function. 
bitset operator^(const bitset&, const bitset&) 
bitset 
Bitwise exclusive or of two bitsets. This is a global function, not a member function. 
template<class Char, class Traits, size_t N> basic_istream<Char,Traits>& operator>>(basic_istream<Char,Traits>&, bitset<N>&) 
bitset 
Extract a bitset from an input stream. 
template<class Char, class Traits, size_t N> basic_ostream<Char,Traits>& operator>>(basic_ostream<Char,Traits>&, const bitset<N>&) 
bitset 
Output a bitset to an output stream. 
New members
These members are not defined in the Assignable, Default Constructible, or Equality Comparable requirements, but are specific to bitset.
Member  Description 

reference 
A proxy class that acts as a reference to a single bit. It contains an assignment operator, a conversion to bool, an operator~, and a member function flip. It exists only as a helper class for bitset's operator[]. That is, it supports the expressions x = b[i], b[i] = x, b[i] = b[j], x = ~b[i] , and b[i].flip(). (Where b is a bitset and x is a bool.) 
bitset(unsigned long val) 
Conversion from unsigned long. Constructs a bitset, initializing the first min(N, sizeof(unsigned long) * CHAR_BIT) bits to the corresponding bits in val and all other bits, if any, to zero. 
template<class Char, class Traits, class Alloc> explicit bitset(const basic_string<Char,Traits,Alloc>& s, size_t pos = 0, size_t n = basic_string<Char,Traits,Alloc>::npos) 
Conversion from string. Constructs a bitset, initializing the first M bits to the corresponding characters in s, where M is defined as min(N, min(s.size() – pos, n)). Note that the highest character position in s, not the lowest, corresponds to the least significant bit. That is, character position pos + M – 1 – i corresponds to bit i. So, for example, bitset(string("1101")) is the same as bitset(13ul). This function throws out_of_range if pos > s.size(), and invalid_argument if any of the characters used to initialize the bits are anything other than 0 or 1. 
bitset& operator&=(const bitset&) 
Bitwise and. 
bitset& operator=(const bitset&) 
Bitwise inclusive or. 
bitset& operator^=(const bitset&) 
Bitwise exclusive or. 
bitset& operator<<=(size_t n) 
Left shift, where bit 0 is considered the least significant bit. Bit i takes on the previous value of bit i – n, or zero if no such bit exists. 
bitset& operator>>=(size_t n) 
Right shift, where bit 0 is considered the least significant bit. Bit i takes on the previous value of bit i + n, or zero if no such bit exists. 
bitset operator<<(size_t n) const 
Returns a copy of *this shifted left by n bits. Note that the expression b << n is equivalent to constructing a temporary copy of b and then using operator<<=. 
bitset operator>>(size_t n) const 
Returns a copy of *this shifted right by n bits. Note that the expression b >> n is equivalent to constructing a temporary copy of b and then using operator>>=. 
bitset& set() 
Sets every bit. 
bitset& flip() 
Flips the value of every bit. 
bitset operator~() const 
Returns a copy of *this with all of its bits flipped. 
bitset& reset() 
Clears every bit. 
bitset& set(size_t n, int val = 1) 
Sets bit n if val is nonzero, and clears bit n if val is zero. Throws out_of_range if n >= N. 
bitset& reset(size_t n) 
Clears bit n. Throws out_of_range if n >= N. 
bitset flip(size_t n) 
Flips bit n. Throws out_of_range if n >= N. 
size_t size() const 
Returns N. 
size_t count() const 
Returns the number of bits that are set. 
bool any() const 
Returns true if any bits are set. 
bool none() const 
Returns true if no bits are set. 
bool test(size_t n) const 
Returns true if bit n is set. Throws out_of_range if n >= N. 
reference operator[](size_t n) 
Returns a reference to bit n. Note that reference is a proxy class with an assignment operator and a conversion to bool, which allows you to use operator[] for assignment. That is, you can write both x = b[n] and b[n] = x. 
bool operator[](size_t n) const 
Returns true if bit n is set. 
unsigned long to_ulong() const 
Returns an unsigned long corresponding to the bits in *this. Throws overflow_error if it is impossible to represent *this as an unsigned long. (That is, if N is larger than the number of bits in an unsigned long and if any of the highorder bits are set. 
template<class Char, class Traits, class Alloc> basic_string <Char,Traits,Alloc> to_string() const 
Returns a string representation of *this: each character is 1 if the corresponding bit is set, and 0 if it is not. In general, character position i corresponds to bit position N – 1 – i. Note that this member function relies on two language features, member templates and explicit function template argument specification, that are not yet universally available; this member function is disabled for compilers that do not support those features. Note also that the syntax for calling this member function is somewhat cumbersome. To convert a bitset b to an ordinary string, you must write b.template to_string<char, char_traits<char>, allocator<char> >() 
bitset operator&(const bitset&, const bitset&) 
Bitwise and of two bitsets. This is a global function, not a member function. Note that the expression b1 & b2 is equivalent to creating a temporary copy of b1, using operator&=, and returning the temporary copy. 
bitset operator(const bitset&, const bitset&) 
Bitwise or of two bitsets. This is a global function, not a member function. Note that the expression b1  b2 is equivalent to creating a temporary copy of b1, using operator=, and returning the temporary copy. 
bitset operator^(const bitset&, const bitset&) 
Bitwise exclusive or of two bitsets. This is a global function, not a member function. Note that the expression b1 ^ b2 is equivalent to creating a temporary copy of b1, using operator^=, and returning the temporary copy. 
template<class Char, class Traits, size_t N> basic_istream<Char, Traits>& operator>>(basic_istream<Char,Traits>& is, bitset<N>& x) 
Extract a bitset from an input stream. This function first skips whitespace, then extracts up to N characters from the input stream. It stops either when it has successfully extracted N character, or when extraction fails, or when it sees a character that is something other than 1 (in which case it does not extract that character). It then assigns a value to the bitset in the same way as if it were initializing the bitset from a string. So, for example, if the input stream contains the characters "1100abc", it will assign the value 12ul to the bitset, and the next character read from the input stream will be a. 
template<class Char, class Traits, size_t N> basic_ostream<Char,Traits>& operator>>(basic_ostream<Char,Traits>& os, const bitset<N>& x) 
Output a bitset to an output stream. This function behaves as if it converts the bitset to a string and then writes that string to the output stream. That is, it is equivalent to os << x.template to_string<Char,Traits,allocator<Char> >() 
See also
vector, bit_vector, string
Category: iterators
Component type: overview
Summary
Iterators are a generalization of pointers: they are objects that point to other objects. As the name suggests, iterators are often used to iterate over a range of objects: if an iterator points to one element in a range, then it is possible to increment it so that it points to the next element.
Iterators are central to generic programming because they are an interface between containers and algorithms: algorithms typically take iterators as arguments, so a container need only provide a way to access its elements using iterators. This makes it possible to write a generic algorithm that operates on many different kinds of containers, even containers as different as a vector and a doubly linked list.
The STL defines several different concepts related to iterators, several predefined iterators, and a collection of types and functions for manipulating iterators.
Description
Iterators are in fact not a single concept, but six concepts that form a hierarchy: some of them define only a very restricted set of operations, while others define additional functionality. The five concepts that are actually used by algorithms are Input Iterator, Output Iterator, Forward Iterator, Bidirectional Iterator, and Random Access Iterator. A sixth concept, Trivial Iterator, is introduced only to clarify the definitions of the other iterator concepts.
The most restricted sorts of iterators are Input Iterators and Output Iterators, both of which permit "single pass" algorithms but do not necessarily support "multipass" algorithms. Input iterators only guarantee read access: it is possible to dereference an Input Iterator to obtain the value it points to, but not it is not necessarily possible to assign a new value through an input iterator. Similarly, Output Iterators only guarantee write access: it is possible to assign a value through an Output Iterator, but not necessarily possible to refer to that value.
Forward Iterators are a refinement of Input Iterators and Output Iterators: they support the Input Iterator and Output Iterator operations and also provide additional functionality. In particular, it is possible to use "multipass" algorithms with Forward Iterators. A Forward Iterator may be constant, in which case it is possible to access the object it points to but not to to assign a new value through it, or mutable , in which case it is possible to do both.
Bidirectional Iterators, like Forward Iterators, allow multipass algorithms. As the name suggests, they are different in that they support motion in both directions: a Bidirectional Iterator may be incremented to obtain the next element or decremented to obtain the previous element. A Forward Iterator, by contrast, is only required to support forward motion. An iterator used to traverse a singly linked list, for example, would be a Forward Iterator , while an iterator used to traverse a doubly linked list would be a Bidirectional Iterator.
Finally, Random Access Iterators allow the operations of pointer arithmetic: addition of arbitrary offsets, subscripting, subtraction of one iterator from another to find a distance, and so on.
Most algorithms are expressed not in terms of a single iterator but in terms of a range of iterators [1]; the notation [first, last) refers to all of the iterators from first up to, but not including, last. [2] Note that a range may be empty, i.e.first and last may be the same iterator. Note also that if there are n iterators in a range, then the notation [first, last) represents n+1 positions. This is crucial: algorithms that operate on n things frequently require n+1 positions. Linear search, for example (find) must be able to return some value to indicate that the search was unsuccessful.
Sometimes it is important to be able to infer some properties of an iterator: the type of object that is returned when it is dereferenced, for example. There are two different mechanisms to support this sort of inferrence: an older mechanism called Iterator Tags, and a newer mechanism called iterator_traits [3].
Concepts
• Trivial Iterator
• Input Iterator
• Output Iterator
• Forward Iterator
• Bidirectional Iterator
• Random Access Iterator
Types
• istream_iterator
• ostream_iterator
• reverse_iterator
• reverse_bidirectional_iterator
• insert_iterator
• front_insert_iterator
• back_insert_iterator
• iterator_traits
• input_iterator_tag
• output_iterator_tag
• forward_iterator_tag
• bidirectional_iterator_tag
• random_access_iterator_tag
• input_iterator
• output_iterator
• forward_iterator
• bidirectional_iterator
• random_access_iterator
Functions
• distance_type
• value_type
• iterator_category
• distance
• advance
• inserter
• front_inserter
• back_inserter
Notes
[1] Ranges are not a welldefined concept for Trivial Iterators, because a Trivial Iterator cannot be incremented: there is no such thing as a next element. They are also not a welldefined concept for Output Iterators, because it is impossible to compare two Output Iterators for equality. Equality is crucial to the definition of a range, because only by comparing an iterator for equality with the last element is it possible to step through a range.
[2] Sometimes the notation [first, last) refers to the iterators first, first+1, …, last1 and sometimes it refers to the objects pointed to by those iterators: *first, *(first+1), …, *(last1). In most cases it will be obvious from context which of these is meant; where the distinction is important, the notation will be qualified explicitly as "range of iterators" or "range of objects".
[3] The iterator_traits class relies on a C++ feature known as partial specialization. Many of today's compilers don't implement the complete standard; in particular, many compilers do not support partial specialization. If your compiler does not support partial specialization, then you will not be able to use iterator_traits, and you will instead have to continue using the functions iterator_category, distance_type, and value_type.
Category: iterators
Component type: concept
Description
A Trivial Iterator is an object that may be dereferenced to refer to some other object. Arithmetic operations (such as increment and comparison) are not guaranteed to be supported.
Refinement of
Assignable, Equality Comparable, Default Constructible
Associated types
Value type  The type of the value obtained by dereferencing a Trivial Iterator 
Notation
X
A type that is a model of Trivial Iterator
T
The value type of X
x, y
Object of type X
t
Object of type T
Definitions
A type that is a model of Trivial Iterator may be mutable, meaning that the values referred to by objects of that type may be modified, or constant, meaning that they may not. For example, int* is a mutable iterator type and const int* is a constant iterator type. If an iterator type is mutable, this implies that its value type is a model of Assignable; the converse, though, is not necessarily true.
A Trivial Iterator may have a singular value, meaning that the results of most operations, including comparison for equality, are undefined. The only operation that a is guaranteed to be supported is assigning a nonsingular iterator to a singular iterator.
A Trivial Iterator may have a dereferenceable value, meaning that dereferencing it yields a welldefined value. Dereferenceable iterators are always nonsingular, but the converse is not true. For example, a null pointer is nonsingular (there are well defined operations involving null pointers) even thought it is not dereferenceable.
Invalidating a dereferenceable iterator means performing an operation after which the iterator might be nondereferenceable or singular. For example, if p is a pointer, then delete p invalidates p.
Valid expressions
In addition to the expressions defined in Assignable, Equality Comparable, and Default Constructible, the following expressions must be valid.
Name  Expression  Type requirements  Return type 

Default constructor  X x 

Dereference  *x  Convertible to T [1]  
Dereference assignment  *x = t 
X is mutable  
Member access  x>m [2] 
T is a type for which x.m is defined 
Expression semantics
Name  Expression  Precondition  Semantics  Postcondition 

Default constructor  X x 
x is singular  
Dereference  *x 
x is dereferenceable  
Dereference assignment  *x = t 
x is dereferenceable  *x is a copy of t  
Member access  x>m 
x is dereferenceable  Equivalent to (*x).m 
Complexity guarantees
The complexity of operations on trivial iterators is guaranteed to be amortized constant time.
Invariants
Identity  x == y if and only if &*x == &*y 
Models
• A pointer to an object that is not part of an array.
Notes
[1] The requirement for the return type of *x is specified as "convertible to T", rather than simply T, because it sometimes makes sense for an iterator to return some sort of proxy object instead of the object that the iterator conceptually points to. Proxy objects are implementation details rather than part of an interface (one use of them, for example, is to allow an iterator to behave differently depending on whether its value is being read or written), so the value type of an iterator that returns a proxy is still T.
[2] Defining operator> for iterators depends on a feature that is part of the C++ language but that is not yet implemented by all C++ compilers. If your compiler does not yet support this feature, the workaround is to use (*it).m instead of it>m.
See also
Input Iterator, Output Iterator, Forward Iterator, Bidirectional Iterator, Random Access Iterator, Iterator Overview
Category: iterators
Component type: concept
Description
An Input Iterator is an iterator that may be dereferenced to refer to some object, and that may be incremented to obtain the next iterator in a sequence. Input Iterators are not required to be mutable.
Refinement of
Trivial iterator.
Associated types
Value type  The type of the value obtained by dereferencing an Input Iterator 
Distance type  A signed integral type used to represent the distance from one iterator to another, or the number of elements in a range. 
Notation
X
A type that is a model of Input Iterator
T
The value type of X
i, j
Object of type X
t
Object of type T
Definitions
An iterator is pasttheend if it points beyond the last element of a container. Pasttheend values are nonsingular and nondereferenceable.
An iterator is valid if it is dereferenceable or pasttheend.
An iterator i is incrementable if there is a "next" iterator, that is, if ++i is welldefined. Pasttheend iterators are not incrementable.
An Input Iterator j is reachable from an Input Iterator i if, after applying operator++ to i a finite number of times, i == j. [1]
The notation [i,j) refers to a range of iterators beginning with i and up to but not including j.
The range [i,j) is a valid range if both i and j are valid iterators, and j is reachable from i [2].
Valid expressions
In addition to the expressions defined in Trivial Iterator, the following expressions must be valid.
Name  Expression  Return type 

Preincrement  ++i 
X& 
Postincrement  (void)i++ 

Postincrement and dereference  *i++ 
T 
Expression semantics
Name  Expression  Precondition  Semantics  Postcondition 

Dereference  *t 
i is incrementable  
Preincrement  ++i 
i is dereferenceable  i is dereferenceable or pasttheend [3] [4]  
Postincrement  (void)i++ 
i is dereferenceable  Equivalent to (void)++i  i is dereferenceable or pasttheend [3] [4] 
Postincrement and dereference  *i++ 
i is dereferenceable  Equivalent to {T t = *i; ++i; return t;}  i is dereferenceable or pasttheend [3] [4] 
Complexity guarantees
All operations are amortized constant time.
Models
• istream_iterator
Notes
[1] i == j does not imply ++i == ++j.
[2] Every iterator in a valid range [i, j) is dereferenceable, and j is either dereferenceable or pasttheend. The fact that every iterator in the range is dereferenceable follows from the fact that incrementable iterators must be deferenceable.
[3] After executing ++i, it is not required that copies of the old value of i be dereferenceable or that they be in the domain of operator==.
[4] It is not guaranteed that it is possible to pass through the same input iterator twice.
See also
Output Iterator, Iterator overview
Category: iterators
Component type: concept
Description
An Output Iterator is a type that provides a mechanism for storing (but not necessarily accessing) a sequence of values. Output Iterators are in some sense the converse of Input Iterators, but they have a far more restrictive interface: they do not necessarily support member access or equality, and they do not necessarily have either an associated distance type or even a value type [1]. Intuitively, one picture of an Output Iterator is a tape: you can write a value to the current location and you can advance to the next location, but you cannot read values and you cannot back up or rewind.
Refinement of
Assignable, DefaultConstructible
Associated types
None. [1]
Notation
X
A type that is a model of Output Iterator
x, y
Object of type X
Definitions
If x is an Output Iterator of type X, then the expression *x = t; stores the value t into x. Note that operator=, like other C++ functions, may be overloaded; it may, in fact, even be a template function. In general, then, t may be any of several different types. A type T belongs to the set of value types of X if, for an object t of type T, *x = t; is welldefined and does not require performing any nontrivial conversions on t. [1]
An Output Iterator may be singular, meaning that the results of most operations, including copying and dereference assignment, are undefined. The only operation that is guaranteed to be supported is assigning a nonsingular iterator to a singular iterator.
An Output Iterator may be dereferenceable, meaning that assignment through it is defined. Dereferenceable iterators are always nonsingular, but nonsingular iterators are not necessarily dereferenceable.
Valid expressions
Name  Expression  Type requirements  Return type 

Default constructor  X x; X() 

Copy constructor  X(x) 
X 

Copy constructor  X y(x); or X y = x; 

Dereference assignment  *x = t 
t is convertible to a type in the set of value types of X. [1]  Result is not used 
Preincrement  ++x 
X& 

Postincrement  (void) x++ 
void 

Postincrement and assign  *x++ = t; 
Result is not used 
Expression semantics
Name  Expression  Precondition  Semantics  Postcondition 

Default constructor  X x; X() 
x may be singular  
Copy constructor  X(x) 
x is nonsingular  *X(x) = t is equivalent to *x = t [2]  
Copy constructor  X x(y); or X x = y; 
y is nonsingular  *y = t is equivalent to *x = t [2]  
Dereference assignment  *x = t 
x is dereferenceable. If there has been a previous assignment through x, then there has been an intervening increment. [3]  
Preincrement  ++x 
x is dereferenceable. x has previously been assigned through. If x has previously been incremented, then there has been an intervening assignment through x [3] [4]  x points to the next location into which a value may be stored  
Postincrement  (void) x++ 
x is dereferenceable. x has previously been assigned through.  Equivalent to (void) ++x  x points to the next location into which a value may be stored 
Postincrement and assign  *x++ = t; 
x is dereferenceable. If there has been a previous assignment through x, then there has been an intervening increment. [3] [4]  Equivalent to {*x = t; ++x; }  x points to the next location into which a value may be stored 
Complexity guarantees
The complexity of operations on output iterators is guaranteed to be amortized constant time.
Models
• ostream_iterator
• insert_iterator
• front_insert_iterator
• back_insert_iterator
Notes
[1] Other iterator types, including Trivial Iterator and Input Iterator, define the notion of a value type, the type returned when an iterator is dereferenced. This notion does not apply to Output Iterators, however, since the dereference operator (unary operator*) does not return a usable value for Output Iterators. The only context in which the dereference operator may be used is assignment through an output iterator: *x = t. Although Input Iterators and output iterators are roughly symmetrical concepts, there is an important sense in which accessing and storing values are not symmetrical: for an Input Iterator ыoperator* must return a unique type, but, for an Output Iterator, in the expression *x = t, there is no reason why operator= must take a unique type. [5] Consequently, there need not be any unique "value type" for Output Iterators.
[2] There should be only one active copy of a single Output Iterator at any one time. That is: after creating and using a copy x of an Output Iterator y, the original output iterator y should no longer be used.
[3] Assignment through an Output Iterator x is expected to alternate with incrementing x, and there must be an assignment through x before x is ever incremented. Any other order of operations results in undefined behavior. That is: {*x = t ; ++x; *x = t2; ++x} is acceptable, but {*x = t; ++x; ++x; *x = t2;} is not.
[4] Note that an Output Iterator need not define comparison for equality. Even if an operator== is defined, x == y need not imply ++x == ++y.
[5] If you are implementing an Output Iterator class X, one sensible way to define *x = t is to define X::operator*() to return an object of some private class X_proxy, and then to define X_proxy::operator=. Note that you may overload X_proxy::operator=, or even define it as a member template; this allows assignment of more than one type through Output Iterators of class X.
See also
Trivial Iterator, Input Iterator, Iterator overview
Category: iterators
Component type: concept
Description
A Forward Iterator is an iterator that corresponds to the usual intuitive notion of a linear sequence of values. It is possible to use Forward Iterators (unlike Input Iterators and Output Iterators) in multipass algorithms. Forward Iterators do not, however, allow stepping backwards through a sequence, but only, as the name suggests, forward.
A type that is a model of Forward Iterator may be either mutable or immutable, as defined in the Trivial Iterators requirements.
Refinement of
Input Iterator, Output Iterator
Associated types
The same as for Input Iterator
Notation
X
A type that is a model of Forward Iterator
T
The value type of X
i, j
Object of type X
t
Object of type T
Valid expressions
Forward Iterator does not define any new expressions beyond those defined in Input Iterator. However, some of the restrictions described in Input Iterator are relaxed.
Name  Expression  Return type 

Preincrement  ++i 
X& 
Postincrement  i++ 
X 
Expression semantics
Forward Iterator does not define any new expressions beyond those defined in Input Iterator. However, some of the restrictions described in Input Iterator are relaxed.
Name  Expression  Precondition  Semantics  Postcondition 

Preincrement  ++i 
i is dereferenceable  i points to the next value  i is dereferenceable or pasttheend. &i == &++i . If i == j , then ++i == ++j. [1] 
Postincrement  i++ 
i is dereferenceable  Equivalent to {X tmp = i; ++i; return tmp;}  i is dereferenceable or pasttheend. [1] 
Complexity guarantees
The complexity of operations on Forward Iterators is guaranteed to be amortized constant time.
Models
• T*
• hash_set<T>::iterator
Notes
[1] The restrictions described in Input Iterator have been removed. Incrementing a forward iterator does not invalidate copies of the old value and it is guaranteed that, if i and j are dereferenceable and i == j, then ++i == ++j. As a consequence of these two facts, it is possible to pass through the same Forward Iterator twice.
See also
Input Iterator, Output Iterator, Bidirectional Iterator, Random Access Iterator, Iterator overview
Category: iterators
Component type: concept
Description
A Bidirectional Iterator is an iterator that can be both incremented and decremented. The requirement that a Bidirectional Iterator can be decremented is the only thing that distinguishes Bidirectional Iterators from Forward Iterators.
Refinement of
Forward Iterator
Associated types
The same as for Forward Iterator.
Notation
X
A type that is a model of Bidirectional Iterator
T
The value type of X
i, j
Object of type X
t
Object of type T
Valid expressions
In addition to the expressions defined in Forward Iterator, the following expressions must be valid.
Name  Expression  Return type 

Predecrement  i 
X& 
Postdecrement  i 
X 
Expression Semantics
Semantics of an expression is defined only where it is not defined in Forward Iterator.
Name  Expression  Precondition  Semantics  Postcondition 

Predecrement  i 
i is dereferenceable or pasttheend. There exists a dereferenceable iterator j such that i == ++j.  i is modified to point to the previous element.  i is dereferenceable. &i = &i . If i == j , then i == j . If j is dereferenceable and i == ++j , then i == j. 
Postdecrement  i 
i is dereferenceable or pasttheend. There exists a dereferenceable iterator j such that i == ++j.  Equivalent to { X tmp = i; i; return tmp; } 
Complexity guarantees
The complexity of operations on bidirectional iterators is guaranteed to be amortized constant time.
Invariants
Symmetry of increment and decrement  If i is dereferenceable, then ++i; i; is a null operation. Similarly, i; ++i; is a null operation. 
Models
• T*
• list<T>::iterator
See also
Input Iterator, Output Iterator, Forward Iterator, Random Access Iterator, Iterator overview
Category: iterators
Component type: concept
Description
A Random Access Iterator is an iterator that provides both increment and decrement (just like a Bidirectional Iterator), and that also provides constanttime methods for moving forward and backward in arbitrarysized steps. Random Access Iterators provide essentially all of the operations of ordinary C pointer arithmetic.
Refinement of
Bidirectional Iterator, LessThan Comparable
Associated types
The same as for Bidirectional Iterator
Notation
X
A type that is a model of Random Access Iterator
T
The value type of X
Distance
The distance type of X
i, j
Object of type X
t
Object of type T
n
Object of type Distance
Valid expressions
In addition to the expressions defined in Bidirectional Iterator, the following expressions must be valid.
Name  Expression  Type requirements  Return type 

Iterator addition  i += n 
X& 

Iterator addition  i + n orn + i 
X 

Iterator subtraction  i –= n 
X& 

Iterator subtraction  i – n 
X 

Difference  i – j 
Distance 

Element operator  i[n] 
Convertible to T  
Element assignment  i[n] = t 
X is mutable  Convertible to T 
Expression semantics
Semantics of an expression is defined only where it differs from, or is not defined in, Bidirectional Iterator or LessThan Comparable.
Name  Expression  Precondition  Semantics  Postcondition 

Forward motion  i += n 
Including i itself, there must be n dereferenceable or pasttheend iterators following or preceding i, depending on whether n is positive or negative.  If n > 0, equivalent to executing ++i n times. If n < 0, equivalent to executing i n times. If n == 0 , this is a null operation. [1]  i is dereferenceable or pasttheend. 
Iterator addition  i + n or n + i 
Same as for i += n  Equivalent to { X tmp = i; return tmp += n; } . The two forms i + n and n + i are identical.  Result is dereferenceable or pasttheend 
Iterator subtraction  i –= n 
Including i itself, there must be n dereferenceable or pasttheend iterators preceding or following i, depending on whether n is positive or negative.  Equivalent to i += (n).  i is dereferenceable or pasttheend. 
Iterator subtraction  i – n 
Same as for i –= n  Equivalent to { X tmp = i; return tmp –= n; }.  Result is dereferenceable or pasttheend 
Difference  i – j 
Either i is reachable from j or j is reachable from i, or both.  Returns a number n such that i == j + n  
Element operator  i[n] 
i + n exists and is dereferenceable.  Equivalent to *(i + n) [2]  
Element assignment  i[n] = t 
i + n exists and is dereferenceable.  Equivalent to *(i + n) = t [2]  i[n] is a copy of t. 
Less  i < j 
Either i is reachable from j or j is reachable from i, or both. [3]  As described in LessThan Comparable [4] 
Complexity guarantees
All operations on Random Access Iterators are amortized constant time. [5]
Invariants
Symmetry of addition and subtraction  If i + n is welldefined, then i += n; i –= n; and (i + n) – n are null operations. Similarly, if i – n is welldefined, then i –= n; i += n; and (i – n) + n are null operations. 
Relation between distance and addition  If i – j is welldefined, then i == j + (i – j). 
Reachability and distance  If i is reachable from j , then i – j >= 0. 
Ordering  operator< is a strict weak ordering, as defined in LessThan Comparable. 
Models
• T*
• vector<T>::iterator
• vector<T>::const_iterator
• deque<T>::iterator
• deque<T>::const_iterator
Notes
[1] "Equivalent to" merely means that i += n yields the same iterator as if i had been incremented (decremented) n times. It does not mean that this is how operator+= should be implemented; in fact, this is not a permissible implementation. It is guaranteed that i += n is amortized constant time, regardless of the magnitude of n. [5]
[2] One minor syntactic oddity: in C, if p is a pointer and n is an int, then p[n] and n[p] are equivalent. This equivalence is not guaranteed, however, for Random Access Iterators: only i[n] need be supported. This isn't a terribly important restriction, though, since the equivalence of p[n] and n[p] has essentially no application except for obfuscated C contests.
[3] The precondition defined in LessThan Comparable is that i and j be in the domain of operator<. Essentially, then, this is a definition of that domain: it is the set of pairs of iterators such that one iterator is reachable from the other.
[4] All of the other comparison operators have the same domain and are defined in terms of operator<, so they have exactly the same semantics as described in LessThan Comparable.
[5] This complexity guarantee is in fact the only reason why Random Access Iterator exists as a distinct concept. Every operation in iterator arithmetic can be defined for Bidirectional Iterators; in fact, that is exactly what the algorithms advance and distance do. The distinction is simply that the Bidirectional Iterator implementations are linear time, while Random Access Iterators are required to support random access to elements in amortized constant time. This has major implications for the sorts of algorithms that can sensibly be written using the two types of iterators.
See also
LessThan Comparable, Trivial Iterator, Bidirectional Iterator, Iterator overview
Category: iterators
Component type: overview
Summary
Iterator tag functions are a method for accessing information that is associated with iterators. Specifically, an iterator type must, as discussed in the Input Iterator requirements, have an associated distance type and value type. [1] It is sometimes important for an algorithm parameterized by an iterator type to be able to determine the distance type and value type. Iterator tags also allow algorithms to determine an iterator's category, so that they can take different actions depending on whether an iterator is an Input Iterator, Output Iterator, Forward Iterator, Bidirectional Iterator, or Random Access Iterator.
Note that the iterator tag functions distance_type, value_type, and iterator_category are an older method of accessing the type information associated with iterators: they were defined in the original STL. The draft C++ standard, however, defines a different and more convenient mechanism: iterator_traits. Both mechanisms are supported [2], for reasons of backwards compatibility, but the older mechanism will eventually be removed.
Description
The basic idea of the iterator tag functions, and of iterator_traits, is quite simple: iterators have associated type information, and there must be a way to access that information. Specifically, iterator tag functions and iterator_traits are used to determine an iterator's value type, distance type, and iterator category.
An iterator's category is the most specific concept that it is a model of: Input Iterator, Output Iterator, Forward Iterator, Bidirectional Iterator, or Random Access Iterator. This information is expressed in the C++ type system by defining five category tag types, input_iterator_tag, output_iterator_tag, forward_iterator_tag, bidirectional_iterator_tag, and random_access_iterator_tag, each of which corresponds to one of those concepts. [3]
The function iterator_category takes a single argument, an iterator, and returns the tag corresponding to that iterator's category. That is, it returns a random_access_iterator_tag if its argument is a pointer, a bidirectional_iterator_tag if its argument is a list::iterator, and so on. Iterator_traits provides the same information in a slightly different way: if I is an iterator, then iterator_traits<I>::iterator_category is a nested typedef: it is one of the five category tag types.
An iterator's value type is the type of object that is returned when the iterator is dereferenced. (See the discussion in the Input Iterator requirements.) Ideally, one might want value_type to take a single argument, an iterator, and return the iterator's value type. Unfortunately, that's impossible: a function must return an object, and types aren't objects. Instead, value_type returns the value (T*)0, where T is the argument's value type. The iterator_traits class, however, does not have this restriction: iterator_traits<I>::value_type is a type, not a value. It is a nested typedef, and it can be used in declarations of variables, as an function's argument type or return type, and in any other ways that C++ types can be used.
(Note that the function value_type need not be defined for Output Iterators, since an Output Iterator need not have a value type. Similarly, iterator_traits<I>::value_type is typically defined as void when I is an output iterator)
An iterator's distance type, or difference type (the terms are synonymous) is the type that is used to represent the distance between two iterators. (See the discussion in the Input Iterator requirements.) The function distance_type returns this information in the same form that value_type does: its argument is an iterator, and it returns the value (Distance*)0, where Distance is the iterator's distance type. Similarly, iterator_traits<I>::difference_type is I's distance type.
Just as with value_type, the function distance_type need not be defined for Output Iterators, and, if I is an Output Iterator, iterator_traits<I>::difference_type may be defined as void. An Output Iterator need not have a distance type.
The functions iterator_category, value_type, and distance_type must be provided for every type of iterator. (Except, as noted above, that value_type and distance_type need not be provided for Output Iterators.) In principle, this is simply a matter of overloading: anyone who defines a new iterator type must define those three functions for it. In practice, there's a slightly more convenient method. The STL defines five base classes, output_iterator, input_iterator, forward_iterator, bidirectional_iterator, and random_access_iterator. The functions iterator_category, value_type, and distance_type are defined for those base classes. The effect, then, is that if you are defining a new type of iterator you can simply derive it from one of those base classes, and the iterator tag functions will automatically be defined correctly. These base classes contain no member functions or member variables, so deriving from one of them ought not to incur any overhead.
(Again, note that base classes are provided solely for the convenience of people who define iterators. If you define a class Iter that is a new kind of Bidirectional Iterator, you do not have to derive it from the base class bidirectional_iterator. You do, however, have to make sure that iterator_category, value_type, and distance_type are defined correctly for arguments of type Iter, and deriving Iter from bidirectional_iterator is usually the most convenient way to do that.)
Examples
This example uses the value_type iterator tag function in order to declare a temporary variable of an iterator's value type. Note the use of an auxiliary function, __iter_swap. This is a very common idiom: most uses of iterator tags involve auxiliary functions.
template <class ForwardIterator 1, class ForwardIterator 2, class ValueType>
inline void __iter_swap(ForwardIterator1 a, ForwardIterator2 b, ValueType*) {
ValueType tmp = *a;
*a = *b;
*b = tmp;
}
template <class ForwardIterator 1, class ForwardIterator 2>
inline void iter_swap(ForwardIterator1 a, ForwardIterator2 b) {
__iter_swap(a, b, value_type(a));
}
This example does exactly the same thing, using iterator_traits instead. Note how much simpler it is: the auxiliary function is no longer required.
template <class ForwardIterator 1, class ForwardIterator 2>
inline void iter_swap(ForwardIterator1 a, ForwardIterator2 b) {
iterator_traits <ForwardIterator1>::value_type tmp = *a;
*a = *b;
*b = tmp;
}
This example uses the iterator_category iterator tag function: reverse can be implemented for either Bidirectional Iterator s or for Random Access Iterators , but the algorithm for Random Access Iterators is more efficient. Consequently, reverse is written to dispatch on the iterator category. This dispatch takes place at compile time, and should not incur any runtime penalty.
template <class BidirectionalIterator>
void __reverse(BidirectionalIterator first, BidirectionalIterator last, bidirectional_iterator_tag ) {
while (true)
if (first == last  first == –last) return;
else iter_swap(first++, last);
}
template <class RandomAccessIterator>
void __reverse(RandomAccessIterator first, RandomAccessIterator last, random_access_iterator_tag) {
while (first < last) iter_swap(first++, last);
}
template <class BidirectionalIterator>
inline void reverse (BidirectionalIterator first, BidirectionalIterator last) {
__reverse(first, last, iterator_category(first));
}
In this case, iterator_traits would not be different in any substantive way: it would still be necessary to use auxiliary functions to dispatch on the iterator category. The only difference is changing the toplevel function to
template <class BidirectionalIterator>
inline void reverse(BidirectionalIterator first, BidirectionalIterator last) {
__reverse(first, last, iterator_traits<first>::iterator_category());
}
Types
• output_iterator
• input_iterator
• forward_iterator
• bidirectional_iterator
• random_access_iterator
• output_iterator_tag
• input_iterator_tag
• forward_iterator_tag
• bidirectional_iterator_tag
• random_access_iterator_tag
• iterator_traits
Functions
• iterator_category
• value_type
• distance_type
Notes
[1] Output Iterators have neither a distance type nor a value type; in many ways, in fact, Output Iterators aren't really iterators. Output iterators do not have a value type, because it is impossible to obtain a value from an output iterator but only to write a value through it. They do not have a distance type, similarly, because it is impossible to find the distance from one output iterator to another. Finding a distance requires a comparison for equality, and output iterators do not support operator==.
[2] The iterator_traits class relies on a C++ feature known as partial specialization. Many of today's compilers don't implement the complete standard; in particular, many compilers do not support partial specialization. If your compiler does not support partial specialization, then you will not be able to use iterator_traits, and you will have to continue to use the older iterator tag functions.
[3] Note that Trivial Iterator does not appear in this list. The Trivial Iterator concept is introduced solely for conceptual clarity; the STL does not actually define any Trivial Iterator types, so there is no need for a Trivial Iterator tag. There is, in fact, a strong reason not to define one: the C++ type system does not provide any way to distinguish between a pointer that is being used as a trivial iterator (that is, a pointer to an object that isn't part of an array) and a pointer that is being used as a Random Access Iterator into an array.
See also
Input Iterator, Output Iterator, Forward Iterator, Bidirectional Iterator, Random Access Iterator, iterator_traits, Iterator Overview
Category: iterators
Component type: type
Description
As described in the Iterator Overview, one of the most important facts about iterators is that they have associated types. An iterator type, for example, has an associated value type : the type of object that the iterator points to. It also has an associated distance type, or difference type, a signed integral type that can be used to represent the distance between two iterators.
(Pointers, for example, are iterators; the value type of int* is int. Its distance type is ptrdiff_t, because, if p1 and p2 are pointers, the expression p1 – p2 has type ptrdiff_t.)
Generic algorithms often need to have access to these associated types; an algorithm that takes a range of iterators, for example, might need to declare a temporary variable whose type is the iterators' value type. The class iterator_traits is a mechanism that allows such declarations.
The most obvious way to allow declarations of that sort would be to require that all iterators declare nested types; an iterator I's value type, for example, would be I::value_type. That can't possibly work, though. Pointers are iterators, and pointers aren't classes; if I is (say) int* , then it's impossible to define I::value_type to be int. Instead, I's value type is written iterator_traits<I>::value_type. iterator_traits is a template class that contains nothing but nested typedef s; in addition to value_type, iterator_traits defines the nested types iterator_category, difference_type, pointer, and reference.
The library contains two definitions of iterator_traits: a fully generic one, and a specialization that is used whenever the template argument is a pointer type [1]. The fully generic version defines iterator_traits<I>::value_type as a synonym for I::value_type, iterator_traits<I>::difference_type as a synonym for I::difference_type, and so on. Since pointers don't have nested types, iterator_traits<T*> has a different definition.
The implementation of iterator_traits is actually simpler than this discussion.
template <class Iterator>
struct iterator_traits {
typedef typename Iterator::iterator_category iterator_category;
typedef typename Iterator::value_type value_type;
typedef typename Iterator::difference_type difference_type;
typedef typename Iterator::pointer pointer;
typedef typename Iterator::reference reference;
};
template <class T>
struct iterator_traits<T*> {
typedef random_access_iterator_tag iterator_category;
typedef T value_type;
typedef ptrdiff_t difference_type;
typedef T* pointer;
typedef T& reference;
};
If you are defining a new iterator type I, then you must ensure that iterator_traits<I> is defined properly. There are two ways to do this. First, you can define your iterator so that it has nested types I::value_type, I::difference_type, and so on. Second, you can explicitly specialize iterator_traits for your type. The first way is almost always more convenient, however, especially since you can easily ensure that your iterator has the appropriate nested types just by inheriting from one of the base classes input_iterator, output_iterator, forward_iterator, bidirectional_iterator, or random_access_iterator.
Note that iterator_traits is new; it was added to the draft C++ standard relatively recently. Both the old iterator tags mechanism and the new iterator_traits mechanism are currently supported [1 , but the old iterator tag functions are no longer part of the standard C++ library and they will eventually be removed.
Example
This generic function returns the last element in a nonempty range. Note that there is no way to define a function with this interface in terms of the old value_type function, because the function's return type must be declared to be the iterator's value type.
template <class InputIterator>
iterator_traits<InputIterator>::value_type last_value(InputIterator first, InputIterator last) {
iterator_traits<InputIterator>::value_type result = *first;
for (++first; first != last; ++first) result = *first;
return result;
}
(Note: this is an example of how to use iterator_traits; it is not an example of good code. There are better ways of finding the last element in a range of bidirectional iterators, or even forward iterators.)
Definition
Defined in the standard header iterator, and in the nonstandard backwardcompatibility header iterator.h.
Template parameters
Parameter  Description 

Iterator 
The iterator type whose associated types are being accessed. 
Model of
Default Constructible, Assignable
Type requirements
• Iterator is a model of one of the iterator concepts. (Input Iterator, Output Iterator, Forward Iterator, Bidirectional Iterator, or Random Access Iterator.)
Public base classes
None.
Members
None, except for nested types.
Member  Description 

iterator_category 
One of the types input_iterator_tag, output_iterator_tag, forward_iterator_tag, bidirectional_iterator_tag, or random_access_iterator_tag. An iterator's category is the most specific iterator concept that it is a model of. 
value_type 
Iterator's value type, as defined in the Trivial Iterator requirements. 
difference_type 
Iterator's distance type, as defined in the Input Iterator requirements. 
pointer 
Iterator's pointer type: a pointer to its value type. 
reference 
Iterator's reference type: a reference to its value type. 
Notes
[1] The iterator_traits class relies on a C++ feature known as partial specialization. Many of today's compilers don't implement the complete standard; in particular, many compilers do not support partial specialization. If your compiler does not support partial specialization, then you will not be able to use iterator_traits, and you will have to continue using the old iterator tag functions iterator_category, distance_type, and value_type. This is one reason that those functions have not yet been removed.
See also
The iterator overview, iterator tags, input_iterator_tag, output_iterator_tag, forward_iterator_tag, bidirectional_iterator_tag, random_access_iterator_tag, input_iterator, output_iterator, forward_iterator, bidirectional_iterator, random_access_iterator
Category: iterators
Component type: function
Prototype
Iterator_category is overloaded; it is in fact six different functions.
inline output_iterator_tag iterator_category(const output_iterator&);
template <class T, class Distance> inline input_iterator_tag
iterator_category(const input_iterator<T, Distance>&);
template <class T, class Distance> inline forward_iterator_tag
iterator_category(const forward_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 random_access_iterator<T, Distance>&);
template <class T> inline random_access_iterator_tag iterator_category(const T*);
Description
Iterator_category is an iterator tag function: it is used to determine the category to which an iterator belongs. Specifically, every iterator must belong to a type that is a model of the concept Output Iterator, Input Iterator, Forward Iterator, Bidirectional Iterator, or Random Access Iterator. [1] Iterator_category returns an object of class output_iterator_tag, input_iterator_tag, forward_iterator_tag, or random_access_iterator_tag, depending on which concept the type of iterator_category 's argument is a model of. [2] This information is useful in the case of an algorithm that has a sensible definition for more than one category of iterator, but whose definition is different depending on the category.
Although iterator_category looks like a single function whose return type depends on its argument type, in reality it is a set of functions; the name iterator_category is overloaded. The function iterator_category must be overloaded for every iterator type.
In practice, ensuring that iterator_category is defined requires essentially no work at all. It is already defined for pointers, and for the base classes input_iterator, output_iterator, forward_iterator, bidirectional_iterator, and random_access_iterator. If you are implementing a new type of forward iterator, for example, you can simply derive it from the base class forward_iterator; this means that iterator_category (along with distance_type and value_type ) will automatically be defined for your iterator. These base classes are empty: they contain no member functions or member variables, but only type information. Using them should therefore incur no overhead.
Note that, while the function iterator_category was present in the original STL, it is no longer present in the most recent draft C++ standard: it has been replaced by the iterator_traits class. At present both mechanisms are supported [3], but eventually iterator_category will be removed.
Definition
Defined in the standard header iterator, and in the nonstandard backwardcompatibility header iterator.h. This function is no longer part of the C++ standard, although it was present in early drafts of the standard. It is retained in this implementation for backward compatibility.
Requirements on types
The argument of iterator_category must be an iterator.
Preconditions
None. Iterator_category's argument is even permitted to be a singular iterator.
Complexity
At most amortized constant time. In many cases, a compiler should be able to optimize away iterator_category entirely.
Example
Reverse can be implemented for either Bidirectional Iterators or for Random Access Iterators, but the algorithm for Random Access Iterators is more efficient. Consequently, reverse uses iterator_category to select whichever algorithm is appropriate for the iterator type. This dispatch takes place at compile time, and should not incur any runtime penalty.
template <class BidirectionalIterator>
void __reverse(BidirectionalIterator first, BidirectionalIterator last, bidirectional_iterator_tag ) {
while (true)
if (first == last  first == last) return;
else iter_swap(first++, last);
}
template <class RandomAccessIterator>
void __reverse(RandomAccessIterator first, RandomAccessIterator last, random_access_iterator_tag ) {
while (first < last) iter_swap(first++, last);
}
template <class BidirectionalIterator>
inline void reverse(BidirectionalIterator first, BidirectionalIterator last) {
__reverse(first, last, iterator_category(first));
}
Notes
[1] The STL also defines one other concept, Trivial Iterator. This concept is introduced only for conceptual clarity, however, in order to separate the axioms related to an object that refers to another object from those related to iteration over a range. In fact, the STL does not define any types that are Trivial Iterators. Although builtin C pointers may be Trivial Iterators, the C type system does not allow a distinction between pointers that are Trivial Iterators and pointers that are Random Access Iterators into C arrays. Consequently, there is no Trivial Iterator category tag.
[2] Any type that is a model of Forward Iterator is also a model of Input Iterator, any type that is a model of Bidirectional Iterator is also a model of Forward Iterator, and any type that is a model of Random Access Iterator is also a model of Bidirectional Iterator. Iterator_category must return a tag representing the most specific concept that its argument is a model of. If its argument is a vector::iterator, for example, then it must return random_access_iterator_tag.
[3] The iterator_traits class relies on a C++ feature known as partial specialization. Many of today's compilers don't implement the complete standard; in particular, many compilers do not support partial specialization. If your compiler does not support partial specialization, then you will not be able to use iterator_traits, and you will have to continue using the functions iterator_category, distance_type, and value_type. This is one reason that those functions have not yet been removed.
See also
The Iterator Tags overview, iterator_traits, distance_type, value_type, output_iterator_tag, input_iterator_tag, forward_iterator_tag, bidirectional_iterator_tag, random_access_iterator_tag
Category: iterators
Component type: function
Prototype
Distance_type is overloaded; it is in fact five different functions.
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
Distance_type is an iterator tag function: it is used to determine the distance type associated with an iterator. An Input Iterator, Forward Iterator, Bidirectional Iterator, or Random Access Iterator [1] must have associated with it some signed integral type that is used to represent the distance between two iterators of that type. In some cases (such as an algorithm that must declare a local variable that represents the size of a range), it is necessary to find out an iterator's distance type. Accordingly, distance_type(Iter) returns (Distance*)0, where Distance is Iter's distance type.
Although distance_type looks like a single function whose return type depends on its argument type, in reality it is a set of functions; the name distance_type is overloaded. The function distance_type must be overloaded for every iterator type [1].
In practice, ensuring that distance_type is defined requires essentially no work at all. It is already defined for pointers, and for the base classes input_iterator, forward_iterator, bidirectional_iterator, and random_access_iterator. If you are implementing a new type of forward iterator, for example, you can simply derive it from the base class forward_iterator; this means that distance_type (along with iterator_category and value_type) will automatically be defined for your iterator. These base classes are empty: they contain no member functions or member variables, but only type information. Using them should therefore incur no overhead.
Note that, while the function distance_type was present in the original STL, it is no longer present in the most recent draft C++ standard: it has been replaced by the iterator_traits class. At present both mechanisms are supported [2], but eventually distance_type will be removed.
Definition
Defined in the standard header iterator, and in the nonstandard backwardcompatibility header iterator.h. This function is no longer part of the C++ standard, although it was present in early drafts of the standard. It is retained in this implementation for backward compatibility.
Requirements on types
The argument of distance_type must be an Input Iterator, Forward Iterator, Bidirectional Iterator, or Random Access Iterator. [1]
Preconditions
None. Distance_type's argument is even permitted to be a singular iterator.
Complexity
At most amortized constant time. In many cases, a compiler should be able to optimize away distance_type entirely.
Example
template <class RandomAccessIterator, class LessThanComparable, class Distance>
RandomAccessIterator __lower_bound(RandomAccessIterator first, RandomAccessIterator last, const LessThanComparable& value, Distance*)
Distance len = last – first;
Distance half;
RandomAccessIterator middle;
while (len > 0) {
half = len / 2;
middle = first + half;
if (*middle < value) {
first = middle + 1;
len = len – half – 1;
} else
len = half;
}
return first;
}
template <class RandomAccessIterator, class LessThanComparable>
inline RandomAccessIterator lower_bound(RandomAccessIterator first, RandomAccessIterator last, const LessThanComparable& value) {
return __lower_bound(first, last, value, distance_type(first));
}
The algorithm lower_bound (a type of binary search) takes a range of iterators, and must declare a local variable whose type is the iterators' distance type. It uses distance type, and an auxiliary function, so that it can declare that variable. [3] Note: this is a simplified example. The actual algorithm lower_bound can operate on a range of Random Access Iterators or a range of Forward Iterators. It uses both distance_type and iterator_category.
Notes
[1] Note that distance_type is not defined for Output Iterators or for Trivial Iterators. There is no meaningful definition of a distance for either of those concepts, so there is no need for a distance type.
[2] The iterator_traits class relies on a C++ feature known as partial specialization. Many of today's compilers don't implement the complete standard; in particular, many compilers do not support partial specialization. If your compiler does not support partial specialization, then you will not be able to use iterator_traits, and you will have to continue using the functions iterator_category, distance_type, and value_type. This is one reason that those functions have not yet been removed.
[3] This use of an auxiliary function is an extremely common idiom: distance_type is almost always used with auxiliary functions, simply because it returns type information in a form that is hard to use in any other way. This is one of the reasons that distance_type is so much less convenient than iterator_traits.
See also
The Iterator Tags overview, iterator_traits, iterator_category, value_type, output_iterator_tag, input_iterator_tag, forward_iterator_tag, bidirectional_iterator_tag, random_access_iterator_tag
Category: iterators
Component type: function
Prototype
Value_type is overloaded; it is in fact five different functions.
template <class T, class Distance>
inline T* value_type(const input_iterator<T, Distance>&);
template <class T, class Distance>
inline T* value_type(const forward_iterator<T, Distance>&);
template <class T, class Distance>
inline T* value_type(const bidirectional_iterator<T, Distance>&);
template <class T, class Distance>
inline T* value_type(const random_access_iterator<T, Distance>&);
template <class T>
inline T* value_type(const T*);
Description
Value_type is an iterator tag function: it is used to determine the value type associated with an iterator. An iterator's value type is the type of object returned when the iterator is dereferenced; Output Iterators do not have value types (Output Iterators may only be used for storing values, not for accessing values), but Input Iterators, Forward Iterators, Bidirectional Iterators, and Random Access Iterators do. [1]
In some cases, such as an algorithm that must declare a local variable that holds a value returned from dereferencing an iterator, it is necessary to find out an iterator's value type. Accordingly, value_type(Iter) returns (T*)0 , where T is Iter's value type.
Although value_type looks like a single function whose return type depends on its argument type, in reality it is a set of functions; the name value_type is overloaded. The function value_type must be overloaded for every iterator type [1].
In practice, ensuring that value_type is defined requires essentially no work at all. It is already defined for pointers, and for the base classes input_iterator, forward_iterator, bidirectional_iterator, and random_access_iterator. If you are implementing a new type of forward iterator, for example, you can simply derive it from the base class forward_iterator; this means that value_type (along with iterator_category and distance_type) will automatically be defined for your iterator. These base classes are empty: they contain no member functions or member variables, but only type information. Using them should therefore incur no overhead.
Note that, while the function value_type was present in the original STL, it is no longer present in the most recent draft C++ standard: it has been replaced by the iterator_traits class At present both mechanisms are supported [2], but eventually value_type will be removed.
Definition
Defined in the standard header iterator, and in the nonstandard backwardcompatibility header iterator.h. This function is no longer part of the C++ standard, although it was present in early drafts of the standard. It is retained in this implementation for backward compatibility.
Requirements on types
The argument of value_type must be an Input Iterator, Forward Iterator, Bidirectional Iterator, or Random Access Iterator. [1]
Preconditions
None. Value_type's argument is even permitted to be a singular iterator.
Complexity
At most amortized constant time. In many cases, a compiler should be able to optimize away value_type entirely.
Example
This example uses the value_type iterator tag function in order to declare a temporary variable of an iterator's value type.
template <class ForwardIterator 1, class ForwardIterator 2, class ValueType>
inline void __iter_swap(ForwardIterator1 a, ForwardIterator2 b, ValueType*) {
T tmp = *a;
*a = *b;
*b = tmp;
}
template <class ForwardIterator 1, class ForwardIterator 2>
inline void iter_swap(ForwardIterator1 a, ForwardIterator2 b) {
__iter_swap(a, b, value_type (a));
}
Notes
[1] Note that distance_type is not defined for Output Iterators or for Trivial Iterators. In the case of Output Iterators, this is because an Output Iterator does not have a value type: it is not possible to dereference an Output Iterator and obtain a value. In the case of Trivial Iterators, this is because the concept was introduced only for conceptual clarity, in order to separate the axioms related to an object that refers to another object from those related to iteration over a range. In fact, the STL does not define any types that are Trivial Iterators. Although builtin C pointers may be Trivial Iterators, the C type system does not allow a distinction between pointers that are Trivial Iterators and pointers that are Random Access Iterators into C arrays. Consequently, there is no Trivial Iterator category tag or iterator base.
[2] The iterator_traits class relies on a C++ feature known as partial specialization. Many of today's compilers don't implement the complete standard; in particular, many compilers do not support partial specialization. If your compiler does not support partial specialization, then you will not be able to use iterator_traits, and you will have to continue using the functions iterator_category, distance_type, and value_type. This is one reason that those functions have not yet been removed.
See also
The Iterator Tags overview, iterator_traits, iterator_category, distance_type, output_iterator_tag, input_iterator_tag, forward_iterator_tag, bidirectional_iterator_tag, random_access_iterator_tag
Category: iterators
Component type: type
Description
Input_iterator_tag is an empty class: it has no member functions, member variables, or nested types. It is used solely as a "tag": a representation of the Input Iterator concept within the C++ type system. Specifically, it is used as a return value for the function iterator_category. Iterator_category takes a single argument, an iterator, and returns an object whose type depends on the iterator's category. Iterator_category's return value is of type input_iterator_tag if its argument is an Input Iterator.
Example
See iterator_category
Definition
Defined in the standard header iterator, and in the nonstandard backwardcompatibility header iterator.h.
Template parameters
None.
Model of
Assignable
Type requirements
None.
Public base classes
None.
Members
None.
New Members
None.
See also
iterator_category, Iterator Tags, iterator_traits, output_iterator_tag, forward_iterator_tag, bidirectional_iterator_tag, random_access_iterator_tag
Category: iterators
Component type: type
Description
Output_iterator_tag is an empty class: it has no member functions, member variables, or nested types. It is used solely as a "tag": a representation of the Output Iterator concept within the C++ type system. Specifically, it is used as a return value for the function iterator_category. Iterator_category takes a single argument, an iterator, and returns an object whose type depends on the iterator's category. Iterator_category's return value is of type output_iterator_tag if its argument is an Output Iterator.
Example
See iterator_category
Definition
Defined in the standard header iterator, and in the nonstandard backwardcompatibility header iterator.h.
Template parameters
None.
Model of
Assignable
Type requirements
None.
Public base classes
None.
Members
None.
New Members
None.
See also
iterator_category, Iterator Tags, iterator_traits, input_iterator_tag, forward_iterator_tag, bidirectional_iterator_tag, random_access_iterator_tag
Category: iterators
Component type: type
Description
Forward_iterator_tag is an empty class: it has no member functions, member variables, or nested types. It is used solely as a "tag": a representation of the Forward Iterator concept within the C++ type system. Specifically, it is used as a return value for the function iterator_category. Iterator_category takes a single argument, an iterator, and returns an object whose type depends on the iterator's category. Iterator_category's return value is of type forward_iterator_tag if its argument is a Forward Iterator.
Example
See iterator_category
Definition
Defined in the standard header iterator, and in the nonstandard backwardcompatibility header iterator.h.
Template parameters
None.
Model of
Assignable
Type requirements
None.
Public base classes
None.
Members
None.
New Members
None.
See also
iterator_category, Iterator Tags, iterator_traits, output_iterator_tag, input_iterator_tag, bidirectional_iterator_tag, random_access_iterator_tag
Category: iterators
Component type: type
Description
Bidirectional_iterator_tag is an empty class: it has no member functions, member variables, or nested types. It is used solely as a "tag": a representation of the Bidirectional Iterator concept within the C++ type system. Specifically, it is used as a return value for the function iterator_category. Iterator_category takes a single argument, an iterator, and returns an object whose type depends on the iterator's category. Iterator_category's return value is of type bidirectional_iterator_tag if its argument is a Bidirectional Iterator.
Example
See iterator_category
Definition
Defined in the standard header iterator, and in the nonstandard backwardcompatibility header iterator.h.
Template parameters
None.
Model of
Assignable
Type requirements
None.
Public base classes
None.
Members
None.
New Members
None.
See also
iterator_category, Iterator Tags, iterator_traits, output_iterator_tag, input_iterator_tag, forward_iterator_tag random_access_iterator_tag
Category: iterators
Component type: type
Description
Random_access_iterator_tag is an empty class: it has no member functions, member variables, or nested types. It is used solely as a "tag": a representation of the Random Access Iterator concept within the C++ type system. Specifically, it is used as a return value for the function iterator_category. Iterator_category takes a single argument, an iterator, and returns an object whose type depends on the iterator's category. Iterator_category 's return value is of type random_access_iterator_tag if its argument is a Random Access Iterator.
Example
See iterator_category.
Definition
Defined in the standard header iterator, and in the nonstandard backwardcompatibility header iterator.h.
Template parameters
None.
Model of
Assignable.
Type requirements
None.
Public base classes
None.
Members
None.
New Members
None.
See also
iterator_category, Iterator Tags, iterator_traits, output_iterator_tag, input_iterator_tag, forward_iterator_tag, bidirectional_iterator_tag
Category: iterators
Component type: type
Description
Input_iterator is an iterator base class: it is intended that an iterator that is a model of Input Iterator, and whose value type and distance type are T and Distance, may be defined by inheriting from input_iterator<T, Distance> [1]. Input_iterator is entirely empty: it has no member functions, member variables, or nested types. It exists solely to simplify the definition of the functions iterator_category, distance_type, and value_type.
Example
class my_input_iterator : public input_iterator<double> {
…
};
This declares my_input_iterator to be an Input Iterator whose value type is double and whose distance type is ptrdiff_t. If Iter is an object of class my_input_iterator, then iterator_category(Iter) will return input_iterator_tag(), value_type(Iter) will return (double*)0 , and distance_type(Iter) will return (ptrdiff_t*)0.
Definition
Defined in the standard header iterator, and in the nonstandard backwardcompatibility header iterator.h. This class is no longer part of the C++ standard, although it was present in early drafts of the standard. It is retained in this implementation for backward compatibility.
Template parameters
Parameter  Description  Default 

T 
The iterator's value type  
Distance 
The iterator's distance type  ptrdiff_t 
Model of
Assignable
Public base classes
None
Type requirements
The distance type must be a signed integral type.
Public base classes
None.
Members
None.
New Members
None.
Notes
[1] It is not required that an Input Iterator inherit from the base input_iterator. It is, however, required that the functions iterator_category, distance_type, and value_type be defined for every Input Iterator. (Or, if you are using the iterator_traits mechanism, that iterator_traits is properly specialized for every Input Iterator.) Since those functions are defined for the base input_iterator, the easiest way to ensure that are defined for a new iterator class is to derive that class from input_iterator and rely on the derivedtobase standard conversion of function arguments.
See also
The Iterator Tags overview, iterator_traits, iterator_category, value_type, distance_type, output_iterator, forward_iterator, bidirectional_iterator, random_access_iterator
Category: iterators
Component type: type
Description
Output_iterator is an iterator base class: it is intended that an iterator that is a model of Output Iterator may be defined by inheriting from output_iterator [1]. Output_iterator is entirely empty: it has no member functions, member variables, or nested types. It exists solely to simplify the definition of the functions iterator_category, distance_type, and value_type.
Example
class my_output_iterator : public output_iterator {
…
};
This declares my_output_iterator to be an Output Iterator. If Iter is an object of class my_output_iterator, then iterator_category(Iter) will return output_iterator_tag(), and distance_type and value_type will be undefined for objects of class my_output_iterator.
Definition
Defined in the standard header iterator, and in the nonstandard backwardcompatibility header iterator.h. This class is no longer part of the C++ standard, although it was present in early drafts of the standard. It is retained in this implementation for backward compatibility.
Template parameters
None. (Note that Output Iterators need have neither distance types nor value types.)
Model of
Assignable
Public base classes
None
Type requirements
None.
Public base classes
None.
Members
None.
New Members
None.
Notes
[1] It is not required that an Output Iterator inherit from the base output_iterator. It is, however, required that the function iterator_category be defined for every Output Iterator. (Or, if you are using the iterator_traits mechanism, that iterator_traits is properly specialized for every Output Iterator.) Since it is defined for the base output_iterator, the easiest way to ensure that it defined for a new type is to derive that class from output_iterator and rely on the derivedtobase standard conversion of function arguments.
See also
The Iterator Tags overview, iterator_traits, iterator_category, value_type, distance_type, input_iterator, forward_iterator, bidirectional_iterator, random_access_iterator
Category: iterators
Component type: type
Description
Forward_iterator is an iterator base class: it is intended that an iterator that is a model of Forward Iterator, and whose value type and distance type are T and Distance, may be defined by inheriting from forward_iterator<T, Distance>[1]. Forward_iterator is entirely empty: it has no member functions, member variables, or nested types. It exists solely to simplify the definition of the functions iterator_category, distance_type, and value_type.
Example
class my_forward_iterator : public forward_iterator<double> {
…
};
This declares my_forward_iterator to be a Forward Iterator whose value type is double and whose distance type is ptrdiff_t. If Iter is an object of class my_forward_iterator, then iterator_category(Iter) will return forward_iterator_tag(), value_type(Iter) will return (double*)0, and distance_type(Iter) will return (ptrdiff_t*)0.
Definition
Defined in the standard header iterator, and in the nonstandard backwardcompatibility header iterator.h. This class is no longer part of the C++ standard, although it was present in early drafts of the standard. It is retained in this implementation for backward compatibility.
Template parameters
Parameter  Description  Default 

T 
The iterator's value type  
Distance 
The iterator's distance type  ptrdiff_t 
Model of
Assignable
Public base classes
None
Type requirements
The distance type must be a signed integral type.
Public base classes
None.
Members
None.
New Members
None.
Notes
[1] It is not required that a Forward Iterator inherit from the base forward_iterator. It is, however, required that the functions iterator_category, distance_type, and value_type be defined for every Forward Iterator. (Or, if you are using the iterator_traits mechanism, that iterator_traits is properly specialized for every Forward Iterator.) Since those functions are defined for the base forward_iterator, the easiest way to ensure that are defined for a new type is to derive that class from forward_iterator and rely on the derivedtobase standard conversion of function arguments.
See also
The Iterator Tags overview, iterator_traits, iterator_category, value_type, distance_type, input_iterator, output_iterator, bidirectional_iterator, random_access_iterator
bidirectional_iterator<T, Distance>
Category: iterators
Component type: type
Description
Bidirectional_iterator is an iterator base class: it is intended that an iterator that is a model of Bidirectional Iterator, and whose value type and distance type are T and Distance, may be defined by inheriting from bidirectional_iterator<T, Distance> [1]. Bidirectional_iterator is entirely empty: it has no member functions, member variables, or nested types. It exists solely to simplify the definition of the functions iterator_category, distance_type, and value_type.
Example
class my_bidirectional_iterator : public bidirectional_iterator<double> {
…
};
This declares my_bidirectional_iterator to be a Bidirectional Iterator whose value type is double and whose distance type is ptrdiff_t. If Iter is an object of class my_bidirectional_iterator, then iterator_category(Iter) will return bidirectional_iterator_tag(), value_type(Iter) will return (double*)0, and distance_type(Iter) will return (ptrdiff_t*)0.
Definition
Defined in the standard header iterator, and in the nonstandard backwardcompatibility header iterator.h. This class is no longer part of the C++ standard, although it was present in early drafts of the standard. It is retained in this implementation for backward compatibility.
Template parameters
Parameter  Description  Default 

T 
The iterator's value type  
Distance 
The iterator's distance type  ptrdiff_t 
Model of
Assignable
Public base classes
None
Type requirements
The distance type must be a signed integral type.
Public base classes
None.
Members
None.
New Members
None.
Notes
[1] It is not required that a Bidirectional Iterator inherit from the base bidirectional_iterator. It is, however, required that the functions iterator_category, distance_type, and value_type be defined for every Bidirectional Iterator. (Or, if you are using the iterator_traits mechanism, that iterator_traits is properly specialized for every Bidirectional Iterator.) Since those functions are defined for the base bidirectional_iterator, the easiest way to ensure that are defined for a new type is to derive that class from bidirectional_iterator and rely on the derivedtobase standard conversion of function arguments.
See also
The Iterator Tags overview, iterator_traits, iterator_category, value_type, distance_type, input_iterator, output_iterator, forward_iterator, random_access_iterator
random_access_iterator<T, Distance>
Category: iterators
Component type: type
Description
Random_access_iterator is an iterator base class: it is intended that an iterator that is a model of Random Access Iterator, and whose value type and distance type are T and Distance, may be defined by inheriting from random_access_iterator<T, Distance> [1]. Random_access_iterator is entirely empty: it has no member functions, member variables, or nested types. It exists solely to simplify the definition of the functions iterator_category, distance_type, and value_type.
Example
class my_random_access_iterator : public random_access_iterator<double> {
…
};
This declares my_random_access_iterator to be a Random Access Iterator whose value type is double and whose distance type is ptrdiff_t. If Iter is an object of class my_random_access_iterator, then iterator_category(Iter) will return random_access_iterator_tag(), value_type(Iter) will return (double*)0 , and distance_type(Iter) will return (ptrdiff_t*)0.
Definition
Defined in the standard header iterator, and in the nonstandard backwardcompatibility header iterator.h. This class is no longer part of the C++ standard, although it was present in early drafts of the standard. It is retained in this implementation for backward compatibility.
Template parameters
Parameter  Description  Default 

T 
The iterator's value type  
Distance 
The iterator's distance type  ptrdiff_t 
Model of
Assignable
Public base classes
None
Type requirements
The distance type must be a signed integral type.
Public base classes
None.
Members
None.
New Members
None.
Notes
[1] It is not required that a Random Access Iterator inherit from the base random_access_iterator. It is, however, required that the functions iterator_category, distance_type, and value_type be defined for every Random Access Iterator . (Or, if you are using the iterator_traits mechanism, that iterator_traits is properly specialized for every Random Access Iterator.) Since those functions are defined for the base random_access_iterator, the easiest way to ensure that are defined for a new type is to derive that class from random_access_iterator and rely on the derivedtobase standard conversion of function arguments.
See also
The Iterator Tags overview, iterator_traits, iterator_category, value_type, distance_type, input_iterator, output_iterator, forward_iterator, bidirectional_iterator
Categories: algorithms, iterators
Component type: function
Prototype
Distance is an overloaded name; there are actually two distance functions.
template <class InputIterator>
inline iterator_traits<InputIterator>::difference_type distance(InputIterator first, InputIterator last);
template <class InputIterator, class Distance>
void distance(InputIterator first, InputIterator last, Distance& n);
Description
Finds the distance between first and last, i.e. the number of times that first must be incremented until it is equal to last. [1] The first version of distance, which takes two arguments, simply returns that distance; the second version, which takes three arguments and which has a return type of void, increments n by that distance.
The second version of distance was the one defined in the original STL, and the first version is the one defined in the draft C++ standard; the definition was changed because the older interface was clumsy and errorprone. The older interface required the use of a temporary variable, and it has semantics that are somewhat nonintuitive: it increments n by the distance from first to last , rather than storing that distance in n. [2]
Both interfaces are currently supported [3], for reasons of backward compatibility, but eventually the older version will be removed.
Definition
Defined in the standard header iterator, and in the nonstandard backwardcompatibility header iterator.h.
Requirements on types
For the first version:
• InputIterator is a model of Input Iterator.
For the second version:
• InputIterator is a model of Input Iterator.
• Distance is an integral type that is able to represent a distance between iterators of type InputIterator.
Preconditions
• [first, last) is a valid range, as defined in the Input Iterator requirements.
Complexity
Constant time if InputIterator is a model of random access iterator, otherwise linear time.
Example
int main() {
list<int> L;
L.push_back(0);
L.push_back(1);
assert(distance(L.begin(), L.end()) == L.size());
}
Notes
[1] This is the reason that distance is not defined for output iterators: it is impossible to compare two output iterators for equality.
[2] Forgetting to initialize n to 0 is a common mistake.
[3] The new distance interface uses the iterator_traits class, which relies on a C++ feature known as partial specialization. Many of today's compilers don't implement the complete standard; in particular, many compilers do not support partial specialization. If your compiler does not support partial specialization, then you will not be able to use the newer version of distance, or any other STL components that involve iterator_traits.
See also
distance_type, advance, Input iterator, Random access iterator, Iterator tags, iterator_traits, Iterator overview.
Categories: algorithms, iterators
Component type: function
Prototype
template <class InputIterator, class Distance>
void advance(InputIterator& i, Distance n);
Description
Advance(i, n) increments the iterator i by the distance n . If n > 0 it is equivalent to executing ++i n times, and if n < 0 it is equivalent to executing i n times. If n == 0 , the call has no effect.
Definition
Defined in the standard header iterator, and in the nonstandard backwardcompatibility header iterator.h.
Requirements on types
• InputIterator is a model of Input Iterator.
• Distance is an integral type that is convertible to InputIterator's distance type.
Preconditions
• i is nonsingular.
• Every iterator between i and i+n (inclusive) is nonsingular.
• If InputIterator is a model of input iterator or forward iterator, then n must be nonnegative. If InputIterator is a model of bidirectional iterator or random access iterator, then this precondition does not apply.
Complexity
Constant time if InputIterator is a model of random access iterator, otherwise linear time.
Example
list<int> L;
L.push_back(0);
L.push_back(1);
list<int>::iterator i = L.begin();
advance(i, 2);
assert(i == L.end());
See also
distance, Input iterator, Bidirectional Iterator, Random access iterator, iterator_traits, Iterator overview.
Category: iterators
Component type: type
Description
An istream_iterator is an Input Iterator that performs formatted input of objects of type T from a particular istream. When end of stream is reached, the istream_iterator takes on a special end of stream value, which is a pasttheend iterator. Note that all of the restrictions of an Input Iterator must be obeyed, including the restrictions on the ordering of operator* and operator++ operations.
Example
Fill a vector with values read from standard input.
vector<int> V;
copy(istream_iterator<int>(cin), istream_iterator<int>(), back_inserter(V));
Definition
Defined in the standard header iterator, and in the nonstandard backwardcompatibility header iterator.h.
Template parameters
Parameter  Description  Default 

The istream_iterator's value type. Operator* returns a const T&.  
Distance 
The istream_iterator 's distance type.  ptrdiff_t 
Model of
Input Iterator
Type requirements
The value type T must be a type such that cin >> T is a valid expression.
The value type T must be a model of Default Constructible.
The distance type must, as described in the Input Iterator requirements, be a signed integral type.
Public base classes
None.
Members
Member  Where defined  Description 

istream_iterator() 
istream_iterator 
See below. 
istream_iterator(istream&) 
istream_iterator 
See below. 
istream_iterator(const istream_iterator&) 
Trivial Iterator  The copy constructor 
istream_iterator& operator=(const istream_iterator&) 
Trivial Iterator  The assignment operator 
const T& operator*() const 
Input Iterator  Returns the next object in the stream. 
istream_iterator& operator++() 
Input Iterator  Preincrement. 
istream_iterator& operator++(int) 
Input Iterator  Postincrement. 
bool operator==(const istream_iterator&, const istream_iterator&) 
Trivial iterator  The equality operator. This is a global function, not a member function. 
input_iterator_tag iterator_category(const istream_iterator&) 
iterator tags  Returns the iterator's category. 
T* value_type(const istream_iterator&) 
iterator tags  Returns the iterator's value type. 
Distance* distance_type(const istream_iterator&) 
iterator tags  Returns the iterator's distance type. 
New members
These members are not defined in the Input Iterator requirements, but are specific to istream_iterator.
Function  Description 

istream_iterator() 
The default constructor: Constructs an endofstream iterator. This is a pasttheend iterator, and it is useful when constructing a "range". 
istream_iterator(istream& s) 
Creates an istream_iterator that reads values from the input stream s. When s reaches end of stream, this iterator will compare equal to an endofstream iterator created using the default constructor. 
See also
ostream_iterator, Input Iterator, Output Iterator.
Category: iterators
Component type: type
Description
An ostream_iterator is an Output Iterator that performs formatted output of objects of type T to a particular ostream. Note that all of the restrictions of an Output Iterator must be obeyed, including the restrictions on the ordering of operator* and operator++ operations.
Example
Copy the elements of a vector to the standard output, one per line.
vector<int> V;
// …
copy(V.begin(), V.end(), ostream_iterator<int>(cout, "\n"));
Definition
Defined in the standard header iterator, and in the nonstandard backwardcompatibility header iterator.h.
Template parameters
Parameter  Description 

T 
The type of object that will be written to the ostream. The set of value types of an ostream_iterator consists of a single type, T. 
Model of
Output Iterator.
Type requirements
T must be a type such that cout << T is a valid expression.
Public base classes
None.
Members
Member  Where defined  Description 

ostream_iterator(ostream&) 
ostream_iterator 
See below. 
ostream_iterator(ostream&, const char* s) 
ostream_iterator 
See below. 
ostream_iterator(const ostream_iterator&) 
Output Iterator  The copy constructor 
ostream_iterator& operator=(const ostream_iterator&) 
Output Iterator  The assignment operator 
ostream_iterator& operator=(const T&) 
Output Iterator  Used to implement the Output Iterator requirement *i = t. [1] 
ostream_iterator& operator*() 
Output Iterator  Used to implement the Output Iterator requirement *i = t. [1] 
ostream_iterator& operator++() 
Output Iterator  Preincrement 
ostream_iterator& operator++(int) 
Output Iterator  Postincrement 
output_iterator_tag iterator_category(const ostream_iterator&) 
iterator tags  Returns the iterator's category. 
New members
These members are not defined in the Output Iterator requirements, but are specific to ostream_iterator.
Function  Description 

ostream_iterator(ostream& s)  Creates an ostream_iterator such that assignment of t through it is equivalent to s << t. 
ostream_iterator(ostream& s, const char* delim)  Creates an ostream_iterator such that assignment of t through it is equivalent to s << t << delim. 
Notes
[1] Note how assignment through an ostream_iterator is implemented. In general, unary operator* must be defined so that it returns a proxy object, where the proxy object defines operator= to perform the output operation. In this case, for the sake of simplicity, the proxy object is the ostream_iterator itself. That is, *i simply returns i , and *i = t is equivalent to i = t. You should not, however, rely on this behavior. It is an implementation detail, and it is not guaranteed to remain the same in future versions.
See also
istream_iterator, Output Iterator, Input Iterator.
front_insert_iterator<FrontInsertionSequence>
Categories: iterators, adaptors
Component type: type
Description
Front_insert_iterator is an iterator adaptor that functions as an Output Iterator: assignment through a front_insert_iterator inserts an object before the first element of a Front Insertion Sequence. [1] [2]
Example
list<int> L;
L.push_front(3);
front_insert_iterator<list<int> > ii(L);
*ii++ = 0;
*ii++ = 1;
*ii++ = 2;
copy(L.begin(), L.end(), ostream_iterator<int>(cout, " "));
// The values that are printed are 2 1 0 3
Definition
Defined in the standard header iterator, and in the nonstandard backwardcompatibility header iterator.h.
Template parameters
Parameter  Description 

FrontInsertionSequence 
The type of Front Insertion Sequence into which values will be inserted. 
Model of
Output Iterator. A front insert iterator's set of value types (as defined in the Output Iterator requirements) consists of a single type: FrontInsertionSequence::value_type.
Type requirements
The template parameter FrontInsertionSequence must be a Front Insertion Sequence.
Public base classes
None.
Members
Member  Where defined  Description 

front_insert_iterator(FrontInsertionSequence&) 
front_insert_iterator 
See below. 
front_insert_iterator(const front_insert_iterator&) 
Trivial Iterator  The copy constructor 
front_insert_iterator& operator=(const front_insert_iterator&) 
Trivial Iterator  The assignment operator 
front_insert_iterator& operator*() 
Output Iterator  Used to implement the output iterator expression *i = x. [3] 
front_insert_iterator& operator=(const FrontInsertionSequence::value_type&) 
Output Iterator  Used to implement the output iterator expression *i = x. [3] 
front_insert_iterator& operator++() 
Output Iterator  Preincrement. 
front_insert_iterator& operator++(int) 
Output Iterator  Postincrement. 
output_iterator_tag iterator_category(const front_insert_iterator&) iterator tags 
Returns the iterator's category.  This is a global function, not a member. 
template<class FrontInsertionSequence> front_insert_iterator<FrontInsertionSequence> front_inserter(FrontInsertionSequence& S) 
front_insert_iterator 
See below. 
New members.
These members are not defined in the Output Iterator requirements, but are specific to front_insert_iterator.
Member  Description 

front_insert_iterator(FrontInsertionSequence& S) 
Constructs a front_insert_iterator that inserts objects before the first element of S. 
template<class FrontInsertionSequence> front_insert_iterator<FrontInsertionSequence> front_inserter(FrontInsertionSequence& S); 
Equivalent to front_insert_iterator<FrontInsertionSequence>(S). [4] This is a global function, not a member function. 
Notes
[1] Note the difference between assignment through a FrontInsertionSequence::iterator and assignment through an front_insert_iterator<FrontInsertionSequence>. If i is a valid FrontInsertionSequence::iterator, then it points to some particular element in the front insertion sequence; the expression *i = t replaces that element with t, and does not change the total number of elements in the sequence. If ii is a valid front_insert_iterator<FrontInsertionSequence>, however, then the expression *ii = t is equivalent, for some FrontInsertionSequence seq, to the expression seq.push_front(t). That is, it does not overwrite any of seq's elements and it does change seq's size.
[2] Note the difference between a front_insert_iterator and an insert_iterator. It may seem that a front_insert_iterator is the same as an insert_iterator constructed with an insertion point that is the beginning of a sequence. In fact, though, there is a very important difference: every assignment through afront_insert_iterator corresponds to an insertion before the first element of the sequence. If you are inserting elements at the beginning of a sequence using an insert_iterator, then the elements will appear in the order in which they were inserted. If, however, you are inserting elements at the beginning of a sequence using a front_insert_iterator, then the elements will appear in the reverse of the order in which they were inserted.
[3] Note how assignment through an front_insert_iterator is implemented. In general, unary operator* must be defined so that it returns a proxy object, where the proxy object defines operator= to perform the insert operation. In this case, for the sake of simplicity, the proxy object is the front_insert_iterator itself. That is, *i simply returns i, and *i = t is equivalent to i = t. You should not, however, rely on this behavior. It is an implementation detail, and it is not guaranteed to remain the same in future versions.
[4] This function exists solely for the sake of convenience: since it is a nonmember function, the template parameters may be inferred and the type of the front_insert_iterator need not be declared explicitly. One easy way to reverse a range and insert it at the beginning of a Front Insertion Sequence S, for example, is copy(first, last, front_inserter(S)).
See also
insert_iterator, back_insert_iterator, Output Iterator, Sequence, Front Insertion Sequence, Iterator overview
back_insert_iterator<BackInsertionSequence>
Categories: iterators, adaptors
Component type: type
Description
Back_insert_iterator is an iterator adaptor that functions as an Output Iterator: assignment through a back_insert_iterator inserts an object after the last element of a Back Insertion Sequence. [1]
Example
list<int> L;
L.push_front(3);
back_insert_iterator<list<int> > ii(L);
*ii++ = 0;
*ii++ = 1;
*ii++ = 2;
copy (L.begin(), L.end(), ostream_iterator<int>(cout, " "));
// The values that are printed are 3 0 1 2
Definition
Defined in the standard header iterator, and in the nonstandard backwardcompatibility header iterator.h.
Template parameters
Parameter  Description 

BackInsertionSequence 
The type of Back Insertion Sequence into which values will be inserted. 
Model of
Output Iterator. An insert iterator's set of value types (as defined in the Output Iterator requirements) consists of a single type: BackInsertionSequence::value_type.
Type requirements
The template parameter BackInsertionSequence must be a Back Insertion Sequence.
Public base classes
None.
Members
Member  Where defined  Description 

back_insert_iterator(BackInsertionSequence&) 
back_insert_iterator 
See below. 
back_insert_iterator(const back_insert_iterator&) 
Trivial Iterator  The copy constructor 
back_insert_iterator& operator=(const back_insert_iterator&) 
Trivial Iterator  The assignment operator 
back_insert_iterator& operator*() 
Output Iterator  Used to implement the output iterator expression *i = x. [2] 
back_insert_iterator& operator=(const BackInsertionSequence::value_type&) 
Output Iterator  Used to implement the output iterator expression *i = x. [2] 
back_insert_iterator& operator++() 
Output Iterator  Preincrement. 
back_insert_iterator& operator++(int) 
Output Iterator  Postincrement. 
output_iterator_tag iterator_category(const back_insert_iterator&) 
iterator tags  Returns the iterator's category. This is a global function, not a member. 
template<class BackInsertionSequence> back_insert_iterator<BackInsertionSequence> back_inserter(BackInsertionSequence& S) 
back_insert_iterator 
See below. 
New members
These members are not defined in the Output Iterator requirements, but are specific to back_insert_iterator.
Member function  Description 

back_insert_iterator(BackInsertionSequence& S) 
Constructs a back_insert_iterator that inserts objects after the last element of S. (That is, it inserts objects just before S's pasttheend iterator.) 
template<class BackInsertionSequence> back_insert_iterator<BackInsertionSequence> back_inserter(BackInsertionSequence& S); 
Equivalent to back_insert_iterator<BackInsertionSequence>(S). [3] This is a global function, not a member function. 
Notes
[1] Note the difference between assignment through a BackInsertionSequence::iterator and assignment through a back_insert_iterator<BackInsertionSequence>. If i is a valid BackInsertionSequence::iterator, then it points to some particular element in the back insertion sequence; the expression *i = t replaces that element with t, and does not change the total number of elements in the back insertion sequence. If ii is a valid back_insert_iterator<BackInsertionSequence>, however, then the expression *ii = t is equivalent, to the expression seq.push_back(t). That is, it does not overwrite any of seq's elements and it does change seq's size.
[2] Note how assignment through a back_insert_iterator is implemented. In general, unary operator* must be defined so that it returns a proxy object, where the proxy object defines operator= to perform the insert operation. In this case, for the sake of simplicity, the proxy object is the back_insert_iterator itself. That is, *i simply returns i, and *i = t is equivalent to i = t. You should not, however, rely on this behavior. It is an implementation detail, and it is not guaranteed to remain the same in future versions.
[3] This function exists solely for the sake of convenience: since it is a nonmember function, the template parameters may be inferred and the type of the back_insert_iterator need not be declared explicitly. One easy way to reverse a range and insert it at the end of a Back Insertion Sequence S, for example, is reverse_copy(first, last, back_inserter(S)).
See also
insert_iterator, front_insert_iterator, Output Iterator, Back Insertion Sequence, Sequence, Iterator overview
Categories: iterators, adaptors
Component type: type
Description
Insert_iterator is an iterator adaptor that functions as an Output Iterator: assignment through an insert_iterator inserts an object into a Container. Specifically, if ii is an insert_iterator, then ii keeps track of a Container c and an insertion point p; the expression *ii = x performs the insertion c.insert(p, x). [1]
There are two different Container concepts that define this expression: Sequence, and Sorted Associative Container. Both concepts define insertion into a container by means of c.insert(p, x), but the semantics of this expression is very different in the two cases.
For a Sequence S, the expression S.insert(p, x) means to insert the value ximmediately before the iterator p. That is, the twoargument version of insert allows you to control the location at which the new element will be inserted. For a Sorted Associative Container, however, no such control is possible: the elements in a Sorted Associative Container always appear in ascending order of keys. Sorted Associative Containers define the twoargument version of insert as an optimization. The first argument is only a hint: it points to the location where the search will begin.
If you assign through an insert_iterator several times, then you will be inserting several elements into the underlying container. In the case of a Sequence, they will appear at a particular location in the underlying sequence, in the order in which they were inserted: one of the arguments to insert_iterator's constructor is an iterator p, and the new range will be inserted immediately before p.
In the case of a Sorted Associative Container, however, the iterator in the insert_iterator's constructor is almost irrelevant. The new elements will not necessarily form a contiguous range; they will appear in the appropriate location in the container, in ascending order by key. The order in which they are inserted only affects efficiency: inserting an alreadysorted range into a Sorted Associative Container is an O(N) operation.
Example
Insert a range of elements into a list.
list <int> L;
L.push_front(3);
insert_iterator<list<int> > ii(L, L.begin());
*ii++ = 0;
*ii++ = 1;
*ii++ = 2;
copy(L.begin(), L.end(), ostream_iterator<int>(cout, " "));
// The values that are printed are 0 1 2 3.
Merge two sorted lists, inserting the resulting range into a set. Note that a set never contains duplicate elements.
int main() {
const int N = 6;
int A1[N] = {1, 3, 5, 7, 9, 11};
int A2[N] = {1, 2, 3, 4, 5, 6};
set<int> result;
merge (A1, A1 + N, A2, A2 + N,
inserter(result, result.begin()));
copy(result.begin(), result.end(), ostream_iterator<int>(cout, " "));
cout << endl;
// The output is "1 2 3 4 5 6 7 9 11".
}
Definition
Defined in the standard header iterator, and in the nonstandard backwardcompatibility header iterator.h.
Template parameters
Parameter  Description 

Container 
The type of Container into which values will be inserted. 
Model of
Output Iterator. An insert iterator's set of value types (as defined in the Output Iterator requirements) consists of a single type: Container::value_type.
Type requirements
• The template parameter Container is a model of Container.
• Container is variablesized, as described in the Container requirements.
• Container has a twoargument insert member function. Specifically, if c is an object of type Container, p is an object of type Container::iterator and v is an object of type Container::value_type, then c.insert(p, v) must be a valid expression.
Public base classes
None.
Members
Member  Where defined  Description 

insert_iterator(Container&, Container::iterator) 
insert_iterator 
See below. 
insert_iterator(const insert_iterator&) 
Trivial Iterator  The copy constructor 
insert_iterator& operator=(const insert_iterator&) 
Trivial Iterator  The assignment operator 
insert_iterator& operator*() 
Output Iterator  Used to implement the output iterator expression *i = x. [2] 
insert_iterator& operator=(const Container::value_type&) 
Output Iterator  Used to implement the output iterator expression *i = x. [2] 
insert_iterator& operator++() 
Output Iterator  Preincrement. 
insert_iterator& operator++(int) 
Output Iterator  Postincrement. 
output_iterator_tag iterator_category(const insert_iterator&) 
iterator tags  Returns the iterator's category. This is a global function, not a member. 
template<class Container, class Iter) insert_iterator<Container> inserter(Container& C, Iter i); 
insert_iterator 
See below. 
New members
These members are not defined in the Output Iterator requirements, but are specific to insert_iterator.
Member  Description 

insert_iterator(Container& C, Container::iterator i) 
Constructs an insert_iterator that inserts objects in C. If Container is a Sequence, then each object will be inserted immediately before the element pointed to by i. If C is a Sorted Associative Container, then the first insertion will use i as a hint for beginning the search. The iterator i must be a dereferenceable or pasttheend iterator in C. 
template<class Container, class Iter) insert_iterator<Container> inserter(Container& C, Iter i); 
Equivalent to insert_iterator<Container>(C, i). [2] This is a global function, not a member function. 
Notes
[1] Note the difference between assignment through a Container::iterator and assignment through an insert_iterator<Container>. If i is a valid Sequence::iterator, then it points to some particular element in the container; the expression *i = t replaces that element with t, and does not change the total number of elements in the container. If ii is a valid insert_iterator<container>, however, then the expression *ii = t is equivalent, for some container c and some valid container::iterator j, to the expression c.insert(j, t). That is, it does not overwrite any of c's elements and it does change c's size.
[2] Note how assignment through an insert_iterator is implemented. In general, unary operator* must be defined so that it returns a proxy object, where the proxy object defines operator= to perform the insert operation. In this case, for the sake of simplicity, the proxy object is the insert_iterator itself. That is, *i simply returns i, and *i = t is equivalent to i = t. You should not, however, rely on this behavior. It is an implementation detail, and it is not guaranteed to remain the same in future versions.
[3] This function exists solely for the sake of convenience: since it is a nonmember function, the template parameters may be inferred and the type of the insert_iterator need not be declared explicitly. One easy way to reverse a range and insert it into a Sequence S, for example, is reverse_copy(first, last, inserter(S, S.begin())).
See also
front_insert_iterator, back_insert_iterator, Output Iterator, Sequence, Iterator overview
reverse_iterator<RandomAccessIterator, T, Reference, Distance>
Categories: iterators, adaptors
Component type: type
Description
Reverse_iterator is an iterator adaptor that enables backwards traversal of a range. Operator++ applied to an object of class reverse_iterator<RandomAccessIterator> means the same thing as operator applied to an object of class RandomAccessIterator. There are two different reverse iterator adaptors: the class reverse_iterator has a template argument that is a Random Access Iterator, and the class reverse_bidirectional_iterator has a template argument that is a Bidirectional Iterator. [1]
Example
template <class T>
void forw(const vector<T>& V) {
vector<T>::iterator first = V.begin();
vector<T>::iterator last = V.end();
while (first != last) cout << *first++ << endl;
}
template <class T>
void rev(const vector<T>& V) {
typedef reverse_iterator<vector<T>::iterator, T, vector<T>::reference_type, vector<T>::difference_type> reverse_iterator; [2]
reverse_iterator rfirst(V.end());
reverse_iterator rlast(V.begin());
while (rfirst != rlast) cout << *rfirst++ << endl;
}
In the function forw, the elements are printed in the order *first, *(first+1) , …, *(last1). In the function rev, they are printed in the order *(last – 1), *(last  2), …, *first. [3]
Definition
Defined in the standard header iterator, and in the nonstandard backwardcompatibility header iterator.h.
Template parameters
Parameter  Description  Default 

RandomAccessIterator 
The base iterator class. Incrementing an object of class reverse_iterator<Iterator> corresponds to decrementing an object of class Iterator.  
T 
The reverse iterator's value type. This should always be the same as the base iterator's value type.  
Reference 
The reverse iterator's reference type. This should always be the same as the base iterator's reference type.  T& 
Distance 
The reverse iterator's distance type. This should always be the same as the base iterator's distance type.  ptrdiff_t 
Model of
Random Access Iterator
Type requirements
The base iterator type (that is, the template parameter RandomAccessIterator) must be a Random Access Iterator. The reverse_iterator's value type, reference type, and distance type (that is, the template parameters T, Reference, and Distance, respectively) must be the same as the base iterator's value type, reference type, and distance type.
Public base classes
None.
Members
Member  Where defined  Description 

self 
reverse_iterator 
See below 
reverse_iterator() 
Trivial Iterator  The default constructor 
reverse_iterator(const reverse_iterator& x) 
Trivial Iterator  The copy constructor 
reverse_iterator& operator=(const reverse_iterator& x) 
Trivial Iterator  The assignment operator 
reverse_iterator(RandomAccessIterator x) 
reverse_iterator 
See below. 
RandomAccessIterator base() 
reverse_iterator 
See below. 
Reference operator*() const 
Trivial Iterator  The dereference operator 
reverse_iterator& operator++() 
Forward Iterator  Preincrement 
reverse_iterator operator++(int) 
Forward Iterator  Postincrement 
reverse_iterator& operator() 
Bidirectional Iterator  Predecrement 
reverse_iterator operator(int) 
Bidirectional Iterator  Postdecrement 
reverse_iterator operator+(Distance) 
Random Access Iterator  Iterator addition 
reverse_iterator& operator+=(Distance) 
Random Access Iterator  Iterator addition 
reverse_iterator operator(Distance) 
Random Access Iterator  Iterator subtraction 
reverse_iterator& operator=(Distance) 
Random Access Iterator  Iterator subtraction 
Reference operator[](Distance) 
Random Access Iterator  Random access to an element. 
reverse_iterator operator+(Distance, reverse_iterator) 
Random Access Iterator  Iterator addition. This is a global function, not a member function. 
Distance operator(const reverse_iterator&, const reverse_iterator&) 
Random Access Iterator  Finds the distance between two iterators. This is a global function, not a member function. 
bool operator==(const reverse_iterator&, const reverse_iterator&) 
Trivial Iterator  Compares two iterators for equality. This is a global function, not a member function. 
bool operator<(const reverse_iterator&, const reverse_iterator&) 
Random Access Iterator  Determines whether the first argument precedes the second. This is a global function, not a member function. 
random_access_iterator_tag iterator_category(const reverse_iterator&) 
Iterator tags  Returns the iterator's category. This is a global function, not a member function. 
T* value_type(const reverse_iterator&) 
Iterator tags  Returns the iterator's value type. This is a global function, not a member function. 
Distance* distance_type(const reverse_iterator&) 
Iterator tags  Returns the iterator's distance type. This is a global function, not a member function. 
New members
These members are not defined in the Random Access Iterator requirements, but are specific to reverse_iterator.
Member  Description 

self 
A typedef for reverse_iterator<RandomAccessIterator, T, Reference, Distance>. 
RandomAccessIterator base() 
Returns the current value of the reverse_iterator's base iterator. If ri is a reverse iterator and i is any iterator, the two fundamental identities of reverse iterators can be written as reverse_iterator(i).base() == i and &*ri == &*(ri.base() – 1). 
reverse_iterator(RandomAccessIterator i) 
Constructs a reverse_iterator whose base iterator is i. 
Notes
[1] There isn't really any good reason to have two separate classes: this separation is purely because of a technical limitation in some of today's C++ compilers. If the two classes were combined into one, then there would be no way to declare the return types of the iterator tag functions iterator_category, distance_type and value_type correctly. The iterator traits class solves this problem: it addresses the same issues as the iterator tag functions, but in a cleaner and more flexible manner. Iterator traits, however, rely on partial specialization, and many C++ compilers do not yet implement partial specialization. Once compilers that support partial specialization become more common, these two different reverse iterator classes will be combined into a single class.
[2] The declarations for rfirst and rlast are written in this clumsy form simply as an illustration of how to declare a reverse_iterator. Vector is a Reversible Container, so it provides a typedef for the appropriate instantiation of reverse_iterator. The usual way of declaring these variables is much simpler:
vector<T>::reverse_iterator rfirst = rbegin();
vector<T>::reverse_iterator rlast = rend();
[3] Note the implications of this remark. The variable rfirst is initialized as reverse_iterator<…> rfirst(V.end());. The value obtained when it is dereferenced, however, is *(V.end() – 1). This is a general property: the fundamental identity of reverse iterators is &*(reverse_iterator(i)) == &*(i – 1). This code sample shows why this identity is important: if [f, l) is a valid range, then it allows [reverse_iterator(l), reverse_iterator(f)) to be a valid range as well. Note that the iterator l is not part of the range, but it is required to be dereferenceable or pasttheend. There is no requirement that any such iterator precedes f.
See also
Reversible Container, reverse_bidirectional_iterator, Random Access Iterator, iterator tags, Iterator Overview
reverse_bidirectional_iterator<BidirectionalIterator, T, Reference, Distance>
Categories: iterators, adaptors
Component type: type
Description
Reverse_bidirectional_iterator is an iterator adaptor that enables backwards traversal of a range. Operator++ applied to an object of class reverse_bidirectional_iterator<BidirectionalIterator> means the same thing as operator applied to an object of class BidirectionalIterator. There are two different reverse iterator adaptors: the class reverse_bidirectional_iterator has a template argument that is a Bidirectional Iterator, and the class reverse_iterator has a template argument that is a Random Access Iterator. [1]
Example
template <class T>
void forw(const list <T>& L) {
list<T>::iterator first = L.begin();
list<T>::iterator last = L.end();
while (first != last) cout << *first++ << endl;
}
template <class T>
void rev(const list <T>& L) {
typedef reverse_bidirectional_iterator<list<T>::iterator, T, list<T>::reference_type, list<T>::difference_type> reverse_iterator; [2]
reverse_iterator rfirst(L.end());
reverse_iterator rlast(L.begin());
while (rfirst != rlast) cout << *rfirst++ << endl;
}
In the function forw, the elements are printed in the order *first, *(first+1) , …, *(last1). In the function rev, they are printed in the order *(last – 1), *(last  2), …, *first. [3]
Definition
Defined in the standard header iterator, and in the nonstandard backwardcompatibility header iterator.h. This class is no longer part of the C++ standard, but it was present in early drafts, and it is retained in this implementation for backward compatibility.
Template parameters
Parameter  Description  Default 

BidirectionalIterator 
The base iterator class. Incrementing an object of class reverse_bidirectional_iterator<BidirectionalIterator> corresponds to decrementing an object of class BidirectionalIterator.  
T 
The reverse iterator's value type. This should always be the same as the base iterator's value type.  
Reference 
The reverse iterator's reference type. This should always be the same as the base iterator's reference type.  T& 
Distance 
The reverse iterator's distance type. This should always be the same as the base iterator's distance type.  ptrdiff_t 
Model of
Bidirectional Iterator.
Type requirements
The base iterator type (that is, the template parameter BidirectionalIterator) must be a Bidirectional Iterator. The reverse_bidirectional_iterator's value type, reference type, and distance type (that is, the template parameters T, Reference, and Distance, respectively) must be the same as the base iterator's value type, reference type, and distance type.
Public base classes
None.
Members
Member  Where defined  Description 

self 
reverse_bidirectional_iterator 
See below 
reverse_bidirectional_iterator() 
Trivial Iterator  The default constructor 
reverse_bidirectional_iterator(const reverse_bidirectional_iterator& x) 
Trivial Iterator  The copy constructor 
reverse_bidirectional_iterator& operator=(const reverse_bidirectional_iterator& x) 
Trivial Iterator  The assignment operator 
reverse_bidirectional_iterator(BidirectionalIterator x) 
reverse_bidirectional_iterator 
See below. 
BidirectionalIterator base() 
reverse_bidirectional_iterator  See below. 
Reference operator*() const 
Trivial Iterator  The dereference operator 
reverse_bidirectional_iterator& operator++() 
Forward Iterator  Preincrement 
reverse_bidirectional_iterator operator++(int) 
Forward Iterator  Postincrement 
reverse_bidirectional_iterator& operator() 
Bidirectional Iterator  Predecrement 
reverse_bidirectional_iterator operator(int) 
Bidirectional Iterator  Postdecrement 
bool operator==(const reverse_bidirectional_iterator&, const reverse_bidirectional_iterator&) 
Trivial Iterator  Compares two iterators for equality. This is a global function, not a member function. 
bidirectional_iterator_tag iterator_category(const reverse_bidirectional_iterator&) 
Iterator tags  Returns the iterator's category. This is a global function, not a member function. 
T* value_type(const reverse_bidirectional_iterator&) 
Iterator tags  Returns the iterator's value type. This is a global function, not a member function. 
Distance* distance_type(const reverse_bidirectional_iterator&) 
Iterator tags  Returns the iterator's distance type. This is a global function, not a member function. 
New members
These members are not defined in the Bidirectional Iterator requirements, but are specific to reverse_bidirectional_iterator.
Member  Description 

self 
A typedef for reverse_bidirectional_iterator<BidirectionalIterator, T, Reference, Distance>. 
BidirectionalIterator base() 
Returns the current value of the reverse_bidirectional_iterator's base iterator. If ri is a reverse iterator and i is any iterator, the two fundamental identities of reverse iterators can be written as reverse_bidirectional_iterator(i).base() == i and &*ri == &*(ri.base() – 1). 
reverse_bidirectional_iterator(BidirectionalIterator i) 
Constructs a reverse_bidirectional_iterator whose base iterator is i. 
Notes
[1] There isn't really any good reason to have two separate classes: this separation is purely because of a technical limitation in some of today's C++ compilers. If the two classes were combined into one, then there would be no way to declare the return types of the iterator tag functions iterator_category, distance_type and value_type correctly. The iterator traits class solves this problem: it addresses the same issues as the iterator tag functions, but in a cleaner and more flexible manner. Iterator traits, however, rely on partial specialization, and many C++ compilers do not yet implement partial specialization. Once compilers that support partial specialization become more common, these two different reverse iterator classes will be combined into a single class.
[2] The declarations for rfirst and rlast are written in this clumsy form simply as an illustration of how to declare a reverse_bidirectional_iterator. List is a Reversible Container, so it provides a typedef for the appropriate instantiation of reverse_bidirectional_iterator. The usual way of declaring these variables is much simpler:
list<T>::reverse_bidirectional_iterator rfirst = rbegin();
list<T>::reverse_bidirectional_iterator rlast = rend();
[3] Note the implications of this remark. The variable rfirst is initialized as reverse_bidirectional_iterator<…> rfirst(V.end());. The value obtained when it is dereferenced, however, is *(V.end() – 1). This is a general property: the fundamental identity of reverse iterators is &*(reverse_bidirectional_iterator(i)) == &*(i – 1). This code sample shows why this identity is important: if [f, l) is a valid range, then it allows [reverse_bidirectional_iterator(l), reverse_bidirectional_iterator(f)) to be a valid range as well. Note that the iterator l is not part of the range, but it is required to be dereferenceable or pasttheend. There is no requirement that any such iterator precedes f.
See also
Reversible Container, reverse_iterator, Bidirectional Iterator, iterator tags, Iterator overview
raw_storage_iterator<ForwardIterator, T>
Categories: allocators, iterators, adaptors
Component type: type
Description
In C++, the operator new allocates memory for an object and then creates an object at that location by calling a constructor. Occasionally, however, it is useful to separate those two operations. [1] If i is an iterator that points to a region of uninitialized memory, then you can use construct to create an object in the location pointed to by i. Raw_storage_iterator is an adaptor that makes this procedure more convenient. If r is a raw_storage_iterator, then it has some underlying iterator i. The expression *r = x is equivalent to construct(&*i, x).
Example
class Int {
public:
Int(int x) : val(x) {}
int get() { return val; }
private:
int val;
};
int main() {
int A1[] = {1, 2, 3, 4, 5, 6, 7};
const int N = sizeof(A1) / sizeof(int);
Int* A2 = (Int*)malloc(N * sizeof(Int));
transform(A1, A1 + N, raw_storage_iterator<Int*, int>(A2), negate<int>());
}
Definition
Defined in the standard header memory, and in the nonstandard backwardcompatibility header iterator.h.
Template parameters
Parameter  Description 

OutputIterator  The type of the raw_storage_iterator's underlying iterator. 
T 
The type that will be used as the argument to the constructor. 
Model of
Output Iterator
Type requirements
• ForwardIterator is a model of Forward Iterator
• ForwardIterator's value type has a constructor that takes a single argument of type T.
Public base classes
None.
Members
Member  Where defined  Description 

raw_storage_iterator(ForwardIterator x) 
raw_storage_iterator 
See below. 
raw_storage_iterator(const raw_storage_iterator&) 
trivial iterator  The copy constructor 
raw_storage_iterator& operator=(const raw_storage_iterator&) 
trivial iterator  The assignment operator 
raw_storage_iterator& operator*() 
Output Iterator  Used to implement the output iterator expression *i = x. [2] 
raw_storage_iterator& operator=(const Sequence::value_type&) 
Output Iterator  Used to implement the output iterator expression *i = x. [2] 
raw_storage_iterator& operator++() 
Output Iterator  Preincrement. 
raw_storage_iterator& operator++(int) 
Output Iterator  Postincrement. 
output_iterator_tag iterator_category(const raw_storage_iterator&) 
iterator tags  Returns the iterator's category. This is a global function, not a member. 
New members
These members are not defined in the Output Iterator requirements, but are specific to raw_storage_iterator.
Function  Description 

raw_storage_iterator(ForwardIterator i) 
Creates a raw_storage_iterator whose underlying iterator is i. 
raw_storage_iterator& operator=(const T& val) 
Constructs an object of ForwardIterator's value type at the location pointed to by the iterator, using val as the constructor's argument. 
Notes
[1] In particular, this sort of lowlevel memory management is used in the implementation of some container classes.
[2] Note how assignment through a raw_storage_iterator is implemented. In general, unary operator* must be defined so that it returns a proxy object, where the proxy object defines operator= to perform the insert operation. In this case, for the sake of simplicity, the proxy object is the raw_storage_iterator itself. That is, *i returns i, and *i = t is equivalent to i = t . You should not, however, rely on this behavior. It is an implementation detail, and it is not guaranteed to remain the same in future versions.
See also
Allocators, construct, destroy, uninitialized_copy uninitialized_fill, uninitialized_fill_n
sequence_buffer<Container, buf_sz>
Categories: iterators, adaptors
Component type: type
Description
Sequence_buffer is similar to back_insert_iterator: it is an output iterator adaptor that appends elements to the end of a container.
The main difference between sequence_buffer and back_insert_iterator is that back_insert_iterator inserts elements into a sequence one element at a time; sequence_buffer, however, as the "buffer" part of the name suggests, accumulates elements into a buffer and appends the entire buffer in a single operation.
Specifically, the expression *it = v adds v to the end of it's internal buffer. The buffer is automatically flushed when it gets full, or when it is destroyed; flushing the buffer means emptying it and appending its contents to it 's underlying container. (It is also possible to flush the buffer manually, by invoking the flush() member function.)
This difference has two implications. First, sequence_buffer is only useful if appending an array of N elements is much more efficient than inserting a single element N times. Second, sequence_buffer assumes that it can insert elements at the end of a container using an append member function. This member function is not part of the Container or Sequence requirements. The sequence_buffer adaptor can be used with rope, but not with any of the other containers in the library. (This is the reason why sequence_buffer is defined in the file rope.h, instead of in iterator.h.)
If you want to build up a string one character at a time, it is much more efficient to use sequence_buffer than to repeatedly add single characters to the end of a rope.
Example
int main() {
const char* const s = "this is a test";
const int N = strlen(s);
crope r;
transform(s, s + N, sequence_buffer<crope>(r), toupper);
cout << "r = " << r << endl;
}
Definition
Defined in the header rope, and in the backwardcompatibility header rope.h. The sequence_buffer class, and the rope header, are SGI extensions; they are not part of the C++ standard.
Template parameters
Parameter  Description  Default 

Container 
The type of the underlying container that elements are being written to. [1]  
buf_sz 
Number of elements in the buffer. This is a number, not a type. buf_sz has type size_t.  100 
Model of
Output Iterator.
Type requirements
• Container is a variablesized Forward Container
• Container 's value type T is a model of Default Constructible, as well as Assignable.
• Container has a member function that appends a range. Specifically: If x is an object of type Container and f and l are of type T*, then x.append(f, l) appends the range [f, l) to x. [1]
Public base classes
output_iterator
Members
Member  Where defined  Description 

value_type 
sequence_buffer 
The underlying container's value type. 
sequence_buffer(Container& C) 
sequence_buffer 
Create a sequence_buffer whose underlying container is C. 
sequence_buffer() 
Default Constructible  The default constructor. The resulting iterator is singular. 
sequence_buffer(const sequence_buffer&) 
Assignable  Copy constructor. 
sequence_buffer& operator=(const sequence_buffer& s) 
Assignable  Assignment operator. 
sequence_buffer& operator=(sequence_buffer& s) 
Assignable  Faster version of assignment operator. 
sequence_buffer& operator=(const value_type&) 
Output Iterator  Used to implement the Output Iterator requirement *i = t. [2] 
sequence_buffer& operator*() 
Output Iterator  Used to implement the Output Iterator requirement *i = t. [2] 
sequence_buffer& operator++() 
Output Iterator  Preincrement 
sequence_buffer& operator++(int) 
Output Iterator  Postincrement 
void flush() 
sequence_buffer 
Flush the buffer. 
void push_back(value_type) 
sequence_buffer 
i.push_back(x) is equivalent to *i = x. 
void append(value_type* s, size_t len) 
sequence_buffer 
Append multiple values. 
New members
These members are not defined in the Output Iterator requirements, but are specific to sequence_buffer.
Function  Description 

value_type 
The underlying container's value type. That is, typename Container::value_type. 
sequence_buffer(Container& C) 
Create a sequence_buffer whose underlying container is C. Elements appended to the sequence_buffer will be appended to C whenever the sequence_buffer is flushed. 
void flush() 
Append all elements in the buffer to the underlying container, and empty the buffer. That is, make the underlying container consistent with the sequence_buffer. Note that flush is called automatically whenever the buffer is full, and also by sequence_buffer's destructor. Sometimes, however, it is useful to be sure that the buffer is flushed at a particular time. 
void push_back(value_type x) 
Append x to the sequence_buffer. Note that this member function is strictly unnecessary: i.push_back(x) is just alternate syntax for *i = x. 
void append(value_type* s, size_t len) 
Append the range [s, s + len) to the sequence_buffer. Note that i.append(s, n) is just the same as copy(s, s + n, i). The append member function, however, is faster. 
Notes
[1] Despite the name "sequence_buffer", this adaptor cannot actually be used with arbitrary sequences: it requires that the template argument Container have an append member function that can insert multiple elements at the end of the container. This member function is not part of the Sequence requirements. This means that sequence_buffer can be used with rope, but not with any of the other predefined container classes.
[2] Note how assignment through a sequence_buffer is implemented. In general, unary operator* must be defined so that it returns a proxy object, where the proxy object defines operator= to perform the output operation. In this case, for the sake of simplicity, the proxy object is the sequence_buffer itself. That is, *i simply returns i, and *i = t is equivalent to i = t. You should not, however, rely on this behavior. It is an implementation detail, and it is not guaranteed to remain the same in future versions.
See also
Output Iterator, rope, front_insert_iterator, back_insert_iterator, insert_iterator
Category: algorithms
Component type: function
Prototype
template <class InputIterator, class UnaryFunction>
UnaryFunction for_each(InputIterator first, InputIterator last, UnaryFunction f);
Description
For_each applies the function object f to each element in the range [first, last); f's return value, if any, is ignored. Applications are performed in forward order, i.e. from first to last. For_each returns the function object after it has been applied to each element. [1]
Definition
Defined in the standard header algorithm, and in the nonstandard backwardcompatibility header algo.h.
Requirements on types
• InputIterator is a model of Input Iterator
• UnaryFunction is a model of Unary Function
• UnaryFunction does not apply any nonconstant operation through its argument.
• InputIterator's value type is convertible to UnaryFunction 's argument type.
Preconditions
• [first, last) is a valid range.
Complexity
Linear. Exactly last – first applications of UnaryFunction.
Example
template<class T> struct print : public unary_function<T, void> {
print(ostream& out) : os(out), count(0) {}
void operator() (T x) { os << x << ' '; ++count; }
ostream& os;
int count;
};
int main() {
int A[] = {1, 4, 2, 8, 5, 7};
const int N = sizeof(A) / sizeof(int);
print<int> P = for_each(A, A + N, print<int>(cout));
cout << endl << P.count << " objects printed." << endl;
}
Notes
[1] This return value is sometimes useful, since a function object may have local state. It might, for example, count the number of times that it is called, or it might have a status flag to indicate whether or not a call succeeded.
See also
The function object overview, count, copy
Category: algorithms
Component type: function
Prototype
template<class InputIterator, class EqualityComparable>
InputIterator find(InputIterator first, InputIterator last, const EqualityComparable& value);
Description
Returns the first iterator i in the range [first, last) such that *i == value. Returns last if no such iterator exists.
Definition
Defined in the standard header algorithm, and in the nonstandard backwardcompatibility header algo.h.
Requirements on types
• EqualityComparable is a model of EqualityComparable.
• InputIterator is a model of InputIterator.
• Equality is defined between objects of type EqualityComparable and objects of InputIterator's value type.
Preconditions
• [first, last) is a valid range.
Complexity
Linear: at most last – first comparisons for equality.
Example
list <int>L;
L.push_back(3);
L.push_back(1);
L.push_back(7);
list<int>::iterator result = find(L.begin(), L.end(), 7);
assert(result == L.end()  *result == 7);
See also
find_if.
Category: algorithms
Component type: function
Prototype
template<class InputIterator, class Predicate>
InputIterator find_if(InputIterator first, InputIterator last, Predicate pred);
Description
Returns the first iterator i in the range [first, last) such that pred(*i) is true. Returns last if no such iterator exists.
Definition
Defined in the standard header algorithm, and in the nonstandard backwardcompatibility header algo.h.
Requirements on types
• Predicate is a model of Predicate.
• InputIterator is a model of InputIterator.
• The value type of InputIterator is convertible to the argument type of Predicate.
Preconditions
• [first, last) is a valid range.
• For each iterator i in the range [first, last), *i is in the domain of Predicate.
Complexity
Linear: at most last – first applications of Pred.
Example
list<int> L;
L.push_back(3);
L.push_back(0);
L.push_back(3); L.push_back(2);
list<int>::iterator result = find_if(L.begin(), L.end(), bind2nd(greater<int>(), 0));
assert(result == L.end()  *result > 0);
See also
find.
Category: algorithms
Component type: function
Prototype
Adjacent_find is an overloaded name; there are actually two adjacent_find functions.
template <class ForwardIterator>
ForwardIterator adjacent_find(ForwardIterator first, ForwardIterator last);
template <class ForwardIterator, class BinaryPredicate>
ForwardIterator adjacent_find(ForwardIterator first, ForwardIterator last, BinaryPredicate binary_pred);
Description
The first version of adjacent_find returns the first iterator i such that i and i+1 are both valid iterators in [first, last), and such that *i == *(i+1). It returns last if no such iterator exists.
The second version of adjacent_find returns the first iterator i such that i and i+1 are both valid iterators in [first, last), and such that binary_pred(*i, *(i+1)) is true. It returns last if no such iterator exists.
Definition
Defined in the standard header algorithm, and in the nonstandard backwardcompatibility header algo.h.
Requirements on types
For the first version:
• ForwardIterator is a model of Forward Iterator.
• ForwardIterator 's value type is Equality Comparable.
For the second version:
• ForwardIterator is a model of Forward Iterator.
• ForwardIterator's value type is convertible to BinaryPredicate's first argument type and to its second argument type.
Preconditions
• [first, last) is a valid range.
Complexity
Linear. If first == last then no comparison are performed; otherwise, at most (last – first) – 1 comparisons.
Example
Find the first element that is greater than its successor.
int A[] = {1, 2, 3, 4, 6, 5, 7, 8};
const int N = sizeof(A) / sizeof(int);
const int* p = adjacent_find(A, A + N, greater <int>());
cout << "Element " << p – A << " is out of order: " << *p << " > " << *(p + 1) << "." << endl;
See also
find, mismatch, equal, search
Category: algorithms
Component type: function
Prototype
find_first_of is an overloaded name; there are actually two find_first_of functions.
template <class InputIterator, class ForwardIterator>
InputIterator find_first_of(InputIterator first1, InputIterator last1, ForwardIterator first2, ForwardIterator last2);
template <class InputIterator, class ForwardIterator, class BinaryPredicate>
InputIterator find_first_of(InputIterator first1, InputIterator last1, ForwardIterator first2, ForwardIterator last2, BinaryPredicate comp);
Description
Find_first_of is similar to find, in that it performs linear seach through a range of Input Iterators. The difference is that while find searches for one particular value, find_first_of searches for any of several values. Specifically, find_first_of searches for the first occurrance in the range [first1, last1) of any of the elements in [first2, last2). (Note that this behavior is reminiscent of the function strpbrk from the standard C library.)
The two versions of find_first_of differ in how they compare elements for equality. The first uses operator==, and the second uses and arbitrary usersupplied function object comp. The first version returns the first iterator i in [first1, last1) such that, for some iterator j in [first2, last2), *i == *j. The second returns the first iterator i in [first1, last1) such that, for some iterator j in [first2, last2), comp(*i, *j) is true. As usual, both versions return last1 if no such iterator i exists.
Definition
Defined in the standard header algorithm, and in the nonstandard backwardcompatibility header algo.h.
Requirements on types
For the first version:
• InputIterator is a model of Input Iterator.
• ForwardIterator is a model of Forward Iterator.
• InputIterator 's value type is EqualityComparable , and can be compared for equality with ForwardIterator's value type.
For the second version:
• InputIterator is a model of Input Iterator.
• ForwardIterator is a model of Forward Iterator.
• BinaryPredicate is a model of Binary Predicate.
• InputIterator's value type is convertible to BinaryPredicate's first argument type.
• ForwardIterator's value type is convertible to BinaryPredicate's second argument type.
Preconditions
• [first1, last1) is a valid range.
• [first2, last2) is a valid range.
Complexity
At most (last1 – first1) * (last2 – first2) comparisons.
Example
Like strpbrk, one use for find_first_of is finding whitespace in a string; space, tab, and newline are all whitespace characters.
int main() {
const char* WS = "\t\n ";
const int n_WS = strlen(WS);
char* s1 = "This sentence contains five words.";
char* s2 = "OneWord";
char* end1 = find_first_of(s1, s1 + strlen(s1), WS, WS + n_WS);
char* end2 = find_first_of(s2, s2 + strlen(s2), WS, WS + n_WS);
printf("First word of s1: %.*s\n", end1 – s1, s1);
printf("First word of s2: %.*s\n", end2 – s2, s2);
}
See also
find, find_if, search
Category: algorithms
Component type: function
Prototype
Count is an overloaded name: there are two count functions.
template <class InputIterator, class EqualityComparable>
iterator_traits<InputIterator>::difference_type count(InputIterator first, InputIterator last, const EqualityComparable& value);
template <class InputIterator, class EqualityComparable, class Size>
void count(InputIterator first, InputIterator last, const EqualityComparable& value, Size& n);
Description
Count finds the number of elements in [first, last) that are equal to value. More precisely, the first version of count returns the number of iterators i in [first, last) such that *i == value. The second version of count adds to n the number of iterators i in [first, last) such that *i == value.
The second version of count was the one defined in the original STL, and the first version is the one defined in the draft C++ standard; the definition was changed because the older interface was clumsy and errorprone. The older interface required the use of a temporary variable, which had to be initialized to 0 before the call to count.
Both interfaces are currently supported [1], for reasons of backward compatibility, but eventually the older version will be removed.
Definition
Defined in the standard header algorithm, and in the nonstandard backwardcompatibility header algo.h.
Requirements on types
For the first version, which takes three arguments:
• InputIterator is a model of Input Iterator.
• EqualityComparable is a model of Equality Comparable.
• InputIterator's value type is a model of Equality Comparable.
• An object of InputIterator's value type can be compared for equality with an object of type EqualityComparable.
For the second version, which takes four arguments:
• InputIterator is a model of Input Iterator.
• EqualityComparable is a model of Equality Comparable.
• Size is an integral type that can hold values of InputIterator's distance type.
• InputIterator's value type is a model of Equality Comparable.
• An object of InputIterator's value type can be compared for equality with an object of type EqualityComparable.
Preconditions
• [first, last) is a valid range.
For the second version:
• [first, last) is a valid range.
• n plus the number of elements equal to value does not exceed the maximum value of type Size.
Complexity
Linear. Exactly last – first comparisons.
Example
int main() {
int A[] = { 2, 0, 4, 6, 0, 3, 1, –7 };
const int N = sizeof(A) / sizeof(int);
cout << "Number of zeros: " << count(A, A + N, 0) << endl;
}
Notes
[1] The new count interface uses the iterator_traits class, which relies on a C++ feature known as partial specialization. Many of today's compilers don't implement the complete standard; in particular, many compilers do not support partial specialization. If your compiler does not support partial specialization, then you will not be able to use the newer version of count, or any other STL components that involve iterator_traits.
See also
count_if, find, find_if
Category: algorithms
Component type: function
Prototype
Count_if is an overloaded name: there are two count_if functions.
template <class InputIterator, class Predicate> iterator_traits<InputIterator>::difference_type count_if(InputIterator first, InputIterator last, Predicate pred);
template <class InputIterator, class Predicate, class Size>
void count_if(InputIterator first, InputIterator last, Predicate pred, Size& n);
Description
Count_if finds the number of elements in [first, last) that satisfy the predicate pred. More precisely, the first version of count_if returns the number of iterators i in [first, last) such that pred(*i) is true . The second version of count adds to n the number of iterators i in [first, last) such that pred(*i) is true.
The second version of count_if was the one defined in the original STL, and the first version is the one defined in the draft C++ standard; the definition was changed because the older interface was clumsy and errorprone. The older interface required the use of a temporary variable, which had to be initialized to 0 before the call to count_if.
Both interfaces are currently supported [1], for reasons of backward compatibility, but eventually the older version will be removed.
Definition
Defined in the standard header algorithm, and in the nonstandard backwardcompatibility header algo.h.
Requirements on types
For the first version, which takes three arguments:
• InputIterator is a model of Input Iterator.
• Predicate is a model of Predicate.
• InputIterator's value type is convertible to Predicate's argument type.
For the second version, which takes four arguments:
• InputIterator is a model of Input Iterator.
• Predicate is a model of Predicate.
• Size is an integral type that can hold values of InputIterator's distance type.
• InputIterator's value type is convertible to Predicate's argument type.
Preconditions
For the first version:
• [first, last) is a valid range.
For the second version:
• [first, last) is a valid range.
• n plus the number of elements that satisfy pred does not exceed the maximum value of type Size.
Complexity
Linear. Exactly last – first applications of pred.
Example
int main() {
int A[] = { 2, 0, 4, 6, 0, 3, 1, –7 };
const int N = sizeof(A) / sizeof(int);
cout << "Number of even elements: " << count_if(A, A + N, compose1(bind2nd(equal_to<int>(), 0), bind2nd(modulus<int>(), 2))) << endl;
}
Notes
[1] The new count interface uses the iterator_traits class, which relies on a C++ feature known as partial specialization . Many of today's compilers don't implement the complete standard; in particular, many compilers do not support partial specialization. If your compiler does not support partial specialization, then you will not be able to use the newer version of count, or any other STL components that involve iterator_traits.
See also
count, find, find_if
Category: algorithms
Component type: function
Prototype
Mismatch is an overloaded name; there are actually two mismatch functions.
template <class InputIterator1, class InputIterator2>
pair<InputIterator1, InputIterator2> mismatch(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2);
template <class InputIterator1, class InputIterator2, class BinaryPredicate>
pair<InputIterator1, InputIterator2> mismatch(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, BinaryPredicate binary_pred);
Description
Mismatch finds the first position where the two ranges [first1, last1) and [first2, first2 + (last1 – first1)) differ. The two versions of mismatch use different tests for whether elements differ.
The first version of mismatch finds the first iterator i in [first1, last1) such that *i != *(first2 + (i – first1)). The return value is a pair whose first element is i and whose second element is *(first2 + (i – first1)). If no such iterator i exists, the return value is a pair whose first element is last1 and whose second element is *(first2 + (last1 – first1)).
The second version of mismatch finds the first iterator i in [first1, last1) such that binary_pred(*i, *(first2 + (i – first1)) is false. The return value is a pair whose first element is i and whose second element is *(first2 + (i – first1)). If no such iterator i exists, the return value is a pair whose first element is last1 and whose second element is *(first2 + (last1 – first1)).
Definition
Defined in the standard header algorithm, and in the nonstandard backwardcompatibility header algo.h.
Requirements on types
For the first version:
• InputIterator1 is a model of Input Iterator.
• InputIterator2 is a model of Input Iterator.
• InputIterator1's value type is a model of Equality Comparable.
• InputIterator2's value type is a model of Equality Comparable.
• InputIterator1's value type can be compared for equality with InputIterator2's value type.
For the second version:
• InputIterator1 is a model of Input Iterator.
• InputIterator2 is a model of Input Iterator.
• BinaryPredicate is a model of Binary Predicate.
• InputIterator1's value type is convertible to BinaryPredicate's first argument type.
• InputIterator2's value type is convertible to BinaryPredicate's second argument type.
Preconditions
• [first1, last1) is a valid range.
• [first2, first2 + (last2 – last1)) is a valid range.
Complexity
Linear. At most last1 – first1 comparisons.
Example
int A1[] = { 3, 1, 4, 1, 5, 9, 3 };
int A2[] = { 3, 1, 4, 2, 8, 5, 7 };
const int N = sizeof(A1) / sizeof(int);
pair<int*, int*> result = mismatch(A1, A1 + N, A2);
cout << "The first mismatch is in position " << result.first – A1 << endl;
cout << "Values are: " << *(result.first) << ", " << *(result.second) << endl;
See also
equal, search, find, find_if
Category: algorithms
Component type: function
Prototype
Equal is an overloaded name; there are actually two equal functions.
template <class InputIterator 1, class InputIterator 2>
bool equal(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2);
template <class InputIterator 1, class InputIterator 2, class BinaryPredicate>
bool equal(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, BinaryPredicate binary_pred);
Description
Equal returns true if the two ranges [first1, last1) and [first2, first2 + (last1 – first1)) are identical when compared elementbyelement, and otherwise returns false. [1]
The first version of equal returns true if and only if for every iterator i in [first1, last1), *i == *(first2 + (i – first1)). The second version of equal returns true if and only if for every iterator i in [first1, last1), binary_pred(*i, *(first2 + (i – first1)) is true.
Definition
Defined in the standard header algorithm, and in the nonstandard backwardcompatibility header algo.h.
Requirements on types
For the first version:
• InputIterator1 is a model of Input Iterator.
• InputIterator2 is a model of Input Iterator.
• InputIterator1's value type is a model of Equality Comparable.
• InputIterator2's value type is a model of Equality Comparable.
• InputIterator1's value type can be compared for equality with InputIterator2's value type.
For the second version:
• InputIterator1 is a model of Input Iterator.
• InputIterator2 is a model of Input Iterator.
• BinaryPredicate is a model of Binary Predicate.
• InputIterator1's value type is convertible to BinaryPredicate 's first argument type.
• InputIterator2's value type is convertible to BinaryPredicate 's second argument type.
Preconditions
• [first1, last1) is a valid range.
• [first2, first2 + (last2 – last1)) is a valid range.
Complexity
Linear. At most last1 – first1 comparisons.
Example
int A1[] = { 3, 1, 4, 1, 5, 9, 3 };
int A2[] = { 3, 1, 4, 2, 8, 5, 7 };
const int N = sizeof(A1) / sizeof(int);
cout << "Result of comparison: " << equal(A1, A1 + N, A2) << endl;
Notes
[1] Note that this is very similar to the behavior of mismatch: The only real difference is that while equal will simply return false if the two ranges differ, mismatch returns the first location where they do differ. The expression equal(f1, l1, f2) is precisely equivalent to the expression mismatch(f1, l1, f2).first == l1, and this is in fact how equal could be implemented.
See also
mismatch, search, find, find_if
Category: algorithms
Component type: function
Prototype
Search is an overloaded name; there are actually two search functions.
template <class ForwardIterator1, class ForwardIterator2>
ForwardIterator1 search(ForwardIterator1 first1, ForwardIterator1 last1, ForwardIterator2 first2, ForwardIterator2 last2);
template <class ForwardIterator1, class ForwardIterator2, class BinaryPredicate>
ForwardIterator1 search(ForwardIterator1 first1, ForwardIterator1 last1, ForwardIterator2 first2, ForwardIterator2 last2, BinaryPredicate binary_pred);
Description
Search finds a subsequence within the range [first1, last1) that is identical to [first2, last2) when compared elementbyelement. It returns an iterator pointing to the beginning of that subsequence, or else last1 if no such subsequence exists. The two versions of search differ in how they determine whether two elements are the same: the first uses operator==, and the second uses the usersupplied function object binary_pred.
The first version of search returns the first iterator i in the range [first1, last1 – (last2 – first2)) [1] such that, for every iterator j in the range [first2, last2), *(i + (j – first2)) == *j. The second version returns the first iterator i in [first1, last1 – (last2 – first2)) such that, for every iterator j in [first2, last2), binary_pred(*(i + (j – first2)), *j) is true. These conditions simply mean that every element in the subrange beginning with i must be the same as the corresponding element in [first2, last2).
Definition
Defined in the standard header algorithm, and in the nonstandard backwardcompatibility header algo.h.
Requirements on types
For the first version:
• ForwardIterator1 is a model of Forward Iterator.
• ForwardIterator2 is a model of Forward Iterator.
• ForwardIterator1's value type is a model of EqualityComparable.
• ForwardIterator2's value type is a model of EqualityComparable.
• Objects of ForwardIterator1's value type can be compared for equality with Objects of ForwardIterator2's value type.
For the second version:
• ForwardIterator1 is a model of Forward Iterator.
• ForwardIterator2 is a model of Forward Iterator.
• BinaryPredicate is a model of Binary Predicate.
• ForwardIterator1's value type is convertible to BinaryPredicate's first argument type.
• ForwardIterator2's value type is convertible to BinaryPredicate's second argument type.
Preconditions
• [first1, last1) is a valid range.
• [first2, last2) is a valid range.
Complexity
Worst case behavior is quadratic: at most (last1 – first1) * (last2 – first2) comparisons. This worst case, however, is rare. Average complexity is linear.
Example
const char S1[] = "Hello, world!";
const char S2[] = "world";
const int N1 = sizeof(S1) – 1;
const int N2 = sizeof(S2) – 1;
const char* p = search(S1, S1 + N1, S2, S2 + N2);
printf("Found subsequence \"%s\" at character %d of sequence \"%s\".\n", S2, p – S1, S1);
Notes
[1] The reason that this range is [first1, last1 – (last2 – first2)), instead of simply [first1, last1), is that we are looking for a subsequence that is equal to the complete sequence [first2, last2). An iterator i can't be the beginning of such a subsequence unless last1 – i is greater than or equal to last2 – first2. Note the implication of this: you may call search with arguments such that last1 – first1 is less than last2 – first2, but such a search will always fail.
See also
find, find_if, find_end, search_n, mismatch, equal
Category: algorithms
Component type: function
Prototype
Search_n is an overloaded name; there are actually two search_n functions.
template<class ForwardIterator, class Integer, class T>
ForwardIterator search_n(ForwardIterator first, ForwardIterator last, Integer count, const T& value);
template<class ForwardIterator, class Integer, class T, class BinaryPredicate>
ForwardIterator search_n(ForwardIterator first, ForwardIterator last, Integer count, const T& value, BinaryPredicate binary_pred);
Description
Search_n searches for a subsequence of count consecutive elements in the range [first, last), all of which are equal to value. [1] It returns an iterator pointing to the beginning of that subsequence, or else last if no such subsequence exists. The two versions of search_n differ in how they determine whether two elements are the same: the first uses operator==, and the second uses the usersupplied function object binary_pred.
The first version of search returns the first iterator i in the range [first, last – count) [2] such that, for every iterator j in the range [i, i + count), *j == value. The second version returns the first iterator i in the range [first, last – count) such that, for every iterator j in the range [i, i + count), binary_pred(*j, value) is true.
Definition
Defined in the standard header algorithm, and in the nonstandard backwardcompatibility header algo.h.
Requirements on types
For the first version:
• ForwardIterator is a model of Forward Iterator.
• Integer is an integral type.
• T is a model of EqualityComparable.
• ForwardIterator's value type is a model of EqualityComparable.
• Objects of ForwardIterator's value type can be compared for equality with Objects of type T.
For the second version:
• ForwardIterator is a model of Forward Iterator.
• Integer is an integral type.
• T is a model of EqualityComparable.
• BinaryPredicate is a model of Binary Predicate.
• ForwardIterator's value type is convertible to BinaryPredicate's first argument type.
• T is convertible to BinaryPredicate's second argument type.
Preconditions
• [first, last) is a valid range.
• count is nonnegative [1].
Complexity
Linear. Search_n performs at most last – first comparisons.
(The C++ standard permits the complexity to be O(n(last – first )), but this is unnecessarily lax. There is no reason for search_n to examine any element more than once.)
Example
bool eq_nosign(int x, int y) { return abs(x) == abs(y); }
void lookup(int* first, int* last, size_t count, int val) {
cout << "Searching for a sequence of " << count << " '" << val << "'" << (count != 1 ? "s: " : ": ");
int* result = search_n(first, last, count, val);
if (result == last) cout << "Not found" << endl;
else cout << "Index = " << result – first << endl;
}
void lookup_nosign(int* first, int* last, size_t count, int val) {
cout << "Searching for a (signinsensitive) sequence of " << count << " '" << val << "'" << (count != 1 ? "s: " : ": ");
int* result = search_n(first, last, count, val, eq_nosign);
if (result == last) cout << "Not found" << endl;
else cout << "Index = " << result – first << endl;
}
int main() {
const int N = 10;
int A[N] = {1, 2, 1, 1, 3, –3, 1, 1, 1, 1};
lookup(A, A+N, 1, 4);
lookup(A, A+N, 0, 4);
lookup(A, A+N, 1, 1);
lookup(A, A+N, 2, 1);
lookup(A, A+N, 3, 1);
lookup(A, A+N, 4, 1);
lookup(A, A+N, 1, 3);
lookup(A, A+N, 2, 3);
lookup_nosign(A, A+N, 1, 3);
lookup_nosign(A, A+N, 2, 3);
}
The output is
Searching for a sequence of 1 '4': Not found
Searching for a sequence of 0 '4's: Index = 0
Searching for a sequence of 1 '1': Index = 0
Searching for a sequence of 2 '1's: Index = 2
Searching for a sequence of 3 '1's: Index = 6
Searching for a sequence of 4 '1's: Index = 6
Searching for a sequence of 1 '3': Index = 4
Searching for a sequence of 2 '3's: Not found
Searching for a (signinsensitive) sequence of 1 '3': Index = 4
Searching for a (signinsensitive) sequence of 2 '3's: Index = 4
Notes
[1] Note that count is permitted to be zero: a subsequence of zero elements is well defined. If you call search_n with count equal to zero, then the search will always succeed: no matter what value is, every range contains a subrange of zero consecutive elements that are equal to value. When search_n is called with count equal to zero, the return value is always first.
[2] The reason that this range is [first, last – count), rather than just [first, last), is that we are looking for a subsequence whose length is count; an iterator i can't be the beginning of such a subsequence unless last – count is greater than or equal to count. Note the implication of this: you may call search_n with arguments such that last – first is less than count, but such a search will always fail.
See also
search, find_end, find, find_if
Category: algorithms
Component type: function
Prototype
find_end is an overloaded name; there are actually two find_end functions.
template<class ForwardIterator1, class ForwardIterator2>
ForwardIterator1 find_end(ForwardIterator1 first1, ForwardIterator1 last1, ForwardIterator2 first2, ForwardIterator2 last2);
template<class ForwardIterator1, class ForwardIterator2, class BinaryPredicate>
ForwardIterator1 find_end(ForwardIterator1 first1, ForwardIterator1 last1, ForwardIterator2 first2, ForwardIterator2 last2, BinaryPredicate comp);
Description
Find_end is misnamed: it is much more similar to search than to find, and a more accurate name would have been search_end.
Like search, find_end attempts to find a subsequence within the range [first1, last1) that is identical to [first2, last2). The difference is that while search finds the first such subsequence, find_end finds the last such subsequence. Find_end returns an iterator pointing to the beginning of that subsequence; if no such subsequence exists, it returns last1.
The two versions of find_end differ in how they determine whether two elements are the same: the first uses operator==, and the second uses the usersupplied function object comp.
The first version of find_end returns the last iterator i in the range [first1, last1 – (last2 – first2)) such that, for every iterator j in the range [first2, last2), *(i + (j – first2)) == *j. The second version of find_end returns the last iterator i in [first1, last1 – (last2 – first2)) such that, for every iterator j in [first2, last2), binary_pred(*(i + (j – first2)), *j) is true. These conditions simply mean that every element in the subrange beginning with i must be the same as the corresponding element in [first2, last2).
Definition
Defined in the standard header algorithm, and in the nonstandard backwardcompatibility header algo.h.
Requirements on types
For the first version:
• ForwardIterator1 is a model of Forward Iterator.
• ForwardIterator2 is a model of Forward Iterator.
• ForwardIterator1's value type is a model of EqualityComparable.
• ForwardIterator2's value type is a model of EqualityComparable.
• Objects of ForwardIterator1's value type can be compared for equality with Objects of ForwardIterator2's value type.
For the second version:
• ForwardIterator1 is a model of Forward Iterator.
• ForwardIterator2 is a model of Forward Iterator.
• BinaryPredicate is a model of Binary Predicate.
• ForwardIterator1's value type is convertible to BinaryPredicate's first argument type.
• ForwardIterator2's value type is convertible to BinaryPredicate's second argument type.
Preconditions
• [first1, last1) is a valid range.
• [first2, last2) is a valid range.
Complexity
The number of comparisons is proportional to (last1 – first1) * (last2 – first2). If both ForwardIterator1 and ForwardIterator2 are models of Bidirectional Iterator, then the average complexity is linear and the worst case is at most (last1 – first1) * (last2 – first2) comparisons.
Example
int main() {
char* s = "executable.exe";
char* suffix = "exe";
const int N = strlen(s);
const int N_suf = strlen(suffix);
char* location = find_end(s, s + N, suffix, suffix + N_suf);
if (location != s + N) {
cout << "Found a match for " << suffix << " within " << s << endl;
cout << s << endl;
int i;
for (i = 0; i < (location – s); ++i) cout << ' ';
for (i = 0; i < N_suf; ++i) cout << '^';
cout << endl;
} else cout << "No match for " << suffix << " within " << s << endl;
}
Notes
[1] The reason that this range is [first1, last1 – (last2 – first2)), instead of simply [first1, last1), is that we are looking for a subsequence that is equal to the complete sequence [first2, last2). An iterator i can't be the beginning of such a subsequence unless last1 – i is greater than or equal to last2 – first2. Note the implication of this: you may call find_end with arguments such that last1 – first1 is less than last2 – first2, but such a search will always fail.
See also
search
Category: algorithms
Component type: function
Prototype
template <class InputIterator, class OutputIterator>
OutputIterator copy(InputIterator first, InputIterator last, OutputIterator result);
Description
Copy copies elements from the range [first, last) to the range [result, result + (last – first)). That is, it performs the assignments *result = *first, *(result + 1) = *(first + 1), and so on. [1] Generally, for every integer n from 0 to last – first, copy performs the assignment *(result + n) = *(first + n). Assignments are performed in forward order, i.e. in order of increasing n. [2]
The return value is result + (last – first)
Definition
Defined in the standard header algorithm, and in the nonstandard backwardcompatibility header algo.h.
Requirements on types
• InputIterator is a model of Input Iterator.
• OutputIterator is a model of Output Iterator.
• InputIterator's value type is convertible to a type in OutputIterator's set of value types.
Preconditions
• [first, last) is a valid range.
• result is not an iterator within the range [first, last).
• There is enough space to hold all of the elements being copied. More formally, the requirement is that [result, result + (last – first)) is a valid range. [1]
Complexity
Linear. Exactly last – first assignments are performed.
Example
vector<int> V(5);
iota(V.begin(), V.end(), 1);
list<int> L(V.size());
copy(V.begin(), V.end(), L.begin());
assert(equal(V.begin(), V.end(), L.begin()));
Notes
[1] Note the implications of this. Copy cannot be used to insert elements into an empty Container: it overwrites elements, rather than inserting elements. If you want to insert elements into a Sequence, you can either use its insert member function explicitly, or else you can use copy along with an insert_iterator adaptor.
[2] The order of assignments matters in the case where the input and output ranges overlap: copy may not be used if result is in the range [first, last). That is, it may not be used if the beginning of the output range overlaps with the input range, but it may be used if the end of the output range overlaps with the input range; copy_backward has opposite restrictions. If the two ranges are completely nonoverlapping, of course, then either algorithm may be used. The order of assignments also matters if result is an ostream_iterator, or some other iterator whose semantics depends on the order or assignments.
See also
copy_backward, copy_n
Category: algorithms
Component type: function
Prototype
template <class InputIterator, class Size, class OutputIterator>
OutputIterator copy_n(InputIterator first, Size count, OutputIterator result);
Description
Copy_n copies elements from the range [first, first + n) to the range [result, result + n). That is, it performs the assignments *result = *first, *(result + 1) = *(first + 1), and so on. Generally, for every integer i from 0 up to (but not including) n, copy_n performs the assignment *(result + i) = *(first + i). Assignments are performed in forward order, i.e. in order of increasing n. [1]
The return value is result + n.
Definition
Defined in the standard header algorithm, and in the nonstandard backwardcompatibility header algo.h. This function is an SGI extension; it is not part of the C++ standard.
Requirements on types
• InputIterator is a model of Input Iterator.
• OutputIterator is a model of Output Iterator.
• Size is an integral type.
• InputIterator's value type is convertible to a type in OutputIterator's set of value types.
Preconditions
• n >= 0.
• [first, first + n) is a valid range.
• result is not an iterator within the range [first, first + n).
• [result, result + n) is a valid range.
Complexity
Linear. Exactly n assignments are performed.
Example
vector<int> V(5);
iota(V.begin(), V.end(), 1);
list<int> L(V.size());
copy_n(V.begin(), V.size(), L.begin());
assert(equal(V.begin(), V.end(), L.begin()));
Notes
[1] Copy_n is almost, but not quite, redundant. If first is an input iterator, as opposed to a forward iterator, then the copy_n operation can't be expressed in terms of copy.
See also
copy, copy_backward
Category: algorithms
Component type: function
Prototype
template <class BidirectionalIterator1, class BidirectionalIterator2>
BidirectionalIterator2 copy_backward(BidirectionalIterator1 first, BidirectionalIterator1 last, BidirectionalIterator2 result);
Description
Copy_backward copies elements from the range [first, last) to the range [result – (last – first), result) [1]. That is, it performs the assignments *(result – 1) = *(last – 1), *(result – 2) = *(last – 2), and so on. Generally, for every integer n from 0 to last – first, copy_backward performs the assignment *(result – n – 1) = *(last – n – 1). Assignments are performed from the end of the input sequence to the beginning, i.e. in order of increasing n. [2]
The return value is result – (last – first)
Definition
Defined in the standard header algorithm, and in the nonstandard backwardcompatibility header algo.h.
Requirements on types
• BidirectionalIterator1 and BidirectionalIterator2 are models of BidirectionalIterator.
• BidirectionalIterator1's value type is convertible to BidirectionalIterator2's value type.
Preconditions
• [first, last) is a valid range.
• result is not an iterator within the range [first, last).
• There is enough space to hold all of the elements being copied. More formally, the requirement is that [result – (last – first), result) is a valid range.
Complexity
Linear. Exactly last – first assignments are performed.
Example
vector<int> V(15);
iota(V.begin(), V.end(), 1);
copy_backward(V.begin(), V.begin() + 10, V.begin() + 15);
Notes
[1] Result is an iterator that points to the end of the output range. This is highly unusual: in all other STL algorithms that denote an output range by a single iterator, that iterator points to the beginning of the range.
[2] The order of assignments matters in the case where the input and output ranges overlap: copy_backward may not be used if result is in the range [first, last). That is, it may not be used if the end of the output range overlaps with the input range, but it may be used if the beginning of the output range overlaps with the input range; copy has opposite restrictions. If the two ranges are completely nonoverlapping, of course, then either algorithm may be used.
See also
copy, copy_n
Category: algorithms
Component type: function
Prototype
template <class Assignable>
void swap(Assignable& a, Assignable& b);
Description
Assigns the contents of a to b and the contents of b to a. This is used as a primitive operation by many other algorithms.
Definition
Defined in the standard header algorithm, and in the nonstandard backwardcompatibility header algo.h.
Requirements on types
• Assignable is a model of Assignable.
Preconditions
None.
Complexity
Amortized constant time. [1] [2]
Example
int x = 1;
int y = 2;
assert(x == 1 && y == 2);
swap(x, y);
assert(x == 2 && y == 1);
Notes
[1] The time required to swap two objects of type T will obviously depend on the type; "constant time" does not mean that performance will be the same for an 8bit char as for a 128bit complex<double>.
[2] This implementation of swap makes one call to a copy constructor and two calls to an assignment operator; roughly, then, it should be expected to take about the same amount of time as three assignments. In many cases, however, it is possible to write a specialized version of swap that is far more efficient. Consider, for example, swapping two vector<double>s each of which has N elements. The unspecialized version requires 3*N assignments of double, but a specialized version requires only nine pointer assignments. This is important because swap is used as a primitive operation in many other STL algorithms, and because containers of containers (list<vector<char> >, for example) are very common. The STL includes specialized versions of swap for all container classes. Userdefined types should also provide specialized versions of swap whenever it is possible to write one that is more efficient than the general version.
See also
iter_swap, swap_ranges
Category: algorithms
Component type: function
Prototype
template <class ForwardIterator1, class ForwardIterator 2>
inline void iter_swap(ForwardIterator1 a, ForwardIterator2 b);
Description
Equivalent to swap(*a, *b). [1]
Definition
Declared in algo.h. The implementation is in algobase.h.
Requirements on types
• ForwardIterator1 and ForwardIterator2 are models of Forward Iterator.
• ForwardIterator1 and ForwardIterator2 are mutable.
• ForwardIterator1 and ForwardIterator2 have the same value type.
Preconditions
• ForwardIterator1 and ForwardIterator2 are dereferenceable.
Complexity
See swap for a discussion.
Example
int x = 1;
int y = 2;
assert(x == 1 && y == 2);
iter_swap(&x, &y);
assert(x == 2 && y == 1);
Notes
[1] Strictly speaking, iter_swap is redundant. It exists only for technical reasons: in some circumstances, some compilers have difficulty performing the type deduction required to interpret swap(*a, *b).
See also
swap, swap_ranges
Category: algorithms
Component type: function
Prototype
template <class ForwardIterator1, class ForwardIterator2>
ForwardIterator2 swap_ranges(ForwardIterator1 first1, ForwardIterator1 last1, ForwardIterator2 first2);
Description
Swap_ranges swaps each of the elements in the range [first1, last1) with the corresponding element in the range [first2, first2 + (last1 – first1)). That is, for each integer n such that 0 <= n < (last1 – first1), it swaps *(first1 + n) and *(first2 + n). The return value is first2 + (last1 – first1).
Definition
Defined in the standard header algorithm, and in the nonstandard backwardcompatibility header algo.h.
Requirements on types
ForwardIterator1 and ForwardIterator2 must both be models of Forward Iterator. The value types of ForwardIterator1 and ForwardIterator2 must be convertible to each other.
Preconditions
• [first1, last1) is a valid range.
• [first2, first2 + (last1 – first1)) is a valid range.
• The two ranges [first1, last1) and [first2, first2 + (last1 – first1)) do not overlap.
Complexity
Linear. Exactly last1 – first1 swaps are performed.
Example
vector<int> V1, V2;
V1.push_back(1);
V1.push_back(2);
V2.push_back(3);
V2.push_back(4);
assert(V1[0] == 1 && V1[1] == 2 && V2[0] == 3 && V2[1] == 4);
swap_ranges(V1.begin(), V1.end(), V2.begin());
assert(V1[0] == 3 && V1[1] == 4 && V2[0] == 1 && V2[1] == 2);
See also
swap, iter_swap.
Category: algorithms
Component type: function
Prototype
Transform is an overloaded name; there are actually two transform functions.
template <class InputIterator, class OutputIterator, class UnaryFunction>
OutputIterator transform(InputIterator first, InputIterator last, OutputIterator result, UnaryFunction op);
template <class InputIterator1, class InputIterator2, class OutputIterator, class BinaryFunction>
OutputIterator transform(InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, OutputIterator result, BinaryFunction binary_op);
Description
Transform performs an operation on objects; there are two versions of transform, one of which uses a single range of Input Iterators and one of which uses two ranges of Input Iterators.
The first version of transform performs the operation op(*i) for each iterator i in the range [first, last) , and assigns the result of that operation to *o, where o is the corresponding output iterator. That is, for each n such that 0 <= n < last – first, it performs the assignment *(result + n) = op(*(first + n)). The return value is result + (last – first).
The second version of transform is very similar, except that it uses a Binary Function instead of a Unary Function: it performs the operation op(*i1, *i2) for each iterator i1 in the range [first1, last1) and assigns the result to *o, where i2 is the corresponding iterator in the second input range and where o is the corresponding output iterator. That is, for each n such that 0 <= n < last1 – first1, it performs the assignment *(result + n) = op(*(first1 + n), *(first2 + n). The return value is result + (last1 – first1).
Note that transform may be used to modify a sequence "in place": it is permissible for the iterators first and result to be the same. [1]
Definition
Defined in the standard header algorithm, and in the nonstandard backwardcompatibility header algo.h.
Requirements on types
For the first (unary) version:
• InputIterator must be a model of Input Iterator.
• OutputIterator must be a model of Output Iterator.
• UnaryFunction must be a model of Unary Function.
• InputIterator's value type must be convertible to UnaryFunction's argument type.
• UnaryFunction's result type must be convertible to a type in OutputIterator's set of value types.
For the second (binary) version:
• InputIterator1 and InputIterator2 must be models of Input Iterator.
• OutputIterator must be a model of Output Iterator.
• BinaryFunction must be a model of Binary Function.
• InputIterator1's and InputIterator2's value types must be convertible, respectively, to BinaryFunction's first and second argument types.
• UnaryFunction's result type must be convertible to a type in OutputIterator's set of value types.
Preconditions
For the first (unary) version:
• [first, last) is a valid range.
• result is not an iterator within the range [first+1, last). [1]
• There is enough space to hold all of the elements being copied. More formally, the requirement is that [result, result + (last – first)) is a valid range.
For the second (binary) version:
• [first1, last1) is a valid range.
• [first2, first2 + (last1 – first1)) is a valid range.
• result is not an iterator within the range [first1+1, last1) or [first2 + 1, first2 + (last1 – first1)).
• There is enough space to hold all of the elements being copied. More formally, the requirement is that [result, result + (last1 – first1)) is a valid range.
Complexity
Linear. The operation is applied exactly last – first times in the case of the unary version, or last1 – first1 in the case of the binary version.
Example
Replace every number in an array with its negative.
const int N = 1000;
double A[N];
iota (A, A+N, 1);
transform(A, A+N, A, negate<double>());
Calculate the sum of two vectors, storing the result in a third vector.
const int N = 1000;
vector<int> V1(N);
vector<int> V2(N);
vector <int> V3(N);
iota(V1.begin(), V1.end(), 1);
fill(V2.begin(), V2.end(), 75);
assert(V2.size() >= V1.size() && V3.size() >= V1.size());
transform(V1.begin(), V1.end(), V2.begin(), V3.begin(), plus <int>());
Notes
[1] The Output Iterator result is not permitted to be the same as any of the Input Iterators in the range [first, last), with the exception of first itself. That is: transform(V.begin(), V.end(), V.begin(), fabs) is valid, but transform(V.begin(), V.end(), V.begin() + 1, fabs) is not.
See also
The function object overview, copy, generate, fill
Category: algorithms
Component type: function
Prototype
template <class ForwardIterator, class T>
void replace(ForwardIterator first, ForwardIterator last, const T& old_value, const T& new_value)
Description
Replace replaces every element in the range [first, last) equal to old_value with new_value. That is: for every iterator i , if *i == old_value then it performs the assignment *i = new_value.
Definition
Defined in the standard header algorithm, and in the nonstandard backwardcompatibility header algo.h.
Requirements on types
• ForwardIterator is a model of Forward Iterator.
• ForwardIterator is mutable.
• T is convertible to ForwardIterator's value type.
• T is Assignable.
• T is EqualityComparable, and may be compared for equality with objects of ForwardIterator's value type.
Preconditions
• [first, last) is a valid range.
Complexity
Linear. Replace performs exactly last – first comparisons for equality, and at most last – first assignments.
Example
vector<int> V;
V.push_back(1);
V.push_back(2);
V.push_back(3);
V.push_back(1);
replace(V.begin(), V.end(), 1, 99);
assert(V[0] == 99 && V[3] == 99);
See also
replace_if, replace_copy, replace_copy_if
Category: algorithms
Component type: function
Prototype
template <class ForwardIterator, class Predicate, class T>
void replace_if(ForwardIterator first, ForwardIterator last, Predicate pred, const T& new_value)
Description
Replace_if replaces every element in the range [first, last) for which pred returns true with new_value. That is: for every iterator i, if pred(*i) is true then it performs the assignment *i = new_value.
Definition
Defined in the standard header algorithm, and in the nonstandard backwardcompatibility header algo.h.
Requirements on types
• ForwardIterator is a model of Forward Iterator.
• ForwardIterator is mutable.
• Predicate is a model of Predicate.
• ForwardIterator's value type is convertible to Predicate's argument type.
• T is convertible to Forward Iterator's value type.
• T is Assignable.
Preconditions
• [first, last) is a valid range.
Complexity
Linear. Replace_if performs exactly last – first applications of pred, and at most last – first assignments.
Example
Replace every negative number with 0.
vector<int> V;
V.push_back(1);
V.push_back(3);
V.push_back(2);
V.push_back(1);
replace_if(V.begin(), V.end(), bind2nd(less<int>(), 0), –1);
assert(V[1] == 0 && V[3] == 0);
See also
replace, replace_copy, replace_copy_if
Category: algorithms
Component type: function
Prototype
template <class InputIterator, class OutputIterator, class T>
OutputIterator replace_copy(InputIterator first, InputIterator last, OutputIterator result, const T& old_value, const T& new_value);
Description
Replace_copy copies elements from the range [first, last) to the range [result, result + (lastfirst)), except that any element equal to old_value is not copied; new_value is copied instead. More precisely, for every integer n such that 0 <= n < lastfirst, replace_copy performs the assignment *(result+n) = new_value if *(first+n) == old_value, and *(result+n) = *(first+n) otherwise.
Definition
Defined in the standard header algorithm, and in the nonstandard backwardcompatibility header algo.h.
Requirements on types
• InputIterator is a model of Input Iterator.
• OutputIterator is a model of Output Iterator.
• T is EqualityComparable, and may be compared for equality with objects of InputIterator's value type.
• T is Assignable.
• T is convertible to a type in OutputIterator's set of value types.
Preconditions
• [first, last) is a valid range.
• There is enough space in the output range to store the copied values. That is, [result, result + (lastfirst)) is a valid range.
• result is not an iterator within the range [first, last).
Complexity
Linear. Replace_copy performs exactly last – first comparisons for equality and exactly last – first assignments.
Example
vector<int> V1;
V1.push_back(1);
V1.push_back(2);
V1.push_back(3);
V1.push_back(1);
vector<int> V2(4);
replace_copy(V1.begin(), V1.end(), V2.begin(), 1, 99);
assert(V[0] == 99 && V[1] == 2 && V[2] == 3 && V[3] == 99);
See also
copy, replace, replace_if, replace_copy_if
Category: algorithms
Component type: function
Prototype
template <class InputIterator, class OutputIterator, class Predicate, class T>
OutputIterator replace_copy_if(InputIterator first, InputIterator last, OutputIterator result, Predicate pred, const T& new_value)
Description
Replace_copy_if copies elements from the range [first, last) to the range [result, result + (lastfirst)), except that any element for which pred is true is not copied; new_value is copied instead. More precisely, for every integer n such that 0 <= n < lastfirst, replace_copy_if performs the assignment *(result+n) = new_value if pred(*(first+n)) , and *(result+n) = *(first+n) otherwise.
Definition
Defined in the standard header algorithm, and in the nonstandard backwardcompatibility header algo.h.
Requirements on types
• InputIterator is a model of Input Iterator.
• OutputIterator is a model of Output Iterator.
• Predicate is a model of Predicate.
• T is convertible to Predicate's argument type.
• T is Assignable.
• T is convertible to a type in OutputIterator's set of value types.
Preconditions
• [first, last) is a valid range.
• There is enough space in the output range to store the copied values. That is, [result, result + (lastfirst)) is a valid range.
• result is not an iterator within the range [first, last).
Complexity
Linear. Replace_copy performs exactly last – first applications of pred and exactly last – first assignments.
Example
Copy elements from one vector to another, replacing all negative numbers with 0.
vector<int> V1;
V1.push_back(1);
V1.push_back(1);
V1.push_back(5);
V1.push_back(2);
vector<int> V2(4);
replace_copy_if(V1.begin(), V1.end(), V2.begin(), bind2nd(less<int>(), 0), 0);
assert(V[0] == 1 && V[1] == 0 && V[2] == 0 && V[3] == 2);
See also
copy, replace, replace_if, replace_copy
Category: algorithms
Component type: function
Prototype
template <class ForwardIterator, class T>
void fill(ForwardIterator first, ForwardIterator last, const T& value);
Description
Fill assigns the value value to every element in the range [first, last). That is, for every iterator i in [first, last), it performs the assignment *i = value.
Definition
Defined in the standard header algorithm, and in the nonstandard backwardcompatibility header algo.h.
Requirements on types
• ForwardIterator is a model of Forward Iterator . [1]
• ForwardIterator is mutable.
• T is a model of Assignable.
• T is convertible to Forward Iterator's value type.
Preconditions
• [first, last) is a valid range.
Complexity
Linear. Fill performs exactly last – first assignments.
Example
vector <double> V(4);
fill(V.begin(), V.end(), 137);
assert(V[0] == 137 && V[1] == 137 && V[2] == 137 && V[3] == 137);
Notes
[1] The reason that fill requires its argument to be a mutable forward iterator, rather than merely an output iterator, is that it uses a range [first, last) of iterators. There is no sensible way to describe a range of output iterators, because it is impossible to compare two output iterators for equality. The fill_n algorithm does have an interface that permits use of an output iterator.
See also
copy, fill_n, generate, generate_n, iota
Category: algorithms
Component type: function
Prototype
template <class OutputIterator, class Size, class T>
OutputIterator fill_n(OutputIterator first, Size n, const T& value);
Description
Fill_n assigns the value value to every element in the range [first, first+n). That is, for every iterator i in [first, first+n), it performs the assignment *i = value. The return value is first + n.
Definition
Defined in the standard header algorithm, and in the nonstandard backwardcompatibility header algo.h.
Requirements on types
• OutputIterator is a model of Output Iterator.
• Size is an integral type (either signed or unsigned).
• T is a model of Assignable.
• T is convertible to a type in OutputIterator's set of value types.
Preconditions
• n >= 0.
• There is enough space to hold n values. That is, [first, first+n) is a valid range.
Complexity
Linear. Fill_n performs exactly n assignments.
Example
vector<double> V;
fill_n(back_inserter(V), 4, 137);
assert(V.size() == 4 && V[0] == 42 && V[1] == 42 && V[2] == 42 && V[3] == 42);
See also
copy, fill, generate, generate_n, iota
Category: algorithms
Component type: function
Prototype
template <class ForwardIterator, class Generator>
void generate(ForwardIterator first, ForwardIterator last, Generator gen);
Description
Generate assigns the result of invoking gen, a function object that takes no arguments, to each element in the range [first, last). [1]
Definition
Defined in the standard header algorithm, and in the nonstandard backwardcompatibility header algo.h.
Requirements on types
• ForwardIterator is a model of Forward Iterator. [2]
• ForwardIterator is mutable.
• Generator is a model of Generator.
• Generator's result type is convertible to ForwardIterator's value type.
Preconditions
• [first, last) is a valid range.
Complexity
Linear. Exactly last – first invocations of gen. [1]
Example
Fill a vector with random numbers, using the standard C library function rand.
vector<int> V;
…
generate(V.begin(), V.end(), rand);
Notes
[1] The function object gen is invoked for each iterator in the range [first, last), as opposed to just being invoked a single time outside the loop. This distinction is important because a Generator need not return the same result each time it is invoked; it is permitted to read from a file, refer to and modify local state, and so on.
[2] The reason that generate requires its argument to be a mutable Forward Iterator, rather than just an Output Iterator, is that it uses a range [first, last) of iterators. There is no sensible way to describe a range of Output Iterators, because it is impossible to compare two Output Iterators for equality. The generate_n algorithm does have an interface that permits use of an Output Iterator.
See also
copy, fill, fill_n, generate_n, iota
Category: algorithms
Component type: function
Prototype
template <class OutputIterator, class Size, class Generator>
OutputIterator generate_n(OutputIterator first, Size n, Generator gen);
Description
Generate_n assigns the result of invoking gen, a function object that takes no arguments, to each element in the range [first, first+n). [1] The return value is first + n.
Definition
Defined in the standard header algorithm, and in the nonstandard backwardcompatibility header algo.h.
Requirements on types
• OutputIterator is a model of Output Iterator.
• Size is an integral type (either signed or unsigned).
• Generator is a model of Generator.
• Generator's result type is convertible to a type in OutputIterator 's set of value types.
Preconditions
• n >= 0.
• There is enough space to hold n values. That is, [first, first+n) is a valid range.
Complexity
Linear. Exactly n invocations of gen. [1]
Example
Print 100 random numbers, using the C standard library function rand.
generate_n(ostream_iterator<int>(cout, "\n"), 100, rand);
Notes
[1] The function object gen is invoked n times (once for each iterator in the range [first, first+n) ), as opposed to just being invoked a single time outside the loop. This distinction is important because a Generator need not return the same result each time it is invoked; it is permitted to read from a file, refer to and modify local state, and so on.
See also
copy, fill, fill_n, generate, iota
Category: algorithms
Component type: function
Prototype
template <class ForwardIterator, class T>
ForwardIterator remove(ForwardIterator first, ForwardIterator last, const T& value);
Description
Remove removes from the range [first, last) all elements that are equal to value. That is, remove returns an iterator new_last such that the range [first, new_last) contains no elements equal to value. [1] The iterators in the range [new_last, last) are all still dereferenceable, but the elements that they point to are unspecified. Remove is stable, meaning that the relative order of elements that are not equal to value is unchanged.
Definition
Defined in the standard header algorithm, and in the nonstandard backwardcompatibility header algo.h.
Requirements on types
• ForwardIterator is a model of Forward Iterator.
• ForwardIterator is mutable.
• T is a model of Equality Comparable.
• Objects of type T can be compared for equality with objects of ForwardIterator's value type.
Preconditions
• [first, last) is a valid range.
Complexity
Linear. Remove performs exactly last – first comparisons for equality.
Example
vector<int> V;
V.push_back(3);
V.push_back(1);
V.push_back(4);
V.push_back(1);
V.push_back(5);
V.push_back(9);
copy(V.begin(), V.end(), ostream_iterator<int>(cout, " "));
// The output is "3 1 4 1 5 9".
vector<int>::iterator new_end = remove(V.begin(), V.end(), 1);
copy(V.begin(), new_end, ostream_iterator<int>(cout, " "));
// The output is "3 4 5 9".
Notes
[1] The meaning of "removal" is somewhat subtle. Remove does not destroy any iterators, and does not change the distance between first and last. (There's no way that it could do anything of the sort.) So, for example, if V is a vector, remove(V.begin(), V.end(), 0) does not change V.size(): V will contain just as many elements as it did before. Remove returns an iterator that points to the end of the resulting range after elements have been removed from it; it follows that the elements after that iterator are of no interest, and may be discarded. If you are removing elements from a Sequence, you may simply erase them. That is, a reasonable way of removing elements from a Sequence is S.erase(remove(S.begin(), S.end(), x), S.end()).
See also
remove_if, remove_copy, remove_copy_if, unique, unique_copy.
Category: algorithms
Component type: function
Prototype
template <class ForwardIterator, class Predicate>
ForwardIterator remove_if(ForwardIterator first, ForwardIterator last, Predicate pred);
Description
Remove_if removes from the range [first, last) every element x such that pred(x) is true. That is, remove_if returns an iterator new_last such that the range [first, new_last) contains no elements for which pred is true. [1] The iterators in the range [new_last, last) are all still dereferenceable, but the elements that they point to are unspecified. Remove_if is stable, meaning that the relative order of elements that are not removed is unchanged.
Definition
Defined in the standard header algorithm, and in the nonstandard backwardcompatibility header algo.h.
Requirements on types
• ForwardIterator is a model of Forward Iterator.
• ForwardIterator is mutable.
• Predicate is a model of Predicate.
• ForwardIterator's value type is convertible to Predicate's argument type.
Preconditions
• [first, last) is a valid range.
Complexity
Linear. Remove_if performs exactly last – first applications of pred.
Example
Remove all even numbers from a vector.
vector<int> V;
V.push_back(1);
V.push_back(4);
V.push_back(2);
V.push_back(8);
V.push_back(5);
V.push_back(7);
copy(V.begin(), V.end(), ostream_iterator<int>(cout, " "));
// The output is "1 4 2 8 5 7"
vector<int>::iterator new_end = remove_if(V.begin(), V.end(), compose1(bind2nd(equal_to<int>(), 0), bind2nd( modulus<int>(), 2)));
V.erase(new_end, V.end()); [1]
copy(V.begin(), V.end(), ostream_iterator<int>(cout, " "));
// The output is "1 5 7".
Notes
[1] The meaning of "removal" is somewhat subtle. Remove_if does not destroy any iterators, and does not change the distance between first and last. (There's no way that it could do anything of the sort.) So, for example, if V is a vector