javautils.collections
Class Unfold

java.lang.Object
  |
  +--javautils.collections.Unfold

public abstract class Unfold

extends java.lang.Object

Template method for unfolding, or generating, a collection.

Unfolding is related to external iterators like the Iterator-interface of the Java Collections Framework. While an external iterator returns elements one-by-one, an unfold produces the complete collection of elements.

Unlike the Iterator-interface of the Java Collections Framework, this template method for unfolding collections clearly separates non-side-effecting queries and side-effecting commands. As a consequence, it can be less error prone to write an unfold than it is to write an iterator.

Why should I use an unfold instead of a simple loop?

Because an unfold immediately tells that the intention is to produce a new collection or a sequence of elements. A loop only tells that the code performs iteration, but the intention behind the iteration is not immediately obvious from a loop.

Example: Generating integers

The following example method creates an iterator that generates integers in a given range.

 public static Iterator iteratorForIntegers(final int min,
                                            final int max) {
   return new Unfold() {
       int next = min;

       protected boolean more() { return next <= max; }
       protected Object value() { return new Integer(next); }
       protected void advance() { ++next; }
     }.unfoldAsIterator();
 }
 

Constructor Summary

Unfold()

Method Summary

protected abstract void	advance() Advances the internal state of the generator by using side-effects.
protected void	init() Called once before other methods to initialize the unfold.
protected abstract boolean	more() True if and only if there are more elements to generate.
java.util.List	unfold() return unfoldTo(new ArrayList());
java.util.Iterator	unfoldAsIterator() An iterator that generates the same sequence of elements.
java.util.Map	unfoldMap() return unfoldTo(new HashMap());
java.util.List	unfoldRight() return unfoldRightTo(new LinkedList());
java.util.List	unfoldRightTo(java.util.LinkedList to) init(); while (more()) { to.addFirst(value()); advance(); } return to;
java.util.Collection	unfoldTo(java.util.Collection to) init(); while (more()) { to.add(value()); advance(); } return to;
java.util.List	unfoldTo(java.util.List to) return (List)unfoldTo((Collection)to);
java.util.Map	unfoldTo(java.util.Map to) init(); while (more()) { Map.Entry entry = (Map.Entry)value(); to.put(entry.getKey(), entry.getValue()); advance(); } return to;
java.util.Set	unfoldTo(java.util.Set to) return (Set)unfoldTo((Set)to);
protected abstract java.lang.Object	value() The element to be added to the generated list.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Unfold

public Unfold()

Method Detail

init

protected void init()

Called once before other methods to initialize the unfold.

more

protected abstract boolean more()

True if and only if there are more elements to generate. This method should not have side-effects.

value

protected abstract java.lang.Object value()

The element to be added to the generated list. This method should not have side-effects.

advance

protected abstract void advance()

Advances the internal state of the generator by using side-effects.

unfold

public final java.util.List unfold()

 return unfoldTo(new ArrayList());
 

unfoldMap

public final java.util.Map unfoldMap()

 return unfoldTo(new HashMap());
 

unfoldTo

public final java.util.Collection unfoldTo(java.util.Collection to)

 init();
 while (more()) {
   to.add(value());
   advance();
 }
 return to;
 

unfoldTo

public final java.util.Map unfoldTo(java.util.Map to)

 init();
 while (more()) {
   Map.Entry entry = (Map.Entry)value();
   to.put(entry.getKey(), entry.getValue());
   advance();
 }
 return to;
 

unfoldTo

public final java.util.List unfoldTo(java.util.List to)

 return (List)unfoldTo((Collection)to);
 

unfoldTo

public final java.util.Set unfoldTo(java.util.Set to)

 return (Set)unfoldTo((Set)to);
 

unfoldRight

public final java.util.List unfoldRight()

 return unfoldRightTo(new LinkedList());
 

unfoldRightTo

public final java.util.List unfoldRightTo(java.util.LinkedList to)

 init();
 while (more()) {
   to.addFirst(value());
   advance();
 }
 return to;
 

unfoldAsIterator

public final java.util.Iterator unfoldAsIterator()

An iterator that generates the same sequence of elements. The returned iterator will not support the remove-operation.