llvm::fallible

A wrapper class for fallible iterators.

Synopsis

Declared in <llvm/ADT/fallible_iterator.h>

template<typename Underlying>
class fallible_iterator;

Description

The fallible_iterator template wraps an underlying iterator‐like class whose increment and decrement operations are replaced with fallible versions like:

Error inc();
Error dec();

It produces an interface that is (mostly) compatible with a traditional c++ iterator, including ++ and ‐‐ operators that do not fail.

Instances of the wrapper are constructed with an instance of the underlying iterator and (for non‐end iterators) a reference to an Error instance. If the underlying increment/decrement operations fail, the Error is returned via this reference, and the resulting iterator value set to an end‐of‐range sentinel value. This enables the following loop idiom:

class Archive { // E.g. Potentially malformed on-disk archive
public:
  fallible_iterator<ArchiveChildItr> children_begin(Error &Err);
  fallible_iterator<ArchiveChildItr> children_end();
  iterator_range<fallible_iterator<ArchiveChildItr>>
  children(Error &Err) {
    return make_range(children_begin(Err), children_end());
  //...
};

void walk(Archive &A) {
  Error Err = Error::success();
  for (auto &C : A.children(Err)) {
    // Loop body only entered when increment succeeds.
  }
  if (Err) {
    // handle error.
  }
}

The wrapper marks the referenced Error as unchecked after each increment and/or decrement operation, and clears the unchecked flag when a non‐end value is compared against end (since, by the increment invariant, not being an end value proves that there was no error, and is equivalent to checking that the Error is success). This allows early exits from the loop body without requiring redundant error checks.