TfIterator< T, Reverse > Class Template Reference

A simple iterator adapter for STL containers. More...

Public Types

typedef Tf_IteratorInterface< T, Reverse > IterInterface
 
typedef IterInterface::IteratorType Iterator
 
typedef std::iterator_traits< Iterator >::reference Reference
 

Public Member Functions

 TfIterator ()
 Default constructor. This iterator is uninitialized. More...
 
 TfIterator (T &container)
 Constructs an iterator to traverse each element of the specified STL container object. More...
 
 TfIterator (T &&container)
 Allow rvalues only if the container type T should be copied by TfIterator. More...
 
 TfIterator (Iterator const &begin, Iterator const &end)
 Constructs an iterator to traverse a subset of the elements in a container. More...
 
bool operator! () const
 Returns true if this iterator is exhausted. More...
 
bool operator== (const TfIterator &iterator) const
 Returns true if this Iterator.has the same position in the sequence as the specified iterator. More...
 
bool operator!= (const TfIterator &iterator) const
 Returns false if (*this == iterator) returns true, returns true otherwise. More...
 
TfIteratoroperator++ ()
 Pre-increment operator. More...
 
TfIterator operator++ (int)
 Post-increment operator. More...
 
Reference operator * ()
 Returns the element referenced by this iterator. More...
 
Reference operator * () const
 Returns the element referenced by this iterator. More...
 
Iterator & operator-> ()
 Returns a pointer to the element referenced by this iterator. More...
 
 operator bool () const
 Explicit bool conversion operator. More...
 
 operator Iterator () const
 Returns an STL iterator that has the same position as this iterator. More...
 
const Iterator & base () const
 Returns an STL iterator that has the same position as this iterator. More...
 
TfIterator GetNext () const
 Returns an iterator that is positioned at the next element in the sequence. More...
 

Detailed Description

template<class T, bool Reverse = false>
class TfIterator< T, Reverse >

A simple iterator adapter for STL containers.

TfIterator iterates over the elements in an STL container, according to the semantics of the simple iterator pattern. The following examples compare the TfIterator to STL, highlighting the brevity of the TfIterator interface.

std::vector<int> vector;
std::set<int> set;
// TfIterator 'while' loop
while (i) {
int x = *i++;
}
// STL 'while' loop
std::vector<int>::iterator i = vector.begin();
while (i != vector.end()) {
int x = *i++;
}
// TfIterator 'for' loop
std::set<int> set;
for (TfIterator< const std::set<int> > j = set; j; ++j) {
int x = *j;
}
// STL 'for' loop
std::set<int> set;
for (std::set<int>::iterator j = set.begin(); j != set.end(); ++j) {
int x = *j;
}

Note that using the TF_FOR_ALL() macro, even more brevity is possible. For example, to print out all items of a set<int> s, we could write

printf("%d\n", *i);

Typically, a TfIterator is used to traverse all of the elements in an STL container. For ordered sets, other uses include iterating over a subset of the elements in the container, and using a TfIterator as a sentinel.

// Iterate over subset
TfIterator< std::vector<int> > iterator(start, finish);
// TfIterator sentinel
TfIterator< std::vector<int> > sentinel(finish, finish);
while (iterator != sentinel) {
int x = *iterator++;
}

The Simple Iterator Pattern

The simple iterator pattern generalizes pointer semantics to traverse a set of elements, much like STL iterators. However, the simple iterator pattern subscribes to a simpler subset of pointer operations: pointer assignment (operator=), auto-increment (operator++), dereferencing (operator*), redirection (operator->), and null pointer comparison (operator! and operator bool). The simpler interface improves code legibility for the typical set traversals for which iterators are most commonly used. It is particularly useful for specifying iterators over sets of elements that are maintained by a user object, since the interface calls for only one GetIterator() entry point rather than dual begin() and end() calls. This is especially desirable when the object owns many different sets.

// The simple iterator pattern.
class Iterator {
Iterator(); // default c'tor
Iterator(const Iterator&); // copy c'tor
Iterator& operator=(const Iterator &); // assignment
Iterator& operator++(); // pre-increment
Iterator operator++(int); // post-increment
reference operator *(); // dereference
pointer operator->(); // redirection
bool operator==(const Iterator &) const; // equality
bool operator!=(const Iterator &) const; // inequality
bool operator!() const // is exhausted
operator bool() const; // is not exhausted
};
Parameters
Tcontainer type

Definition at line 176 of file iterator.h.

Constructor & Destructor Documentation

◆ TfIterator() [1/4]

TfIterator ( )
inline

Default constructor. This iterator is uninitialized.

Definition at line 198 of file iterator.h.

◆ TfIterator() [2/4]

TfIterator ( T &  container)
inline

Constructs an iterator to traverse each element of the specified STL container object.

Parameters
containercontainer object

Definition at line 203 of file iterator.h.

◆ TfIterator() [3/4]

TfIterator ( T &&  container)
inline

Allow rvalues only if the container type T should be copied by TfIterator.

Definition at line 206 of file iterator.h.

◆ TfIterator() [4/4]

TfIterator ( Iterator const &  begin,
Iterator const &  end 
)
inline

Constructs an iterator to traverse a subset of the elements in a container.

This iterator is exhausted when it reaches the end iterator.

Parameters
beginiterator at the beginning of the sequence
enditerator at the end of the sequence

Definition at line 220 of file iterator.h.

Member Function Documentation

◆ base()

const Iterator& base ( ) const
inline

Returns an STL iterator that has the same position as this iterator.

Returns
STL iterator at the same position as this iterator

Definition at line 307 of file iterator.h.

◆ GetNext()

TfIterator GetNext ( ) const
inline

Returns an iterator that is positioned at the next element in the sequence.

Returns
iterator at next element in the sequence

Definition at line 314 of file iterator.h.

◆ operator *() [1/2]

Reference operator * ( )
inline

Returns the element referenced by this iterator.

Returns
element

Definition at line 269 of file iterator.h.

◆ operator *() [2/2]

Reference operator * ( ) const
inline

Returns the element referenced by this iterator.

Returns
element

Definition at line 277 of file iterator.h.

◆ operator bool()

operator bool ( ) const
inlineexplicit

Explicit bool conversion operator.

The Iterator object converts to true if it has not been exhausted.

Definition at line 293 of file iterator.h.

◆ operator Iterator()

operator Iterator ( ) const
inline

Returns an STL iterator that has the same position as this iterator.

Returns
STL iterator at the same position as this iterator

Definition at line 300 of file iterator.h.

◆ operator!()

bool operator! ( ) const
inline

Returns true if this iterator is exhausted.

Returns
true if this iterator is exhausted

Definition at line 227 of file iterator.h.

◆ operator!=()

bool operator!= ( const TfIterator< T, Reverse > &  iterator) const
inline

Returns false if (*this == iterator) returns true, returns true otherwise.

Definition at line 241 of file iterator.h.

◆ operator++() [1/2]

TfIterator& operator++ ( )
inline

Pre-increment operator.

Advances this iterator to the next element in the sequence.

Returns
this iterator

Definition at line 248 of file iterator.h.

◆ operator++() [2/2]

TfIterator operator++ ( int  )
inline

Post-increment operator.

Advances this iterator to the next element in the sequence, and returns a copy of this iterator prior to the increment.

Returns
copy of this iterator prior to increment

Definition at line 261 of file iterator.h.

◆ operator->()

Iterator& operator-> ( )
inline

Returns a pointer to the element referenced by this iterator.

Returns
pointer to element

Definition at line 285 of file iterator.h.

◆ operator==()

bool operator== ( const TfIterator< T, Reverse > &  iterator) const
inline

Returns true if this Iterator.has the same position in the sequence as the specified iterator.

The end of the sequence need not be the same.

Parameters
iteratoriterator to compare
Returns
true if this Iterator.has the same position as iterator

Definition at line 235 of file iterator.h.


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