Standard Template Library Programmer's Guide

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 Iteratoris an important statement about what those two classes have in common.) Concepts are used for the documentation of both types and functions .

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 Functionrequirements is that a Unary Functionmust have an argument type ; if F is a type that models Unary Functionand 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 Iteratoruses 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 Iteratorand a Random Access Iteratoris 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 Comparableimposes 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 semanticssection or from other requirements in the invariantssection).

• 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.

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 Containerand 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 Containerpage applies to vector , and there is no need to repeat it in the vector page. Instead, the Memberssection 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 Containeror Back Insertion Sequencerequirements. these members are defined in the New memberssection.

• Notes: footnotes (if any) that are referred to by other parts of the page.

• See Also: links to other related pages.

A page that documents a function has the following sections.

• Prototype:the function's declaration.

• Description:a summary of what the function does.