omnibus issue for added Iterators/Iterables functionality

[GoogleCodeExporter]

Iterables/Iterators lacks:

* size(Iter)/count(Iter)
* elementAt(Iter,int)
* elementAtPercentile(Iter,double)
* randomElement(Iter)
* contains(Iter,Object)
* removeFirst(Iter,Object)
* removeAll(Iter,Object)
* truncate(Iter,int)
* narrow(Iter) [see Functions for an example]
* index(Iter) [yields an IndexedIterator having an index() method]

The Iterables forms would, as usual, use special-case logic depending on
what type of iterable it is, so we don't do anything slower than we had to.
For example finding the element at position 99999 in a Multiset should not
actually iterate the whole thing, but should make use of the entrySet().

Clearly we've survived ok without these so far, but I'm throwing them out
here to collect input on which might be more important to you than others.

Original issue reported on code.google.com by kevin...@gmail.com on 23 Oct 2007 at 5:04

[GoogleCodeExporter]

Would be nice to have the other Collection methods lacking for Iterables (like
Iterables.addAll()), e.g. Iterables.containsAll(), removeAll(), retainAll().

Original comment by jahlborn@gmail.com on 25 Oct 2007 at 2:50

[GoogleCodeExporter]

also merge() of two or more sorted iterators. (we have this internally already).

Original comment by kevin...@gmail.com on 5 Nov 2007 at 6:51

[GoogleCodeExporter]

For Iterables, it seems like many of these could be "solved" by presenting a 
List
view.  Obviously, anyone who called size() or tried to go backward with a
ListIterator would be sorry, but if we can add either asList() (with warnings) 
or
size(), elementAt(), randomElement(), contains(), removeFirst(), removeAll(),
truncate(), index(), addAll(), containsAll(), removeAll(), and retainAll(), I 
think
it may be worth it.

Are there any obvious problems, other than the fact that it can be misused?  
And is
misuse a serious enough problem to abandon it?

Original comment by cpov...@google.com on 8 Nov 2007 at 7:10

[GoogleCodeExporter]

Damn, you're right!  Once again, my brain always seems to forget that List does 
not
imply RandomAccess.  This will be so much simpler.  Brilliant, thanks.

Original comment by kevin...@gmail.com on 8 Nov 2007 at 7:29

[GoogleCodeExporter]

I'd like to see added to this list:

drop(Iter, int)
take(Iter, int)

Where "drop" returns another Iterable/ator that is the same as before but skips 
the
first "int" values.  "take" returns an Iterable/ator that returns up to the 
first
"int" values, and is then done.  The names "drop" and "take" are from the 
Haskell
functions of the same name.

My current use case for "drop" is:
   Foo thing = listOfThings.get(0);
   for (foo : Iterables.drop(listOfThings, 1)) {
     thing = someWeirdActionsWith(thing, foo);
   }

That is, I want to do what is essentially reduce/inject/foldl (depending on what
other language you're familiar with), but with the nice syntax that java affords
Iterables.

Original comment by fiz...@gmail.com on 8 Nov 2007 at 7:47

[GoogleCodeExporter]

It's not clear to me how I can assign this to myself in the bug tracker, but:  
I'm on it.

Original comment by cpov...@google.com on 8 Nov 2007 at 11:36

[GoogleCodeExporter]

If i understand correctly, you intend on creating a List view for an Iterable 
so you
can call, for example, addAll() on a Collection?  This is a good idea, however, 
i
believe a variety of the collections in the standard jdk call size() on the 
incoming
collection, which would sort of negate the usefulness of this view.  maybe you 
could
create the view with a caller provided approximate size?  just something to 
think about.

Original comment by jahlborn@gmail.com on 9 Nov 2007 at 3:08

[GoogleCodeExporter]

A good point.  I'd added some documentation to indicate that Iterables.addAll() 
is
more appropriate for those cases.  (I also have a note explaining that creating 
a
"real" List with Lists.newArrayList(Iterable) or Lists.immutableList(Iterable) 
is
advisable most of the time.)

I think this is a better approach than having size() return an estimate, since, 
for
example, an array-based List's addAll() method might depend on an accurate 
return
value from size() to determine its new capacity.

Original comment by cpov...@google.com on 9 Nov 2007 at 5:06

[GoogleCodeExporter]

Since this is omnibus can I also add:
  <E extends Comparable> boolean isSorted(Iterable<E> elements)

and also a version that uses a comparator?

Original comment by chris.no...@gmail.com on 21 Nov 2007 at 6:55

[GoogleCodeExporter]

This will go onto Ordering, and I believe will also accept varargs.  I was 
thinking
to call it isIncreasing() and also have isStrictlyIncreasing(); your thoughts?

It does lead to the question of whether Ordering should also provide the
corresponding decreasing methods; it doesn't have to since there is
.reverse().isIncreasing(); but then we do have both min and max.

Original comment by kevin...@gmail.com on 21 Nov 2007 at 7:43

[GoogleCodeExporter]

I'm fine with just increasing and not decreasing. Min/max is more common and so 
it
makes sense for them to be special.

Not sure but it might be nice to have an easy way to get a natural order 
Ordering.
Ordering.forComparator(Comparators.naturalOrder()) seems a little long-winded 
for
what I presume is pretty common.

Original comment by chris.no...@gmail.com on 21 Nov 2007 at 7:55

[GoogleCodeExporter]

Absolutely.  At the same time that Ordering itself appears out here in the
open-source code base, the Comparators methods will actually return Orderings
(Ordering implements Comparator).  Both these changes have been made internally 
already.

Original comment by kevin...@gmail.com on 21 Nov 2007 at 8:14

[GoogleCodeExporter]

Itera...s methods just added:  size(), isEmpty() limit(), skip(), getLast().

Original comment by kevin...@gmail.com on 24 Mar 2008 at 8:27

[GoogleCodeExporter]

Most things described in this entry have been done; most of the remainder are 
not
considered important; anything else important that should be done should be 
filed as
its own issue.

Original comment by kevin...@gmail.com on 17 Mar 2009 at 5:01

• Changed state: Fixed