Iterator< Item > Class Template Reference

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

#include <Iterator.hpp>

Inheritance diagram for Iterator< Item >:

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.

virtual void first ( )

pure virtual

Method that initializes the iteration.

Implemented in IteratorAdaptor< T1, T2, Adaptor >, CompositeIterator< Item >, STLIterator< Container, Type >, STLIterator< std::vector< Type >, Type >, STLIterator< std::list< Type >, Type >, FilterIterator< Item, Filter >, CancellableIterator< Item >, TruncateIterator< Item >, CompoundIterator< T1, T2, Update >, SubjectIterator< Item >, SubjectIterator< Type >, PairedIterator< T1, T2 >, BankFasta::Iterator, BankBinary::Iterator, IteratorFile< Item >, ProductIterator< T1, T2 >, TokenizerIterator, and NullIterator< Item >.

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 >.

virtual bool isDone ( )

pure virtual

Method telling whether the iteration is finished or not.

Returns

true if iteration is finished, false otherwise.

Implemented in IteratorAdaptor< T1, T2, Adaptor >, CompositeIterator< Item >, STLIterator< Container, Type >, STLIterator< std::vector< Type >, Type >, STLIterator< std::list< Type >, Type >, FilterIterator< Item, Filter >, CancellableIterator< Item >, TruncateIterator< Item >, CompoundIterator< T1, T2, Update >, SubjectIterator< Item >, SubjectIterator< Type >, PairedIterator< T1, T2 >, BankFasta::Iterator, ProductIterator< T1, T2 >, BankBinary::Iterator, IteratorFile< Item >, TokenizerIterator, and NullIterator< Item >.

virtual Item& item ( )

pure virtual

Method that returns the current iterated item. Note that the returned type is the template type.

Returns

the current item in the iteration.

Implemented in IteratorAdaptor< T1, T2, Adaptor >, CompositeIterator< Item >, STLIterator< Container, Type >, STLIterator< std::vector< Type >, Type >, STLIterator< std::list< Type >, Type >, FilterIterator< Item, Filter >, CancellableIterator< Item >, TruncateIterator< Item >, CompoundIterator< T1, T2, Update >, SubjectIterator< Item >, SubjectIterator< Type >, PairedIterator< T1, T2 >, BankFasta::Iterator, ProductIterator< T1, T2 >, BankBinary::Iterator, IteratorFile< Item >, TokenizerIterator, and NullIterator< Item >.

void iterate ( const Functor &  f )

inline

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

virtual void next ( )

pure virtual

Method that goes to the next item in the iteration.

Returns

status of the iteration

Implemented in IteratorAdaptor< T1, T2, Adaptor >, CompositeIterator< Item >, STLIterator< Container, Type >, STLIterator< std::vector< Type >, Type >, STLIterator< std::list< Type >, Type >, FilterIterator< Item, Filter >, CancellableIterator< Item >, TruncateIterator< Item >, CompoundIterator< T1, T2, Update >, SubjectIterator< Item >, SubjectIterator< Type >, PairedIterator< T1, T2 >, BankFasta::Iterator, BankBinary::Iterator, ProductIterator< T1, T2 >, IteratorFile< Item >, TokenizerIterator, and NullIterator< 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:

• /builds/workspace/publish-doc-api-gitlab/gatb-core/src/gatb/tools/designpattern/api/Iterator.hpp