Add withKeyValue to MutableMultimap and subtypes. Closes #1303.

Signed-off-by: Donald Raab <Donald.Raab@bnymellon.com>

eclipse-collections-api/src/main/java/org/eclipse/collections/api/multimap/MutableMultimap.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021 Goldman Sachs and others.
+ * Copyright (c) 2022 Goldman Sachs and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * and Eclipse Distribution License v. 1.0 which accompany this distribution.
@@ -34,6 +34,16 @@ public interface MutableMultimap<K, V>
 
     boolean put(K key, V value);
 
+    /**
+     * Puts the key / value combination into the MutableMultimap and returns the MutableMultimap (this).
+     * @since 11.1
+     */
+    default MutableMultimap<K, V> withKeyValue(K key, V value)
+    {
+        this.put(key, value);
+        return this;
+    }
+
     /**
      * Modification operation similar to put, however, takes the key-value pair as the input.
      *

eclipse-collections-api/src/main/java/org/eclipse/collections/api/multimap/bag/MutableBagIterableMultimap.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021 Goldman Sachs and others.
+ * Copyright (c) 2022 Goldman Sachs and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * and Eclipse Distribution License v. 1.0 which accompany this distribution.
@@ -24,6 +24,17 @@
 public interface MutableBagIterableMultimap<K, V>
         extends MutableMultimap<K, V>, BagMultimap<K, V>
 {
+    /**
+     * Puts the key / value combination into the MutableBagIterableMultimap and returns the MutableBagIterableMultimap (this).
+     * @since 11.1
+     */
+    @Override
+    default MutableBagIterableMultimap<K, V> withKeyValue(K key, V value)
+    {
+        this.put(key, value);
+        return this;
+    }
+
     @Override
     MutableBagIterable<V> replaceValues(K key, Iterable<? extends V> values);
 

eclipse-collections-api/src/main/java/org/eclipse/collections/api/multimap/bag/MutableBagMultimap.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021 Goldman Sachs and others.
+ * Copyright (c) 2022 Goldman Sachs and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * and Eclipse Distribution License v. 1.0 which accompany this distribution.
@@ -24,6 +24,17 @@
 public interface MutableBagMultimap<K, V>
         extends MutableBagIterableMultimap<K, V>, UnsortedBagMultimap<K, V>
 {
+    /**
+     * Puts the key / value combination into the MutableBagMultimap and returns the MutableBagMultimap (this).
+     * @since 11.1
+     */
+    @Override
+    default MutableBagMultimap<K, V> withKeyValue(K key, V value)
+    {
+        this.put(key, value);
+        return this;
+    }
+
     /**
      * @since 11.0
      */

eclipse-collections-api/src/main/java/org/eclipse/collections/api/multimap/list/MutableListMultimap.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021 Goldman Sachs and others.
+ * Copyright (c) 2022 Goldman Sachs and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * and Eclipse Distribution License v. 1.0 which accompany this distribution.
@@ -26,6 +26,17 @@
 public interface MutableListMultimap<K, V>
         extends ListMultimap<K, V>, MutableMultimap<K, V>
 {
+    /**
+     * Puts the key / value combination into the MutableListMultimap and returns the MutableListMultimap (this).
+     * @since 11.1
+     */
+    @Override
+    default MutableListMultimap<K, V> withKeyValue(K key, V value)
+    {
+        this.put(key, value);
+        return this;
+    }
+
     /**
      * @since 11.0
      */

eclipse-collections-api/src/main/java/org/eclipse/collections/api/multimap/set/MutableSetIterableMultimap.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021 Goldman Sachs and others.
+ * Copyright (c) 2022 Goldman Sachs and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * and Eclipse Distribution License v. 1.0 which accompany this distribution.
@@ -25,6 +25,17 @@
 public interface MutableSetIterableMultimap<K, V>
         extends SetMultimap<K, V>, MutableMultimap<K, V>
 {
+    /**
+     * Puts the key / value combination into the MutableSetIterableMultimap and returns the MutableSetIterableMultimap (this).
+     * @since 11.1
+     */
+    @Override
+    default MutableSetIterableMultimap<K, V> withKeyValue(K key, V value)
+    {
+        this.put(key, value);
+        return this;
+    }
+
     @Override
     MutableSetIterable<V> replaceValues(K key, Iterable<? extends V> values);
 

eclipse-collections-api/src/main/java/org/eclipse/collections/api/multimap/set/MutableSetMultimap.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021 Goldman Sachs and others.
+ * Copyright (c) 2022 Goldman Sachs and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * and Eclipse Distribution License v. 1.0 which accompany this distribution.
@@ -25,6 +25,17 @@
 public interface MutableSetMultimap<K, V>
         extends UnsortedSetMultimap<K, V>, MutableSetIterableMultimap<K, V>
 {
+    /**
+     * Puts the key / value combination into the MutableSetMultimap and returns the MutableSetMultimap (this).
+     * @since 11.1
+     */
+    @Override
+    default MutableSetMultimap<K, V> withKeyValue(K key, V value)
+    {
+        this.put(key, value);
+        return this;
+    }
+
     /**
      * @since 11.0
      */

eclipse-collections-api/src/main/java/org/eclipse/collections/api/multimap/sortedbag/MutableSortedBagMultimap.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021 Goldman Sachs and others.
+ * Copyright (c) 2022 Goldman Sachs and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * and Eclipse Distribution License v. 1.0 which accompany this distribution.
@@ -26,6 +26,17 @@
 public interface MutableSortedBagMultimap<K, V>
         extends MutableBagIterableMultimap<K, V>, SortedBagMultimap<K, V>
 {
+    /**
+     * Puts the key / value combination into the MutableSortedBagMultimap and returns the MutableSortedBagMultimap (this).
+     * @since 11.1
+     */
+    @Override
+    default MutableSortedBagMultimap<K, V> withKeyValue(K key, V value)
+    {
+        this.put(key, value);
+        return this;
+    }
+
     @Override
     MutableSortedBag<V> replaceValues(K key, Iterable<? extends V> values);
 

eclipse-collections-api/src/main/java/org/eclipse/collections/api/multimap/sortedset/MutableSortedSetMultimap.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021 Goldman Sachs and others.
+ * Copyright (c) 2022 Goldman Sachs and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * and Eclipse Distribution License v. 1.0 which accompany this distribution.
@@ -27,6 +27,17 @@
 public interface MutableSortedSetMultimap<K, V>
         extends MutableSetIterableMultimap<K, V>, SortedSetMultimap<K, V>
 {
+    /**
+     * Puts the key / value combination into the MutableSortedSetMultimap and returns the MutableSortedSetMultimap (this).
+     * @since 11.1
+     */
+    @Override
+    default MutableSortedSetMultimap<K, V> withKeyValue(K key, V value)
+    {
+        this.put(key, value);
+        return this;
+    }
+
     @Override
     MutableSortedSet<V> replaceValues(K key, Iterable<? extends V> values);
 

unit-tests/src/test/java/org/eclipse/collections/impl/multimap/bag/HashBagMultimapTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021 Goldman Sachs.
+ * Copyright (c) 2022 Goldman Sachs and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * and Eclipse Distribution License v. 1.0 which accompany this distribution.
@@ -29,18 +29,16 @@ protected <K, V> MutableBagMultimap<K, V> newMultimap()
     @Override
     protected <K, V> MutableBagMultimap<K, V> newMultimapWithKeyValue(K key, V value)
     {
-        MutableBagMultimap<K, V> mutableMultimap = this.newMultimap();
-        mutableMultimap.put(key, value);
-        return mutableMultimap;
+        return this.<K, V>newMultimap()
+                .withKeyValue(key, value);
     }
 
     @Override
     protected <K, V> MutableBagMultimap<K, V> newMultimapWithKeysValues(K key1, V value1, K key2, V value2)
     {
-        MutableBagMultimap<K, V> mutableMultimap = this.newMultimap();
-        mutableMultimap.put(key1, value1);
-        mutableMultimap.put(key2, value2);
-        return mutableMultimap;
+        return this.<K, V>newMultimap()
+                .withKeyValue(key1, value1)
+                .withKeyValue(key2, value2);
     }
 
     @Override
@@ -49,11 +47,10 @@ protected <K, V> MutableBagMultimap<K, V> newMultimapWithKeysValues(
             K key2, V value2,
             K key3, V value3)
     {
-        MutableBagMultimap<K, V> mutableMultimap = this.newMultimap();
-        mutableMultimap.put(key1, value1);
-        mutableMultimap.put(key2, value2);
-        mutableMultimap.put(key3, value3);
-        return mutableMultimap;
+        return this.<K, V>newMultimap()
+                .withKeyValue(key1, value1)
+                .withKeyValue(key2, value2)
+                .withKeyValue(key3, value3);
     }
 
     @Override
@@ -63,12 +60,11 @@ protected <K, V> MutableBagMultimap<K, V> newMultimapWithKeysValues(
             K key3, V value3,
             K key4, V value4)
     {
-        MutableBagMultimap<K, V> mutableMultimap = this.newMultimap();
-        mutableMultimap.put(key1, value1);
-        mutableMultimap.put(key2, value2);
-        mutableMultimap.put(key3, value3);
-        mutableMultimap.put(key4, value4);
-        return mutableMultimap;
+        return this.<K, V>newMultimap()
+                .withKeyValue(key1, value1)
+                .withKeyValue(key2, value2)
+                .withKeyValue(key3, value3)
+                .withKeyValue(key4, value4);
     }
 
     @SafeVarargs

unit-tests/src/test/java/org/eclipse/collections/impl/multimap/bag/SynchronizedBagMultimapTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021 Shotaro Sano.
+ * Copyright (c) 2022 Shotaro Sano and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * and Eclipse Distribution License v. 1.0 which accompany this distribution.
@@ -26,39 +26,35 @@ public <K, V> MutableBagMultimap<K, V> newMultimap()
     @Override
     public <K, V> MutableBagMultimap<K, V> newMultimapWithKeyValue(K key, V value)
     {
-        MutableBagMultimap<K, V> mutableMultimap = this.newMultimap();
-        mutableMultimap.put(key, value);
-        return mutableMultimap;
+        return this.<K, V>newMultimap()
+                .withKeyValue(key, value);
     }
 
     @Override
     public <K, V> MutableBagMultimap<K, V> newMultimapWithKeysValues(K key1, V value1, K key2, V value2)
     {
-        MutableBagMultimap<K, V> mutableMultimap = this.newMultimap();
-        mutableMultimap.put(key1, value1);
-        mutableMultimap.put(key2, value2);
-        return mutableMultimap;
+        return this.<K, V>newMultimap()
+                .withKeyValue(key1, value1)
+                .withKeyValue(key2, value2);
     }
 
     @Override
     public <K, V> MutableBagMultimap<K, V> newMultimapWithKeysValues(K key1, V value1, K key2, V value2, K key3, V value3)
     {
-        MutableBagMultimap<K, V> mutableMultimap = this.newMultimap();
-        mutableMultimap.put(key1, value1);
-        mutableMultimap.put(key2, value2);
-        mutableMultimap.put(key3, value3);
-        return mutableMultimap;
+        return this.<K, V>newMultimap()
+                .withKeyValue(key1, value1)
+                .withKeyValue(key2, value2)
+                .withKeyValue(key3, value3);
     }
 
     @Override
     public <K, V> MutableBagMultimap<K, V> newMultimapWithKeysValues(K key1, V value1, K key2, V value2, K key3, V value3, K key4, V value4)
     {
-        MutableBagMultimap<K, V> mutableMultimap = this.newMultimap();
-        mutableMultimap.put(key1, value1);
-        mutableMultimap.put(key2, value2);
-        mutableMultimap.put(key3, value3);
-        mutableMultimap.put(key4, value4);
-        return mutableMultimap;
+        return this.<K, V>newMultimap()
+                .withKeyValue(key1, value1)
+                .withKeyValue(key2, value2)
+                .withKeyValue(key3, value3)
+                .withKeyValue(key4, value4);
     }
 
     @Override

unit-tests/src/test/java/org/eclipse/collections/impl/multimap/bag/sorted/TreeBagMultimapTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2021 Goldman Sachs.
+ * Copyright (c) 2022 Goldman Sachs and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * and Eclipse Distribution License v. 1.0 which accompany this distribution.
@@ -47,18 +47,16 @@ public <K, V> MutableSortedBagMultimap<K, V> newMultimap()
     @Override
     public <K, V> MutableSortedBagMultimap<K, V> newMultimapWithKeyValue(K key, V value)
     {
-        MutableSortedBagMultimap<K, V> mutableMultimap = this.newMultimap();
-        mutableMultimap.put(key, value);
-        return mutableMultimap;
+        return this.<K, V>newMultimap()
+                .withKeyValue(key, value);
     }
 
     @Override
     public <K, V> MutableSortedBagMultimap<K, V> newMultimapWithKeysValues(K key1, V value1, K key2, V value2)
     {
-        MutableSortedBagMultimap<K, V> mutableMultimap = this.newMultimap();
-        mutableMultimap.put(key1, value1);
-        mutableMultimap.put(key2, value2);
-        return mutableMultimap;
+        return this.<K, V>newMultimap()
+                .withKeyValue(key1, value1)
+                .withKeyValue(key2, value2);
     }
 
     @Override
@@ -67,11 +65,10 @@ public <K, V> MutableSortedBagMultimap<K, V> newMultimapWithKeysValues(
             K key2, V value2,
             K key3, V value3)
     {
-        MutableSortedBagMultimap<K, V> mutableMultimap = this.newMultimap();
-        mutableMultimap.put(key1, value1);
-        mutableMultimap.put(key2, value2);
-        mutableMultimap.put(key3, value3);
-        return mutableMultimap;
+        return this.<K, V>newMultimap()
+                .withKeyValue(key1, value1)
+                .withKeyValue(key2, value2)
+                .withKeyValue(key3, value3);
     }
 
     @Override
@@ -81,12 +78,11 @@ public <K, V> MutableSortedBagMultimap<K, V> newMultimapWithKeysValues(
             K key3, V value3,
             K key4, V value4)
     {
-        MutableSortedBagMultimap<K, V> mutableMultimap = this.newMultimap();
-        mutableMultimap.put(key1, value1);
-        mutableMultimap.put(key2, value2);
-        mutableMultimap.put(key3, value3);
-        mutableMultimap.put(key4, value4);
-        return mutableMultimap;
+        return this.<K, V>newMultimap()
+                .withKeyValue(key1, value1)
+                .withKeyValue(key2, value2)
+                .withKeyValue(key3, value3)
+                .withKeyValue(key4, value4);
     }
 
     @Override