Page History

Iterators are a generalization of pointers that allow a C++ program to work with different data structures (containers) in a uniform manner [ISO/IEC 14882-2014]. Pointers, references, and iterators share a close relationship in which it is required that referencing values be done through a valid iterator, pointer, or reference. Storing an iterator, reference, or pointer to an element within a container for any length of time comes with a risk that the underlying container may be modified such that the stored iterator, pointer, or reference becomes invalid. For instance, when a sequence container such as std::vector requires an underlying reallocation, outstanding iterators, pointers, and references will be invalidated [Kalev 99]. Use only a valid pointer, reference, or iterator to refer to an element of a container.

The C++ Standard, [container.requirements.general], paragraph 12 [ISO/IEC 14882-2014] states the following: 

Unless otherwise specified (either explicitly or by defining a function in terms of other functions), invoking a container member function or passing a container as an argument to a library function shall not invalidate iterators to, or change the values of, objects within that container.

The C++ Standard allows references and pointers to be invalidated independently for the same operation, which may result in an invalidated reference but not an invalidated pointer. However, relying on this distinction is insecure because the object pointed to by the pointer may be different than expected even if the pointer is valid. For instance, it is possible to retrieve a pointer to an element from a container, erase that element (invalidating references when destroying the underlying object), then insert a new element at the same location within the container causing the extant pointer to now point to a valid, but distinct object. Thus, any operation that invalidates a pointer or a reference should be treated as though it invalidates both pointers and references.

The following container functions can invalidate iterators, references, and pointers under certain circumstances.

Reallocation can occur when a member function modifies its container. Modifying member functions include {{reserve()}} and {{resize()}}, {{push_back()}}, {{pop_back()}}, {{erase()}}, {{clear()}}, {{insert()}}, and others. In addition, assignment operations and modifying algorithms can also cause reallocation. When a container reallocates its elements, their addresses change. Consequently, the values of existing iterators are invalidated \[[Kalev 99|AA. C++ References#Kalev 99]\]. Using invalid iterators yields undefined results.

In particular the following operations on containers invalidate any iterators over these containers:

...

...

Pointers and references to objects within a container are also invalidated when iterators are invalidated. A single exception applies for the deque class: it preserves pointers and references to internal objects upon inserts to either its beginning or its end, but it does not preserve iterators.

Non-Compliant Code Example

A std::basic_string object is also a container to which this rule applies. For more specific information pertaining to std::basic_string containers, see STR52-CPP. Use valid references, pointers, and iterators to reference elements of a basic_string.

Noncompliant Code Example

In this noncompliant code example, pos is invalidated after the first call to insert()In this example, the iterator pos is invalidated after the call to insert, and subsequent loop iterations have undefined behavior.

#include <deque>
 
double data[5] = { 2.3, 3.7, 1.4, 0.8, 9.6 };

void f(const double *items, std::size_t count) {
  std::deque<double> d;
deque<double>::iterator  auto pos = d.begin();

  for (std::size_t i = 0; i < 5count; ++i, ++pos) {
    d.insert(pos++, dataitems[i] + 41.0);
  }
}

Compliant Solution

...

(Updated Iterator)

In this compliant solution, pos is assigned a valid iterator on each insertion, preventing undefined behavior.Update pos each time insert is called to keep the iterators valid, and then increment it:

#include <deque>
double data[5] = { 2.3, 3.7, 1.4, 0.8, 9.6 };

 
void f(const double *items, std::size_t count) {
  std::deque<double> d;
deque<double>::iterator  auto pos = d.begin();

  for (std::size_t i = 0; i < 5count; ++i, ++pos) {
    pos = d.insert(pos, dataitems[i] + 41.0);
  ++pos;}
}

Compliant Solution

...

(Generic Algorithm)

This compliant solution replaces the handwritten loop with the generic standard template library algorithm std::transform(). The call to std::transform() accepts the range of elements to transform, the location to store the transformed values (which, in this case, is a std::inserter object to insert them at the beginning of d), and the transformation function to apply (which, in this case, is a simple lambda)Use one of the STL algorithms.

#include <algorithm>
double data[5] = { 2.3, 3.7, 1.4, 0.8, 9.6 };
#include <deque>
#include <iterator>
 
void f(const double *items, std::size_t count) {
  std::deque<double> d;

  std::transform(dataitems, dataitems +5 count,
     std::inserter(d, d.begin()),
                bind2nd(plus<int>(), 41)); [](double d) { return d + 41.0; });
}

Risk Assessment

Using invalid iterators yields undefined resultsreferences, pointers, or iterators to reference elements of a container results in undefined behavior.

References

\[[Meyers 01|AA. C++ References#Meyers 01]\] Item 43: Prefer algorithm calls to hand-written loops.
\[[Sutter 04|AA. C++ References#Sutter 04]\] Item 84: Prefer algorithm calls to handwritten loops.
\[[Kalev 99|AA. C++ References#Kalev 99]\] ANSI/ISO C+\+ Professional Programmer's Handbook.
\[[ISO/IEC 14882-2003|AA. C++ References#ISO/IEC 14882-2003]\] Section 24: Iterators Library.

Automated Detection

Related Vulnerabilities

Search for vulnerabilities resulting from the violation of this rule on the CERT website.

Related Guidelines

Bibliography

...

Image Added Image Added Image AddedSTL00-CPP. Understand how container classes are stored      14. Templates and the STL (STL)      STL31-CPP. Use Valid Iterator Ranges