CTR32-CPP. Use valid references, pointers, and iterators to reference elements of a container

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, pos is invalidated after the call to insert(), and subsequent loop iterations have undefined behavior:

#include <deque>
 
void f(const double *items, std::size_t count) {
  std::deque<double> d;
  auto pos = d.begin();
  for (std::size_t i = 0; i < count; ++i, ++pos) {
    d.insert(pos, items[i] + 41.0);
  }
}

Compliant Solution (Updated Iterator)

In this compliant solution, pos is assigned a valid iterator on each insertion, removing the undefined behavior:

#include <deque>
 
void f(const double *items, std::size_t count) {
  std::deque<double> d;
  auto pos = d.begin();
  for (std::size_t i = 0; i < count; ++i, ++pos) {
    pos = d.insert(pos, items[i] + 41.0);
  }
}

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

#include <deque>
#include <algorithm>
#include <iterator>
 
void f(const double *items, std::size_t count) {
  std::deque<double> d;
  std::transform(items, items + count, std::inserter(d, d.begin()),
                 [](double d) { return d + 41.0; });
}

Noncompliant Code Example

In this noncompliant code example, data is 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");
  // ...
  g(data);

}

Compliant Solution

In this compliant solution, 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 *);

void f(std::string &example_string) {
  // ...
  example_string.replace(0, 2, "bb");
  // ...
  g(example_string.data());
}

Risk Assessment

Using invalid references, 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