llvm::fallible_iterator< Underlying > Class Template Reference

A wrapper class for fallible iterators. More...

#include "llvm/ADT/fallible_iterator.h"

Public Member Functions
decltype(auto)	operator* ()
	Forward dereference to the underlying iterator.
decltype(auto)	operator* () const
	Forward const dereference to the underlying iterator.
template<typename T = Underlying>
enable_if_struct_deref_supported< T >	operator-> ()
	Forward structure dereference to the underlying iterator (if the underlying iterator supports it).
template<typename T = Underlying>
enable_if_struct_deref_supported< const T >	operator-> () const
	Forward const structure dereference to the underlying iterator (if the underlying iterator supports it).
fallible_iterator &	operator++ ()
	Increment the fallible iterator.
fallible_iterator &	operator-- ()
	Decrement the fallible iterator.

Static Public Member Functions
static fallible_iterator	itr (Underlying I, Error &Err)
	Construct a fallible iterator that cannot be used as an end-of-range value.
static fallible_iterator	end (Underlying I)
	Construct a fallible iterator that can be used as an end-of-range value.

Friends
bool	operator== (const fallible_iterator &LHS, const fallible_iterator &RHS)
	Compare fallible iterators for equality.
bool	operator!= (const fallible_iterator &LHS, const fallible_iterator &RHS)
	Compare fallible iterators for inequality.

Detailed Description

template<typename Underlying>
class llvm::fallible_iterator< Underlying >

A wrapper class for fallible iterators.

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.

Definition at line 68 of file fallible_iterator.h.

Member Function Documentation

end()

template<typename Underlying >

static fallible_iterator llvm::fallible_iterator< Underlying >::end ( Underlying  I )

inlinestatic

Construct a fallible iterator that can be used as an end-of-range value.

A value created by this method can be dereferenced (if the underlying value points at a valid value) and compared, but not incremented or decremented.

Definition at line 94 of file fallible_iterator.h.

References I.

Referenced by llvm::object::Archive::child_end(), llvm::object::MinidumpFile::getMemory64List(), and llvm::make_fallible_end().

itr()

template<typename Underlying >

static fallible_iterator llvm::fallible_iterator< Underlying >::itr ( Underlying  I, Error &  Err  )

inlinestatic

Construct a fallible iterator that cannot be used as an end-of-range value.

A value created by this method can be dereferenced, incremented, decremented and compared, providing the underlying type supports it.

The error that is passed in will be initially marked as checked, so if the iterator is not used at all the Error need not be checked.

Definition at line 84 of file fallible_iterator.h.

References I.

Referenced by llvm::object::Archive::child_begin(), llvm::object::MinidumpFile::getMemory64List(), and llvm::make_fallible_itr().

operator*() [1/2]

template<typename Underlying >

decltype(auto) llvm::fallible_iterator< Underlying >::operator* ( )

inline

Forward dereference to the underlying iterator.

Definition at line 99 of file fallible_iterator.h.

operator*() [2/2]

template<typename Underlying >

decltype(auto) llvm::fallible_iterator< Underlying >::operator* ( ) const

inline

Forward const dereference to the underlying iterator.

Definition at line 102 of file fallible_iterator.h.

operator++()

template<typename Underlying >

fallible_iterator & llvm::fallible_iterator< Underlying >::operator++ ( )

inline

Increment the fallible iterator.

If the underlying 'inc' operation fails, this will set the Error value and update this iterator value to point to end-of-range.

The Error value is marked as needing checking, regardless of whether the 'inc' operation succeeds or fails.

Definition at line 125 of file fallible_iterator.h.

References assert().

operator--()

template<typename Underlying >

fallible_iterator & llvm::fallible_iterator< Underlying >::operator-- ( )

inline

Decrement the fallible iterator.

If the underlying 'dec' operation fails, this will set the Error value and update this iterator value to point to end-of-range.

The Error value is marked as needing checking, regardless of whether the 'dec' operation succeeds or fails.

Definition at line 141 of file fallible_iterator.h.

References assert().

operator->() [1/2]

template<typename Underlying >

template<typename T = Underlying>

enable_if_struct_deref_supported< T > llvm::fallible_iterator< Underlying >::operator-> ( )

inline

Forward structure dereference to the underlying iterator (if the underlying iterator supports it).

Definition at line 107 of file fallible_iterator.h.

operator->() [2/2]

template<typename Underlying >

template<typename T = Underlying>

enable_if_struct_deref_supported< const T > llvm::fallible_iterator< Underlying >::operator-> ( ) const

inline

Forward const structure dereference to the underlying iterator (if the underlying iterator supports it).

Definition at line 114 of file fallible_iterator.h.

Friends And Related Function Documentation

operator!=

template<typename Underlying >

bool operator!= ( const fallible_iterator< Underlying > &  LHS, const fallible_iterator< Underlying > &  RHS  )

friend

Compare fallible iterators for inequality.

See notes for operator==.

Definition at line 189 of file fallible_iterator.h.

operator==

template<typename Underlying >

bool operator== ( const fallible_iterator< Underlying > &  LHS, const fallible_iterator< Underlying > &  RHS  )

friend

Compare fallible iterators for equality.

Returns true if both LHS and RHS are end-of-range values, or if both are non-end-of-range values whose underlying iterator values compare equal.

If this is a comparison between an end-of-range iterator and a non-end-of-range iterator, then the Error (referenced by the non-end-of-range value) is marked as checked: Since all increment/decrement operations result in an end-of-range value, comparing false against end-of-range is equivalent to checking that the Error value is success. This flag management enables early returns from loop bodies without redundant Error checks.

Definition at line 162 of file fallible_iterator.h.

---

The documentation for this class was generated from the following file:

• include/llvm/ADT/fallible_iterator.h