Collections Data Structure Java

/*
 * 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.
 */
import java.io.Serializable;
/**
 * 

NumberRange represents an inclusive range of 
 * {@link java.lang.Number} objects of the same type.


 *
 * @author Christopher Elkins
 * @author Stephen Colebourne
 * @since 2.0 (previously in org.apache.commons.lang)
 * @version $Id: NumberRange.java 437554 2006-08-28 06:21:41Z bayard $
 */
public final class NumberRange extends Range implements Serializable {
    
    /**
     * Required for serialization support.
     * 
     * @see java.io.Serializable
     */
    private static final long serialVersionUID = 71849363892710L;
    /**
     * The minimum number in this range.
     */
    private final Number min;
    /**
     * The maximum number in this range.
     */
    private final Number max;
    
    /**
     * Cached output hashCode (class is immutable).
     */
    private transient int hashCode = 0;
    /**
     * Cached output toString (class is immutable).
     */
    private transient String toString = null;
    /**
     * 

Constructs a new NumberRange using the specified
     * number as both the minimum and maximum in this range.


     *
     * @param num the number to use for this range
     * @throws IllegalArgumentException if the number is null
     * @throws IllegalArgumentException if the number doesn't implement Comparable
     * @throws IllegalArgumentException if the number is Double.NaN or Float.NaN
     */
    public NumberRange(Number num) {
        if (num == null) {
            throw new IllegalArgumentException("The number must not be null");
        }
        if (num instanceof Comparable == false) {
            throw new IllegalArgumentException("The number must implement Comparable");
        }
        if (num instanceof Double && ((Double) num).isNaN()) {
            throw new IllegalArgumentException("The number must not be NaN");
        }
        if (num instanceof Float && ((Float) num).isNaN()) {
            throw new IllegalArgumentException("The number must not be NaN");
        }
        this.min = num;
        this.max = num;
    }
    /**
     * 

Constructs a new NumberRange with the specified
     * minimum and maximum numbers (both inclusive).


     * 
     * 

The arguments may be passed in the order (min,max) or (max,min). The
     * {@link #getMinimumNumber()} and {@link #getMaximumNumber()} methods will return the
     * correct value.


     * 
     * 

This constructor is designed to be used with two Number
     * objects of the same type. If two objects of different types are passed in,
     * an exception is thrown.


     *
     * @param num1  first number that defines the edge of the range, inclusive
     * @param num2  second number that defines the edge of the range, inclusive
     * @throws IllegalArgumentException if either number is null
     * @throws IllegalArgumentException if the numbers are of different types
     * @throws IllegalArgumentException if the numbers don't implement Comparable
     */
    public NumberRange(Number num1, Number num2) {
        if (num1 == null || num2 == null) {
            throw new IllegalArgumentException("The numbers must not be null");
        }
        if (num1.getClass() != num2.getClass()) {
            throw new IllegalArgumentException("The numbers must be of the same type");
        }
        if (num1 instanceof Comparable == false) {
            throw new IllegalArgumentException("The numbers must implement Comparable");
        }
        if (num1 instanceof Double) {
            if (((Double) num1).isNaN() || ((Double) num2).isNaN()) {
                throw new IllegalArgumentException("The number must not be NaN");
            }
        } else if (num1 instanceof Float) {
            if (((Float) num1).isNaN() || ((Float) num2).isNaN()) {
                throw new IllegalArgumentException("The number must not be NaN");
            }
        }
        
        int compare = ((Comparable) num1).compareTo(num2);
        if (compare == 0) {
            this.min = num1;
            this.max = num1;
        } else if (compare > 0) {
            this.min = num2;
            this.max = num1;
        } else {
            this.min = num1;
            this.max = num2;
        }
    }
    
    // Accessors
    //--------------------------------------------------------------------
    /**
     * 

Returns the minimum number in this range.


     *
     * @return the minimum number in this range
     */
    public Number getMinimumNumber() {
        return min;
    }
    /**
     * 

Returns the maximum number in this range.


     *
     * @return the maximum number in this range
     */
    public Number getMaximumNumber() {
        return max;
    }
    // Tests
    //--------------------------------------------------------------------
    
    /**
     * 

Tests whether the specified number occurs within
     * this range.


     * 
     * 

null is handled and returns false.


     *
     * @param number  the number to test, may be null
     * @return true if the specified number occurs within this range
     * @throws IllegalArgumentException if the number is of a different type to the range
     */
    public boolean containsNumber(Number number) {
        if (number == null) {
            return false;
        }
        if (number.getClass() != min.getClass()) {
            throw new IllegalArgumentException("The number must be of the same type as the range numbers");
        }
        int compareMin = ((Comparable) min).compareTo(number);
        int compareMax = ((Comparable) max).compareTo(number);
        return compareMin <= 0 && compareMax >= 0;
    }
    // Range tests
    //--------------------------------------------------------------------
    // use Range implementations
    // Basics
    //--------------------------------------------------------------------
    /**
     * 

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

.
     * 
     * 

To be equal, the class, minimum and maximum must be equal.


     *
     * @param obj the reference object with which to compare
     * @return true if this object is equal
     */
    public boolean equals(Object obj) {
        if (obj == this) {
            return true;
        }
        if (obj instanceof NumberRange == false) {
            return false;
        }
        NumberRange range = (NumberRange) obj;
        return min.equals(range.min) && max.equals(range.max);
    }
    /**
     * 

Gets a hashCode for the range.


     *
     * @return a hash code value for this object
     */
    public int hashCode() {
        if (hashCode == 0) {
            hashCode = 17;
            hashCode = 37 * hashCode + getClass().hashCode();
            hashCode = 37 * hashCode + min.hashCode();
            hashCode = 37 * hashCode + max.hashCode();
        }
        return hashCode;
    }
    /**
     * 

Gets the range as a String.


     *
     * 

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


     *
     * @return the String representation of this range
     */
    public String toString() {
        if (toString == null) {
            StringBuffer buf = new StringBuffer(32);
            buf.append("Range[");
            buf.append(min);
            buf.append(',');
            buf.append(max);
            buf.append(']');
            toString = buf.toString();
        }
        return toString;
    }
}
/*
 * 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.
 */
/**
 * 

Range represents a range of numbers of the same type.


 * 
 * 

Specific subclasses hold the range values as different types. Each
 * subclass should be immutable and {@link java.io.Serializable Serializable}
 * if possible.


 *
 * @author Stephen Colebourne
 * @since 2.0
 * @version $Id: Range.java 437554 2006-08-28 06:21:41Z bayard $
 */
abstract class Range {
    /**
     * 

Constructs a new range.


     */
    public Range() {
        super();
    }
    // Accessors
    //--------------------------------------------------------------------
    /**
     * 

Gets the minimum number in this range.


     *
     * @return the minimum number in this range
     */
    public abstract Number getMinimumNumber();
    /**
     * 

Gets the minimum number in this range as a long.


     * 
     * 

This implementation uses the {@link #getMinimumNumber()} method. 
     * Subclasses may be able to optimise this.


     *
     * @return the minimum number in this range
     */
    public long getMinimumLong() {
        return getMinimumNumber().longValue();
    }
    /**
     * 

Gets the minimum number in this range as a int.


     * 
     * 

This implementation uses the {@link #getMinimumNumber()} method. 
     * Subclasses may be able to optimise this.


     *
     * @return the minimum number in this range
     */
    public int getMinimumInteger() {
        return getMinimumNumber().intValue();
    }
    /**
     * 

Gets the minimum number in this range as a double.


     * 
     * 

This implementation uses the {@link #getMinimumNumber()} method. 
     * Subclasses may be able to optimise this.


     *
     * @return the minimum number in this range
     */
    public double getMinimumDouble() {
        return getMinimumNumber().doubleValue();
    }
    /**
     * 

Gets the minimum number in this range as a float.


     * 
     * 

This implementation uses the {@link #getMinimumNumber()} method. 
     * Subclasses may be able to optimise this.


     *
     * @return the minimum number in this range
     */
    public float getMinimumFloat() {
        return getMinimumNumber().floatValue();
    }
    /**
     * 

Gets the maximum number in this range.


     *
     * @return the maximum number in this range
     */
    public abstract Number getMaximumNumber();
    /**
     * 

Gets the maximum number in this range as a long.


     * 
     * 

This implementation uses the {@link #getMaximumNumber()} method. 
     * Subclasses may be able to optimise this.


     *
     * @return the maximum number in this range
     */
    public long getMaximumLong() {
        return getMaximumNumber().longValue();
    }
    /**
     * 

Gets the maximum number in this range as a int.


     * 
     * 

This implementation uses the {@link #getMaximumNumber()} method. 
     * Subclasses may be able to optimise this.


     *
     * @return the maximum number in this range
     */
    public int getMaximumInteger() {
        return getMaximumNumber().intValue();
    }
    /**
     * 

Gets the maximum number in this range as a double.


     * 
     * 

This implementation uses the {@link #getMaximumNumber()} method. 
     * Subclasses may be able to optimise this.


     *
     * @return the maximum number in this range
     */
    public double getMaximumDouble() {
        return getMaximumNumber().doubleValue();
    }
    /**
     * 

Gets the maximum number in this range as a float.


     * 
     * 

This implementation uses the {@link #getMaximumNumber()} method. 
     * Subclasses may be able to optimise this.


     *
     * @return the maximum number in this range
     */
    public float getMaximumFloat() {
        return getMaximumNumber().floatValue();
    }
    // Include tests
    //--------------------------------------------------------------------
    
    /**
     * 

Tests whether the specified Number occurs within
     * this range.


     * 
     * 

The exact comparison implementation varies by subclass. It is
     * intended that an int specific subclass will compare using
     * int comparison.


     * 
     * 

null is handled and returns false.


     *
     * @param number  the number to test, may be null
     * @return true if the specified number occurs within this range
     * @throws IllegalArgumentException if the Number cannot be compared
     */
    public abstract boolean containsNumber(Number number);
    /**
     * 

Tests whether the specified Number occurs within
     * this range using long comparison..


     * 
     * 

null is handled and returns false.


     * 
     * 

This implementation forwards to the {@link #containsLong(long)} method.


     *
     * @param value  the long to test, may be null
     * @return true if the specified number occurs within this
     *  range by long comparison
     */
    public boolean containsLong(Number value) {
        if (value == null) {
            return false;
        }
        return containsLong(value.longValue());
    }
    /**
     * 

Tests whether the specified long occurs within
     * this range using long comparison.


     * 
     * 

This implementation uses the {@link #getMinimumLong()} and 
     * {@link #getMaximumLong()} methods and should be good for most uses.


     * 
     * @param value  the long to test
     * @return true if the specified number occurs within this
     *  range by long comparison
     */
    public boolean containsLong(long value) {
        return value >= getMinimumLong() && value <= getMaximumLong();
    }
    /**
     * 

Tests whether the specified Number occurs within
     * this range using int comparison..


     * 
     * 

null is handled and returns false.


     * 
     * 

This implementation forwards to the {@link #containsInteger(int)} method.


     *
     * @param value  the integer to test, may be null
     * @return true if the specified number occurs within this
     *  range by int comparison
     */
    public boolean containsInteger(Number value) {
        if (value == null) {
            return false;
        }
        return containsInteger(value.intValue());
    }
    /**
     * 

Tests whether the specified int occurs within
     * this range using int comparison.


     * 
     * 

This implementation uses the {@link #getMinimumInteger()} and 
     * {@link #getMaximumInteger()} methods and should be good for most uses.


     * 
     * @param value  the int to test
     * @return true if the specified number occurs within this
     *  range by int comparison
     */
    public boolean containsInteger(int value) {
        return value >= getMinimumInteger() && value <= getMaximumInteger();
    }
    /**
     * 

Tests whether the specified Number occurs within
     * this range using double comparison..


     * 
     * 

null is handled and returns false.


     * 
     * 

This implementation forwards to the {@link #containsDouble(double)} method.


     *
     * @param value  the double to test, may be null
     * @return true if the specified number occurs within this
     *  range by double comparison
     */
    public boolean containsDouble(Number value) {
        if (value == null) {
            return false;
        }
        return containsDouble(value.doubleValue());
    }
    /**
     * 

Tests whether the specified double occurs within
     * this range using double comparison.


     * 
     * 

This implementation uses the {@link #getMinimumDouble()} and 
     * {@link #getMaximumDouble()} methods and should be good for most uses.


     * 
     * @param value  the double to test
     * @return true if the specified number occurs within this
     *  range by double comparison
     */
    public boolean containsDouble(double value) {
        int compareMin = compare(getMinimumDouble(), value);
        int compareMax = compare(getMaximumDouble(), value);
        return compareMin <= 0 && compareMax >= 0;
    }
    /**
     * 

Tests whether the specified Number occurs within
     * this range using float comparison.


     * 
     * 

null is handled and returns false.


     * 
     * 

This implementation forwards to the {@link #containsFloat(float)} method.


     *
     * @param value  the float to test, may be null
     * @return true if the specified number occurs within this
     *  range by float comparison
     */
    public boolean containsFloat(Number value) {
        if (value == null) {
            return false;
        }
        return containsFloat(value.floatValue());
    }
    /**
     * 

Tests whether the specified float occurs within
     * this range using float comparison.


     * 
     * 

This implementation uses the {@link #getMinimumFloat()} and 
     * {@link #getMaximumFloat()} methods and should be good for most uses.


     * 
     * @param value  the float to test
     * @return true if the specified number occurs within this
     *  range by float comparison
     */
    public boolean containsFloat(float value) {
        int compareMin = compare(getMinimumFloat(), value);
        int compareMax = compare(getMaximumFloat(), value);
        return compareMin <= 0 && compareMax >= 0;
    }
    // Range tests
    //--------------------------------------------------------------------
    /**
     * 

Tests whether the specified range occurs entirely within this range.


     * 
     * 

The exact comparison implementation varies by subclass. It is
     * intended that an int specific subclass will compare using
     * int comparison.


     * 
     * 

null is handled and returns false.


     * 
     * 

This implementation uses the {@link #containsNumber(Number)} method.
     * Subclasses may be able to optimise this.


     *
     * @param range  the range to test, may be null
     * @return true if the specified range occurs entirely within
     *  this range; otherwise, false
     * @throws IllegalArgumentException if the Range cannot be compared
     */
    public boolean containsRange(Range range) {
        if (range == null) {
            return false;
        }
        return containsNumber(range.getMinimumNumber()) 
            && containsNumber(range.getMaximumNumber());
    }
    /**
     * 

Tests whether the specified range overlaps with this range.


     * 
     * 

The exact comparison implementation varies by subclass. It is
     * intended that an int specific subclass will compare using
     * int comparison.


     * 
     * 

null is handled and returns false.


     * 
     * 

This implementation uses the {@link #containsNumber(Number)} and
     * {@link #containsRange(Range)} methods.
     * Subclasses may be able to optimise this.


     *
     * @param range  the range to test, may be null
     * @return true if the specified range overlaps with this
     *  range; otherwise, false
     * @throws IllegalArgumentException if the Range cannot be compared
     */
    public boolean overlapsRange(Range range) {
        if (range == null) {
            return false;
        }
        return range.containsNumber(getMinimumNumber())
            || range.containsNumber(getMaximumNumber())
            || containsNumber(range.getMinimumNumber());
    }
    // Basics
    //--------------------------------------------------------------------
    /**
     * 

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

.
     * 
     * 

To be equal, the class, minimum and maximum must be equal.


     * 
     * 

This implementation uses the {@link #getMinimumNumber()} and 
     * {@link #getMaximumNumber()} methods. 
     * Subclasses may be able to optimise this.


     *
     * @param obj the reference object with which to compare
     * @return true if this object is equal
     */
    public boolean equals(Object obj) {
        if (obj == this) {
            return true;
        } else if (obj == null || obj.getClass() != getClass()) {
            return false;
        } else {
            Range range = (Range) obj;
            return getMinimumNumber().equals(range.getMinimumNumber()) &&
                   getMaximumNumber().equals(range.getMaximumNumber());
        }
    }
    /**
     * 

Gets a hashCode for the range.


     * 
     * 

This implementation uses the {@link #getMinimumNumber()} and 
     * {@link #getMaximumNumber()} methods. 
     * Subclasses may be able to optimise this.


     *
     * @return a hash code value for this object
     */
    public int hashCode() {
        int result = 17;
        result = 37 * result + getClass().hashCode();
        result = 37 * result + getMinimumNumber().hashCode();
        result = 37 * result + getMaximumNumber().hashCode();
        return result;
    }
    /**
     * 

Gets the range as a String.


     *
     * 

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


     * 
     * 

This implementation uses the {@link #getMinimumNumber()} and 
     * {@link #getMaximumNumber()} methods. 
     * Subclasses may be able to optimise this.


     *
     * @return the String representation of this range
     */
    public String toString() {
        StringBuffer buf = new StringBuffer(32);
        buf.append("Range[");
        buf.append(getMinimumNumber());
        buf.append(',');
        buf.append(getMaximumNumber());
        buf.append(']');
        return buf.toString();
    }
    /**
     * 

Compares two doubles for order.


     *
     * 

This method is more comprehensive than the standard Java greater
     * than, less than and equals operators.


     * 

         *  
  • It returns -1 if the first value is less than the second.

  •      *  
  • It returns +1 if the first value is greater than the second.

  •      *  
  • It returns 0 if the values are equal.

  •      * 

     *
     * 


     * The ordering is as follows, largest to smallest:
     * 


         *  
  • NaN
         *  
  • Positive infinity
         *  
  • Maximum double
         *  
  • Normal positive numbers
         *  
  • +0.0
         *  
  • -0.0
         *  
  • Normal negative numbers
         *  
  • Minimum double (-Double.MAX_VALUE)
         *  
  • Negative infinity
         * 

     * 


     *
     * 

Comparing NaN with NaN will
     * return 0.


     * 
     * @param lhs  the first double
     * @param rhs  the second double
     * @return -1 if lhs is less, +1 if greater,
     *  0 if equal to rhs
     */
    public static int compare(double lhs, double rhs) {
        if (lhs < rhs) {
            return -1;
        }
        if (lhs > rhs) {
            return +1;
        }
        // Need to compare bits to handle 0.0 == -0.0 being true
        // compare should put -0.0 < +0.0
        // Two NaNs are also == for compare purposes
        // where NaN == NaN is false
        long lhsBits = Double.doubleToLongBits(lhs);
        long rhsBits = Double.doubleToLongBits(rhs);
        if (lhsBits == rhsBits) {
            return 0;
        }
        // Something exotic! A comparison to NaN or 0.0 vs -0.0
        // Fortunately NaN's long is > than everything else
        // Also negzeros bits < poszero
        // NAN: 9221120237041090560
        // MAX: 9218868437227405311
        // NEGZERO: -9223372036854775808
        if (lhsBits < rhsBits) {
            return -1;
        } else {
            return +1;
        }
    }
    
    /**
     * 

Compares two floats for order.


     *
     * 

This method is more comprehensive than the standard Java greater than,
     * less than and equals operators.


     * 

         *  
  • It returns -1 if the first value is less than the second.
         *  
  • It returns +1 if the first value is greater than the second.
         *  
  • It returns 0 if the values are equal.
         * 

     *
     * 

 The ordering is as follows, largest to smallest:
     * 


         * 
  • NaN
         * 
  • Positive infinity
         * 
  • Maximum float
         * 
  • Normal positive numbers
         * 
  • +0.0
         * 
  • -0.0
         * 
  • Normal negative numbers
         * 
  • Minimum float (-Float.MAX_VALUE)
         * 
  • Negative infinity
         * 

     *
     * 

Comparing NaN with NaN will return
     * 0.


     * 
     * @param lhs  the first float
     * @param rhs  the second float
     * @return -1 if lhs is less, +1 if greater,
     *  0 if equal to rhs
     */
    public static int compare(float lhs, float rhs) {
        if (lhs < rhs) {
            return -1;
        }
        if (lhs > rhs) {
            return +1;
        }
        //Need to compare bits to handle 0.0 == -0.0 being true
        // compare should put -0.0 < +0.0
        // Two NaNs are also == for compare purposes
        // where NaN == NaN is false
        int lhsBits = Float.floatToIntBits(lhs);
        int rhsBits = Float.floatToIntBits(rhs);
        if (lhsBits == rhsBits) {
            return 0;
        }
        //Something exotic! A comparison to NaN or 0.0 vs -0.0
        //Fortunately NaN's int is > than everything else
        //Also negzeros bits < poszero
        //NAN: 2143289344
        //MAX: 2139095039
        //NEGZERO: -2147483648
        if (lhsBits < rhsBits) {
            return -1;
        } else {
            return +1;
        }
    }
}