[commons-lang] 05/06: [LANG-1479] Add Range.fit(T) to fit a value into a range.

[gg...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-lang.git

commit b1d01fecee3b347b2488eb34bd33c90db0847399
Author: Gary Gregory <ga...@gmail.com>
AuthorDate: Thu Aug 22 10:33:05 2019 -0400

    [LANG-1479] Add Range.fit(T) to fit a value into a range.
---
 src/changes/changes.xml                            |  1 +
 src/main/java/org/apache/commons/lang3/Range.java  | 22 ++++++++++++++++++++++
 .../java/org/apache/commons/lang3/RangeTest.java   | 17 ++++++++++++++++-
 3 files changed, 39 insertions(+), 1 deletion(-)

diff --git a/src/changes/changes.xml b/src/changes/changes.xml
index 905a7b2..45c58a4 100644
--- a/src/changes/changes.xml
+++ b/src/changes/changes.xml
@@ -56,6 +56,7 @@ The <action> type attribute can be add,update,fix,remove.
     <action issue="LANG-1437" type="update" dev="ggregory" due-to="Andrei Troie">Remove redundant if statements in join methods #411.</action>
     <action issue="LANG-1460" type="fix" dev="kinow" due-to="Larry West">Trivial: year of release for 3.9 says 2018, should be 2019</action>
     <action issue="LANG-1476" type="fix" dev="kinow" due-to="emopers">Use synchronise on a set created with Collections.synchronizedSet before iterating</action>
+    <action issue="LANG-1479" type="add" dev="ggregory">Add Range.fit(T) to fit a value into a range.</action>
   </release>
 
   <release version="3.9" date="2019-04-09" description="New features and bug fixes. Requires Java 8, supports Java 9, 10, 11">
diff --git a/src/main/java/org/apache/commons/lang3/Range.java b/src/main/java/org/apache/commons/lang3/Range.java
index 4f3da66..449be0c 100644
--- a/src/main/java/org/apache/commons/lang3/Range.java
+++ b/src/main/java/org/apache/commons/lang3/Range.java
@@ -453,6 +453,28 @@ public final class Range<T> implements Serializable {
     }
 
     /**
+     * <p>
+     * Fits the given element into this range by returning the given element or, if out of bounds, the range minimum if
+     * below, or the range maximum if above.
+     * </p>
+     *
+     * @param element the element to check for, not null
+     * @return the minimum, the element, or the maximum depending on the element's location relative to the range
+     * @since 3.10
+     */
+    public T fit(final T element) {
+        // Comparable API says throw NPE on null
+        Validate.notNull(element, "Element is null");
+        if (isAfter(element)) {
+            return minimum;
+        } else if (isBefore(element)) {
+            return maximum;
+        } else {
+            return element;
+        }
+    }
+
+    /**
      * <p>Gets the range as a {@code String}.</p>
      *
      * <p>The format of the String is '[<i>min</i>..<i>max</i>]'.</p>
diff --git a/src/test/java/org/apache/commons/lang3/RangeTest.java b/src/test/java/org/apache/commons/lang3/RangeTest.java
index 4705115..29b9967 100644
--- a/src/test/java/org/apache/commons/lang3/RangeTest.java
+++ b/src/test/java/org/apache/commons/lang3/RangeTest.java
@@ -171,6 +171,22 @@ public class RangeTest {
     }
 
     @Test
+    public void testFit() {
+        assertEquals(intRange.getMinimum(), intRange.fit(Integer.MIN_VALUE));
+        assertEquals(intRange.getMinimum(), intRange.fit(intRange.getMinimum()));
+        assertEquals(intRange.getMaximum(), intRange.fit(Integer.MAX_VALUE));
+        assertEquals(intRange.getMaximum(), intRange.fit(intRange.getMaximum()));
+        assertEquals(15, intRange.fit(15));
+    }
+
+    @Test
+    public void testFitNull() {
+        assertThrows(NullPointerException.class, () -> {
+            intRange.fit(null);
+        });
+    }
+
+    @Test
     public void testGetMaximum() {
         assertEquals(20, (int) intRange.getMaximum());
         assertEquals(20L, (long) longRange.getMaximum());
@@ -367,5 +383,4 @@ public class RangeTest {
         final String str = intRange.toString("From %1$s to %2$s");
         assertEquals("From 10 to 20", str);
     }
-
 }