Note on java.util.functions

[Brian Goetz]

Thanks for reviewing.  

> Iterables.getFirst() and Iterators.getFirst() should throw
> NoSuchElementException if there are no elements, not return null, which is
> a perfectly valid element in some collections. Also, they should just be
> named first(), IMHO.

Except that is not their intended semantics.  The intended semantics is that they be find-first, where "not found" is an expected condition.  One possibility for making this clearer is to return something like Guava's Option.  

Ultimately this comment is indicative of bad naming; obviously "getFirst" suggests to you (and probably others) that there must be a first element, maybe this should be called "findFirst" or something like that.  It is made worse by the fact that getOnly *does* throw.  The assymmetry is deliberate; one is a way of asserting the Iterable has exactly one element (getOnly); the other is a way of saying "get me the first one if there is any; I don't care if there are more."  Both are important use cases, but probably should be named differently.  

> The Blocks.chain() overloads that take lists or arrays of blocks claim to
> make defensive copies, but do not.

These methods are likely to go away anyway.  I don't think they carry their weight.  

> Several static utility classes throw AssertionError in the ctor, but
> Iterables, Iterators, and ParallelIterables just throw Error. I think
> AssertionError should be preferred; that's what java.util.Objects uses.

Agreed.

> I know it's early days for this package, but I thought I'd mention it
> anyway. This is all based on the April 12 lambda build
> 1.8.0-ea-lambda-nightly-h140-20120412-b35-b00.

Thanks for reading!