Falcon::Iterator Class Reference

Base abstract class for generic Item sequence/collection iterators. More...

#include <iterator.h>

Inheritance diagram for Falcon::Iterator:

[legend]

List of all members.

Classes
union	t_position_holder
Public Types
typedef void(*	t_deletor_func )(Iterator *)
Public Member Functions
virtual FalconData *	clone () const
void	data (void *dt)
void *	data () const
t_deletor_func	deletor () const
void	deletor (t_deletor_func f)
	Sets a deep deletor for this iterator.
bool	equal (const Iterator &other) const
void	erase ()
	Erase an element pointed by this iterator.
virtual void	gcMark (uint32 mark)
Item &	getCurrent () const
	Must be called after an isValid() check.
Item &	getCurrentKey () const
	Must be called after an isValid() check.
bool	hasCurrent () const
	True if this iterator has a current element.
bool	hasNext () const
bool	hasPrev () const
void	insert (const Item &item)
	Insert an item at current position in a non-dictionary sequence.
void	invalidate ()
	Turns this in an invalid iterator.
bool	isOwner (void *collection) const
bool	isValid () const
	Iterator (const Iterator &other)
	Iterator (Sequence *owner, bool tail=false)
bool	next ()
	Advance to the next item.
void	nextIter (Iterator *n)
Iterator *	nextIter () const
void	position (int64 pos)
int64	position () const
bool	prev ()
	Retreat to the previous item.
void	sequence (Sequence *s)
Sequence *	sequence () const
virtual	~Iterator ()

---

Detailed Description

Base abstract class for generic Item sequence/collection iterators.

Iterators and sequences cooperate so that:

• The iterator provides a common non-abstract non-virtual interface to access sequentially sequences of different nature.
• The underlying sequence provides the virtual functionalities needed to access itself and receive orders from its own iterators.

A common usage pattern may be:

   // ItemArray() supports the sequence interface.
   Sequence* seq = &some_item.asArray()->items();
   ...
   Iterator iter( seq ); // starts at begin.
   while( iter.hasCurrent() )   // while we have some element
   {
      Item& current = iter.getCurrent();
      // ... do something
      
      iter.next()
   }

Iterators support the FalconData interface, so they can be set directly as inner data for FalconObject (i.e. Falcon script level iterator instances), or be guarded by the garbage collector via the GCPointer garbage pointer shells.

In that case, instead of having iterators in the stack, it's possible to have them in the heap (allocated with "new").

Iterators can be deleted via a simple delete.

Iterators forward their gcMark() call to the sequence they are linked to, so if the sequence is part of a garbage sensible data (CoreArray, CoreObject, GCPointer etc.), the item stays alive untill all the iterators are gone.

If a sequence is autonomously destroyed (i.e. via an explicit delete on a non-garbage sensible data), all the iterators on that sequence are "invalidated".

Iterators are invalidated also when the sequence is changed so that the values of some or all iterators become no more valid (i.e. iterators to array or to paged maps).

Invalidated iterators do not point to any sequence anymore, and calling any of their member except for disposal or isValid() causes a crash.

Iterators are usually able to refer to the target sequence without the need for local structures. When this is not possible, their data member is filled with some structure specific iterator data, and their deletor() function is set to a function that can collect this deep reference data when the iterator is destroyed. As this function is totally independent from the source sequence, even deep iterators can be destroyed after their sequence has been destroyed, and they have been invalidated.

If the iterator is destroyed while still valid (i.e. because of stack unroll), the Sequence::disposeIterator() callback method of the owner sequence is called; this gives the sequence the chance to de-account the iterator (and it's usually done in the Sequence base class). The disposeIterator() callback must NEVER destroy deep data in the iterator, which is done by the deletor() callback as a separate step.

Note:

The Sequence-iterator pattern works well when there are a limited number of active iterator per sequence (1 to 3), which is a common practical usage in many cases. Avoid using an iterator-per-item strategy (i.e. back-referenced sequence items, able to delete themselves via an erase on their iterator).

---

Member Typedef Documentation

typedef void(* Falcon::Iterator::t_deletor_func)(Iterator *)

---

Constructor & Destructor Documentation

Falcon::Iterator::Iterator	(	Sequence *	owner,
		bool	tail = false
	)			[inline]

References Falcon::Sequence::getIterator().

Falcon::Iterator::Iterator

(

const Iterator &

other

)

[inline]

virtual Falcon::Iterator::~Iterator

(

)

[virtual]

---

Member Function Documentation

virtual FalconData* Falcon::Iterator::clone

(

)

const [virtual]

Implements Falcon::FalconData.

void Falcon::Iterator::data

(

void *

dt

)

[inline]

void* Falcon::Iterator::data

(

)

const [inline]

t_deletor_func Falcon::Iterator::deletor

(

)

const [inline]

void Falcon::Iterator::deletor

(

t_deletor_func

f

)

[inline]

Sets a deep deletor for this iterator.

Should be called by the Sequence::getIterator and Sequence::copyIterator re-implementations in case this iterator is given a deep data that must be deleted at termination.

If non-zero, this callback is called at iterator destruction.

bool Falcon::Iterator::equal

(

const Iterator &

other

)

const [inline]

References Falcon::Sequence::equalIterator(), fassert, and m_owner.

void Falcon::Iterator::erase

(

)

[inline]

Erase an element pointed by this iterator.

This erases the element in the sequence pointed by this iterator. the iterator is moved to the next element, or if this was the last element in the collection, it points to past-end.

The operation may or may not invalidate the other iterators on the sequence, depending on the nature of the sequecne; however, the iterator itself it's granted to stay valid.

References fassert.

virtual void Falcon::Iterator::gcMark

(

uint32

mark

)

[virtual]

Implements Falcon::FalconData.

Item& Falcon::Iterator::getCurrent

(

)

const [inline]

Must be called after an isValid() check.

References fassert.

Item& Falcon::Iterator::getCurrentKey

(

)

const [inline]

Must be called after an isValid() check.

Calling this on non-dictionary sequences will cause an AccessError to be thrown.

References fassert.

bool Falcon::Iterator::hasCurrent

(

)

const [inline]

True if this iterator has a current element.

Iterators past the last element (at end) are still valid, but they can't be used to access a current element.

bool Falcon::Iterator::hasNext

(

)

const [inline]

bool Falcon::Iterator::hasPrev

(

)

const [inline]

void Falcon::Iterator::insert

(

const Item &

item

)

[inline]

Insert an item at current position in a non-dictionary sequence.

Calling this on a dictionary sequence will cause an AccessError to be thrown.

The item is insert before the position to which the iterator points. If the iterator isValid() but not hasCurrent(), insertion is at past end (append).

After the insert, the iterator is not moved (still points to the same element).

References fassert.

void Falcon::Iterator::invalidate

(

)

[inline]

Turns this in an invalid iterator.

Notice that invalid iterators doesn't back-mark their owner.

bool Falcon::Iterator::isOwner

(

void *

collection

)

const [inline]

bool Falcon::Iterator::isValid

(

)

const [inline]

bool Falcon::Iterator::next

(

)

[inline]

Advance to the next item.

Returns:

false if the iterator couldn't be advanced (because invalid or at end).

References fassert.

void Falcon::Iterator::nextIter

(

Iterator *

n

)

[inline]

Iterator* Falcon::Iterator::nextIter

(

)

const [inline]

void Falcon::Iterator::position

(

int64

pos

)

[inline]

int64 Falcon::Iterator::position

(

)

const [inline]

bool Falcon::Iterator::prev

(

)

[inline]

Retreat to the previous item.

Returns:

false if the iterator couldn't be retreated (because invalid or at begin).

References fassert.

void Falcon::Iterator::sequence

(

Sequence *

s

)

[inline]

Sequence* Falcon::Iterator::sequence

(

)

const [inline]

---

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

• /home/gian/Progetti/falcon/core/include/falcon/iterator.h