/* * 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.io.Serializable; import java.util.Comparator; import net.lax1dude.eaglercraft.v1_8.HString; /** *

* An immutable range of objects from a minimum to maximum point inclusive. *

* *

* The objects need to either be implementations of {@code Comparable} or you * need to supply a {@code Comparator}. *

* *

* #ThreadSafe# if the objects and comparator are thread-safe *

* * @param The type of range values. * @since 3.0 */ public final class Range implements Serializable { @SuppressWarnings({ "rawtypes", "unchecked" }) private enum ComparableComparator implements Comparator { INSTANCE; /** * Comparable based compare implementation. * * @param obj1 left hand side of comparison * @param obj2 right hand side of comparison * @return negative, 0, positive comparison value */ @Override public int compare(final Object obj1, final Object obj2) { return ((Comparable) obj1).compareTo(obj2); } } /** * Serialization version. * * @see java.io.Serializable */ private static final long serialVersionUID = 1L; /** *

* Obtains a range with the specified minimum and maximum values (both * inclusive). *

* *

* The range uses the natural ordering of the elements to determine where values * lie in the range. *

* *

* The arguments may be passed in the order (min,max) or (max,min). The * getMinimum and getMaximum methods will return the correct values. *

* * @param 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 IllegalArgumentException if either element is null * @throws ClassCastException if the elements are not {@code Comparable} */ public static > Range between(final T fromInclusive, final T toInclusive) { return between(fromInclusive, toInclusive, null); } /** *

* Obtains a range with the specified minimum and maximum values (both * inclusive). *

* *

* The range uses the specified {@code Comparator} to determine where values lie * in the range. *

* *

* The arguments may be passed in the order (min,max) or (max,min). The * getMinimum and getMaximum methods will return the correct values. *

* * @param 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 IllegalArgumentException if either element is null * @throws ClassCastException if using natural ordering and the elements * are not {@code Comparable} */ public static Range between(final T fromInclusive, final T toInclusive, final Comparator comparator) { return new Range<>(fromInclusive, toInclusive, comparator); } /** *

* Obtains a range using the specified element as both the minimum and maximum * in this range. *

* *

* The range uses the natural ordering of the elements to determine where values * lie in the range. *

* * @param 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 ClassCastException if the element is not {@code Comparable} */ public static > Range is(final T element) { return between(element, element, null); } /** *

* Obtains a range using the specified element as both the minimum and maximum * in this range. *

* *

* The range uses the specified {@code Comparator} to determine where values lie * in the range. *

* * @param the type of the elements in this range * @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 ClassCastException if using natural ordering and the elements * are not {@code Comparable} */ public static Range is(final T element, final Comparator comparator) { return between(element, element, comparator); } /** * The ordering scheme used in this range. */ private final Comparator comparator; /** * Cached output hashCode (class is immutable). */ private transient int hashCode; /** * The maximum value in this range (inclusive). */ private final T maximum; /** * The minimum value in this range (inclusive). */ private final T minimum; /** * Cached output toString (class is immutable). */ private transient String toString; /** * Creates an instance. * * @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 */ @SuppressWarnings("unchecked") private Range(final T element1, final T element2, final Comparator comp) { if (element1 == null || element2 == null) { throw new IllegalArgumentException( "Elements in a range must not be null: element1=" + element1 + ", element2=" + element2); } if (comp == null) { this.comparator = ComparableComparator.INSTANCE; } else { this.comparator = comp; } if (this.comparator.compare(element1, element2) < 1) { this.minimum = element1; this.maximum = element2; } else { this.minimum = element2; this.maximum = element1; } } /** *

* Checks whether the specified element occurs within this range. *

* * @param element the element to check for, null returns false * @return true if the specified element occurs within this range */ public boolean contains(final T element) { if (element == null) { return false; } return comparator.compare(element, minimum) > -1 && comparator.compare(element, maximum) < 1; } /** *

* Checks whether this range contains all the elements of the specified range. *

* *

* This method may fail if the ranges have two different comparators or element * types. *

* * @param otherRange the range to check, null returns false * @return true if this range contains the specified range * @throws RuntimeException if ranges cannot be compared */ public boolean containsRange(final Range otherRange) { if (otherRange == null) { return false; } return contains(otherRange.minimum) && contains(otherRange.maximum); } /** *

* Checks where the specified element occurs relative to this range. *

* *

* The API is reminiscent of the Comparable interface returning {@code -1} if * the element is before the range, {@code 0} if contained within the range and * {@code 1} if the element is after the range. *

* * @param element the element to check for, not null * @return -1, 0 or +1 depending on the element's location relative to the range */ public int elementCompareTo(final T element) { // Comparable API says throw NPE on null Validate.notNull(element, "element"); if (isAfter(element)) { return -1; } else if (isBefore(element)) { return 1; } else { return 0; } } // Element tests // -------------------------------------------------------------------- /** *

* Compares this range to another object to test if they are equal. *

* . * *

* To be equal, the minimum and maximum values must be equal, which ignores any * differences in the comparator. *

* * @param obj the reference object with which to compare * @return true if this object is equal */ @Override public boolean equals(final Object obj) { if (obj == this) { return true; } else if (obj == null || obj.getClass() != getClass()) { return false; } else { @SuppressWarnings("unchecked") // OK because we checked the class above final Range range = (Range) obj; return minimum.equals(range.minimum) && maximum.equals(range.maximum); } } /** *

* Gets the comparator being used to determine if objects are within the range. *

* *

* Natural ordering uses an internal comparator implementation, thus this method * never returns null. See {@link #isNaturalOrdering()}. *

* * @return the comparator being used, not null */ public Comparator getComparator() { return comparator; } /** *

* Gets the maximum value in this range. *

* * @return the maximum value in this range, not null */ public T getMaximum() { return maximum; } /** *

* Gets the minimum value in this range. *

* * @return the minimum value in this range, not null */ public T getMinimum() { return minimum; } /** *

* Gets a suitable hash code for the range. *

* * @return a hash code value for this object */ @Override public int hashCode() { int result = hashCode; if (hashCode == 0) { result = 17; result = 37 * result + getClass().hashCode(); result = 37 * result + minimum.hashCode(); result = 37 * result + maximum.hashCode(); hashCode = result; } return result; } /** * Calculate the intersection of {@code this} and an overlapping Range. * * @param other overlapping Range * @return range representing the intersection of {@code this} and {@code other} * ({@code this} if equal) * @throws IllegalArgumentException if {@code other} does not overlap * {@code this} * @since 3.0.1 */ public Range intersectionWith(final Range other) { if (!this.isOverlappedBy(other)) { throw new IllegalArgumentException( HString.format("Cannot calculate intersection with non-overlapping range %s", other)); } if (this.equals(other)) { return this; } 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()); } /** *

* Checks whether this range is after the specified element. *

* * @param element the element to check for, null returns false * @return true if this range is entirely after the specified element */ public boolean isAfter(final T element) { if (element == null) { return false; } return comparator.compare(element, minimum) < 0; } /** *

* Checks whether this range is completely after the specified range. *

* *

* This method may fail if the ranges have two different comparators or element * types. *

* * @param otherRange the range to check, null returns false * @return true if this range is completely after the specified range * @throws RuntimeException if ranges cannot be compared */ public boolean isAfterRange(final Range otherRange) { if (otherRange == null) { return false; } return isAfter(otherRange.maximum); } /** *

* Checks whether this range is before the specified element. *

* * @param element the element to check for, null returns false * @return true if this range is entirely before the specified element */ public boolean isBefore(final T element) { if (element == null) { return false; } return comparator.compare(element, maximum) > 0; } /** *

* Checks whether this range is completely before the specified range. *

* *

* This method may fail if the ranges have two different comparators or element * types. *

* * @param otherRange the range to check, null returns false * @return true if this range is completely before the specified range * @throws RuntimeException if ranges cannot be compared */ public boolean isBeforeRange(final Range otherRange) { if (otherRange == null) { return false; } return isBefore(otherRange.minimum); } /** *

* Checks whether this range ends with the specified element. *

* * @param element the element to check for, null returns false * @return true if the specified element occurs within this range */ public boolean isEndedBy(final T element) { if (element == null) { return false; } return comparator.compare(element, maximum) == 0; } /** *

* Whether or not the Range is using the natural ordering of the elements. *

* *

* Natural ordering uses an internal comparator implementation, thus this method * is the only way to check if a null comparator was specified. *

* * @return true if using natural ordering */ public boolean isNaturalOrdering() { return comparator == ComparableComparator.INSTANCE; } /** *

* Checks whether this range is overlapped by the specified range. *

* *

* Two ranges overlap if there is at least one element in common. *

* *

* This method may fail if the ranges have two different comparators or element * types. *

* * @param otherRange the range to test, null returns false * @return true if the specified range overlaps with this range; otherwise, * {@code false} * @throws RuntimeException if ranges cannot be compared */ public boolean isOverlappedBy(final Range otherRange) { if (otherRange == null) { return false; } return otherRange.contains(minimum) || otherRange.contains(maximum) || contains(otherRange.minimum); } /** *

* Checks whether this range starts with the specified element. *

* * @param element the element to check for, null returns false * @return true if the specified element occurs within this range */ public boolean isStartedBy(final T element) { if (element == null) { return false; } return comparator.compare(element, minimum) == 0; } /** *

* 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. *

* *
	 * Range<Integer> range = Range.between(16, 64);
	 * range.fit(-9) -->  16
	 * range.fit(0)  -->  16
	 * range.fit(15) -->  16
	 * range.fit(16) -->  16
	 * range.fit(17) -->  17
	 * ...
	 * range.fit(63) -->  63
	 * range.fit(64) -->  64
	 * range.fit(99) -->  64
	 * 
* * @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"); if (isAfter(element)) { return minimum; } else if (isBefore(element)) { return maximum; } else { return element; } } /** *

* Gets the range as a {@code String}. *

* *

* The format of the String is '[min..max]'. *

* * @return the {@code String} representation of this range */ @Override public String toString() { if (toString == null) { toString = "[" + minimum + ".." + maximum + "]"; } return toString; } /** *

* Formats the receiver using the given format. *

* *

* This uses {@link java.util.Formattable} to perform the formatting. Three * variables may be used to embed the minimum, maximum and comparator. Use * {@code %1$s} for the minimum element, {@code %2$s} for the maximum element * and {@code %3$s} for the comparator. The default format used by * {@code toString()} is {@code [%1$s..%2$s]}. *

* * @param format the format string, optionally containing {@code %1$s}, * {@code %2$s} and {@code %3$s}, not null * @return the formatted string, not null */ public String toString(final String format) { return HString.format(format, minimum, maximum, comparator); } }