IteratorRa< T > Class Template Reference

#include <evo/impl/iter.h>

Inheritance diagram for IteratorRa< T >:

Detailed Description

template<class T>
class evo::IteratorRa< T >

Random access iterator.

Used to iterate through container items.

• Random access iterators support forward and reverse iteration as well as random access by numeric index
• Random access iterators always have a numeric key and support numeric comparison

Template Parameters

T	Container type (must not be const)

Usage

Iterators work like normal pointers.

• Containers with iterators will have built-in Iter (const) and IterM (mutable) iterator types for iteration
• Create iterator for given container, normally set to first position by default
• Explicitly set to start/last/end position using operator=(IteratorPos):

  iter = iterFIRST;
  iter = iterLAST;
  iter = iterEND;

• Explicitly set index position using operator=(Key):

  iter = 5;

• Increment to move to next item:

  ++iter;
  iter++;
  iter += 2;

• Decrement to move to previous item:

  --iter;
  iter--;
  iter -= 2;

• Dereference to access item data:

  *iter

• Evaluate iterator as a bool to check if active (at valid position) or has reached the end:

  if (iter) {
      // Iter is active/valid position
  }
  if (!iter) {
      // Iter is at end position
  }

  Note: This is done through safe bool conversion to avoid implicit conversion side-effects (see SafeBool)
• Caution:
  • Adding or removing container items while an iterator is active (not at end) may move or invalidate the iterator
  • Results are undefined if an invalidated iterator is dereferenced

Example

#include <evo/list.h>
#include <evo/io.h>
using namespace evo;
static Console& c = con();

int main() {
    // Using simple List container
    List<int> list;
    list.add(1);
    list.add(2);
    list.add(3);

    // Const iterator (prints items in order and then in reverse)
    for (List<int>::Iter iter(list, iterFIRST); iter; ++iter)
        c.out << *iter << NL;
    for (List<int>::Iter iter(list, iterLAST); iter; --iter)
        c.out << *iter << NL;

    // Mutable iterator (changes all item values to 1)
    for (List<int>::IterM iter(list, iterFIRST); iter; ++iter)
        *iter = 1;

    // Mutable iterator (change first item to 2)
    {
        List<int>::IterM iter(list);
        iter = 0;
        *iter = 2;
    }

    return 0;
}

Container Definition

Containers normally define iterator types via member typedefs with const and mutable (non-const) variations, normally named Iter (const) and IterM (mutable). The iterator key type is stored by the iterator as a handle and is used to implement the iterator.

Example:

// Example container class
template<class T> class Container {
public:
    // Iterator key -- used internally by container (using uint here as example)
    typedef uint IterKey;

    // Container iterator types
    typedef typename IteratorBi< Container<T>,IterKey,T >::Const Iter;
    typedef IteratorBi< Container<T>,IterKey,T > IterM;

    // ...
};

Implementation Detail - Container Interface

Iterators interact with containers using an expected interface implemented by the container – this is used internally:

• Iterators store a Key value that is passed to the container for internal tracking
• Random access iterators require the following container interface – const-correctness is expected as shown:

  // Iterator key and state, keeps state for iterator, holds iterator key/position
  struct IterKey { ... };
  typedef ... IterKey;
  
  // Iterator item pointer, dereferences to iterator value
  typedef ... IterItem;
  
  // Called by mutable iterator constructor to notify container object that items may change
  void iterInitMutable();
  
  // Return pointer to first item or NULL if none
  const IterItem* iterFirst(IterKey& key) const;
  
  // Return pointer to next item data or NULL if no more
  const IterItem* iterNext(IterKey& key) const;
  
  // Return pointer to last item or NULL if none
  const IterItem* iterLast(IterKey& key) const;
  
  // Return pointer to previous item data or NULL if no more
  const IterItem* iterPrev(IterKey& key) const;
  
  // Return pointer to item data at given numeric key index, or NULL if not valid
  const IterItem* iterSet(IterKey key) const;
  
  // Return item count
  Size iterCount() const;

Public Types
typedef IteratorRa< const T >	Const
	Random access const iterator type. More...
typedef IteratorBase< T >::Item	Item
	Iterator item type. More...
typedef IteratorBase< T >	IterBaseType
	Iterator base type for parameter passing. More...
typedef IteratorRa< T >	IterType
	Iterator type. More...
typedef IteratorBase< T >::Key	Key
	Iterator key type. More...
typedef IteratorRa< typename RemoveConst< T >::Type >	Mutable
	Random access mutable iterator type. More...
typedef IteratorBase< T >::Size	Size
	Size type to use. More...
typedef T	Target
	Iterator target type. More...
typedef StaticIf< IsConst< T >::value, Mutable, Const >::Type	ToggleConst
	Used for converting between Const/Mutable iterators. More...

Public Member Functions
	IteratorRa ()
	Constructor. More...
	IteratorRa (T &obj)
	Constructor. More...
	IteratorRa (T &obj, IteratorPos pos)
	Constructor setting position. More...
	IteratorRa (T &obj, Key num)
	Constructor setting position. More...
	IteratorRa (T &obj, const Key &key, Item *data)
	Constructor. More...
	IteratorRa (const IterType &src)
	Copy constructor. More...
	IteratorRa (const IterBaseType &src)
	Copy constructor. More...
int	compare (const IterBaseType &iter) const
	Compare to another iterator. More...
int	compare (Key num) const
	Compare to a position index. More...
Size	count () const
	Get container item count. More...
Key	index () const
	Get iterator position index. More...
	operator SafeBoolType () const
	Safe (explicit) evaluation as bool type. More...
bool	operator! () const
	Check whether iterator is at end (not valid). More...
bool	operator!= (const IterBaseType &iter) const
	Inequality operator. More...
template<typename T_ >
bool	operator!= (const IteratorBase< T_ > &oth) const
	Check inequality with another iterator. More...
bool	operator!= (Key num) const
	Inequality operator. More...
Item &	operator* ()
	Dereference iterator to get item data reference. More...
IterType	operator+ (Size count) const
	Addition (multi increment) operator. More...
IterType &	operator++ ()
	Pre increment operator. More...
IterType	operator++ (int)
	Post increment operator. More...
IterType &	operator+= (Size count)
	In-place addition (multi increment) operator. More...
IterType	operator- (Size count) const
	Subtraction (multi decrement) operator. More...
IterType &	operator-- ()
	Pre decrement operator. More...
IterType	operator-- (int)
	Post decrement operator. More...
IterType &	operator-= (Size count)
	In-place subtraction (multi decrement) operator. More...
Item *	operator-> ()
	Dereference iterator to access data member. More...
bool	operator< (const IterBaseType &iter) const
	Less-than operator. More...
bool	operator< (Key num) const
	Less-than operator. More...
bool	operator<= (const IterBaseType &iter) const
	Less-than-or-equal operator. More...
bool	operator<= (Key num) const
	Less-than-or-equal operator. More...
IterType &	operator= (const IterType &src)
	Copy/Assignment operator to copy from source iterator. More...
IterType &	operator= (const IterBaseType &src)
	Copy/Assignment operator to copy from source iterator. More...
IterType &	operator= (const ToggleConst &src)
	Assignment operator to copy from source iterator. More...
IterType &	operator= (const typename IterBaseType::ToggleConst &src)
	Assignment operator to copy from source iterator. More...
IterType &	operator= (T &obj)
	Assignment operator. More...
IterType &	operator= (IteratorPos pos)
	Assignment operator to set position. More...
IterType &	operator= (Key num)
	Assignment operator for random access position index. More...
bool	operator== (const IterBaseType &iter) const
	Equality operator. More...
template<typename T_ >
bool	operator== (const IteratorBase< T_ > &oth) const
	Check equality with another iterator. More...
bool	operator== (Key num) const
	Equality operator. More...
bool	operator> (const IterBaseType &iter) const
	Greater-than operator. More...
bool	operator> (Key num) const
	Greater-than operator. More...
bool	operator>= (const IterBaseType &iter) const
	Greater-than-or-equal operator. More...
bool	operator>= (Key num) const
	Greater-than-or-equal operator. More...

Static Public Member Functions
static const IterBaseType &	end ()
	Get iterator at end position. More...

Protected Member Functions
bool	first ()
	Go to first item (used internally). More...
bool	last ()
	Go to last item. More...
bool	next ()
	Go to next item (used internally). More...
bool	next (Size count)
	Go to next item, skipping given count (used internally). More...
bool	prev ()
	Go to previous item. More...
bool	prev (Size count)
	Go to previous item, skipping given count (used internally). More...

Protected Attributes
Item *	data_
	Item pointer. More...
bool	end_
	End flag. More...
Key	key_
	Iterator key. More...
T *	obj_
	Container object pointer. More...

Member Typedef Documentation

Const

typedef IteratorRa<const T> Const

Random access const iterator type.

Item

typedef IteratorBase<T>::Item Item

Iterator item type.

IterBaseType

typedef IteratorBase<T> IterBaseType

Iterator base type for parameter passing.

IterType

typedef IteratorRa<T> IterType

Iterator type.

Key

typedef IteratorBase<T>::Key Key

Iterator key type.

Mutable

typedef IteratorRa<typename RemoveConst<T>::Type> Mutable

Random access mutable iterator type.

Size

typedef IteratorBase<T>::Size Size

Size type to use.

Target

typedef T Target

inherited

Iterator target type.

ToggleConst

typedef StaticIf<IsConst<T>::value,Mutable,Const>::Type ToggleConst

Used for converting between Const/Mutable iterators.

Constructor & Destructor Documentation

IteratorRa() [1/7]

IteratorRa ( )

inline

Constructor.

This sets empty iterator at end.

IteratorRa() [2/7]

IteratorRa ( T &  obj )

inlineexplicit

Constructor.

This sets iterator to first item (or end if empty).

Parameters

obj	Container object for iterator

IteratorRa() [3/7]

IteratorRa ( T &  obj, IteratorPos  pos  )

inlineexplicit

Constructor setting position.

This sets iterator to given position (or end if empty).

Parameters

obj	Container object for iterator
pos	Position to set, either iterFIRST, iterLAST, or iterEND

IteratorRa() [4/7]

IteratorRa ( T &  obj, Key  num  )

inline

Constructor setting position.

This sets iterator to given position (or end if empty).

Parameters

obj	Container object for iterator
num	Position index to set

IteratorRa() [5/7]

IteratorRa ( T &  obj, const Key &  key, Item *  data  )

inline

Constructor.

This initializes iterator with given position data (used internally).

Parameters

obj	Container object for iterator
key	Iterator key to set
data	Iterator data pointer to set

IteratorRa() [6/7]

IteratorRa ( const IterType &  src )

inline

Copy constructor.

Parameters

src	Source iterator to copy

IteratorRa() [7/7]

IteratorRa ( const IterBaseType &  src )

inline

Copy constructor.

Parameters

src	Source iterator to copy

Member Function Documentation

compare() [1/2]

int compare ( const IterBaseType &  iter ) const

inline

Compare to another iterator.

Parameters

iter	Iterator to compare

Returns

Comparison result, -1: this is less, 0: equal, 1: this is greater

compare() [2/2]

int compare ( Key  num ) const

inline

Compare to a position index.

Parameters

num	Position index to compare, END for end position

Returns

Comparison result, -1: this is less, 0: equal, 1: this is greater

count()

Size count ( ) const

inline

Get container item count.

Returns

Item count

end()

static const IterBaseType& end ( )

inlinestaticinherited

Get iterator at end position.

first()

bool first ( )

inlineprotectedinherited

Go to first item (used internally).

Returns

Whether first item was found, false if empty

index()

Key index ( ) const

inline

Get iterator position index.

Returns

Position index, END if end

last()

bool last ( )

inlineprotectedinherited

Go to last item.

Returns

Whether last item was found (false if empty).

next() [1/2]

bool next ( )

inlineprotectedinherited

Go to next item (used internally).

Returns

Whether next item was found, false if no more

next() [2/2]

bool next ( Size  count )

inlineprotected

Go to next item, skipping given count (used internally).

Parameters

count

Number of items to advance

Returns

Whether given item was found, false if no more

operator SafeBoolType()

operator SafeBoolType ( ) const

inlineinherited

Safe (explicit) evaluation as bool type.

• This is called when object is directly evaluated as a bool, and is equivalent to: !operator!()
• See SafeBool

operator!()

bool operator! ( ) const

inlineinherited

Check whether iterator is at end (not valid).

Returns

Whether at end

operator!=() [1/3]

bool operator!= ( const IterBaseType &  iter ) const

inlineinherited

Inequality operator.

Parameters

iter	Iterator to compare

Returns

Whether not equal

operator!=() [2/3]

bool operator!= ( const IteratorBase< T_ > &  oth ) const

inlineinherited

Check inequality with another iterator.

Parameters

oth	Other iterator to check against.

Returns

Whether inequal.

operator!=() [3/3]

bool operator!= ( Key  num ) const

inline

Inequality operator.

Parameters

num	Position index to compare

Returns

Whether not equal to index

operator*()

Item& operator* ( )

inlineinherited

Dereference iterator to get item data reference.

• Iterator must be valid (not at end position)

Returns

Reference to current item data

operator+()

IterType operator+ ( Size  count ) const

inline

Addition (multi increment) operator.

Same as next(Size) on the returned temporary iterator.

• In-place operator+=() is preferred to avoid creating temporary object

Parameters

count

Count to add

Returns

Temporary incremented iterator copy

operator++() [1/2]

IterType& operator++ ( )

inlineinherited

Pre increment operator.

Same as next().

Returns

This

operator++() [2/2]

IterType operator++ ( int  )

inlineinherited

Post increment operator.

Same as next(), but returns iterator copy before increment.

Returns

Iterator copy before increment

operator+=()

IterType& operator+= ( Size  count )

inline

In-place addition (multi increment) operator.

Same as next(Size).

Parameters

count

Count to add

Returns

This

operator-()

IterType operator- ( Size  count ) const

inline

Subtraction (multi decrement) operator.

Same as prev(Size) on the returned temporary iterator.

• In-place operator-=() is preferred to avoid creating temporary object

Parameters

count

Count to subtract

Returns

Temporary decremented iterator copy

operator--() [1/2]

IterType& operator-- ( )

inlineinherited

Pre decrement operator.

Same as prev().

Returns

This.

operator--() [2/2]

IterType operator-- ( int  )

inlineinherited

Post decrement operator.

Same as prev(), but returns iterator copy before decrement.

Returns

Iterator copy before decrement.

operator-=()

IterType& operator-= ( Size  count )

inline

In-place subtraction (multi decrement) operator.

Same as prev(Size).

Parameters

count

Count to subtract

Returns

This

operator->()

Item* operator-> ( )

inlineinherited

Dereference iterator to access data member.

• Iterator must be valid (not at end position)

Returns

Reference to current item data

operator<() [1/2]

bool operator< ( const IterBaseType &  iter ) const

inline

Less-than operator.

Parameters

iter	Iterator to compare

Returns

Whether less than iter

operator<() [2/2]

bool operator< ( Key  num ) const

inline

Less-than operator.

Parameters

num	Position index to compare

Returns

Whether less than index

operator<=() [1/2]

bool operator<= ( const IterBaseType &  iter ) const

inline

Less-than-or-equal operator.

Parameters

iter	Iterator to compare

Returns

Whether less than or equal to iter

operator<=() [2/2]

bool operator<= ( Key  num ) const

inline

Less-than-or-equal operator.

Parameters

num	Position index to compare

Returns

Whether less than or equal to index

operator=() [1/7]

IterType& operator= ( const IterType &  src )

inline

Copy/Assignment operator to copy from source iterator.

Parameters

src	Source iterator to copy

Returns

This

operator=() [2/7]

IterType& operator= ( const IterBaseType &  src )

inline

Copy/Assignment operator to copy from source iterator.

Parameters

src	Source iterator to copy

Returns

This

operator=() [3/7]

IterType& operator= ( const ToggleConst &  src )

inline

Assignment operator to copy from source iterator.

• This allows assigning a mutable iterator to a const iterator
• This triggers a compiler error on attempt to assign a const iterator to a mutable iterator

Parameters

src	Source iterator to copy.

Returns

This.

operator=() [4/7]

IterType& operator= ( const typename IterBaseType::ToggleConst &  src )

inline

Assignment operator to copy from source iterator.

• This allows assigning a mutable iterator to a const iterator
• This triggers a compiler error on attempt to assign a const iterator to a mutable iterator

Parameters

src	Source iterator to copy.

Returns

This.

operator=() [5/7]

IterType& operator= ( T &  obj )

inline

Assignment operator.

This sets iterator to first item (or end if empty).

Parameters

obj	Container object to iterate through

Returns

This

operator=() [6/7]

IterType& operator= ( IteratorPos  pos )

inline

Assignment operator to set position.

Parameters

pos	Position to set, either iterFIRST, iterLAST, or iterEND

Returns

This

operator=() [7/7]

IterType& operator= ( Key  num )

inline

Assignment operator for random access position index.

Parameters

num	Iterator index to set

Returns

This

operator==() [1/3]

bool operator== ( const IterBaseType &  iter ) const

inlineinherited

Equality operator.

Parameters

iter	Iterator to compare

Returns

Whether equal

operator==() [2/3]

bool operator== ( const IteratorBase< T_ > &  oth ) const

inlineinherited

Check equality with another iterator.

Parameters

oth	Other iterator to check against.

Returns

Whether equal.

operator==() [3/3]

bool operator== ( Key  num ) const

inline

Equality operator.

Parameters

num	Position index to compare

Returns

Whether equal to index

operator>() [1/2]

bool operator> ( const IterBaseType &  iter ) const

inline

Greater-than operator.

Parameters

iter	Iterator to compare

Returns

Whether greater than iter

operator>() [2/2]

bool operator> ( Key  num ) const

inline

Greater-than operator.

Parameters

num	Position index to compare

Returns

Whether greater than index

operator>=() [1/2]

bool operator>= ( const IterBaseType &  iter ) const

inline

Greater-than-or-equal operator.

Parameters

iter	Iterator to compare

Returns

Whether greater than or equal to iter

operator>=() [2/2]

bool operator>= ( Key  num ) const

inline

Greater-than-or-equal operator.

Parameters

num	Position index to compare

Returns

Whether greater than or equal to index

prev() [1/2]

bool prev ( )

inlineprotectedinherited

Go to previous item.

Returns

Whether previous item was found (false if no more).

prev() [2/2]

bool prev ( Size  count )

inlineprotected

Go to previous item, skipping given count (used internally).

Parameters

count

Number of items to advance

Returns

Whether given item was found, false if no more

Member Data Documentation

data_

Item* data_

protectedinherited

Item pointer.

end_

bool end_

protectedinherited

End flag.

key_

Key key_

protectedinherited

Iterator key.

obj_

T* obj_

protectedinherited

Container object pointer.

---

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

• evo/impl/iter.h