iterator with pre-defined cycles count

[GoogleCodeExporter]

  /**
   * Returns an iterator that cycles {@code cycleCount} times over the
   * elements of {@code iterable} or until it is empty, that to occur first. 
   * <b>Warning:</b> If {@code cycleCount} has a negative value the resulting
   * iterator may produce an infinite loop. You should use an explicit
break, or
   * be certain that you will eventually remove all the elements.
   */
  public static <T> Iterator<T> cycle(final int cycleCount,
       final Iterable<T> iterable) {
    checkNotNull(iterable);
    return new Iterator<T>() {
      int cycles = cycleCount;
      Iterator<T> iterator = Iterators.emptyIterator();
      Iterator<T> removeFrom;

      public boolean hasNext() {
        if (!iterator.hasNext() && cycles-- != 0) {
          iterator = iterable.iterator();
        }
        return iterator.hasNext();
      }
      public T next() {
        if (!hasNext()) {
          throw new NoSuchElementException();
        }
        removeFrom = iterator;
        return iterator.next();
      }
      public void remove() {
        checkState(removeFrom != null,
            "no calls to next() since last call to remove()");
        removeFrom.remove();
        removeFrom = null;
      }
    };
  }

Original issue reported on code.google.com by jonhnnyw...@gmail.com on 23 Oct 2007 at 6:54

[GoogleCodeExporter]

Try out Iterables.concat(Collections.nCopies(n, iterable)).  Does it do what 
you want?

Original comment by kevin...@gmail.com on 23 Oct 2007 at 7:06

[GoogleCodeExporter]

Comment by jonhnnyweslley via email:

It does.
But it isn't intuitive.
Why don't use Iterators.cycle(n, iterable)

Adding this function don't requires duplicated code.
The original function Iterators.cycle(iterable) calls this:

public static <T> Iterator<T> cycle(final Iterable<T> iterable) {
  checkNotNull(iterable);
  return cycle(-1, iterable);
}

Original comment by kevin...@gmail.com on 23 Oct 2007 at 7:43

[GoogleCodeExporter]

The issue is not duplicated code. If we added your requested method, it would 
just
invoke the one-liner above. (And it would not accept a negative value.)

We do try to avoid one-liner convenience methods as much as we can. We usually 
only
make exceptions it fills *very* common need, so that the bit of syntactic sugar
really pays for itself.  Lists.newArrayList() is the quintessential example of 
this
exception, but of course that's not what we're looking at here.

You're absolutely right that the question we need to ask is whether it's 
intuitive to
one who is not deeply familiar with the libraries. And the answer is: no, it's 
not. 
But there are still a few possible solutions to that problem: adding a new 
one-liner
method is one of them; a documentation fix is another.

[You might notice that we have a method called Iterators.find(Iterator, 
Predicate)
which does nothing but call filter(iterator,predicate).next().  This is an 
example of
a method that shouldn't exist. :)  It has stayed around so far because its 
analogue
in Iterables is *slightly* more useful (find(i,p) instead of
filter(i,p).iterator().next()) and we want to maintain the parity of the two 
classes.]

Original comment by kevin...@gmail.com on 23 Oct 2007 at 7:57

[GoogleCodeExporter]

I believe the right fix for this issue is to add documentation to cycle() 
mentioning
how to cycle a limited number of times.

Original comment by kevin...@gmail.com on 2 Nov 2007 at 12:26

[GoogleCodeExporter]

I updated the Iterables.cycle documentation, as Kevin suggested. It will be in 
the
next release.

Original comment by jared.l....@gmail.com on 18 Jun 2008 at 8:43

[GoogleCodeExporter]

I updated the Iterables.cycle documentation, as Kevin suggested. It will be in 
the
next release.

Original comment by jared.l....@gmail.com on 18 Jun 2008 at 8:43

• Changed state: Fixed