Standard Template Library Programmer's Guide

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