JListIterator< T > Class Template Reference

#include <JListIterator.h>

Inheritance diagram for JListIterator< T >:

Public Member Functions
	JListIterator (const JList< T > &theList, const JListT::Position start=JListT::kStartAtBeginning, const JIndex index=0)
	JListIterator (JList< T > *theList, const JListT::Position start=JListT::kStartAtBeginning, const JIndex index=0)
virtual	~JListIterator ()
const JList< T > *	GetList () const
bool	GetList (JList< T > **obj) const
virtual bool	Prev (T *data, const JListT::Action move=JListT::kMove)=0
virtual bool	Next (T *data, const JListT::Action move=JListT::kMove)=0
bool	Prev (std::function< bool(const T &)> match, T *item)
bool	Next (std::function< bool(const T &)> match, T *item)
virtual void	SkipPrev (const JSize count=1)=0
virtual void	SkipNext (const JSize count=1)=0
virtual void	MoveTo (const JListT::Position newPosition, const JIndex index)
bool	AtBeginning () const
bool	AtEnd () const
JIndex	GetPrevItemIndex () const
JIndex	GetNextItemIndex () const
bool	GetPrevItemIndex (JIndex *i) const
bool	GetNextItemIndex (JIndex *i) const
virtual bool	SetPrev (const T &data, const JListT::Action move=JListT::kMove)=0
virtual bool	SetNext (const T &data, const JListT::Action move=JListT::kMove)=0
virtual bool	RemovePrev (const JSize count=1)=0
virtual bool	RemoveNext (const JSize count=1)=0
virtual bool	Insert (const T &data)=0
T	operator* () const
JListIterator< T > &	operator++ ()
bool	operator== (const JListIterator< T > &it) const

Protected Member Functions
	JListIterator (const JListIterator< T > &source)
JCursorPosition	GetCursor () const
void	SetCursor (const JCursorPosition pos)
virtual void	ListChanged (const JBroadcaster::Message &message)

Friends
class	JList< T >

Constructor & Destructor Documentation

JListIterator() [1/3]

template<class T >

JListIterator< T >::JListIterator	(	const JList< T > &	theList,
		const JListT::Position	start = JListT::kStartAtBeginning,
		const JIndex	index = 0
	)

                The List Iterator Class

An iterator provides an efficient, error-resistant way to loop through the elements of an JList:

JList<MyData>* myList = jnew JList<MyData>;
...
JListIterator<MyData> iterator(myList, kJIteratorStartAtBeginning);
MyData                item;

while(iterator.Next(&item))
{
    <do something with the item>
}

An iterator is robust in the face of insertions and deletions to the JList it is working on:

Each iterator has a current position called a "cursor". The cursor is always positioned at the start of the JList, at the end of the JList, or between two JList items. The cursor position is an ordinal from 0 to n, where n is the number of elements in the JList. The relationship of the cursor position to the JList index is illustrated below:

        +-----+-----+-----+-----+-----+-----+
index   |  1  |  2  |  3  |  4  |  5  |  6  |
        +-----+-----+-----+-----+-----+-----+
cursor  0     1     2     3     4     5     6

Position lets you specify an initial (or changed) cursor position. kJIteratorStartBefore puts the cursor just before the specified item (so Next() will fetch the item) while kJIteratorStartAfter puts it just after (so Prev() will fetch the item).

The operations Next() and Prev() fetch the item just after or the item just before the cursor, respectively, then increment or decrement the cursor. So a sequence of Next() calls will advance forward through an JList, while a sequence of Prev() calls will go backwards through the JList. You can change direction at any time.

If the cursor is positioned at the number of items in the JList and you call Next(), it will return FALSE. Likewise if the cursor is zero and you call Prev().

If the JList is deleted while the cursor is active, all further calls to Next() or Prev() will return FALSE and the cursor position will be fixed at 0.

Implementation notes:

An iterator is easily written as a JBroadcaster so the JList can notify the iterator when changes occur or when it is deleted. Unfortunately, this has the major drawback of creating two JBroadcasterLists each time an iterator is constructed. This is especially painful when iterators are used within ~JBroadcaster, because deleting memory should never allocate memory.

Alternatively, since each iterator is used by exactly one JList, we can construct a linked list of iterators headed in the JList. In order not to transfer the overhead of managing this list into JList, the iterators manage the list. Thus the iterator must be a friend of the JList. This is acceptable because the iterator can't exist without the JList.

JListIterator() [2/3]

template<class T >

JListIterator< T >::JListIterator	(	JList< T > *	theList,
		const JListT::Position	start = JListT::kStartAtBeginning,
		const JIndex	index = 0
	)

~JListIterator()

template<class T >

JListIterator< T >::~JListIterator ( )

virtual

JListIterator() [3/3]

template<class T >

JListIterator< T >::JListIterator ( const JListIterator< T > &  source )

protected

Member Function Documentation

AtBeginning()

template<class T >

bool JListIterator< T >::AtBeginning

(

)

const

Return true if iterator is positioned at the beginning of the list or if the list has been deleted.

AtEnd()

template<class T >

bool JListIterator< T >::AtEnd

(

)

const

Return true if iterator is positioned at the end of the list or if the list has been deleted.

GetCursor()

template<class T >

JCursorPosition JListIterator< T >::GetCursor ( ) const

protected

Return the current cursor position.

GetList() [1/2]

template<class T >

const JList< T > * JListIterator< T >::GetList

(

)

const

Return the current list for this iterator.

GetList() [2/2]

template<class T >

bool JListIterator< T >::GetList

(

JList< T > **

obj

)

const

GetNextItemIndex() [1/2]

template<class T >

JIndex JListIterator< T >::GetNextItemIndex

(

)

const

asserts that there is a next element

GetNextItemIndex() [2/2]

template<class T >

bool JListIterator< T >::GetNextItemIndex

(

JIndex *

i

)

const

Returns true if there is a next element.

GetPrevItemIndex() [1/2]

template<class T >

JIndex JListIterator< T >::GetPrevItemIndex

(

)

const

asserts that there is a previous element

GetPrevItemIndex() [2/2]

template<class T >

bool JListIterator< T >::GetPrevItemIndex

(

JIndex *

i

)

const

Returns true if there is a previous element.

Insert()

template<class T >

virtual bool JListIterator< T >::Insert ( const T &  data )

pure virtual

Implemented in JRunArrayIterator< JFont >, JArrayIterator< T >, JLinkedListIterator< T >, JRunArrayIterator< T >, and JArrayIterator< T * >.

ListChanged()

template<class T >

void JListIterator< T >::ListChanged ( const JBroadcaster::Message &  message )

protectedvirtual

Respond to changes in itsConstList and recursively tell the next iterator in the list to do the same. Assuming that only a handful of iterators are ever in a list, recursion should be safe.

Reimplemented in JBroadcasterMessageIterator< T >, JTaskIterator< T >, JArrayIterator< T >, JArrayIterator< T * >, JLinkedListIterator< T >, JRunArrayIterator< T >, and JRunArrayIterator< JFont >.

MoveTo()

template<class T >

void JListIterator< T >::MoveTo ( const JListT::Position  newPosition, const JIndex  index  )

virtual

Reimplemented in JLinkedListIterator< T >, JRunArrayIterator< T >, and JRunArrayIterator< JFont >.

Next() [1/2]

template<class T >

bool JListIterator< T >::Next	(	std::function< bool(const T &)>	match,
		T *	data
	)

Returns true if there is a next item that matches, fetching the item in the list and adjusting the iterator position to after the item. Otherwise returns false, and the position will be at the end of the list.

Next() [2/2]

template<class T >

virtual bool JListIterator< T >::Next ( T *  data, const JListT::Action  move = JListT::kMove  )

pure virtual

Implemented in JRunArrayIterator< JFont >, JArrayIterator< T * >, JArrayIterator< T >, JLinkedListIterator< T >, and JRunArrayIterator< T >.

operator*()

template<class T >

T JListIterator< T >::operator*

(

)

const

operator++()

template<class T >

JListIterator< T > & JListIterator< T >::operator++

(

)

operator==()

template<class T >

bool JListIterator< T >::operator==

(

const JListIterator< T > &

it

)

const

Prev() [1/2]

template<class T >

bool JListIterator< T >::Prev	(	std::function< bool(const T &)>	match,
		T *	data
	)

Returns true if there is a previous item that matches, fetching the item in the list and adjusting the iterator position to before the item. Otherwise returns false, and the position will be at the beginning of the list.

Prev() [2/2]

template<class T >

virtual bool JListIterator< T >::Prev ( T *  data, const JListT::Action  move = JListT::kMove  )

pure virtual

Implemented in JRunArrayIterator< JFont >, JArrayIterator< T * >, JArrayIterator< T >, JLinkedListIterator< T >, and JRunArrayIterator< T >.

RemoveNext()

template<class T >

virtual bool JListIterator< T >::RemoveNext ( const JSize  count = 1 )

pure virtual

Implemented in JArrayIterator< T >, JArrayIterator< T * >, JLinkedListIterator< T >, JRunArrayIterator< T >, and JRunArrayIterator< JFont >.

RemovePrev()

template<class T >

virtual bool JListIterator< T >::RemovePrev ( const JSize  count = 1 )

pure virtual

Implemented in JArrayIterator< T >, JArrayIterator< T * >, JLinkedListIterator< T >, JRunArrayIterator< T >, and JRunArrayIterator< JFont >.

SetCursor()

template<class T >

void JListIterator< T >::SetCursor ( const JCursorPosition  pos )

protected

Set the current cursor position.

SetNext()

template<class T >

virtual bool JListIterator< T >::SetNext ( const T &  data, const JListT::Action  move = JListT::kMove  )

pure virtual

Implemented in JRunArrayIterator< JFont >, JArrayIterator< T >, JLinkedListIterator< T >, JRunArrayIterator< T >, and JArrayIterator< T * >.

SetPrev()

template<class T >

virtual bool JListIterator< T >::SetPrev ( const T &  data, const JListT::Action  move = JListT::kMove  )

pure virtual

Implemented in JRunArrayIterator< JFont >, JArrayIterator< T >, JLinkedListIterator< T >, JRunArrayIterator< T >, and JArrayIterator< T * >.

SkipNext()

template<class T >

virtual void JListIterator< T >::SkipNext ( const JSize  count = 1 )

pure virtual

Implemented in JArrayIterator< T >, JArrayIterator< T * >, JLinkedListIterator< T >, JRunArrayIterator< T >, and JRunArrayIterator< JFont >.

SkipPrev()

template<class T >

virtual void JListIterator< T >::SkipPrev ( const JSize  count = 1 )

pure virtual

Implemented in JArrayIterator< T >, JArrayIterator< T * >, JLinkedListIterator< T >, JRunArrayIterator< T >, and JRunArrayIterator< JFont >.

Friends And Related Symbol Documentation

JList< T >

template<class T >

friend class JList< T >

friend

---

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

• libjcore/code/JListIterator.h
• libjcore/code/JListIterator.tmpl