Book: Standard Template Library Programmer`s Guide



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.

Containers and algorithms

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.

Iterators

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;

}

Concepts and Modeling

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.

Refinement

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.

Other parts of the STL

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 low-level 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.

Using the STL documentation

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 run-time 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 run-time 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 non-member 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 well-defined 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 run-time complexity. For example, find 's run-time 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.



Containers

Concepts

General concepts

Container

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 fixed-size 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 past-the-end. It is past-the-end 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 past-the-end.
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 non-standard memory models. Note, however, that "smart references" (user-defined reference types that provide additional functionality) are not a viable option. It is impossible for a user-defined 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 user-defined 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 fixed-size 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 run-time 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 constant-time 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

Forward Container

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 element-by-element 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

Reversible Container

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 past-the-end. It is past-the-end if and only if a.size() == 0.
End of reverse range a.rend() Equivalent to X::reverse_iterator(a.begin()). a.end() is past-the-end.

Complexity guarantees

The run-time 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

Random Access Container

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 run-time 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

Sequences

Sequence

Category: containers

Component type: concept

Description

A Sequence is a variable-sized 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 single-element 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

Front Insertion Sequence

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

Back Insertion Sequence

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

Associative Containers

Associative Container

Category: containers

Component type: concept

Description

An Associative Container is a variable-sized 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.

Simple 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

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

Sorted 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 case-insensitive 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

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. Addison-Wesley, 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, run-time 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

Hash Function

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

Unique Associative Container

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

Container classes

Sequences

vector<T, Alloc>

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 backward-compatibility 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

deque<T, Alloc>

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 backward-compatibility 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 "double-ended 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. Addison-Wesley, 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

list<T, Alloc>

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 backward-compatibility 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.

slist<T, Alloc>

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 constant-time 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 backward-compatibility 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 off-the-end 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 off-the-end 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

bit_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 backward-compatibility 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 built-in 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

Associative Containers

set<Key, Compare, Alloc>

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 backward-compatibility 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 backward-compatibility 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

multiset<Key, Compare, Alloc>

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 backward-compatibility 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 backward-compatibility 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 backward-compatibility 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 backward-compatibility 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 backward-compatibility 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 backward-compatibility 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

hash<T>

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 built-in 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 backward-compatibility 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

String package

Character Traits

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 end-of-file 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 non-null pointer of type const X::char_type*.

s A non-null 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 non-negative 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 non-EOF 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

char_traits

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 Three-way lexicographical comparison, much like strncmp.
static size_t length(const char* p) Character Traits Returns length of a null-terminated 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 (non-overlapping) 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 non-const member function, including the non-const 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 null-terminated 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 null-terminated array of characters representing the string's contents.
const charT* data() const basic_string Returns a pointer to an array of characters (not necessarily null-terminated) 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 null-terminated 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 null-terminated 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 null-terminated 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 null-terminated 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 null-terminated 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 null-terminated 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 null-terminated 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 Three-way lexicographical comparison of s and *this.
int compare(size_type pos, size_type n, const basic_string& s) const basic_string Three-way 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 Three-way lexicographical comparison of a substring of s and a substring of *this
int compare(const charT* s) const basic_string Three-way lexicographical comparison of s and *this.
int compare(size_type pos, size_type n, const charT* s, size_type len = npos) const basic_string Three-way 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 null-terminated 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 null-terminated, 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 user-provided 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 null-terminated 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 user-provided 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 null-terminated 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 user-provided 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 Three-way 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 Three-way 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 Three-way 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 Three-way 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 Three-way 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 end-of-file, 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

rope<T, Alloc>

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 reference-counted 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 reference-counted copy-on-write 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 single-character 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 in-place 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 non-const 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 backward-compatibility 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 null-terminated) 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 Single-character 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 Three-way 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 null-terminated) 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 null-terminated) 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 null-terminated) 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) Three-way 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 null-terminated 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

Container adaptors

stack<T, Sequence>

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 backward-compatibility 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 element-by-element. 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. Addison-Wesley, 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

queue<T, 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 backward-compatibility 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 element-by-element. 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. Addison-Wesley, 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 backward-compatibility 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. Addison-Wesley, 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

bitset<N>

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 constant-time 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 N-1 is the most significant bit.

Example

int main() {

 const bitset<12> mask(2730ul);

 cout << "mask = " << mask << endl;

 bitset<12> x;

 cout << "Enter a 12-bit 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 high-order 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

Iterators

Introduction

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 "multi-pass" 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 "multi-pass" 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 multi-pass 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 well-defined 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 well-defined 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, …, last-1 and sometimes it refers to the objects pointed to by those iterators: *first, *(first+1), …, *(last-1). 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.

Concepts

Trivial Iterator

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 well-defined 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

Input Iterator

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 past-the-end if it points beyond the last element of a container. Past-the-end values are nonsingular and nondereferenceable.

An iterator is valid if it is dereferenceable or past-the-end.

An iterator i is incrementable if there is a "next" iterator, that is, if ++i is well-defined. Past-the-end 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 past-the-end [3] [4]
Postincrement (void)i++ i is dereferenceable Equivalent to (void)++i i is dereferenceable or past-the-end [3] [4]
Postincrement and dereference *i++ i is dereferenceable Equivalent to {T t = *i; ++i; return t;} i is dereferenceable or past-the-end [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 past-the-end. 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

Output Iterator

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 well-defined and does not require performing any non-trivial 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

Forward Iterator

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 past-the-end. &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 past-the-end. [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

Bidirectional Iterator

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 past-the-end. 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 past-the-end. 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

Random Access Iterator

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 constant-time methods for moving forward and backward in arbitrary-sized 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 past-the-end 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 past-the-end.
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 past-the-end
Iterator subtraction i –= n Including i itself, there must be n dereferenceable or past-the-end iterators preceding or following i, depending on whether n is positive or negative. Equivalent to i += (-n). i is dereferenceable or past-the-end.
Iterator subtraction i – n Same as for i –= n Equivalent to { X tmp = i; return tmp –= n; }. Result is dereferenceable or past-the-end
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 well-defined, then i += n; i –= n; and (i + n) – n are null operations. Similarly, if i – n is well-defined, then i –= n; i += n; and (i – n) + n are null operations.
Relation between distance and addition If i – j is well-defined, 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

Iterator Tags

Introduction

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 run-time 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 top-level 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

iterator_traits<Iterator>

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 non-empty 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 backward-compatibility 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

iterator_category

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 backward-compatibility 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 run-time 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 built-in 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

distance_type

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 backward-compatibility 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

value_type

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 backward-compatibility 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 built-in 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

Iterator tag classes

input_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 backward-compatibility 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

output_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 backward-compatibility 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

forward_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 backward-compatibility 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

bidirectional_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 backward-compatibility 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

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 backward-compatibility 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

Iterator base classes

input_iterator<T, Distance>

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 backward-compatibility 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 derived-to-base 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

output_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 backward-compatibility 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 derived-to-base 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

forward_iterator<T, Distance>

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 backward-compatibility 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 derived-to-base 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 backward-compatibility 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 derived-to-base 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 backward-compatibility 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 derived-to-base 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

Iterator functions

distance

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 error-prone. 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 backward-compatibility 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.

advance

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 backward-compatibility 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.

Iterator classes

istream_iterator<T, Distance>

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 past-the-end 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 backward-compatibility header iterator.h.

Template parameters

Parameter Description Default
T 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 end-of-stream iterator. This is a past-the-end 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 end-of-stream iterator created using the default constructor.

See also

ostream_iterator, Input Iterator, Output Iterator.

ostream_iterator<T>

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 backward-compatibility 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 backward-compatibility 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 non-member 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 backward-compatibility 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 past-the-end 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 non-member 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

insert_iterator<Container>

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 two-argument 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 two-argument 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 already-sorted 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 backward-compatibility 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 variable-sized, as described in the Container requirements.

• Container has a two-argument 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 past-the-end 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 non-member 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) , …, *(last-1). 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 backward-compatibility 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 past-the-end. 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) , …, *(last-1). 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 backward-compatibility 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 past-the-end. 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 backward-compatibility 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 low-level 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 backward-compatibility 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 variable-sized 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

Algorithms

Non-mutating algorithms

for_each

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 backward-compatibility 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 non-constant 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

find

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 backward-compatibility 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.

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 backward-compatibility 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.

adjacent_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 backward-compatibility 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

find_first_of

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 user-supplied 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 backward-compatibility 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

count

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 error-prone. 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 backward-compatibility 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

count_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 error-prone. 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 backward-compatibility 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

mismatch

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 backward-compatibility 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

equal

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 element-by-element, 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 backward-compatibility 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

search

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 element-by-element. 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 user-supplied 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 backward-compatibility 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

search_n

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 user-supplied 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 backward-compatibility 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 non-negative [1].

Complexity

Linear. Search_n performs at most last – first comparisons.

(The C++ standard permits the complexity to be O(n(lastfirst )), 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 (sign-insensitive) 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 (sign-insensitive) sequence of 1 '3':  Index = 4

Searching for a (sign-insensitive) 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

find_end

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 user-supplied 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 backward-compatibility 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

Mutating algorithms

copy

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 backward-compatibility 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

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 backward-compatibility 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

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 backward-compatibility 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

Swap

swap

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 backward-compatibility 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 8-bit char as for a 128-bit 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. User-defined 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

iter_swap

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

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 backward-compatibility 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.

transform

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 backward-compatibility 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

Replace

replace

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 backward-compatibility 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

replace_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 backward-compatibility 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

replace_copy

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 + (last-first)), 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 < last-first, 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 backward-compatibility 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 + (last-first)) 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

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 + (last-first)), 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 < last-first, 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 backward-compatibility 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 + (last-first)) 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

fill

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 backward-compatibility 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

fill_n

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 backward-compatibility 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

generate

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 backward-compatibility 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

generate_n

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 backward-compatibility 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

Remove

remove

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 backward-compatibility 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.

remove_if

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 backward-compatibility 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.