Update charted to 0.4.8 and roll

packages/quiver/lib/src/collection/multimap.dart

Index: packages/quiver/lib/src/collection/multimap.dart
diff --git a/packages/quiver/lib/src/collection/multimap.dart b/packages/quiver/lib/src/collection/multimap.dart
index 9144478e7cdc6e2a28bf0be2378f1d29fd5deab3..27d64a984796b118e253144dbe8891cd0b79f9d2 100644
--- a/packages/quiver/lib/src/collection/multimap.dart
+++ b/packages/quiver/lib/src/collection/multimap.dart
@@ -14,134 +14,108 @@
 
 part of quiver.collection;
 
-/**
- * An associative container that maps a key to multiple values.
- *
- * Key lookups return mutable collections that are views of the multimap.
- * Updates to the multimap are reflected in these collections and similarly,
- * modifications to the returned collections are reflected in the multimap.
- */
+/// An associative container that maps a key to multiple values.
+///
+/// Key lookups return mutable collections that are views of the multimap.
+/// Updates to the multimap are reflected in these collections and similarly,
+/// modifications to the returned collections are reflected in the multimap.
 abstract class Multimap<K, V> {
-  /**
-   * Constructs a new list-backed multimap.
-   */
+  /// Constructs a new list-backed multimap.
   factory Multimap() => new ListMultimap<K, V>();
 
-  /**
-   * Returns whether this multimap contains the given [value].
-   */
+  /// Constructs a new list-backed multimap. For each element e of [iterable],
+  /// adds an association from [key](e) to [value](e). [key] and [value] each
+  /// default to the identity function.
+  factory Multimap.fromIterable(Iterable iterable,
+      {K key(element), V value(element)}) = ListMultimap<K, V>.fromIterable;
+
+  /// Returns whether this multimap contains the given [value].
   bool containsValue(Object value);
 
-  /**
-   * Returns whether this multimap contains the given [key].
-   */
+  /// Returns whether this multimap contains the given [key].
   bool containsKey(Object key);
 
-  /**
-   * Returns the values for the given [key]. An empty iterable is returned if
-   * [key] is not mapped. The returned collection is a view on the multimap.
-   * Updates to the collection modify the multimap and likewise, modifications
-   * to the multimap are reflected in the returned collection.
-   */
+  /// Returns the values for the given [key]. An empty iterable is returned if
+  /// [key] is not mapped. The returned collection is a view on the multimap.
+  /// Updates to the collection modify the multimap and likewise, modifications
+  /// to the multimap are reflected in the returned collection.
   Iterable<V> operator [](Object key);
 
-  /**
-   * Adds an association from the given key to the given value.
-   */
+  /// Adds an association from the given key to the given value.
   void add(K key, V value);
 
-  /**
-   * Adds an association from the given key to each of the given values.
-   */
+  /// Adds an association from the given key to each of the given values.
   void addValues(K key, Iterable<V> values);
 
-  /**
-   * Adds all associations of [other] to this multimap.
-   *
-   * The operation is equivalent to doing `this[key] = value` for each key
-   * and associated value in other. It iterates over [other], which must
-   * therefore not change during the iteration.
-   */
+  /// Adds all associations of [other] to this multimap.
+  ///
+  /// The operation is equivalent to doing `this[key] = value` for each key and
+  /// associated value in other. It iterates over [other], which must therefore
+  /// not change during the iteration.
   void addAll(Multimap<K, V> other);
 
-  /**
-   * Removes the association between the given [key] and [value]. Returns
-   * `true` if the association existed, `false` otherwise.
-   */
+  /// Removes the association between the given [key] and [value]. Returns
+  /// `true` if the association existed, `false` otherwise.
   bool remove(Object key, V value);
 
-  /**
-   * Removes the association for the given [key]. Returns the collection of
-   * removed values, or an empty iterable if [key] was unmapped.
-   */
+  /// Removes the association for the given [key]. Returns the collection of
+  /// removed values, or an empty iterable if [key] was unmapped.
   Iterable<V> removeAll(Object key);
 
-  /**
-   * Removes all data from the multimap.
-   */
+  /// Removes all data from the multimap.
   void clear();
 
-  /**
-   * Applies [f] to each {key, Iterable<value>} pair of the multimap.
-   *
-   * It is an error to add or remove keys from the map during iteration.
-   */
+  /// Applies [f] to each {key, Iterable<value>} pair of the multimap.
+  ///
+  /// It is an error to add or remove keys from the map during iteration.
   void forEachKey(void f(K key, Iterable<V> value));
 
-  /**
-   * Applies [f] to each {key, value} pair of the multimap.
-   *
-   * It is an error to add or remove keys from the map during iteration.
-   */
+  /// Applies [f] to each {key, value} pair of the multimap.
+  ///
+  /// It is an error to add or remove keys from the map during iteration.
   void forEach(void f(K key, V value));
 
-  /**
-   * The keys of [this].
-   */
+  /// The keys of [this].
   Iterable<K> get keys;
 
-  /**
-   * The values of [this].
-   */
+  /// The values of [this].
   Iterable<V> get values;
 
-  /**
-   * Returns a view of this multimap as a map.
-   */
+  /// Returns a view of this multimap as a map.
   Map<K, Iterable<V>> asMap();
 
-  /**
-   * Returns a view of this multimap as a map.
-   *
-   * DEPRECATED: this method is replaced with `asMap`.
-   */
-  @Deprecated('Will be removed in 0.22.0')
-  Map<K, Iterable<V>> toMap();
-
-  /**
-   * The number of keys in the multimap.
-   */
+  /// The number of keys in the multimap.
   int get length;
 
-  /**
-   * Returns true if there is no key in the multimap.
-   */
+  /// Returns true if there is no key in the multimap.
   bool get isEmpty;
 
-  /**
-   * Returns true if there is at least one key in the multimap.
-   */
+  /// Returns true if there is at least one key in the multimap.
   bool get isNotEmpty;
 }
 
-/**
- * Abstract base class for multimap implementations.
- */
+/// Abstract base class for multimap implementations.
 abstract class _BaseMultimap<K, V, C extends Iterable<V>>
     implements Multimap<K, V> {
-  final Map<K, Iterable<V>> _map = new HashMap();
+  static T _id<T>(x) => x;
+
+  _BaseMultimap();
+
+  /// Constructs a new multimap. For each element e of [iterable], adds an
+  /// association from [key](e) to [value](e). [key] and [value] each default
+  /// to the identity function.
+  _BaseMultimap.fromIterable(Iterable iterable,
+      {K key(element), V value(element)}) {
+    key ??= _id;
+    value ??= _id;
+    for (var element in iterable) {
+      add(key(element), value(element));
+    }
+  }
 
-  Iterable<V> _create();
+  final Map<K, C> _map = new HashMap();
+
+  C _create();
   void _add(C iterable, V value);
   void _addAll(C iterable, Iterable<V> value);
   void _clear(C iterable);
@@ -169,16 +143,14 @@ abstract class _BaseMultimap<K, V, C extends Iterable<V>>
     _addAll(_map[key], values);
   }
 
-  /**
-   * Adds all associations of [other] to this multimap.
-   *
-   * The operation is equivalent to doing `this[key] = value` for each key
-   * and associated value in other. It iterates over [other], which must
-   * therefore not change during the iteration.
-   *
-   * This implementation iterates through each key of [other] and adds the
-   * associated values to this instance via [addValues].
-   */
+  /// Adds all associations of [other] to this multimap.
+  ///
+  /// The operation is equivalent to doing `this[key] = value` for each key and
+  /// associated value in other. It iterates over [other], which must therefore
+  /// not change during the iteration.
+  ///
+  /// This implementation iterates through each key of [other] and adds the
+  /// associated values to this instance via [addValues].
   void addAll(Multimap<K, V> other) => other.forEachKey(addValues);
 
   bool remove(Object key, V value) {
@@ -196,7 +168,7 @@ abstract class _BaseMultimap<K, V, C extends Iterable<V>>
       retValues.addAll(values);
       values.clear();
     }
-    return retValues;
+    return retValues as Iterable<V>;
   }
 
   void clear() {
@@ -204,7 +176,7 @@ abstract class _BaseMultimap<K, V, C extends Iterable<V>>
     _map.clear();
   }
 
-  void forEachKey(void f(K key, Iterable<V> value)) => _map.forEach(f);
+  void forEachKey(void f(K key, C value)) => _map.forEach(f);
 
   void forEach(void f(K key, V value)) {
     _map.forEach((K key, Iterable<V> values) {
@@ -220,18 +192,25 @@ abstract class _BaseMultimap<K, V, C extends Iterable<V>>
   bool get isNotEmpty => _map.isNotEmpty;
 }
 
-/**
- * A multimap implementation that uses [List]s to store the values associated
- * with each key.
- */
+/// A multimap implementation that uses [List]s to store the values associated
+/// with each key.
 class ListMultimap<K, V> extends _BaseMultimap<K, V, List<V>> {
-  ListMultimap() : super();
+  ListMultimap();
+
+  /// Constructs a new list-backed multimap. For each element e of [iterable],
+  /// adds an association from [key](e) to [value](e). [key] and [value] each
+  /// default to the identity function.
+  ListMultimap.fromIterable(Iterable iterable,
+      {K key(element), V value(element)})
+      : super.fromIterable(iterable, key: key, value: value);
+
   @override
   List<V> _create() => new List<V>();
   @override
   void _add(List<V> iterable, V value) {
     iterable.add(value);
   }
+
   @override
   void _addAll(List<V> iterable, Iterable<V> value) => iterable.addAll(value);
   @override
@@ -244,22 +223,27 @@ class ListMultimap<K, V> extends _BaseMultimap<K, V, List<V>> {
   List<V> operator [](Object key) => super[key];
   List<V> removeAll(Object key) => super.removeAll(key);
   Map<K, List<V>> asMap() => new _WrappedMap<K, V, List<V>>(this);
-  @Deprecated('Will be removed in 0.22.0')
-  Map<K, List<V>> toMap() => asMap();
 }
 
-/**
- * A multimap implementation that uses [Set]s to store the values associated
- * with each key.
- */
+/// A multimap implementation that uses [Set]s to store the values associated
+/// with each key.
 class SetMultimap<K, V> extends _BaseMultimap<K, V, Set<V>> {
-  SetMultimap() : super();
+  SetMultimap();
+
+  /// Constructs a new set-backed multimap. For each element e of [iterable],
+  /// adds an association from [key](e) to [value](e). [key] and [value] each
+  /// default to the identity function.
+  SetMultimap.fromIterable(Iterable iterable,
+      {K key(element), V value(element)})
+      : super.fromIterable(iterable, key: key, value: value);
+
   @override
   Set<V> _create() => new Set<V>();
   @override
   void _add(Set<V> iterable, V value) {
     iterable.add(value);
   }
+
   @override
   void _addAll(Set<V> iterable, Iterable<V> value) => iterable.addAll(value);
   @override
@@ -272,13 +256,9 @@ class SetMultimap<K, V> extends _BaseMultimap<K, V, Set<V>> {
   Set<V> operator [](Object key) => super[key];
   Set<V> removeAll(Object key) => super.removeAll(key);
   Map<K, Set<V>> asMap() => new _WrappedMap<K, V, Set<V>>(this);
-  @Deprecated('Will be removed in 0.22.0')
-  Map<K, Set<V>> toMap() => asMap();
 }
 
-/**
- * A [Map] that delegates its operations to an underlying multimap.
- */
+/// A [Map] that delegates its operations to an underlying multimap.
 class _WrappedMap<K, V, C extends Iterable<V>> implements Map<K, C> {
   final _BaseMultimap<K, V, C> _multimap;
 
@@ -310,9 +290,7 @@ class _WrappedMap<K, V, C extends Iterable<V>> implements Map<K, C> {
   Iterable<C> get values => _multimap._groupedValues;
 }
 
-/**
- * Iterable wrapper that syncs to an underlying map.
- */
+/// Iterable wrapper that syncs to an underlying map.
 class _WrappedIterable<K, V, C extends Iterable<V>> implements Iterable<V> {
   final K _key;
   final Map<K, C> _map;
@@ -322,14 +300,12 @@ class _WrappedIterable<K, V, C extends Iterable<V>> implements Iterable<V> {
 
   _addToMap() => _map[_key] = _delegate;
 
-  /**
-   * Ensures we hold an up-to-date delegate. In the case where all mappings for
-   * _key are removed from the multimap, the Iterable referenced by _delegate is
-   * removed from the underlying map. At that point, any new addition via the
-   * multimap triggers the creation of a new Iterable, and the empty delegate
-   * we hold would be stale. As such, we check the underlying map and update
-   * our delegate when the one we hold is empty.
-   */
+  /// Ensures we hold an up-to-date delegate. In the case where all mappings
+  /// for _key are removed from the multimap, the Iterable referenced by
+  /// _delegate is removed from the underlying map. At that point, any new
+  /// addition via the multimap triggers the creation of a new Iterable, and
+  /// the empty delegate we hold would be stale. As such, we check the
+  /// underlying map and update our delegate when the one we hold is empty.
   _syncDelegate() {
     if (_delegate.isEmpty) {
       var updated = _map[_key];
@@ -359,7 +335,7 @@ class _WrappedIterable<K, V, C extends Iterable<V>> implements Iterable<V> {
     return _delegate.every(test);
   }
 
-  Iterable expand(Iterable f(V element)) {
+  Iterable<T> expand<T>(Iterable<T> f(V element)) {
     _syncDelegate();
     return _delegate.expand(f);
   }
@@ -374,7 +350,7 @@ class _WrappedIterable<K, V, C extends Iterable<V>> implements Iterable<V> {
     return _delegate.firstWhere(test, orElse: orElse);
   }
 
-  fold(initialValue, combine(previousValue, V element)) {
+  T fold<T>(T initialValue, T combine(T previousValue, V element)) {
     _syncDelegate();
     return _delegate.fold(initialValue, combine);
   }
@@ -419,7 +395,7 @@ class _WrappedIterable<K, V, C extends Iterable<V>> implements Iterable<V> {
     return _delegate.length;
   }
 
-  Iterable map(f(V element)) {
+  Iterable<T> map<T>(T f(V element)) {
     _syncDelegate();
     return _delegate.map(f);
   }
@@ -482,7 +458,7 @@ class _WrappedIterable<K, V, C extends Iterable<V>> implements Iterable<V> {
 
 class _WrappedList<K, V> extends _WrappedIterable<K, V, List<V>>
     implements List<V> {
-  _WrappedList(Map<K, List<V>> map, K key, List<V> delegate)
+  _WrappedList(Map<K, Iterable<V>> map, K key, List<V> delegate)
       : super(map, key, delegate);
 
   V operator [](int index) => elementAt(index);
@@ -664,7 +640,7 @@ class _WrappedSet<K, V> extends _WrappedIterable<K, V, Set<V>>
     return _delegate.containsAll(other);
   }
 
-  Set<V> difference(Set<V> other) {
+  Set<V> difference(Set<Object> other) {
     _syncDelegate();
     return _delegate.difference(other);
   }