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 through such an object must be done through a valid value. 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 value is invalidated. For instance, when a sequence container such as std::vector requires an underlying reallocation, outstanding iterators and references will be invalidated [Kalev 99]. Only use a valid pointer, reference, or iterator to refer to an element of a container.

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

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 following container functions can invalidate iterators, references and/or pointers under certain circumstances:

(Note, this list is currently incomplete and needs further editing.)

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

Noncompliant Code Example

In this noncompliant code example,

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. This applies only to contiguous-memory iterators, in particular std::vector, std::deque and std::string.

In general iterators on node-based containers such as std::list are not invalidated via modification of the container, unless the element referenced by the iterator is itself erased.

Pointers and references to objects within a container are also invalidated when iterators are invalidated. A single exception applies for the std::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.

Consequently, the values of existing iterators may be invalidated [Kalev 99]. Using invalid iterators yields undefined results.

Non-Compliant Code Example

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

double data[5] = { 2.3, 3.7, 1.4, 0.8, 9.6 };

#include <deque>
 
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, removing the undefined behaviorUpdate pos each time insert is called to keep the iterators valid, and then increment it:

double data[5] = { 2.3, 3.7, 1.4, 0.8, 9.6 };

#include <deque>
 
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 hand-written loop with the generic STL algorithm std::transform. The call to std::transform accepts the range of elements to transform, the location of where 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.

double data[5] = { 2.3, 3.7, 1.4, 0.8, 9.6 };
#include <deque>
#include <algorithm>
#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));

Non-compliant Code Example (std::string::data())

       [](double d) { return d + 41.0; });
}

Noncompliant Code Example

In this noncompliant In this non-compliant code example, data is to be considered out-of-scope just invalidated after the call to replace.(), and so its use in g() is undefined behavior:

#include <iostream>
#include <string>
 
extern void g(const char *);
 
void f(std::string &example_string) {
  const char *data = example_string.data();
  // ...
  example_string.replace(0, 2, "bb");
char val = data[1];

...

  // ...
  g(data);

}

Compliant Solution

In this compliant solution, the data array is created after modifications to the example string are complete. The modification makes the code compliant: replace is called before the call to data().the pointer to example_string's internal buffer is not generated until after the modifications from replace() have completed:

#include <iostream>
#include <string>

extern void g(const char *data = );

void f(std::string &example_string.data();
) {
  // ...
  example_string.replace(0, 2, "bb");
data = 
  // ...
  g(example_string.data());
char val = data[1];}

Risk Assessment

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

Automated Detection

Related Vulnerabilities

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

Related Guidelines

Bibliography

...

...

 .
[ISO/IEC 14882-2003] Section 24: Iterators Library.

      06. Containers (CTR)      CTR33-CPP. Guarantee that copies are made into storage of sufficient size