Falcon::Sequence Class Reference

Abstract sequence class. More...

#include <sequence.h>

Inheritance diagram for Falcon::Sequence:

Inheritance graph
[legend]

List of all members.

Public Member Functions

virtual void append (const Item &data)=0
 Append an item at the end of the sequence.
virtual const Itemback () const =0
 Returns the first element of the sequence.
virtual void clear ()=0
 Removes all the items in the sequence.
virtual void comprehension (VMachine *vm, const Item &compounder, const Item &filter)
 Appends to a sequence comprehension.
virtual bool empty () const =0
 Tells if the series is empty.
virtual const Itemfront () const =0
 Returns the first element of the sequence.
virtual void gcMark (uint32 gen)
void invalidateAllIters ()
 Invalidate all the iterators.
void invalidateAnyOtherIter (Iterator *iter)
 Invalidate all the iterators but one.
virtual void invalidateIteratorOnCriterion () const
 Disposes all the iterators matching a given criterion.
virtual bool isDictionary () const
 Mark this class as a dictionary based sequence.
virtual bool isSequence () const
 Mark this class as a sequence.
virtual bool onCriterion (Iterator *elem) const
 Criterion called back by disposeIteratorOnCriterion().
Garbageableowner ()
void owner (Garbageable *owner)
 The sequence may be bound to an object.
virtual void prepend (const Item &data)=0
 Prepend an item at the beginning of the sequence.
 Sequence ()
virtual ~Sequence ()

Protected Member Functions

virtual void copyIterator (Iterator &tgt, const Iterator &source) const
 Copy an iterator so that the two points to the same item.
virtual void disposeIterator (Iterator &tgt) const
 Called back to destroy deep data that may be associated with an iterator.
virtual bool equalIterator (const Iterator &first, const Iterator &second) const =0
virtual void erase (Iterator &iter)=0
 Deletes the element at position indicated by the iterator.
virtual ItemgetCurrent (const Iterator &iter)=0
virtual ItemgetCurrentKey (const Iterator &iter)=0
virtual void getIterator (Iterator &tgt, bool tail=false) const
 Gets an Iterator valid for this sequence.
virtual bool hasCurrent (const Iterator &iter) const =0
virtual bool hasNext (const Iterator &iter) const =0
virtual bool hasPrev (const Iterator &iter) const =0
virtual void insert (Iterator &iter, const Item &data)=0
 Inserts an element in a position indicated by the iterator.
virtual bool next (Iterator &iter) const =0
virtual bool prev (Iterator &iter) const =0

Protected Attributes

Iteratorm_iterList

Friends

class Iterator


Detailed Description

Abstract sequence class.

A sequence is a special user data which is used as internal mean by sequence oriented falcon classes. It may be also used by extension code to create special lists or generator objects.

The sequence must be able to create an Iterator object for itself. The Iterator will be used internally by the VM or eventually wrapped in a Falcon iterator object and then given to the script.


Constructor & Destructor Documentation

Falcon::Sequence::Sequence (  )  [inline]

virtual Falcon::Sequence::~Sequence (  )  [inline, virtual]


Member Function Documentation

virtual void Falcon::Sequence::append ( const Item data  )  [pure virtual]

virtual const Item& Falcon::Sequence::back (  )  const [pure virtual]

Returns the first element of the sequence.

If the sequence has not an underlying storage, it may generate a temporary item, as the item is immediately copied into some destination by the caller.

This method is never used by the engine to modify the underlying item.

Guarantees are taken so that this method is never called when v_empty() returns false.

Returns:
a valid reference to the first item of the sequence

Implemented in Falcon::CoreTable, Falcon::GeneratorSeq, Falcon::ItemArray, Falcon::ItemList, Falcon::ItemSet, Falcon::LinearDict, Falcon::PageDict, Falcon::PoopSeq, Falcon::RangeSeq, and Falcon::Tokenizer.

virtual void Falcon::Sequence::clear (  )  [pure virtual]

virtual void Falcon::Sequence::comprehension ( VMachine vm,
const Item compounder,
const Item filter 
) [virtual]

Appends to a sequence comprehension.

Just create the target sequence, and then use this function to Fulfill compounds.

Note:
DON'T PASS directly parameter pointers, as the stack may be destroyed in the meanwhile. Instead, pass copies of the items.
Parameters:
vm The virtual machine where to perform atomic calls.
compounder a range, a sequence or a generator function providing a sequence of data.
filter an optional filter function returning true to accept elemnts, false to discard them pass nil if none.

virtual void Falcon::Sequence::copyIterator ( Iterator tgt,
const Iterator source 
) const [protected, virtual]

Copy an iterator so that the two points to the same item.

The source iterator may point to the past-end element, but must not be invalid.

Note:
The base version of this function just adds the iterator to the iterator list; it MUST be called by all the implementations.

Reimplemented in Falcon::CoreSlot, Falcon::CoreTable, Falcon::GeneratorSeq, Falcon::ItemArray, Falcon::ItemList, Falcon::ItemSet, Falcon::LinearDict, Falcon::PageDict, Falcon::PoopSeq, Falcon::RangeSeq, and Falcon::Tokenizer.

virtual void Falcon::Sequence::disposeIterator ( Iterator tgt  )  const [protected, virtual]

Called back to destroy deep data that may be associated with an iterator.

This method is called back at iterator destructor to clear deep data that the sequence may have stored in the iterator.

After this call, the iterator is invalidated (if correctly found in the list).

Note:
The base class version disengage the iterator from the iterator list and invalidates it. It normally shouldn't be overloaded by subclasses, as the final memory cleaning from a deep iterator, if needed, must be separately provided via the Iterator::deletor() interface.

Reimplemented in Falcon::CoreSlot.

virtual bool Falcon::Sequence::empty (  )  const [pure virtual]

Tells if the series is empty.

Returns:
false if there is at least one valid item in the series, false otherwise.

Implemented in Falcon::CoreTable, Falcon::GeneratorSeq, Falcon::ItemArray, Falcon::ItemList, Falcon::ItemSet, Falcon::LinearDict, Falcon::PageDict, Falcon::PoopSeq, Falcon::RangeSeq, and Falcon::Tokenizer.

virtual bool Falcon::Sequence::equalIterator ( const Iterator first,
const Iterator second 
) const [protected, pure virtual]

virtual void Falcon::Sequence::erase ( Iterator iter  )  [protected, pure virtual]

Deletes the element at position indicated by the iterator.

The implementation must check that the iterator is a valid iterator created by this object and pointing to a valid position.

Deletion happens at given position, shifting all the remaining elements backward; after a successful erase, the iterator must point to the element that was previously next in the series, or must be invalidated if the removed element was the last.

If the sequence is empty or the iterator is invalid, an AccessError must be thrown. If the iterator is referencing another sequence, a CodeError must be thrown.

Parameters:
iter an iterator (possibly invalid or not generated by this class).
Returns:
true if the iterator was valid for this object.

Implemented in Falcon::CoreTable, Falcon::GeneratorSeq, Falcon::ItemArray, Falcon::ItemList, Falcon::ItemSet, Falcon::LinearDict, Falcon::PageDict, Falcon::PoopSeq, Falcon::RangeSeq, and Falcon::Tokenizer.

virtual const Item& Falcon::Sequence::front (  )  const [pure virtual]

Returns the first element of the sequence.

If the sequence has not an underlying storage, it may generate a temporary item, as the item is immediately copied into some destination by the caller.

Guarantees are taken so that this method is never called when v_empty() returns false.

Returns:
a valid reference to the first item of the sequence

Implemented in Falcon::CoreTable, Falcon::GeneratorSeq, Falcon::ItemArray, Falcon::ItemList, Falcon::ItemSet, Falcon::LinearDict, Falcon::PageDict, Falcon::PoopSeq, Falcon::RangeSeq, and Falcon::Tokenizer.

virtual void Falcon::Sequence::gcMark ( uint32  gen  )  [virtual]

virtual Item& Falcon::Sequence::getCurrent ( const Iterator iter  )  [protected, pure virtual]

virtual Item& Falcon::Sequence::getCurrentKey ( const Iterator iter  )  [protected, pure virtual]

virtual void Falcon::Sequence::getIterator ( Iterator tgt,
bool  tail = false 
) const [protected, virtual]

Gets an Iterator valid for this sequence.

If you need an iterator as a pointer or in the target stack, use Iterator( Sequence*, bool) instead.

The iterator constructor calls back this method to be configured.

It is possible to call this method thereafter to reset the iterator, even if it's gone invalid.

However, it is not legal to call this method with an iterator coming from another sequence; this will cause the program to throw a CodeError.

Note:
The base version of this function just adds the iterator to the iterator list; it MUST be called by all the implementations.
Parameters:
An Iterator to be set.
tail if false, get an iterator to the first element, else get an iterator to the last element.

Reimplemented in Falcon::CoreSlot, Falcon::CoreTable, Falcon::GeneratorSeq, Falcon::ItemArray, Falcon::ItemList, Falcon::ItemSet, Falcon::LinearDict, Falcon::PageDict, Falcon::PoopSeq, Falcon::RangeSeq, and Falcon::Tokenizer.

Referenced by Falcon::Iterator::Iterator().

virtual bool Falcon::Sequence::hasCurrent ( const Iterator iter  )  const [protected, pure virtual]

virtual bool Falcon::Sequence::hasNext ( const Iterator iter  )  const [protected, pure virtual]

virtual bool Falcon::Sequence::hasPrev ( const Iterator iter  )  const [protected, pure virtual]

virtual void Falcon::Sequence::insert ( Iterator iter,
const Item data 
) [protected, pure virtual]

Inserts an element in a position indicated by the iterator.

The implementation must check that the iterator is a valid iterator created by this object and pointing to a valid position.

Insertion happens at given position, shifting all the remaining elements forward; after a successful insert, the iterator must point to the newly inserted element, and the previously current element is found safely in the next() position of the iterator.

Valid iterators (generated by this owner) pointing to invalid positions must be treated as pointing to last-past-one element; insertion causes append on tail, and at return they must be valid and point to the last valid element (the one just inserted).

If the iterator cannot be used, for example because their owner is not this item, this method will raise a CodeError.

Parameters:
iterator an iterator.
data the item to be inserted
Returns:
true if the iterator was valid for this object.

Implemented in Falcon::CoreTable, Falcon::GeneratorSeq, Falcon::ItemArray, Falcon::ItemList, Falcon::ItemSet, Falcon::LinearDict, Falcon::PageDict, Falcon::PoopSeq, Falcon::RangeSeq, and Falcon::Tokenizer.

void Falcon::Sequence::invalidateAllIters (  ) 

Invalidate all the iterators.

This disengage all the iterators from this sequence. Used when all the sequence becomes invalid.

Iterators are not destroyed (they belong to their owners), but they become invalid and stop pointing to this sequence.

void Falcon::Sequence::invalidateAnyOtherIter ( Iterator iter  ) 

Invalidate all the iterators but one.

This method invalidate all the iterators except the one provided. This is useful in sequence where destructive operations on one iterator (i.e. erase) cause all the other unsupported iterators to become invalid.

virtual void Falcon::Sequence::invalidateIteratorOnCriterion (  )  const [virtual]

Disposes all the iterators matching a given criterion.

Useful to dispose all the iterators in a sequence that match a certain criterion, as i.e. pointing to an element being deleted.

The criterion is provided by subclasses via the onCriterion() callback.

virtual bool Falcon::Sequence::isDictionary (  )  const [inline, virtual]

Mark this class as a dictionary based sequence.

Reimplemented in Falcon::ItemDict.

virtual bool Falcon::Sequence::isSequence (  )  const [inline, virtual]

Mark this class as a sequence.

Reimplemented from Falcon::FalconData.

virtual bool Falcon::Sequence::next ( Iterator iter  )  const [protected, pure virtual]

virtual bool Falcon::Sequence::onCriterion ( Iterator elem  )  const [inline, virtual]

Criterion called back by disposeIteratorOnCriterion().

Return true to remove this iterator, false to let it alive. Disposed iterators are removed from the iterator list of this sequence and invalidated.

Reimplemented in Falcon::ItemArray, Falcon::ItemList, Falcon::ItemSet, and Falcon::LinearDict.

Garbageable* Falcon::Sequence::owner (  )  [inline]

void Falcon::Sequence::owner ( Garbageable owner  )  [inline]

The sequence may be bound to an object.

If the sequence is bound with a falcon script level object, when it receives a gcMark() request, for example, from an iterator referencing it, the related garbageable must be flagged.

virtual void Falcon::Sequence::prepend ( const Item data  )  [pure virtual]

virtual bool Falcon::Sequence::prev ( Iterator iter  )  const [protected, pure virtual]


Friends And Related Function Documentation

friend class Iterator [friend]


Member Data Documentation

Iterator* Falcon::Sequence::m_iterList [mutable, protected]


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

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