Add NumberRange, DoubleRange, IntegerRange, LongRange.

Fix changes.xml

6 files changed, 369 insertions, 16 deletions

diff --git a/src/main/java/org/apache/commons/lang3/DoubleRange.java b/src/main/java/org/apache/commons/lang3/DoubleRange.java
new file mode 100644
index 000000000..0c6d5a971
--- /dev/null
+++ b/src/main/java/org/apache/commons/lang3/DoubleRange.java
@@ -0,0 +1,85 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.commons.lang3;
+
+/**
+ * Specializes {@link NumberRange} for {@link Double}s.
+ *
+ * <p>
+ * This class is not designed to interoperate with other NumberRanges
+ * </p>
+ *
+ * @since 3.13.0
+ */
+public final class DoubleRange extends NumberRange<Double> {
+
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * Creates a range with the specified minimum and maximum values (both inclusive).
+     *
+     * <p>
+     * The range uses the natural ordering of the elements to determine where values lie in the range.
+     * </p>
+     *
+     * <p>
+     * The arguments may be passed in the order (min,max) or (max,min). The getMinimum and getMaximum methods will return the correct values.
+     * </p>
+     *
+     * @param fromInclusive the first value that defines the edge of the range, inclusive.
+     * @param toInclusive the second value that defines the edge of the range, inclusive.
+     * @return the range object, not null.
+     */
+    public static DoubleRange of(final double fromInclusive, final double toInclusive) {
+        return of(Double.valueOf(fromInclusive), Double.valueOf(toInclusive));
+    }
+
+    /**
+     * Creates a range with the specified minimum and maximum values (both inclusive).
+     *
+     * <p>
+     * The range uses the natural ordering of the elements to determine where values lie in the range.
+     * </p>
+     *
+     * <p>
+     * The arguments may be passed in the order (min,max) or (max,min). The getMinimum and getMaximum methods will return the correct values.
+     * </p>
+     *
+     * @param fromInclusive the first value that defines the edge of the range, inclusive.
+     * @param toInclusive the second value that defines the edge of the range, inclusive.
+     * @return the range object, not null.
+     * @throws IllegalArgumentException if either element is null.
+     */
+    public static DoubleRange of(final Double fromInclusive, final Double toInclusive) {
+        return new DoubleRange(fromInclusive, toInclusive);
+    }
+
+    /**
+     * Creates an instance.
+     *
+     * @param number1 the first element, not null
+     * @param number2 the second element, not null
+     * @param comp the comparator to be used, null for natural ordering
+     * @throws NullPointerException when element1 is null.
+     * @throws NullPointerException when element2 is null.
+     */
+    private DoubleRange(final Double number1, final Double number2) {
+        super(number1, number2, null);
+    }
+
+}
diff --git a/src/main/java/org/apache/commons/lang3/IntegerRange.java b/src/main/java/org/apache/commons/lang3/IntegerRange.java
new file mode 100644
index 000000000..3bc320cb9
--- /dev/null
+++ b/src/main/java/org/apache/commons/lang3/IntegerRange.java
@@ -0,0 +1,85 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.commons.lang3;
+
+/**
+ * Specializes {@link NumberRange} for {@link Integer}s.
+ *
+ * <p>
+ * This class is not designed to interoperate with other NumberRanges
+ * </p>
+ *
+ * @since 3.13.0
+ */
+public final class IntegerRange extends NumberRange<Integer> {
+
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * Creates a range with the specified minimum and maximum values (both inclusive).
+     *
+     * <p>
+     * The range uses the natural ordering of the elements to determine where values lie in the range.
+     * </p>
+     *
+     * <p>
+     * The arguments may be passed in the order (min,max) or (max,min). The getMinimum and getMaximum methods will return the correct values.
+     * </p>
+     *
+     * @param fromInclusive the first value that defines the edge of the range, inclusive.
+     * @param toInclusive the second value that defines the edge of the range, inclusive.
+     * @return the range object, not null.
+     */
+    public static IntegerRange of(final int fromInclusive, final int toInclusive) {
+        return of(Integer.valueOf(fromInclusive), Integer.valueOf(toInclusive));
+    }
+
+    /**
+     * Creates a range with the specified minimum and maximum values (both inclusive).
+     *
+     * <p>
+     * The range uses the natural ordering of the elements to determine where values lie in the range.
+     * </p>
+     *
+     * <p>
+     * The arguments may be passed in the order (min,max) or (max,min). The getMinimum and getMaximum methods will return the correct values.
+     * </p>
+     *
+     * @param fromInclusive the first value that defines the edge of the range, inclusive.
+     * @param toInclusive the second value that defines the edge of the range, inclusive.
+     * @return the range object, not null.
+     * @throws IllegalArgumentException if either element is null.
+     */
+    public static IntegerRange of(final Integer fromInclusive, final Integer toInclusive) {
+        return new IntegerRange(fromInclusive, toInclusive);
+    }
+
+    /**
+     * Creates an instance.
+     *
+     * @param number1 the first element, not null
+     * @param number2 the second element, not null
+     * @param comp the comparator to be used, null for natural ordering
+     * @throws NullPointerException when element1 is null.
+     * @throws NullPointerException when element2 is null.
+     */
+    private IntegerRange(final Integer number1, final Integer number2) {
+        super(number1, number2, null);
+    }
+
+}
diff --git a/src/main/java/org/apache/commons/lang3/LongRange.java b/src/main/java/org/apache/commons/lang3/LongRange.java
new file mode 100644
index 000000000..55efe88ab
--- /dev/null
+++ b/src/main/java/org/apache/commons/lang3/LongRange.java
@@ -0,0 +1,85 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.commons.lang3;
+
+/**
+ * Specializes {@link NumberRange} for {@link Long}s.
+ *
+ * <p>
+ * This class is not designed to interoperate with other NumberRanges
+ * </p>
+ *
+ * @since 3.13.0
+ */
+public final class LongRange extends NumberRange<Long> {
+
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * Creates a range with the specified minimum and maximum values (both inclusive).
+     *
+     * <p>
+     * The range uses the natural ordering of the elements to determine where values lie in the range.
+     * </p>
+     *
+     * <p>
+     * The arguments may be passed in the order (min,max) or (max,min). The getMinimum and getMaximum methods will return the correct values.
+     * </p>
+     *
+     * @param fromInclusive the first value that defines the edge of the range, inclusive.
+     * @param toInclusive the second value that defines the edge of the range, inclusive.
+     * @return the range object, not null.
+     */
+    public static LongRange of(final long fromInclusive, final long toInclusive) {
+        return of(Long.valueOf(fromInclusive), Long.valueOf(toInclusive));
+    }
+
+    /**
+     * Creates a range with the specified minimum and maximum values (both inclusive).
+     *
+     * <p>
+     * The range uses the natural ordering of the elements to determine where values lie in the range.
+     * </p>
+     *
+     * <p>
+     * The arguments may be passed in the order (min,max) or (max,min). The getMinimum and getMaximum methods will return the correct values.
+     * </p>
+     *
+     * @param fromInclusive the first value that defines the edge of the range, inclusive.
+     * @param toInclusive the second value that defines the edge of the range, inclusive.
+     * @return the range object, not null.
+     * @throws IllegalArgumentException if either element is null.
+     */
+    public static LongRange of(final Long fromInclusive, final Long toInclusive) {
+        return new LongRange(fromInclusive, toInclusive);
+    }
+
+    /**
+     * Creates an instance.
+     *
+     * @param number1 the first element, not null
+     * @param number2 the second element, not null
+     * @param comp the comparator to be used, null for natural ordering
+     * @throws NullPointerException when element1 is null.
+     * @throws NullPointerException when element2 is null.
+     */
+    private LongRange(final Long number1, final Long number2) {
+        super(number1, number2, null);
+    }
+
+}
diff --git a/src/main/java/org/apache/commons/lang3/NumberRange.java b/src/main/java/org/apache/commons/lang3/NumberRange.java
new file mode 100644
index 000000000..96afc3a5d
--- /dev/null
+++ b/src/main/java/org/apache/commons/lang3/NumberRange.java
@@ -0,0 +1,48 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.commons.lang3;
+
+import java.util.Comparator;
+
+/**
+ * Specializes {@link Range} for {@link Number}s.
+ * <p>
+ * We only offer specializations for Integer, Long, and Double (like Java Streams).
+ * </p>
+ *
+ * @param <N> The Number class.
+ * @since 3.13.0
+ */
+public class NumberRange<N extends Number> extends Range<N> {
+
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * Creates an instance.
+     *
+     * @param number1 the first element, not null
+     * @param number2 the second element, not null
+     * @param comp the comparator to be used, null for natural ordering
+     * @throws NullPointerException when element1 is null.
+     * @throws NullPointerException when element2 is null.
+     */
+    public NumberRange(final N number1, final N number2, final Comparator<N> comp) {
+        super(number1, number2, comp);
+    }
+
+}
diff --git a/src/main/java/org/apache/commons/lang3/Range.java b/src/main/java/org/apache/commons/lang3/Range.java
index f34277828..4318fb6bf 100644
--- a/src/main/java/org/apache/commons/lang3/Range.java
+++ b/src/main/java/org/apache/commons/lang3/Range.java
@@ -18,6 +18,7 @@ package org.apache.commons.lang3;
 
 import java.io.Serializable;
 import java.util.Comparator;
+import java.util.Objects;
 
 /**
  * An immutable range of objects from a minimum to maximum point inclusive.
@@ -30,7 +31,7 @@ import java.util.Comparator;
  * @param <T> The type of range values.
  * @since 3.0
  */
-public final class Range<T> implements Serializable {
+public class Range<T> implements Serializable {
 
     @SuppressWarnings({"rawtypes", "unchecked"})
     private enum ComparableComparator implements Comparator {
@@ -69,11 +70,14 @@ public final class Range<T> implements Serializable {
      * @param fromInclusive  the first value that defines the edge of the range, inclusive
      * @param toInclusive  the second value that defines the edge of the range, inclusive
      * @return the range object, not null
-     * @throws IllegalArgumentException if either element is null
+     * @throws NullPointerException when fromInclusive is null.
+     * @throws NullPointerException when toInclusive is null.
      * @throws ClassCastException if the elements are not {@link Comparable}
+     * @deprecated Use {@link #of(Comparable, Comparable)}.
      */
+    @Deprecated
     public static <T extends Comparable<? super T>> Range<T> between(final T fromInclusive, final T toInclusive) {
-        return between(fromInclusive, toInclusive, null);
+        return of(fromInclusive, toInclusive, null);
     }
 
     /**
@@ -90,9 +94,12 @@ public final class Range<T> implements Serializable {
      * @param toInclusive  the second value that defines the edge of the range, inclusive
      * @param comparator  the comparator to be used, null for natural ordering
      * @return the range object, not null
-     * @throws IllegalArgumentException if either element is null
+     * @throws NullPointerException when fromInclusive is null.
+     * @throws NullPointerException when toInclusive is null.
      * @throws ClassCastException if using natural ordering and the elements are not {@link Comparable}
+     * @deprecated Use {@link #of(Object, Object, Comparator)}.
      */
+    @Deprecated
     public static <T> Range<T> between(final T fromInclusive, final T toInclusive, final Comparator<T> comparator) {
         return new Range<>(fromInclusive, toInclusive, comparator);
     }
@@ -107,11 +114,11 @@ public final class Range<T> implements Serializable {
      * @param <T> the type of the elements in this range
      * @param element  the value to use for this range, not null
      * @return the range object, not null
-     * @throws IllegalArgumentException if the element is null
+     * @throws NullPointerException if the element is null
      * @throws ClassCastException if the element is not {@link Comparable}
      */
     public static <T extends Comparable<? super T>> Range<T> is(final T element) {
-        return between(element, element, null);
+        return of(element, element, null);
     }
 
     /**
@@ -125,11 +132,55 @@ public final class Range<T> implements Serializable {
      * @param element  the value to use for this range, must not be {@code null}
      * @param comparator  the comparator to be used, null for natural ordering
      * @return the range object, not null
-     * @throws IllegalArgumentException if the element is null
+     * @throws NullPointerException if the element is null
      * @throws ClassCastException if using natural ordering and the elements are not {@link Comparable}
      */
     public static <T> Range<T> is(final T element, final Comparator<T> comparator) {
-        return between(element, element, comparator);
+        return of(element, element, comparator);
+    }
+
+    /**
+     * Creates a range with the specified minimum and maximum values (both inclusive).
+     *
+     * <p>The range uses the natural ordering of the elements to determine where
+     * values lie in the range.</p>
+     *
+     * <p>The arguments may be passed in the order (min,max) or (max,min).
+     * The getMinimum and getMaximum methods will return the correct values.</p>
+     *
+     * @param <T> the type of the elements in this range
+     * @param fromInclusive  the first value that defines the edge of the range, inclusive
+     * @param toInclusive  the second value that defines the edge of the range, inclusive
+     * @return the range object, not null
+     * @throws NullPointerException if either element is null
+     * @throws ClassCastException if the elements are not {@link Comparable}
+     * @since 3.13.0
+     */
+    public static <T extends Comparable<? super T>> Range<T> of(final T fromInclusive, final T toInclusive) {
+        return of(fromInclusive, toInclusive, null);
+    }
+
+    /**
+     * Creates a range with the specified minimum and maximum values (both inclusive).
+     *
+     * <p>The range uses the specified {@link Comparator} to determine where
+     * values lie in the range.</p>
+     *
+     * <p>The arguments may be passed in the order (min,max) or (max,min).
+     * The getMinimum and getMaximum methods will return the correct values.</p>
+     *
+     * @param <T> the type of the elements in this range
+     * @param fromInclusive  the first value that defines the edge of the range, inclusive
+     * @param toInclusive  the second value that defines the edge of the range, inclusive
+     * @param comparator  the comparator to be used, null for natural ordering
+     * @return the range object, not null
+     * @throws NullPointerException when fromInclusive is null.
+     * @throws NullPointerException when toInclusive is null.
+     * @throws ClassCastException if using natural ordering and the elements are not {@link Comparable}
+     * @since 3.13.0
+     */
+    public static <T> Range<T> of(final T fromInclusive, final T toInclusive, final Comparator<T> comparator) {
+        return new Range<>(fromInclusive, toInclusive, comparator);
     }
 
     /**
@@ -163,13 +214,13 @@ public final class Range<T> implements Serializable {
      * @param element1  the first element, not null
      * @param element2  the second element, not null
      * @param comp  the comparator to be used, null for natural ordering
+     * @throws NullPointerException when element1 is null.
+     * @throws NullPointerException when element2 is null.
      */
     @SuppressWarnings("unchecked")
     Range(final T element1, final T element2, final Comparator<T> comp) {
-        if (element1 == null || element2 == null) {
-            throw new IllegalArgumentException("Elements in a range must not be null: element1=" +
-                                               element1 + ", element2=" + element2);
-        }
+        Objects.requireNonNull(element1, "element1");
+        Objects.requireNonNull(element2, "element2");
         if (comp == null) {
             this.comparator = ComparableComparator.INSTANCE;
         } else {
@@ -357,7 +408,7 @@ public final class Range<T> implements Serializable {
         }
         final T min = getComparator().compare(minimum, other.minimum) < 0 ? other.minimum : minimum;
         final T max = getComparator().compare(maximum, other.maximum) < 0 ? maximum : other.maximum;
-        return between(min, max, getComparator());
+        return of(min, max, getComparator());
     }
 
     /**
diff --git a/src/main/java/org/apache/commons/lang3/time/DurationUtils.java b/src/main/java/org/apache/commons/lang3/time/DurationUtils.java
index afb3804a5..2a6d7ebd7 100644
--- a/src/main/java/org/apache/commons/lang3/time/DurationUtils.java
+++ b/src/main/java/org/apache/commons/lang3/time/DurationUtils.java
@@ -24,8 +24,8 @@ import java.time.temporal.Temporal;
 import java.util.Objects;
 import java.util.concurrent.TimeUnit;
 
+import org.apache.commons.lang3.LongRange;
 import org.apache.commons.lang3.ObjectUtils;
-import org.apache.commons.lang3.Range;
 import org.apache.commons.lang3.function.FailableBiConsumer;
 import org.apache.commons.lang3.function.FailableConsumer;
 import org.apache.commons.lang3.function.FailableRunnable;
@@ -41,8 +41,7 @@ public class DurationUtils {
     /**
      * An Integer Range that accepts Longs.
      */
-    static final Range<Long> LONG_TO_INT_RANGE = Range.between(NumberUtils.LONG_INT_MIN_VALUE,
-            NumberUtils.LONG_INT_MAX_VALUE);
+    static final LongRange LONG_TO_INT_RANGE = LongRange.of(NumberUtils.LONG_INT_MIN_VALUE, NumberUtils.LONG_INT_MAX_VALUE);
 
     /**
      * Accepts the function with the duration as a long milliseconds and int nanoseconds.