1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.lang.math;
18
19 import java.io.Serializable;
20
21 /**
22 * <p><code>DoubleRange</code> represents an inclusive range of <code>double</code>s.</p>
23 *
24 * @author Stephen Colebourne
25 * @since 2.0
26 * @version $Id: DoubleRange.java 437554 2006-08-28 06:21:41Z bayard $
27 */
28 public final class DoubleRange extends Range implements Serializable {
29
30 /**
31 * Required for serialization support.
32 *
33 * @see java.io.Serializable
34 */
35 private static final long serialVersionUID = 71849363892740L;
36
37 /**
38 * The minimum number in this range (inclusive).
39 */
40 private final double min;
41 /**
42 * The maximum number in this range (inclusive).
43 */
44 private final double max;
45
46 /**
47 * Cached output minObject (class is immutable).
48 */
49 private transient Double minObject = null;
50 /**
51 * Cached output maxObject (class is immutable).
52 */
53 private transient Double maxObject = null;
54 /**
55 * Cached output hashCode (class is immutable).
56 */
57 private transient int hashCode = 0;
58 /**
59 * Cached output toString (class is immutable).
60 */
61 private transient String toString = null;
62
63 /**
64 * <p>Constructs a new <code>DoubleRange</code> using the specified
65 * number as both the minimum and maximum in this range.</p>
66 *
67 * @param number the number to use for this range
68 * @throws IllegalArgumentException if the number is <code>NaN</code>
69 */
70 public DoubleRange(double number) {
71 super();
72 if (Double.isNaN(number)) {
73 throw new IllegalArgumentException("The number must not be NaN");
74 }
75 this.min = number;
76 this.max = number;
77 }
78
79 /**
80 * <p>Constructs a new <code>DoubleRange</code> using the specified
81 * number as both the minimum and maximum in this range.</p>
82 *
83 * @param number the number to use for this range, must not
84 * be <code>null</code>
85 * @throws IllegalArgumentException if the number is <code>null</code>
86 * @throws IllegalArgumentException if the number is <code>NaN</code>
87 */
88 public DoubleRange(Number number) {
89 super();
90 if (number == null) {
91 throw new IllegalArgumentException("The number must not be null");
92 }
93 this.min = number.doubleValue();
94 this.max = number.doubleValue();
95 if (Double.isNaN(min) || Double.isNaN(max)) {
96 throw new IllegalArgumentException("The number must not be NaN");
97 }
98 if (number instanceof Double) {
99 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 }