IteratorFw< T > Class Template Reference

#include <evo/impl/iter.h>

Inheritance diagram for IteratorFw< T >:

Detailed Description

template<class T>
class evo::IteratorFw< T >

Forward iterator.

Used to iterate through container items.

• Forward iterators only support forward iteration.

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/end position using operator=(IteratorPos):

  iter = iterFIRST;
  iter = iterEND;

• Increment to move to next item:

  ++iter;
  iter++;

• 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)
    for (List<int>::Iter iter(list, iterFIRST); 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;

    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 IteratorFw< Container<T>,IterKey,T >::Const Iter;
    typedef IteratorFw< 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
• Forward 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;

Public Types
typedef IteratorFw< const T >	Const
	Forward 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 IteratorFw< T >	IterType
	Iterator type for parameter passing. More...
typedef IteratorBase< T >::Key	Key
	Iterator key type. More...
typedef IteratorFw< typename RemoveConst< T >::Type >	Mutable
	Forward 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
	IteratorFw ()
	Constructor. More...
	IteratorFw (T &obj)
	Constructor. More...
	IteratorFw (T &obj, IteratorPos pos)
	Constructor. More...
	IteratorFw (T &obj, const Key &key, Item *data)
	Constructor. More...
	IteratorFw (const IterType &src)
	Copy constructor. More...
	IteratorFw (const IterBaseType &src)
	Copy constructor. 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...
Item &	operator* ()
	Dereference iterator to get item data reference. More...
IterType &	operator++ ()
	Pre increment operator. More...
IterType	operator++ (int)
	Post increment operator. More...
Item *	operator-> ()
	Dereference iterator to access data member. 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...
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...

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

Protected Member Functions
	IteratorFw (T *obj)
	Constructor (used internally). More...
bool	first ()
	Go to first item (used internally). More...
bool	next ()
	Go to next item (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 IteratorFw<const T> Const

Forward 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 IteratorFw<T> IterType

Iterator type for parameter passing.

Key

typedef IteratorBase<T>::Key Key

Iterator key type.

Mutable

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

Forward 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

IteratorFw() [1/7]

IteratorFw ( )

inline

Constructor.

This sets empty iterator.

IteratorFw() [2/7]

IteratorFw ( T &  obj )

inlineexplicit

Constructor.

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

Parameters

obj	Container object for iterator

IteratorFw() [3/7]

IteratorFw ( T &  obj, IteratorPos  pos  )

inlineexplicit

Constructor.

This sets iterator to first or end position.

Parameters

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

IteratorFw() [4/7]

IteratorFw ( 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

IteratorFw() [5/7]

IteratorFw ( const IterType &  src )

inline

Copy constructor.

Parameters

src	Source iterator to copy

IteratorFw() [6/7]

IteratorFw ( const IterBaseType &  src )

inline

Copy constructor.

Parameters

src	Source iterator to copy

IteratorFw() [7/7]

IteratorFw ( T *  obj )

inlineexplicitprotected

Constructor (used internally).

Only initializes object pointer.

Parameters

obj	Container object pointer

Member Function Documentation

end()

static const IterBaseType& end ( )

inlinestaticinherited

Get iterator at end position.

first()

bool first ( )

inlineprotected

Go to first item (used internally).

Returns

Whether first item was found, false if empty

next()

bool next ( )

inlineprotected

Go to next item (used internally).

Returns

Whether next 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/2]

bool operator!= ( const IterBaseType &  iter ) const

inlineinherited

Inequality operator.

Parameters

iter	Iterator to compare

Returns

Whether not equal

operator!=() [2/2]

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

inlineinherited

Check inequality with another iterator.

Parameters

oth	Other iterator to check against.

Returns

Whether inequal.

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++() [1/2]

IterType& operator++ ( )

inline

Pre increment operator.

Same as next().

Returns

This

operator++() [2/2]

IterType operator++ ( int  )

inline

Post increment operator.

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

Returns

Iterator copy before increment

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/6]

IterType& operator= ( const IterType &  src )

inline

Copy/Assignment operator to copy from source iterator.

Parameters

src	Source iterator to copy

Returns

This

operator=() [2/6]

IterType& operator= ( const IterBaseType &  src )

inline

Copy/Assignment operator to copy from source iterator.

Parameters

src	Source iterator to copy

Returns

This

operator=() [3/6]

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/6]

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/6]

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/6]

IterType& operator= ( IteratorPos  pos )

inline

Assignment operator to set position.

Parameters

pos	Position to set, either iterFIRST or iterEND

Returns

This

operator==() [1/2]

bool operator== ( const IterBaseType &  iter ) const

inlineinherited

Equality operator.

Parameters

iter	Iterator to compare

Returns

Whether equal

operator==() [2/2]

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

inlineinherited

Check equality with another iterator.

Parameters

oth	Other iterator to check against.

Returns

Whether equal.

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