gatb.core-API-1.4.2
Iterator< Item > Class Template Referenceabstract

Definition of the Design Pattern Iterator interface. More...

#include <Iterator.hpp>

Inheritance diagram for Iterator< Item >:
Inheritance graph

Public Member Functions

virtual void first ()=0
 
virtual void next ()=0
 
virtual bool isDone ()=0
 
virtual Item & item ()=0
 
Item * operator-> ()
 
Item & operator* ()
 
template<typename Functor >
void iterate (const Functor &f)
 
virtual void setItem (Item &i)
 
bool get (std::vector< Item > &current)
 
virtual void reset ()
 
virtual void finalize ()
 
virtual std::vector< Iterator< Item > * > getComposition ()
 
- Public Member Functions inherited from SmartPointer
void use ()
 
void forget ()
 
- Public Member Functions inherited from ISmartPointer
virtual ~ISmartPointer ()
 

Additional Inherited Members

- Protected Member Functions inherited from SmartPointer
 SmartPointer ()
 
virtual ~SmartPointer ()
 

Detailed Description

template<class Item>
class gatb::core::tools::dp::Iterator< Item >

Definition of the Design Pattern Iterator interface.

The Iterator concept is here reified as a template class that knows how to iterate some set of objects.

Actually, the interface has two ways for iterating instances: 1- the 'classic' one in terms of Iterator Design Pattern (see first/next/isDone methods) 2- a callback way (see 'iterate' methods) where some client provides a callback that will be called for each object

There may be good reasons for using one way or another. For instance, the first one may be easier to use by clients (no extra method to be defined) but may be less efficient because more methods calls will be carried out.

Note that 'iterate' has great subclassing potentiality; by default, its implementation relies on first/isDone/next/currentItem methods and so can't be faster that the 'classic' way. But specific implementations of Iterator may implement 'iterate' directly by using inner state of the class, and so without call to first/isDone/next/currentItem methods.

Note that for optimization point of view, an algorithm prefers to use the 'iterate' way with optimized implementations.

Sample of use:

dp::Iterator<MyType*>* it = new MyIterator ();
for (it->first(); ! it->isDone(); it->next() )
{
// retrieve the current item of some type
MyType* item = it->item ();
}

A remark on the STL: the Standard Template Library provides also the iterator concept. For instance, one could write:

std::list<MyType*> l;
// we suppose here that we add some items to the list.
for (std::list<MyType*>::iterator it = l.begin(); it != l.end(); it++)
{
// retrieve the current item of some type
MyType* item = *it;
}

We can see the following differences with our own iterator.

  • the iteration loop with the STL needs to know the iterated list, through the beginning iterator 'l.begin()' and the ending iterator 'l.end()'. In our case, we don't have any reference of the iterated container, we can see only a reference on the iterator itself.
  • the iteration loop with the STL makes apparent the actual type of the container ('list' in the example), which is not the case for our iterator, where we can see only the type of the iterated items.
  • the STL iterators can only iterate contents of containers, ie. some items already in memory. Our iterator concept is more general because it can iterate items that it builds on the fly, without having the whole items mounted in memory. A typical use is the parsing of a huge FASTA database (say 8 GBytes for instance). With a STL iterator, we should have the whole sequences lying in some containers before iterating them; with our iterator, it is enough to know a sequence at a given time. Note however that clients of such iterators must not reference a sequence that is transient by nature. In such a case, clients have to copy, if needed, the iterated sequence for some local work.

In brief, our iterator encapsulates more information that the STL iterator, allows to iterate potential containers (versus actual containers) and may be easier to use.

Moreover, we can use our iterator as a basis for other ways for iteration.

note (GR): this iterator system looks like the range of C++11, now that we use C++11, we could switch to range:

for ( MyType elem : range ) { // use elem }

it has the same benefits as the listed benefits of the Iterator class, IMHO

Member Function Documentation

virtual void finalize ( )
inlinevirtual

Method that may be called when an iteration is done. Does nothing by default.

bool get ( std::vector< Item > &  current)
inline

Retrieve some iterated items in a vector. NOTE: In general, this method should be protected against concurrent accesses (IteratorCommand::execute)

Parameters
[in]current: vector to be filled with iterated items. May be resized if not enough items available
Returns
true if the iteration is not finished, false otherwise.
virtual std::vector<Iterator<Item>*> getComposition ( )
inlinevirtual

Get a vector holding the composite structure of the iterator.

Reimplemented in CompositeIterator< Item >, SubjectIterator< Item >, and SubjectIterator< Type >.

void iterate ( const Functor &  f)
inline

Another way to iterate: push model, ie a functor is called for each item.

Item& operator* ( )
inline

Operator overload as a shortcut for the 'item' method.

Item* operator-> ( )
inline

Operator overload as a shortcut for the 'item' method.

virtual void reset ( )
inlinevirtual

Reset the iterator.

Reimplemented in SubjectIterator< Item >, and SubjectIterator< Type >.

virtual void setItem ( Item &  i)
inlinevirtual

Get a reference on the object to be configured as the currently iterated item.

Parameters
[in]i: object to be referred.

Reimplemented in CompositeIterator< Item >, SubjectIterator< Item >, and SubjectIterator< Type >.


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