In describing the various STL entities (containers, algorithms,
function objects, and so on), or showing their syntax, it is often
necessary to use a parameter type and/or a parameter name, or a
function return type or value. It will be helpful to have, for such
items, a consistent naming scheme that conveys as much information as
possible about the given item in the given context. This page describes
the naming conventions followed in the STL reference pages on this web
site. They are collected here for easy reference, and to avoid
duplication. Some frequently used specific names are listed, but the
general idea is to give a sense that from any name used it should be
possible for the reader to infer the type and purpose of the thing
named, based on the context and, if necessary, by referring to the
conventions described here.
Some underlying STL typedefs and types
Some frequently-appearing names are actual STL typedef names or type
names, and it is important not to confuse these with programmer-chosen
names. You will see many of both in these pages. The best course of
action to avoid confusion on this front is to become increasingly
familiar with the STL names so that you recognize one the moment you
see it.
A typical example that crops up frequently is this one:
- size_type
- A typedef for an unsigned integer type sufficiently large to hold
the size of any container in the given context (as in
vector<int>::size_type, for example).
For a full list of the STL typedefs found in the container and
container adaptor classes see here.
And here is a class name that you will see much less frequently:
- allocator
- This is the class name of the default allocator type for a
container.
You should know about this class because you know that any container
will need storage, and it is an object of this class that does the work
of allocating the necessary storage for you in the background. Most of
the time you should be happy to just let it do its thing.
Needless to say, there are many other STL names that will crop up
from time to time. Just be on your guard, and try to distinguish them
from the programmer-defined names described here that will also be
appearing in the same context.
Naming conventions for quantities and sizes
- num, size
- These are generic names used for a quantity (num) or a
size (size), and they are generally assumed to be of type
size_type (relative to some container type).
- i, index
- These are generic names used for index values, and they too are
assumed to be of type size_type. Index values for container
types start at 0, just as they do for arrays.
Naming conventions for container component types and container
component values
- T
- This name is used as a generic placeholder for a type which may
be either a programmer-defined type or a built-in type.
- val, containerVal, targetVal, initialVal, ...
- These are placeholder names for values of type T, which
may be simply generic (val), may emphasize that the value is
actually from a container (containerVal), or suggest the
purpose for which the value will be used (targetVal or
initialVal, and so on). Depending on the context, such a
name may represent a variable containing a value of type T,
a literal constant value of type T, a named constant value
of type T, or even a call to a function which returns a
value of type T.
- KType, VType
- These names are used as generic placeholders for the types of the
first (the key) and second (the value corresponding to the key)
components (respectively) of pair objects being stored in a
map or multimap.
- kVal, vVal, pVal
- kVal and vVal are placeholder names for values
of the first (key) and second (value) components (respectively) of
pair objects being stored in a map or multimap.
kVal is also used as a placeholder name for the component
stored in a set or multiset, and pVal as a placeholder name
for a pair object as a single entity.
Naming conventions for container types and container objects
- ContainerType
- This name is used as a generic placeholder for any container
type.
- vector<T>, deque<T>, list<T>, map<KType,
VType>, ...
- These names are the specific container types you will see
throughout.
- v, v1, v2, ..., otherVector, ...
d, d1, d2, ..., otherDeque, ...
lst, lst1, lst2, ..., otherList, ...
m, m1, m2, ..., otherMap, ...
c, c1, c2, ..., otherContainer, otherLikeContainer, ...
- These names are typical of the kinds of generic names one uses
for containers that don't have any particular application and are
just being used to illustrate properties and behaviors of the
containers themselves. Note our response to the usual frustration
stemming from the fact that the single lowercase letter l
should not be used for a generic list since it too closely resembles
1, the first positive integer. The term
otherLikeContainer simply means another container of the
same kind that you're already dealing with in the current context
(some other vector, for example, if you're already dealing with a
vector).
Naming conventions for iterator types and values
- InIterator, OutIterator, ForIterator, BiIterator,
RandIterator
- These are generic type names used for (respectively) input
iterators, output iterators, forward iterators, bidirectional
iterators, and random access iterators. For example,
vector<int>::iterator is a RandIterator,
while list<string>::iterator is a
BiIterator.
- iter, r_iter
- These are generic variable names used for the default type of
iterator (or reverse_iterator) for a given
container. For example, when used in the vector context,
iter would represent a random access iterator type,
since that is the default iterator type for a
vector container.
- p, r_p
- These are analogues of iter and r_inter
(above), but are shorter and will be used frequently in the sample
programs. The use of p seems appropriate, since it suggests
"pointer" and i has already been used for "index".
- iter1, iter2, ...
otherIter1, otherIter2, ...
inIter1, inIter2, ...
outIter1, outIter2, ...
forIter1, forIter2, ...
biIter1, biIter2, ...
randIter1, randIter2
- These are generic variable names used for two (or more) iterators
of a particular kind in a given context.
- [iter?Begin, iter?End)
[otherIter?Begin, otherIter?End)
[inIter?Begin, inIter?End)
[outIter?Begin, outIter?End)
[forIter?Begin, forIter?End)
[biIter?Begin, biIter?End)
[randIter?Begin, randIter?End)
- These symbols denote STL ranges of values in a container. The
question mark (?) may be replaced by nothing, by a number
and/or by additional descriptive terms in any given situation.
Occasionally a variation of one or more of these forms may appear,
and its meaning and usage will, with luck, be apparent from the
context.
Naming conventions for function/functor types and values
- UnaryFunc
- A type of value-returning unary function, generally taking as a
parameter an item of the same type as the component values of the
container which appears in the same context.
- UnaryPred
- Like a unary function, but returning a value of type
bool, thus making it a "unary predicate function", or "unary
predicate" for short, since it is testing a "predicate", or statement
about a container value (of a container in the same context) and
returning a value of true or false for that
statement.
- UnaryProc
- A type of void unary function (also called a
"procedure"), generally taking as a parameter an item of the same
type as the components of a container in the same context.
- BinaryFunc
- A type of value-returning binary function, generally taking as
parameters two items of the same type as the components of the
container which appears in the same context.
- BinaryPred
- Like a binary function, but returning a value of type
bool, thus making it a "binary predicate function", or
"binary predicate" for short, since it is testing a "predicate", or
statement about two container values (from a container in the same
context), and returning a value of true or false
for that statement. A special kind of binary predicate function that
compares two values and returns true if the first value is
ordered in some way with respect to the second, and false
otherwise. A binary predicate may also be referred to as a comparison
function, or sometimes simply as a comparitor.
- BinaryProc
- A type of void binary function (also called a
"procedure"), generally taking as parameters two items of the same
type as the components of the container which appears in the same
context.
- GeneratorFunc
- A type of function that generates (returns) values or
objects.
- unFunc, unPred, unProc, binFunc, binPred, binProc,
genFunc
- These are generic parameter names for functions of the preceding
seven types.