TfIterator< T, Reverse > Class Template Reference

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

#include <iterator.h>

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

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
TfIterator< std::vector<int> > i(vector);
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

TF_FOR_ALL(i, s)
    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> > start, finish;
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

T	container type

Definition at line 176 of file iterator.h.

Member Typedef Documentation

Iterator

typedef IterInterface::IteratorType Iterator

Definition at line 193 of file iterator.h.

IterInterface

typedef Tf_IteratorInterface<T, Reverse> IterInterface

Definition at line 192 of file iterator.h.

Reference

typedef std::iterator_traits<Iterator>::reference Reference

Definition at line 195 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

container

container 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

begin	iterator at the beginning of the sequence
end	iterator 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 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]

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++() [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

iterator

iterator 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:

• pxr/base/tf/iterator.h