Merge pull request #45 from cbracken/multimap-docs

Corrections to Multimap docs: unmapped keys map to the empty collection (not null).

lib/src/collection/multimap.dart

@@ -16,6 +16,10 @@ 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.
  */
 abstract class Multimap<K, V> {
   /**
@@ -34,8 +38,10 @@ abstract class Multimap<K, V> {
   bool containsKey(Object key);
 
   /**
-   * Returns the values for the given [key] or null if [key] is not
-   * in the multimap.
+   * 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);
 
@@ -65,8 +71,8 @@ abstract class Multimap<K, V> {
   bool remove(Object key, V value);
 
   /**
-   * Removes the association for the given [key]. Returns the value for
-   * [key] in the multimap or null if [key] is not in the multimap.
+   * 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);
 

pubspec.yaml

@@ -1,5 +1,5 @@
 name: quiver
-version: 0.10.2
+version: 0.10.3
 authors:
 - Justin Fagnani <justinfagnani@google.com>
 - Yegor Jbanov <yjbanov@google.com>

test/collection/multimap_test.dart

@@ -310,6 +310,22 @@ void main() {
       expect(values, []);
     });
 
+    test('should return an empty iterable on removeAll of unmapped key', () {
+      Multimap map = new ListMultimap();
+      var removed = map.removeAll('k1');
+      expect(removed, []);
+    });
+
+    test('should be uncoupled from the iterable returned by removeAll', () {
+      Multimap map = new ListMultimap()
+        ..add('k1', 'v1');
+      var removed = map.removeAll('k1');
+      removed.add('v2');
+      map.add('k1', 'v3');
+      expect(removed, ['v1', 'v2']);
+      expect(map['k1'], ['v3']);
+    });
+
     test('should clear the map', () {
       Multimap map = new ListMultimap()
         ..add('k1', 'v1')
@@ -677,6 +693,22 @@ void main() {
       expect(values, []);
     });
 
+    test('should return an empty iterable on removeAll of unmapped key', () {
+      Multimap map = new SetMultimap();
+      var removed = map.removeAll('k1');
+      expect(removed, []);
+    });
+
+    test('should be uncoupled from the iterable returned by removeAll', () {
+      Multimap map = new SetMultimap()
+        ..add('k1', 'v1');
+      var removed = map.removeAll('k1');
+      removed.add('v2');
+      map.add('k1', 'v3');
+      expect(removed, unorderedEquals(['v1', 'v2']));
+      expect(map['k1'], ['v3']);
+    });
+
     test('should clear the map', () {
       Multimap map = new SetMultimap()
         ..add('k1', 'v1')