001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     * 
009     *      http://www.apache.org/licenses/LICENSE-2.0
010     * 
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    package org.apache.commons.lang.math;
018    
019    import java.io.Serializable;
020    
021    /**
022     * <p><code>DoubleRange</code> represents an inclusive range of <code>double</code>s.</p>
023     *
024     * @author Apache Software Foundation
025     * @since 2.0
026     * @version $Id: DoubleRange.java 905636 2010-02-02 14:03:32Z niallp $
027     */
028    public final class DoubleRange extends Range implements Serializable {
029        
030        /**
031         * Required for serialization support.
032         * 
033         * @see java.io.Serializable
034         */
035        private static final long serialVersionUID = 71849363892740L;
036    
037        /**
038         * The minimum number in this range (inclusive).
039         */
040        private final double min;
041        /**
042         * The maximum number in this range (inclusive).
043         */
044        private final double max;
045        
046        /**
047         * Cached output minObject (class is immutable).
048         */
049        private transient Double minObject = null;
050        /**
051         * Cached output maxObject (class is immutable).
052         */
053        private transient Double maxObject = null;
054        /**
055         * Cached output hashCode (class is immutable).
056         */
057        private transient int hashCode = 0;
058        /**
059         * Cached output toString (class is immutable).
060         */
061        private transient String toString = null;
062        
063        /**
064         * <p>Constructs a new <code>DoubleRange</code> using the specified
065         * number as both the minimum and maximum in this range.</p>
066         *
067         * @param number  the number to use for this range
068         * @throws IllegalArgumentException if the number is <code>NaN</code>
069         */
070        public DoubleRange(double number) {
071            super();
072            if (Double.isNaN(number)) {
073                throw new IllegalArgumentException("The number must not be NaN");
074            }
075            this.min = number;
076            this.max = number;
077        }
078    
079        /**
080         * <p>Constructs a new <code>DoubleRange</code> using the specified
081         * number as both the minimum and maximum in this range.</p>
082         *
083         * @param number  the number to use for this range, must not
084         *  be <code>null</code>
085         * @throws IllegalArgumentException if the number is <code>null</code>
086         * @throws IllegalArgumentException if the number is <code>NaN</code>
087         */
088        public DoubleRange(Number number) {
089            super();
090            if (number == null) {
091                throw new IllegalArgumentException("The number must not be null");
092            }
093            this.min = number.doubleValue();
094            this.max = number.doubleValue();
095            if (Double.isNaN(min) || Double.isNaN(max)) {
096                throw new IllegalArgumentException("The number must not be NaN");
097            }
098            if (number instanceof Double) {
099                this.minObject = (Double) number;
100                this.maxObject = (Double) number;
101            }
102        }
103    
104        /**
105         * <p>Constructs a new <code>DoubleRange</code> with the specified
106         * minimum and maximum numbers (both inclusive).</p>
107         * 
108         * <p>The arguments may be passed in the order (min,max) or (max,min). The
109         * getMinimum and getMaximum methods will return the correct values.</p>
110         * 
111         * @param number1  first number that defines the edge of the range, inclusive
112         * @param number2  second number that defines the edge of the range, inclusive
113         * @throws IllegalArgumentException if either number is <code>NaN</code>
114         */
115        public DoubleRange(double number1, double number2) {
116            super();
117            if (Double.isNaN(number1) || Double.isNaN(number2)) {
118                throw new IllegalArgumentException("The numbers must not be NaN");
119            }
120            if (number2 < number1) {
121                this.min = number2;
122                this.max = number1;
123            } else {
124                this.min = number1;
125                this.max = number2;
126            }
127        }
128    
129        /**
130         * <p>Constructs a new <code>DoubleRange</code> with the specified
131         * minimum and maximum numbers (both inclusive).</p>
132         * 
133         * <p>The arguments may be passed in the order (min,max) or (max,min). The
134         * getMinimum and getMaximum methods will return the correct values.</p>
135         *
136         * @param number1  first number that defines the edge of the range, inclusive
137         * @param number2  second number that defines the edge of the range, inclusive
138         * @throws IllegalArgumentException if either number is <code>null</code>
139         * @throws IllegalArgumentException if either number is <code>NaN</code>
140         */
141        public DoubleRange(Number number1, Number number2) {
142            super();
143            if (number1 == null || number2 == null) {
144                throw new IllegalArgumentException("The numbers must not be null");
145            }
146            double number1val = number1.doubleValue();
147            double number2val = number2.doubleValue();
148            if (Double.isNaN(number1val) || Double.isNaN(number2val)) {
149                throw new IllegalArgumentException("The numbers must not be NaN");
150            }
151            if (number2val < number1val) {
152                this.min = number2val;
153                this.max = number1val;
154                if (number2 instanceof Double) {
155                    this.minObject = (Double) number2;
156                }
157                if (number1 instanceof Double) {
158                    this.maxObject = (Double) number1;
159                }
160            } else {
161                this.min = number1val;
162                this.max = number2val;
163                if (number1 instanceof Double) {
164                    this.minObject = (Double) number1;
165                }
166                if (number2 instanceof Double) {
167                    this.maxObject = (Double) number2;
168                }
169            }
170        }
171    
172        // Accessors
173        //--------------------------------------------------------------------
174    
175        /**
176         * <p>Returns the minimum number in this range.</p>
177         *
178         * @return the minimum number in this range
179         */
180        public Number getMinimumNumber() {
181            if (minObject == null) {
182                minObject = new Double(min);            
183            }
184            return minObject;
185        }
186    
187        /**
188         * <p>Gets the minimum number in this range as a <code>long</code>.</p>
189         * 
190         * <p>This conversion can lose information for large values or decimals.</p>
191         *
192         * @return the minimum number in this range
193         */
194        public long getMinimumLong() {
195            return (long) min;
196        }
197    
198        /**
199         * <p>Gets the minimum number in this range as a <code>int</code>.</p>
200         * 
201         * <p>This conversion can lose information for large values or decimals.</p>
202         *
203         * @return the minimum number in this range
204         */
205        public int getMinimumInteger() {
206            return (int) min;
207        }
208    
209        /**
210         * <p>Gets the minimum number in this range as a <code>double</code>.</p>
211         *
212         * @return the minimum number in this range
213         */
214        public double getMinimumDouble() {
215            return min;
216        }
217    
218        /**
219         * <p>Gets the minimum number in this range as a <code>float</code>.</p>
220         * 
221         * <p>This conversion can lose information for large values.</p>
222         *
223         * @return the minimum number in this range
224         */
225        public float getMinimumFloat() {
226            return (float) min;
227        }
228    
229        /**
230         * <p>Returns the maximum number in this range.</p>
231         *
232         * @return the maximum number in this range
233         */
234        public Number getMaximumNumber() {
235            if (maxObject == null) {
236                maxObject = new Double(max);            
237            }
238            return maxObject;
239        }
240    
241        /**
242         * <p>Gets the maximum number in this range as a <code>long</code>.</p>
243         * 
244         * <p>This conversion can lose information for large values or decimals.</p>
245         *
246         * @return the maximum number in this range
247         */
248        public long getMaximumLong() {
249            return (long) max;
250        }
251    
252        /**
253         * <p>Gets the maximum number in this range as a <code>int</code>.</p>
254         * 
255         * <p>This conversion can lose information for large values or decimals.</p>
256         *
257         * @return the maximum number in this range
258         */
259        public int getMaximumInteger() {
260            return (int) max;
261        }
262    
263        /**
264         * <p>Gets the maximum number in this range as a <code>double</code>.</p>
265         *
266         * @return the maximum number in this range
267         */
268        public double getMaximumDouble() {
269            return max;
270        }
271    
272        /**
273         * <p>Gets the maximum number in this range as a <code>float</code>.</p>
274         * 
275         * <p>This conversion can lose information for large values.</p>
276         *
277         * @return the maximum number in this range
278         */
279        public float getMaximumFloat() {
280            return (float) max;
281        }
282    
283        // Tests
284        //--------------------------------------------------------------------
285        
286        /**
287         * <p>Tests whether the specified <code>number</code> occurs within
288         * this range using <code>double</code> comparison.</p>
289         * 
290         * <p><code>null</code> is handled and returns <code>false</code>.</p>
291         *
292         * @param number  the number to test, may be <code>null</code>
293         * @return <code>true</code> if the specified number occurs within this range
294         */
295        public boolean containsNumber(Number number) {
296            if (number == null) {
297                return false;
298            }
299            return containsDouble(number.doubleValue());
300        }
301    
302        /**
303         * <p>Tests whether the specified <code>double</code> occurs within
304         * this range using <code>double</code> comparison.</p>
305         * 
306         * <p>This implementation overrides the superclass for performance as it is
307         * the most common case.</p>
308         * 
309         * @param value  the double to test
310         * @return <code>true</code> if the specified number occurs within this
311         *  range by <code>double</code> comparison
312         */
313        public boolean containsDouble(double value) {
314            return value >= min && value <= max;
315        }
316    
317        // Range tests
318        //--------------------------------------------------------------------
319    
320        /**
321         * <p>Tests whether the specified range occurs entirely within this range
322         * using <code>double</code> comparison.</p>
323         * 
324         * <p><code>null</code> is handled and returns <code>false</code>.</p>
325         *
326         * @param range  the range to test, may be <code>null</code>
327         * @return <code>true</code> if the specified range occurs entirely within this range
328         * @throws IllegalArgumentException if the range is not of this type
329         */
330        public boolean containsRange(Range range) {
331            if (range == null) {
332                return false;
333            }
334            return containsDouble(range.getMinimumDouble())
335                && containsDouble(range.getMaximumDouble());
336        }
337    
338        /**
339         * <p>Tests whether the specified range overlaps with this range
340         * using <code>double</code> comparison.</p>
341         * 
342         * <p><code>null</code> is handled and returns <code>false</code>.</p>
343         *
344         * @param range  the range to test, may be <code>null</code>
345         * @return <code>true</code> if the specified range overlaps with this range
346         */
347        public boolean overlapsRange(Range range) {
348            if (range == null) {
349                return false;
350            }
351            return range.containsDouble(min)
352                || range.containsDouble(max)
353                || containsDouble(range.getMinimumDouble());
354        }
355    
356        // Basics
357        //--------------------------------------------------------------------
358    
359        /**
360         * <p>Compares this range to another object to test if they are equal.</p>.
361         * 
362         * <p>To be equal, the class, minimum and maximum must be equal.</p>
363         *
364         * @param obj the reference object with which to compare
365         * @return <code>true</code> if this object is equal
366         */
367        public boolean equals(Object obj) {
368            if (obj == this) {
369                return true;
370            }
371            if (obj instanceof DoubleRange == false) {
372                return false;
373            }
374            DoubleRange range = (DoubleRange) obj;
375            return (Double.doubleToLongBits(min) == Double.doubleToLongBits(range.min) &&
376                    Double.doubleToLongBits(max) == Double.doubleToLongBits(range.max));
377        }
378    
379        /**
380         * <p>Gets a hashCode for the range.</p>
381         *
382         * @return a hash code value for this object
383         */
384        public int hashCode() {
385            if (hashCode == 0) {
386                hashCode = 17;
387                hashCode = 37 * hashCode + getClass().hashCode();
388                long lng = Double.doubleToLongBits(min);
389                hashCode = 37 * hashCode + ((int) (lng ^ (lng >> 32)));
390                lng = Double.doubleToLongBits(max);
391                hashCode = 37 * hashCode + ((int) (lng ^ (lng >> 32)));
392            }
393            return hashCode;
394        }
395    
396        /**
397         * <p>Gets the range as a <code>String</code>.</p>
398         *
399         * <p>The format of the String is 'Range[<i>min</i>,<i>max</i>]'.</p>
400         *
401         * @return the <code>String</code> representation of this range
402         */
403        public String toString() {
404            if (toString == null) {
405                StringBuffer buf = new StringBuffer(32);
406                buf.append("Range[");
407                buf.append(min);
408                buf.append(',');
409                buf.append(max);
410                buf.append(']');
411                toString = buf.toString();
412            }
413            return toString;
414        }
415    
416    }