Add reduce to Collection.

corelib/src/collection.dart

 // Copyright (c) 2011, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 /**
  * The [Collection] interface is the public interface of all
  * collections.
  */
 interface Collection<E> extends Iterable<E> {
   /**
    * Applies the function [f] to each element of this collection.
    */
   void forEach(void f(E element));
 
   /**
    * Returns a new collection with the elements [: f(e) :]
-   * for each element [e] of this collection. 
+   * for each element [e] of this collection.

[Lasse Reichstein Nielsen, 2012/08/08 07:19:14]

[:e:]. The 'e' is not referring to an existing variable in scope for the
function, so it's just a code expression, not a variable reference.

And <soapbox>I think 'map' should be a constructor, not a method!</soapbox>.
This function could return a lazy collection backed by the original, instead of
creating a new collection of unspecified type.

[Anders Johnsen, 2012/08/08 07:56:14]

I'd like if we could resolve this in another CL. The change here is purely the
editor removing tailing whitespaces.

[Lasse Reichstein Nielsen, 2012/08/10 11:26:56]

Just fix the [:e:] while you are here, and it'll be fine.
You better get used to comments on surrounding code, even if it isn't yours :)

[Anders Johnsen, 2012/11/12 12:02:56]

Done.

    *
    * Note on typing: the return type of f() could be an arbitrary
    * type and consequently the returned collection's
-   * typeis Collection.  
+   * typeis Collection.
    */
   Collection map(f(E element));
 
   /**
+   * Reduce the entire collection to one value value, startign with [init]. To

[Lasse Reichstein Nielsen, 2012/08/08 07:19:14]

"starting". This comment is not very descriptive - it just repeats the function
signature: function is called "reduce", it acts on a collection and an "init"
value and returns a single value. 
The rest is just an example, which is fine in addition to a description, but not
as a replacement.

How about:
Reduce a collection to a single value by iteratively combining each element of
the collection with an existing value using the provided function.
Use [initialValue] as the initial value, and the function [combine] to create a
new value from the previous one and an element.
<insert example>


Perhaps make the initialValue optional, and use the first element of the
collection if it isn't specified (e.g., use a unique private object as default
marker). That would need to throw a NoSuchElementException if the collection is
empty.

[Anders Johnsen, 2012/08/08 07:56:14]

Agreed, this is a way better comment. Updated.

Creating it optional as you suggest is not ideal, since we still want the user
to be able to provide 'null' as a real initial value. If we have a nice way to
mark it as 'unprovided', I'd be happy to change it.

[Lasse Reichstein Nielsen, 2012/08/10 11:26:56]

"Nice" is such a loaded word :)
Let's drop it for now.
Since your argument is untyped, you could do:
 Object _UNSPECIFIED = const Object();
and use that as default.

+   * compute e.g. the sum of a Collection of ints, do
+   *
+   * collection.reduce(0, (prev, element) => prev + element);
+   */
+  reduce(var init, f(var prev, E element));

[Lasse Reichstein Nielsen, 2012/08/08 07:19:14]

Don't abbreviate:
  Object reduce(var initialValue, Object combine(var previousValue, E element));

[Anders Johnsen, 2012/08/08 07:56:14]

Returning Object is annoying since you have to 'cast' it to be able to use it.
Using var(non for return), the analyzer doesn't care and you can call whatever
you want on it.

[Lasse Reichstein Nielsen, 2012/08/10 11:26:56]

Accepted. Use Dynamic or var then.

[Anders Johnsen, 2012/11/12 12:02:56]

Done.

+
+  /**
    * Returns a new collection with the elements of this collection
    * that satisfy the predicate [f].
    *
    * An element satisfies the predicate [f] if [:f(element):]
    * returns true.
    */
   Collection<E> filter(bool f(E element));
 
   /**
    * Returns true if every elements of this collection satisify the
@@ skipping 10 matching lines @@
   /**
    * Returns true if there is no element in this collection.
    */
   bool isEmpty();
 
   /**
    * Returns the number of elements in this collection.
    */
   int get length();
 }