[LANG-1503] Add factory methods to Pair classes with Map.Entry input.

#454.

Also adds tests that were not in the PR.

src/changes/changes.xml

@@ -86,6 +86,7 @@ The <action> type attribute can be add,update,fix,remove.
     <action                   type="update" dev="ggregory" due-to="Gary Gregory">Update POM parent: org.apache.commons:commons-parent 48 -> 50.</action>
     <action                   type="update" dev="ggregory" due-to="Peter Verhas">BooleanUtils Javadoc #469.</action>
     <action                   type="update" dev="ggregory" due-to="Peter Verhas">Functions Javadoc #466.</action>
+    <action issue="LANG-1503" type="add" dev="ggregory" due-to="XenoAmess, Gary Gregory">Add factory methods to Pair classes with Map.Entry input. #454.</action>
   </release>
 
   <release version="3.9" date="2019-04-09" description="New features and bug fixes. Requires Java 8, supports Java 9, 10, 11.">

src/main/java/org/apache/commons/lang3/tuple/ImmutablePair.java

@@ -16,6 +16,8 @@
  */
 package org.apache.commons.lang3.tuple;
 
+import java.util.Map;
+
 /**
  * <p>An immutable pair consisting of two {@code Object} elements.</p>
  *
@@ -80,7 +82,7 @@ public final class ImmutablePair<L, R> extends Pair<L, R> {
     }
 
     /**
-     * <p>Obtains an immutable pair of two objects inferring the generic types.</p>
+     * <p>Creates an immutable pair of two objects inferring the generic types.</p>
      *
      * <p>This factory allows the pair to be created using inference to
      * obtain the generic types.</p>
@@ -94,6 +96,32 @@ public final class ImmutablePair<L, R> extends Pair<L, R> {
     public static <L, R> ImmutablePair<L, R> of(final L left, final R right) {
         return new ImmutablePair<>(left, right);
     }
+
+    /**
+     * <p>Creates an immutable pair from an existing pair.</p>
+     *
+     * <p>This factory allows the pair to be created using inference to
+     * obtain the generic types.</p>
+     *
+     * @param <L> the left element type
+     * @param <R> the right element type
+     * @param pair the existing pair.
+     * @return a pair formed from the two parameters, not null
+     * @since 3.10
+     */
+    public static <L, R> ImmutablePair<L, R> of(final Map.Entry<L, R> pair) {
+        final L left;
+        final R right;
+        if (pair != null) {
+            left = pair.getKey();
+            right = pair.getValue();
+        } else {
+            left = null;
+            right = null;
+        }
+        return new ImmutablePair<>(left, right);
+    }
+
     /** Left object */
     public final L left;
 
@@ -112,7 +140,6 @@ public final class ImmutablePair<L, R> extends Pair<L, R> {
         this.right = right;
     }
 
-    //-----------------------------------------------------------------------
     /**
      * {@inheritDoc}
      */

src/main/java/org/apache/commons/lang3/tuple/MutablePair.java

@@ -16,6 +16,8 @@
  */
 package org.apache.commons.lang3.tuple;
 
+import java.util.Map;
+
 /**
  * <p>A mutable pair consisting of two {@code Object} elements.</p>
  *
@@ -56,7 +58,7 @@ public class MutablePair<L, R> extends Pair<L, R> {
     }
 
     /**
-     * <p>Obtains a mutable pair of two objects inferring the generic types.</p>
+     * <p>Creates a mutable pair of two objects inferring the generic types.</p>
      *
      * <p>This factory allows the pair to be created using inference to
      * obtain the generic types.</p>
@@ -70,6 +72,31 @@ public class MutablePair<L, R> extends Pair<L, R> {
     public static <L, R> MutablePair<L, R> of(final L left, final R right) {
         return new MutablePair<>(left, right);
     }
+
+    /**
+     * <p>Creates a mutable pair from an existing pair.</p>
+     *
+     * <p>This factory allows the pair to be created using inference to
+     * obtain the generic types.</p>
+     *
+     * @param <L> the left element type
+     * @param <R> the right element type
+     * @param pair the existing pair.
+     * @return a pair formed from the two parameters, not null
+     */
+    public static <L, R> MutablePair<L, R> of(final Map.Entry<L, R> pair) {
+        final L left;
+        final R right;
+        if (pair != null) {
+            left = pair.getKey();
+            right = pair.getValue();
+        } else {
+            left = null;
+            right = null;
+        }
+        return new MutablePair<>(left, right);
+    }
+
     /** Left object */
     public L left;
 

src/main/java/org/apache/commons/lang3/tuple/Pair.java

@@ -89,7 +89,7 @@ public abstract class Pair<L, R> implements Map.Entry<L, R>, Comparable<Pair<L,
     }
 
     /**
-     * <p>Obtains an immutable pair of two objects inferring the generic types.</p>
+     * <p>Creates an immutable pair of two objects inferring the generic types.</p>
      *
      * <p>This factory allows the pair to be created using inference to
      * obtain the generic types.</p>
@@ -101,7 +101,23 @@ public abstract class Pair<L, R> implements Map.Entry<L, R>, Comparable<Pair<L,
      * @return a pair formed from the two parameters, not null
      */
     public static <L, R> Pair<L, R> of(final L left, final R right) {
-        return new ImmutablePair<>(left, right);
+        return ImmutablePair.of(left, right);
+    }
+
+    /**
+     * <p>Creates an immutable pair from an existing pair.</p>
+     *
+     * <p>This factory allows the pair to be created using inference to
+     * obtain the generic types.</p>
+     *
+     * @param <L> the left element type
+     * @param <R> the right element type
+     * @param pair the existing pair.
+     * @return a pair formed from the two parameters, not null
+     * @since 3.10
+     */
+    public static <L, R> Pair<L, R> of(final Map.Entry<L, R> pair) {
+        return ImmutablePair.of(pair);
     }
 
     //-----------------------------------------------------------------------

src/test/java/org/apache/commons/lang3/tuple/ImmutablePairTest.java

@@ -54,16 +54,28 @@ public class ImmutablePairTest {
 
     @Test
     public void testBasic() {
-        final ImmutablePair<Integer, String> pair = new ImmutablePair<>(0, "foo");
-        assertEquals(0, pair.left.intValue());
-        assertEquals(0, pair.getLeft().intValue());
-        assertEquals("foo", pair.right);
-        assertEquals("foo", pair.getRight());
-        final ImmutablePair<Object, String> pair2 = new ImmutablePair<>(null, "bar");
-        assertNull(pair2.left);
-        assertNull(pair2.getLeft());
-        assertEquals("bar", pair2.right);
-        assertEquals("bar", pair2.getRight());
+        ImmutablePair<Integer, String> oldPair = new ImmutablePair<>(0, "foo");
+        ImmutablePair<Integer, String> nowPair;
+        for (int i=0; i<4; i++) {
+            nowPair = ImmutablePair.of(oldPair);
+            assertEquals(0, nowPair.left.intValue());
+            assertEquals(0, nowPair.getLeft().intValue());
+            assertEquals("foo", nowPair.right);
+            assertEquals("foo", nowPair.getRight());
+            assertEquals(oldPair, nowPair);
+            oldPair = nowPair;
+        }
+
+        ImmutablePair<Object, String> oldPair2 = new ImmutablePair<>(null, "bar");
+        ImmutablePair<Object, String> nowPair2;
+        for (int i=0; i<4; i++) {
+            nowPair2 = ImmutablePair.of(oldPair2);
+            assertNull(nowPair2.left);
+            assertNull(nowPair2.getLeft());
+            assertEquals("bar", nowPair2.right);
+            assertEquals("bar", nowPair2.getRight());
+            oldPair2 = nowPair2;
+        }
     }
 
     @Test
@@ -121,7 +133,17 @@ public class ImmutablePairTest {
     }
 
     @Test
-    public void testPairOf() {
+    public void testPairOfMapEntry() {
+        final HashMap<Integer, String> map = new HashMap<>();
+        map.put(0, "foo");
+        final Entry<Integer, String> entry = map.entrySet().iterator().next();
+        final Pair<Integer, String> pair = ImmutablePair.of(entry);
+        assertEquals(entry.getKey(), pair.getLeft());
+        assertEquals(entry.getValue(), pair.getRight());
+    }
+
+    @Test
+    public void testPairOfObjects() {
         final ImmutablePair<Integer, String> pair = ImmutablePair.of(0, "foo");
         assertEquals(0, pair.left.intValue());
         assertEquals(0, pair.getLeft().intValue());
@@ -132,6 +154,9 @@ public class ImmutablePairTest {
         assertNull(pair2.getLeft());
         assertEquals("bar", pair2.right);
         assertEquals("bar", pair2.getRight());
+        ImmutablePair pair3 = ImmutablePair.of(null, null);
+        assertNull(pair3.left);
+        assertNull(pair3.right);
     }
 
     @Test

src/test/java/org/apache/commons/lang3/tuple/MutablePairTest.java

@@ -24,6 +24,8 @@ import java.io.ByteArrayInputStream;
 import java.io.ByteArrayOutputStream;
 import java.io.ObjectInputStream;
 import java.io.ObjectOutputStream;
+import java.util.HashMap;
+import java.util.Map.Entry;
 
 import org.junit.jupiter.api.Test;
 
@@ -47,12 +49,28 @@ public class MutablePairTest {
 
     @Test
     public void testBasic() {
-        final MutablePair<Integer, String> pair = new MutablePair<>(0, "foo");
-        assertEquals(0, pair.getLeft().intValue());
-        assertEquals("foo", pair.getRight());
-        final MutablePair<Object, String> pair2 = new MutablePair<>(null, "bar");
-        assertNull(pair2.getLeft());
-        assertEquals("bar", pair2.getRight());
+        MutablePair<Integer, String> oldPair = new MutablePair<>(0, "foo");
+        MutablePair<Integer, String> nowPair;
+        for (int i=0; i<4; i++) {
+            nowPair = MutablePair.of(oldPair);
+            assertEquals(0, nowPair.left.intValue());
+            assertEquals(0, nowPair.getLeft().intValue());
+            assertEquals("foo", nowPair.right);
+            assertEquals("foo", nowPair.getRight());
+            assertEquals(oldPair, nowPair);
+            oldPair = nowPair;
+        }
+
+        MutablePair<Object, String> oldPair2 = new MutablePair<>(null, "bar");
+        MutablePair<Object, String> nowPair2;
+        for (int i=0; i<4; i++) {
+            nowPair2 = MutablePair.of(oldPair2);
+            assertNull(nowPair2.left);
+            assertNull(nowPair2.getLeft());
+            assertEquals("bar", nowPair2.right);
+            assertEquals("bar", nowPair2.getRight());
+            oldPair2 = nowPair2;
+        }
     }
 
     @Test
@@ -88,13 +106,26 @@ public class MutablePairTest {
     }
 
     @Test
-    public void testPairOf() {
+    public void testPairOfMapEntry() {
+        final HashMap<Integer, String> map = new HashMap<>();
+        map.put(0, "foo");
+        final Entry<Integer, String> entry = map.entrySet().iterator().next();
+        final Pair<Integer, String> pair = MutablePair.of(entry);
+        assertEquals(entry.getKey(), pair.getLeft());
+        assertEquals(entry.getValue(), pair.getRight());
+    }
+
+    @Test
+    public void testPairOfObjects() {
         final MutablePair<Integer, String> pair = MutablePair.of(0, "foo");
         assertEquals(0, pair.getLeft().intValue());
         assertEquals("foo", pair.getRight());
         final MutablePair<Object, String> pair2 = MutablePair.of(null, "bar");
         assertNull(pair2.getLeft());
         assertEquals("bar", pair2.getRight());
+        MutablePair pair3 = MutablePair.of(null, null);
+        assertNull(pair3.left);
+        assertNull(pair3.right);
     }
 
     @Test

src/test/java/org/apache/commons/lang3/tuple/PairTest.java

@@ -104,7 +104,17 @@ public class PairTest {
     }
 
     @Test
-    public void testPairOf() {
+    public void testPairOfMapEntry() {
+        final HashMap<Integer, String> map = new HashMap<>();
+        map.put(0, "foo");
+        final Entry<Integer, String> entry = map.entrySet().iterator().next();
+        final Pair<Integer, String> pair = Pair.of(entry);
+        assertEquals(entry.getKey(), pair.getLeft());
+        assertEquals(entry.getValue(), pair.getRight());
+    }
+
+    @Test
+    public void testPairOfObjects() {
         final Pair<Integer, String> pair = Pair.of(0, "foo");
         assertTrue(pair instanceof ImmutablePair<?, ?>);
         assertEquals(0, ((ImmutablePair<Integer, String>) pair).left.intValue());
@@ -113,6 +123,9 @@ public class PairTest {
         assertTrue(pair2 instanceof ImmutablePair<?, ?>);
         assertNull(((ImmutablePair<Object, String>) pair2).left);
         assertEquals("bar", ((ImmutablePair<Object, String>) pair2).right);
+        Pair pair3 = Pair.of(null, null);
+        assertNull(pair3.getLeft());
+        assertNull(pair3.getRight());
     }
 
     @Test