Range


1   /*
2    * Copyright 2002-2005 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.commons.lang.math;
17  
18  /**
19   * <p><code>Range</code> represents a range of numbers of the same type.</p>
20   * 
21   * <p>Specific subclasses hold the range values as different types. Each
22   * subclass should be immutable and {@link java.io.Serializable Serializable}
23   * if possible.</p>
24   *
25   * @author Stephen Colebourne
26   * @since 2.0
27   * @version $Id: Range.java 161243 2005-04-14 04:30:28Z ggregory $
28   */
29  public abstract class Range {
30  
31      /**
32       * <p>Constructs a new range.</p>
33       */
34      public Range() {
35          super();
36      }
37  
38      // Accessors
39      //--------------------------------------------------------------------
40  
41      /**
42       * <p>Gets the minimum number in this range.</p>
43       *
44       * @return the minimum number in this range
45       */
46      public abstract Number   getMinimumNumber();
47  
48      /**
49       * <p>Gets the minimum number in this range as a <code>long</code>.</p>
50       * 
51       * <p>This implementation uses the {@link #getMinimumNumber()} method. 
52       * Subclasses may be able to optimise this.</p>
53       *
54       * @return the minimum number in this range
55       */
56      public long getMinimumLong() {
57          return getMinimumNumber().longValue();
58      }
59  
60      /**
61       * <p>Gets the minimum number in this range as a <code>int</code>.</p>
62       * 
63       * <p>This implementation uses the {@link #getMinimumNumber()} method. 
64       * Subclasses may be able to optimise this.</p>
65       *
66       * @return the minimum number in this range
67       */
68      public int getMinimumInteger() {
69          return getMinimumNumber().intValue();
70      }
71  
72      /**
73       * <p>Gets the minimum number in this range as a <code>double</code>.</p>
74       * 
75       * <p>This implementation uses the {@link #getMinimumNumber()} method. 
76       * Subclasses may be able to optimise this.</p>
77       *
78       * @return the minimum number in this range
79       */
80      public double getMinimumDouble() {
81          return getMinimumNumber().doubleValue();
82      }
83  
84      /**
85       * <p>Gets the minimum number in this range as a <code>float</code>.</p>
86       * 
87       * <p>This implementation uses the {@link #getMinimumNumber()} method. 
88       * Subclasses may be able to optimise this.</p>
89       *
90       * @return the minimum number in this range
91       */
92      public float getMinimumFloat() {
93          return getMinimumNumber().floatValue();
94      }
95  
96      /**
97       * <p>Gets the maximum number in this range.</p>
98       *
99       * @return the maximum number in this range
100      */
101     public abstract Number   getMaximumNumber();
102 
103     /**
104      * <p>Gets the maximum number in this range as a <code>long</code>.</p>
105      * 
106      * <p>This implementation uses the {@link #getMaximumNumber()} method. 
107      * Subclasses may be able to optimise this.</p>
108      *
109      * @return the maximum number in this range
110      */
111     public long getMaximumLong() {
112         return getMaximumNumber().longValue();
113     }
114 
115     /**
116      * <p>Gets the maximum number in this range as a <code>int</code>.</p>
117      * 
118      * <p>This implementation uses the {@link #getMaximumNumber()} method. 
119      * Subclasses may be able to optimise this.</p>
120      *
121      * @return the maximum number in this range
122      */
123     public int getMaximumInteger() {
124         return getMaximumNumber().intValue();
125     }
126 
127     /**
128      * <p>Gets the maximum number in this range as a <code>double</code>.</p>
129      * 
130      * <p>This implementation uses the {@link #getMaximumNumber()} method. 
131      * Subclasses may be able to optimise this.</p>
132      *
133      * @return the maximum number in this range
134      */
135     public double getMaximumDouble() {
136         return getMaximumNumber().doubleValue();
137     }
138 
139     /**
140      * <p>Gets the maximum number in this range as a <code>float</code>.</p>
141      * 
142      * <p>This implementation uses the {@link #getMaximumNumber()} method. 
143      * Subclasses may be able to optimise this.</p>
144      *
145      * @return the maximum number in this range
146      */
147     public float getMaximumFloat() {
148         return getMaximumNumber().floatValue();
149     }
150 
151     // Include tests
152     //--------------------------------------------------------------------
153     
154     /**
155      * <p>Tests whether the specified <code>Number</code> occurs within
156      * this range.</p>
157      * 
158      * <p>The exact comparison implementation varies by subclass. It is
159      * intended that an <code>int</code> specific subclass will compare using
160      * <code>int</code> comparison.</p>
161      * 
162      * <p><code>null</code> is handled and returns <code>false</code>.</p>
163      *
164      * @param number  the number to test, may be <code>null</code>
165      * @return <code>true</code> if the specified number occurs within this range
166      * @throws IllegalArgumentException if the <code>Number</code> cannot be compared
167      */
168     public abstract boolean containsNumber(Number   number);
169 
170     /**
171      * <p>Tests whether the specified <code>Number</code> occurs within
172      * this range using <code>long</code> comparison..</p>
173      * 
174      * <p><code>null</code> is handled and returns <code>false</code>.</p>
175      * 
176      * <p>This implementation forwards to the {@link #containsLong(long)} method.</p>
177      *
178      * @param value  the long to test, may be <code>null</code>
179      * @return <code>true</code> if the specified number occurs within this
180      *  range by <code>long</code> comparison
181      */
182     public boolean containsLong(Number   value) {
183         if (value == null) {
184             return false;
185         }
186         return containsLong(value.longValue());
187     }
188 
189     /**
190      * <p>Tests whether the specified <code>long</code> occurs within
191      * this range using <code>long</code> comparison.</p>
192      * 
193      * <p>This implementation uses the {@link #getMinimumLong()} and 
194      * {@link #getMaximumLong()} methods and should be good for most uses.</p>
195      * 
196      * @param value  the long to test
197      * @return <code>true</code> if the specified number occurs within this
198      *  range by <code>long</code> comparison
199      */
200     public boolean containsLong(long value) {
201         return value >= getMinimumLong() && value <= getMaximumLong();
202     }
203 
204     /**
205      * <p>Tests whether the specified <code>Number</code> occurs within
206      * this range using <code>int</code> comparison..</p>
207      * 
208      * <p><code>null</code> is handled and returns <code>false</code>.</p>
209      * 
210      * <p>This implementation forwards to the {@link #containsInteger(int)} method.</p>
211      *
212      * @param value  the integer to test, may be <code>null</code>
213      * @return <code>true</code> if the specified number occurs within this
214      *  range by <code>int</code> comparison
215      */
216     public boolean containsInteger(Number   value) {
217         if (value == null) {
218             return false;
219         }
220         return containsInteger(value.intValue());
221     }
222 
223     /**
224      * <p>Tests whether the specified <code>int</code> occurs within
225      * this range using <code>int</code> comparison.</p>
226      * 
227      * <p>This implementation uses the {@link #getMinimumInteger()} and 
228      * {@link #getMaximumInteger()} methods and should be good for most uses.</p>
229      * 
230      * @param value  the int to test
231      * @return <code>true</code> if the specified number occurs within this
232      *  range by <code>int</code> comparison
233      */
234     public boolean containsInteger(int value) {
235         return value >= getMinimumInteger() && value <= getMaximumInteger();
236     }
237 
238     /**
239      * <p>Tests whether the specified <code>Number</code> occurs within
240      * this range using <code>double</code> comparison..</p>
241      * 
242      * <p><code>null</code> is handled and returns <code>false</code>.</p>
243      * 
244      * <p>This implementation forwards to the {@link #containsDouble(double)} method.</p>
245      *
246      * @param value  the double to test, may be <code>null</code>
247      * @return <code>true</code> if the specified number occurs within this
248      *  range by <code>double</code> comparison
249      */
250     public boolean containsDouble(Number   value) {
251         if (value == null) {
252             return false;
253         }
254         return containsDouble(value.doubleValue());
255     }
256 
257     /**
258      * <p>Tests whether the specified <code>double</code> occurs within
259      * this range using <code>double</code> comparison.</p>
260      * 
261      * <p>This implementation uses the {@link #getMinimumDouble()} and 
262      * {@link #getMaximumDouble()} methods and should be good for most uses.</p>
263      * 
264      * @param value  the double to test
265      * @return <code>true</code> if the specified number occurs within this
266      *  range by <code>double</code> comparison
267      */
268     public boolean containsDouble(double value) {
269         int compareMin = NumberUtils.compare(getMinimumDouble(), value);
270         int compareMax = NumberUtils.compare(getMaximumDouble(), value);
271         return compareMin <= 0 && compareMax >= 0;
272     }
273 
274     /**
275      * <p>Tests whether the specified <code>Number</code> occurs within
276      * this range using <code>float</code> comparison.</p>
277      * 
278      * <p><code>null</code> is handled and returns <code>false</code>.</p>
279      * 
280      * <p>This implementation forwards to the {@link #containsFloat(float)} method.</p>
281      *
282      * @param value  the float to test, may be <code>null</code>
283      * @return <code>true</code> if the specified number occurs within this
284      *  range by <code>float</code> comparison
285      */
286     public boolean containsFloat(Number   value) {
287         if (value == null) {
288             return false;
289         }
290         return containsFloat(value.floatValue());
291     }
292 
293     /**
294      * <p>Tests whether the specified <code>float</code> occurs within
295      * this range using <code>float</code> comparison.</p>
296      * 
297      * <p>This implementation uses the {@link #getMinimumFloat()} and 
298      * {@link #getMaximumFloat()} methods and should be good for most uses.</p>
299      * 
300      * @param value  the float to test
301      * @return <code>true</code> if the specified number occurs within this
302      *  range by <code>float</code> comparison
303      */
304     public boolean containsFloat(float value) {
305         int compareMin = NumberUtils.compare(getMinimumFloat(), value);
306         int compareMax = NumberUtils.compare(getMaximumFloat(), value);
307         return compareMin <= 0 && compareMax >= 0;
308     }
309 
310     // Range tests
311     //--------------------------------------------------------------------
312 
313     /**
314      * <p>Tests whether the specified range occurs entirely within this range.</p>
315      * 
316      * <p>The exact comparison implementation varies by subclass. It is
317      * intended that an <code>int</code> specific subclass will compare using
318      * <code>int</code> comparison.</p>
319      * 
320      * <p><code>null</code> is handled and returns <code>false</code>.</p>
321      * 
322      * <p>This implementation uses the {@link #containsNumber(Number)} method.
323      * Subclasses may be able to optimise this.</p>
324      *
325      * @param range  the range to test, may be <code>null</code>
326      * @return <code>true</code> if the specified range occurs entirely within
327      *  this range; otherwise, <code>false</code>
328      * @throws IllegalArgumentException if the <code>Range</code> cannot be compared
329      */
330     public boolean containsRange(Range range) {
331         if (range == null) {
332             return false;
333         }
334         return containsNumber(range.getMinimumNumber()) 
335             && containsNumber(range.getMaximumNumber());
336     }
337 
338     /**
339      * <p>Tests whether the specified range overlaps with this range.</p>
340      * 
341      * <p>The exact comparison implementation varies by subclass. It is
342      * intended that an <code>int</code> specific subclass will compare using
343      * <code>int</code> comparison.</p>
344      * 
345      * <p><code>null</code> is handled and returns <code>false</code>.</p>
346      * 
347      * <p>This implementation uses the {@link #containsNumber(Number)} and
348      * {@link #containsRange(Range)} methods.
349      * Subclasses may be able to optimise this.</p>
350      *
351      * @param range  the range to test, may be <code>null</code>
352      * @return <code>true</code> if the specified range overlaps with this
353      *  range; otherwise, <code>false</code>
354      * @throws IllegalArgumentException if the <code>Range</code> cannot be compared
355      */
356     public boolean overlapsRange(Range range) {
357         if (range == null) {
358             return false;
359         }
360         return range.containsNumber(getMinimumNumber())
361             || range.containsNumber(getMaximumNumber())
362             || containsNumber(range.getMinimumNumber());
363     }
364 
365     // Basics
366     //--------------------------------------------------------------------
367 
368     /**
369      * <p>Compares this range to another object to test if they are equal.</p>.
370      * 
371      * <p>To be equal, the class, minimum and maximum must be equal.</p>
372      * 
373      * <p>This implementation uses the {@link #getMinimumNumber()} and 
374      * {@link #getMaximumNumber()} methods. 
375      * Subclasses may be able to optimise this.</p>
376      *
377      * @param obj the reference object with which to compare
378      * @return <code>true</code> if this object is equal
379      */
380     public boolean equals(Object   obj) {
381         if (obj == this) {
382             return true;
383         } else if (obj == null || obj.getClass() != getClass()) {
384             return false;
385         } else {
386             Range range = (Range) obj;
387             return getMinimumNumber().equals(range.getMinimumNumber()) &&
388                    getMaximumNumber().equals(range.getMaximumNumber());
389         }
390     }
391 
392     /**
393      * <p>Gets a hashCode for the range.</p>
394      * 
395      * <p>This implementation uses the {@link #getMinimumNumber()} and 
396      * {@link #getMaximumNumber()} methods. 
397      * Subclasses may be able to optimise this.</p>
398      *
399      * @return a hash code value for this object
400      */
401     public int hashCode() {
402         int result = 17;
403         result = 37 * result + getClass().hashCode();
404         result = 37 * result + getMinimumNumber().hashCode();
405         result = 37 * result + getMaximumNumber().hashCode();
406         return result;
407     }
408 
409     /**
410      * <p>Gets the range as a <code>String</code>.</p>
411      *
412      * <p>The format of the String is 'Range[<i>min</i>,<i>max</i>]'.</p>
413      * 
414      * <p>This implementation uses the {@link #getMinimumNumber()} and 
415      * {@link #getMaximumNumber()} methods. 
416      * Subclasses may be able to optimise this.</p>
417      *
418      * @return the <code>String</code> representation of this range
419      */
420     public String   toString() {
421         StringBuffer   buf = new StringBuffer  (32);
422         buf.append("Range[");
423         buf.append(getMinimumNumber());
424         buf.append(',');
425         buf.append(getMaximumNumber());
426         buf.append(']');
427         return buf.toString();
428     }
429 
430 }
431
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags