IteratorBi< T > Class Template Reference

#include <evo/impl/iter.h>

Inheritance diagram for IteratorBi< T >:

Detailed Description

template<class T>
class evo::IteratorBi< T >

Bidirectional iterator.

Used to iterate through container items.

• Bidirectional iterators support forward and reverse 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/last/end position using operator=(IteratorPos):

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

• Increment to move to next item:

  ++iter;
  iter++;

• Decrement to move to previous 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 in order and then in reverse)
    for (List<int>::Iter iter(list); 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); 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 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
• Bidirectional 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;

Public Types
typedef IteratorBi< const T >	Const
	Bidirectional 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 IteratorBi< T >	IterType
	Iterator type. More...
typedef IteratorBase< T >::Key	Key
	Iterator key type. More...
typedef IteratorBi< typename RemoveConst< T >::Type >	Mutable
	Bidirectional 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
	IteratorBi ()
	Constructor. More...
	IteratorBi (T &obj)
	Constructor. More...
	IteratorBi (T &obj, IteratorPos pos)
	Constructor setting position. More...
	IteratorBi (T &obj, const Key &key, Item *data)
	Constructor. More...
	IteratorBi (const IterType &src)
	Copy constructor. More...
	IteratorBi (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...
IterType &	operator-- ()
	Pre decrement operator. More...
IterType	operator-- (int)
	Post decrement 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
	IteratorBi (T *obj)
	Constructor (used internally). More...
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	prev ()
	Go to previous item. 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 IteratorBi<const T> Const

Bidirectional 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 IteratorBi<T> IterType

Iterator type.

Key

typedef IteratorBase<T>::Key Key

Iterator key type.

Mutable

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

Bidirectional 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

IteratorBi() [1/7]

IteratorBi ( )

inline

Constructor.

This sets empty iterator at end.

IteratorBi() [2/7]

IteratorBi ( T &  obj )

inlineexplicit

Constructor.

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

Parameters

obj	Container object for iterator

IteratorBi() [3/7]

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

IteratorBi() [4/7]

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

inline

Constructor.

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

Parameters

obj	Container object to iterate through
key	Iterator key to set
data	Iterator data pointer to set

IteratorBi() [5/7]

IteratorBi ( const IterType &  src )

inline

Copy constructor.

Parameters

src	Source iterator to copy.

IteratorBi() [6/7]

IteratorBi ( const IterBaseType &  src )

inline

Copy constructor.

Parameters

src	Source iterator to copy.

IteratorBi() [7/7]

IteratorBi ( T *  obj )

inlineexplicitprotected

Constructor (used internally).

Only initializes object pointer.

Parameters

obj	Pointer to container objct.

Member Function Documentation

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

last()

bool last ( )

inlineprotected

Go to last item.

Returns

Whether last item was found (false if empty).

next()

bool next ( )

inlineprotectedinherited

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

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

IterType& operator-- ( )

inline

Pre decrement operator.

Same as prev().

Returns

This.

operator--() [2/2]

IterType operator-- ( int  )

inline

Post decrement operator.

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

Returns

Iterator copy before decrement.

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, iterLAST, 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.

prev()

bool prev ( )

inlineprotected

Go to previous item.

Returns

Whether previous 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