Add exhaust() and extract() methods to Iterators and Iterables

[GoogleCodeExporter]

I propose to add two new methods exhaust() and extract() to both the
Iterators and Iterables utilities.

Iterators.exhaust() is used to eagerly remove all the remaing elements from
the passed-in Iterator and buffer/provide them on the returned instance.
This has two effects: (a) the original Iterator has finished iteration and
can thus no longer be used to modify the backing collection, and (b) the
backing collection will supposedly be empty and ready for reuse, all by the
time the method returns.

Iterables.exhaust() could do essentially the same (clearing the backing
collection, buffering/providing the elements in a new Iterable),
OR
it could return an Iterable wrapper that delegates to Iterators.exhaust()
on every call to iterator(), effectively allowing for an automatic
exhaustion of the backing collection, in case new elements will have been
added (I prefer this behaviour -- maybe we can have both).

The exhaust() method allows a client to conveniently clear and reuse its
collections BEFORE actually processing the elements. The cleared collection
may even recieve new elements within the same loop. It is also useful if
the processing of elements is expensive and you don't want to block the
collection. Today, you would have to create your own temporary storage,
which is sometimes cumbersome and even inefficient if you are only looking
for an Iterable.

Iterators.extract() is used to automatically remove upcoming elements from
the passed-in Iterator on each call to next(), effectivly "popping" them
off the backing collection as-you-go. Once the iteration has finished all
elements will have been removed.

Iterables.extract() will simply wrap and delegate to Iterators.extract().

The extract() method allows to conveniently remove elements from a
collection within an enhanced for-loop.

Here is a sample implementation (pre-existing methods omitted):

class Iterators {
  public static <T> Iterator<T> exhaust(final Iterator<T> iterator) {
    List<T> list = Lists.newLinkedList();
    Iterators.addAll(list, Iterators.extract(iterator));
    return list.iterator();
  }

  public static <T> Iterator<T> extract(final Iterator<T> iterator) {
    return new Iterator<T>() {
      public boolean hasNext() { return iterator.hasNext(); }
      public T next() {
        T next = iterator.next();
        iterator.remove(); // what about an exception?
        return next;
      }
      public void remove() { /* no-op */ }
    }
  }
}

class Iterables {
  public static <T> Iterable<T> exhaust(final Iterable<T> iterable) {
    List<T> list = Lists.newLinkedList();
    Iterables.addAll(list, Iterables.extract(iterable));
    return list;
  }

  // I prefer this, because of the parallelism to Iterables.extract()
  public static <T> Iterable<T> exhaustWrap(final Iterable<T> iterable) {
    return new Iterable<T>() {
      public Iterator<T> iterator() {
        return Iterators.exhaust(iterable.iterator());
      }
    }
  }

  public static <T> Iterable<T> extract(final Iterable<T> iterable) {
    return new Iterable<T>() {
      public Iterator<T> iterator() {
        return Iterators.extract(iterable.iterator());
      }
    }
  }
}

Here are some sample use-cases:

// replace elements in a random collection
{
   // some kind of Iterable<Foo>, but not a Collection<Foo>
   IterableContainer<Foo> container = ...

   // old
   Collection<Foo> temp = new LinkedList<Foo>();
   for (Iterator<Foo> iterator = container.iterator();
       iterator.hasNext(); iterator.remove())
     temp.add( iterator.next() );
   for (Foo foo : temp)
     container.insert( replace(foo) );

   // new
   for (Foo foo : Iterables.exhaust(container))
     container.insert( replace(foo) );

}

// pop off elements as-you-go
{
  Iterable<Waste> garbage = ...

  // old
  for (Iterator<Waste> iterator = garbage.iterator();
      iterator.hasNext(); iterator.remove())
  {
    Waste waste = iterator.next();
    dispose( waste.getRecycle(), waste.getResidual() );
  }

  // new
  for (Waste waste : Iterables.extract(garbage))
    dispose( waste.getRecycle(), waste.getResidual() );
}

// integration with other google-collections methods
{
  List<Foo> list = ...

  // filter "in place"
  Iterables.addAll(list,
    Iterables.filter(Iterables.exhaust(list), someFilter));

  // clear and return last
  Foo last = Iterables.getLast(Iterables.extract(list));
  ...
}

The main purpose of the proposed methods is to clear existing collections
and have them ready for reuse in a neat and convenient way. This is a
missing feature in google-collections.

Thank you for reading.

Cheers!

---

This is a rephrase of my previous post to the user mailing list:

http://groups.google.com/group/google-collections-users/browse_thread/thread/9af
e822079faf021/

Original issue reported on code.google.com by Robin...@gmail.com on 18 Sep 2009 at 1:19

[GoogleCodeExporter]

Original comment by kevin...@gmail.com on 18 Sep 2009 at 5:04

• Added labels: Milestone-Post1.0, Type-Enhancement

[GoogleCodeExporter]

Original comment by kevinb@google.com on 30 Jul 2010 at 3:53

• Removed labels: Milestone-Post1.0

[GoogleCodeExporter]

Original comment by fry@google.com on 26 Jan 2011 at 10:05

• Changed state: Accepted

[GoogleCodeExporter]

Original comment by kevinb@google.com on 27 Jan 2011 at 1:54

[GoogleCodeExporter]

Original comment by kevinb@google.com on 27 Jan 2011 at 1:58

[GoogleCodeExporter]

The proposed Iterators.extract(iter) is already provided as 
Iterators.consumingIterator(iter), and the proposed Iterators.exhaust(iter) is 
just Lists.newArrayList(iter).  I don't think this would add anything new as of 
R08.

Original comment by wasserman.louis on 15 Mar 2011 at 4:59

[GoogleCodeExporter]

Original comment by kevinb@google.com on 13 Jul 2011 at 6:18

• Changed state: Triaged

[GoogleCodeExporter]

Original comment by cpov...@google.com on 13 Jul 2011 at 8:39

• Changed title: Add exhaust() and extract() methods to Iterators and Iterables

[GoogleCodeExporter]

Agreed with Louis.

Original comment by kevinb@google.com on 1 Aug 2011 at 9:15

• Changed state: Fixed

[GoogleCodeExporter]

Original comment by cpov...@google.com on 1 Sep 2011 at 9:20

• Added labels: Milestone-Release08

[GoogleCodeExporter]

This issue has been migrated to GitHub.

It can be found at https://github.com/google/guava/issues/<id>

Original comment by cgdecker@google.com on 1 Nov 2014 at 4:16

• Added labels: MigratedToGitHub

[GoogleCodeExporter]

Original comment by cgdecker@google.com on 3 Nov 2014 at 9:10

• Added labels: Restrict-AddIssueComment-Commit