Falcon::Iterator Class Reference

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

#include <iterator.h>

Inheritance diagram for Falcon::Iterator:

Inheritance graph
[legend]

List of all members.

Classes

union  t_position_holder

Public Types

typedef void(* t_deletor_func )(Iterator *)

Public Member Functions

virtual FalconDataclone () 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)
ItemgetCurrent () const
 Must be called after an isValid() check.
ItemgetCurrentKey () 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)
IteratornextIter () const
void position (int64 pos)
int64 position () const
bool prev ()
 Retreat to the previous item.
void sequence (Sequence *s)
Sequencesequence () const
virtual ~Iterator ()


Detailed Description

Base abstract class for generic Item sequence/collection iterators.

Iterators and sequences cooperate so that:

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


Constructor & Destructor Documentation

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

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]

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:

Generated on Mon Oct 19 10:11:37 2009 for Falcon_Core by  doxygen 1.5.8