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

#454.

Also adds tests that were not in the PR.

3 files changed, 75 insertions, 5 deletions

diff --git a/src/main/java/org/apache/commons/lang3/tuple/ImmutablePair.java b/src/main/java/org/apache/commons/lang3/tuple/ImmutablePair.java
index 488fd7cb5..a9be293ce 100644
--- a/src/main/java/org/apache/commons/lang3/tuple/ImmutablePair.java
+++ b/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}
      */
diff --git a/src/main/java/org/apache/commons/lang3/tuple/MutablePair.java b/src/main/java/org/apache/commons/lang3/tuple/MutablePair.java
index 58a66a725..9750e209e 100644
--- a/src/main/java/org/apache/commons/lang3/tuple/MutablePair.java
+++ b/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;
 
diff --git a/src/main/java/org/apache/commons/lang3/tuple/Pair.java b/src/main/java/org/apache/commons/lang3/tuple/Pair.java
index b64af80fc..fda2618e8 100644
--- a/src/main/java/org/apache/commons/lang3/tuple/Pair.java
+++ b/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);
     }
 
     //-----------------------------------------------------------------------