Iterators

Each container object in Olena like site sets or images have iterators. The iteration mechanism for images is directly derived from the mechanism for site sets.

There are usually three kinds:

• fwd_iter, depends on the container,
• bkd_iter, iterates like forward but to the opposite way,
• iter, usually the same as fwd_iter. It is guaranteed to iterate all over the elements.

Every iterable object have these three kinds of iterator. There are all bidirectional containers. Whatever the iterator used, the basic iterator has the only property of browsing every site once.

The iterator type name depends on the data pointed by it:

Data type	Iterator Names
Site	fwd_piter, bkd_piter, piter
Value	fwd_viter, bkd_viter, viter
Neighboors	fwd_niter, bkd_niter, niter

As you may have noticed, according to the data type, the word “iter” is prefixed by the usual name variable used for that data type. Sites variables are usually called “p” so the proper iterator is “typepiter”. (See the foreword)

An iterator has the following interface:

Return Type	Name	Arguments	Const	Comments
void	start	-	-
void	next	-	-
bool	is_valid	-	-	Return false if created with the default constructor and not associated to a proper container.

Example of different forward iterations:

• box2d: from top to bottom then from left to right.
• p_array<point2d>: from left to right.

A for_all() macro is available to iterate over all the sites:

  box2d b(3, 2);
  mln_piter_(box2d) p(b);

  for_all(p)
    std::cout << p; //prints every site coordinates.

Output:

(0,0)(0,1)(1,0)(1,1)(2,0)(2,1)

Note that when you declare an iterator, prefer using the “mln_*iter” macros. They resolve the iterator type automatically from the given container type passed as parameter. These macros can be used with any container like images or site sets.

Here follow an example with the implemantions of the most basic routines which use the for_all() loop: data::fill() and data::paste().

template <typename I>
void fill(I& ima, mln_value(I) v)
{
  mln_piter(I) p(ima.domain());
  for_all(p)
    ima(p) = v;
}

template <typename I, typename J>
void paste(const I& data, J& dest)
{
  mln_piter(I) p(data.domain());
  for_all(p)
  dest(p) = data(p);
}

Important note: macros for iterators exist in two versions: “mln_*iter” and “mln_*iter_”. The difference is that the first version must be used in templated function whereas the second one must be used in non templated functions.

If you want a list of all the macros available in Olena, please refert to section Useful macros .