LongRange


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  import java.io.Serializable  ;
19  
20  /**
21   * <p><code>LongRange</code> represents an inclusive range of <code>long</code>s.</p>
22   *
23   * @author Stephen Colebourne
24   * @since 2.0
25   * @version $Id: LongRange.java 161243 2005-04-14 04:30:28Z ggregory $
26   */
27  public final class LongRange extends Range implements Serializable   {
28      
29      private static final long serialVersionUID = 71849363892720L;
30  
31      /**
32       * The minimum number in this range (inclusive).
33       */
34      private final long min;
35      /**
36       * The maximum number in this range (inclusive).
37       */
38      private final long max;
39      
40      /**
41       * Cached output minObject (class is immutable).
42       */
43      private transient Long   minObject = null;
44      /**
45       * Cached output maxObject (class is immutable).
46       */
47      private transient Long   maxObject = null;
48      /**
49       * Cached output hashCode (class is immutable).
50       */
51      private transient int hashCode = 0;
52      /**
53       * Cached output toString (class is immutable).
54       */
55      private transient String   toString = null;
56      
57      /**
58       * <p>Constructs a new <code>LongRange</code> using the specified
59       * number as both the minimum and maximum in this range.</p>
60       *
61       * @param number  the number to use for this range
62       */
63      public LongRange(long number) {
64          super();
65          this.min = number;
66          this.max = number;
67      }
68  
69      /**
70       * <p>Constructs a new <code>LongRange</code> using the specified
71       * number as both the minimum and maximum in this range.</p>
72       *
73       * @param number  the number to use for this range, must not
74       *  be <code>null</code>
75       * @throws IllegalArgumentException if the number is <code>null</code>
76       */
77      public LongRange(Number   number) {
78          super();
79          if (number == null) {
80              throw new IllegalArgumentException  ("The number must not be null");
81          }
82          this.min = number.longValue();
83          this.max = number.longValue();
84          if (number instanceof Long  ) {
85              this.minObject = (Long  ) number;
86              this.maxObject = (Long  ) number;
87          }
88      }
89  
90      /**
91       * <p>Constructs a new <code>LongRange</code> with the specified
92       * minimum and maximum numbers (both inclusive).</p>
93       * 
94       * <p>The arguments may be passed in the order (min,max) or (max,min). The
95       * getMinimum and getMaximum methods will return the correct values.</p>
96       * 
97       * @param number1  first number that defines the edge of the range, inclusive
98       * @param number2  second number that defines the edge of the range, inclusive
99       */
100     public LongRange(long number1, long number2) {
101         super();
102         if (number2 < number1) {
103             this.min = number2;
104             this.max = number1;
105         } else {
106             this.min = number1;
107             this.max = number2;
108         }
109     }
110 
111     /**
112      * <p>Constructs a new <code>LongRange</code> with the specified
113      * minimum and maximum numbers (both inclusive).</p>
114      * 
115      * <p>The arguments may be passed in the order (min,max) or (max,min). The
116      * getMinimum and getMaximum methods will return the correct values.</p>
117      *
118      * @param number1  first number that defines the edge of the range, inclusive
119      * @param number2  second number that defines the edge of the range, inclusive
120      * @throws IllegalArgumentException if either number is <code>null</code>
121      */
122     public LongRange(Number   number1, Number   number2) {
123         super();
124         if (number1 == null || number2 == null) {
125             throw new IllegalArgumentException  ("The numbers must not be null");
126         }
127         long number1val = number1.longValue();
128         long number2val = number2.longValue();
129         if (number2val < number1val) {
130             this.min = number2val;
131             this.max = number1val;
132             if (number2 instanceof Long  ) {
133                 this.minObject = (Long  ) number2;
134             }
135             if (number1 instanceof Long  ) {
136                 this.maxObject = (Long  ) number1;
137             }
138         } else {
139             this.min = number1val;
140             this.max = number2val;
141             if (number1 instanceof Long  ) {
142                 this.minObject = (Long  ) number1;
143             }
144             if (number2 instanceof Long  ) {
145                 this.maxObject = (Long  ) number2;
146             }
147         }
148     }
149 
150     // Accessors
151     //--------------------------------------------------------------------
152 
153     /**
154      * <p>Returns the minimum number in this range.</p>
155      *
156      * @return the minimum number in this range
157      */
158     public Number   getMinimumNumber() {
159         if (minObject == null) {
160             minObject = new Long  (min);            
161         }
162         return minObject;
163     }
164 
165     /**
166      * <p>Gets the minimum number in this range as a <code>long</code>.</p>
167      *
168      * @return the minimum number in this range
169      */
170     public long getMinimumLong() {
171         return min;
172     }
173 
174     /**
175      * <p>Gets the minimum number in this range as a <code>int</code>.</p>
176      * 
177      * <p>This conversion can lose information for large values.</p>
178      *
179      * @return the minimum number in this range
180      */
181     public int getMinimumInteger() {
182         return (int) min;
183     }
184 
185     /**
186      * <p>Gets the minimum number in this range as a <code>double</code>.</p>
187      * 
188      * <p>This conversion can lose information for large values.</p>
189      *
190      * @return the minimum number in this range
191      */
192     public double getMinimumDouble() {
193         return min;
194     }
195 
196     /**
197      * <p>Gets the minimum number in this range as a <code>float</code>.</p>
198      * 
199      * <p>This conversion can lose information for large values.</p>
200      *
201      * @return the minimum number in this range
202      */
203     public float getMinimumFloat() {
204         return min;
205     }
206 
207     /**
208      * <p>Returns the maximum number in this range.</p>
209      *
210      * @return the maximum number in this range
211      */
212     public Number   getMaximumNumber() {
213         if (maxObject == null) {
214             maxObject = new Long  (max);            
215         }
216         return maxObject;
217     }
218 
219     /**
220      * <p>Gets the maximum number in this range as a <code>long</code>.</p>
221      *
222      * @return the maximum number in this range
223      */
224     public long getMaximumLong() {
225         return max;
226     }
227 
228     /**
229      * <p>Gets the maximum number in this range cast to an <code>int</code>.</p>
230      * 
231      * <p>This conversion can lose information for large values.</p>
232      * 
233      * @return the maximum number in this range cast to an <code>int</code>.
234      */
235     public int getMaximumInteger() {
236         return (int) max;
237     }
238 
239     /**
240      * <p>Gets the maximum number in this range as a <code>double</code>.</p>
241      * 
242      * <p>This conversion can lose information for large values.</p>
243      * 
244      * @return The maximum number in this range as a <code>double</code>.
245      */
246     public double getMaximumDouble() {
247         return max;
248     }
249 
250     /**
251      * <p>Gets the maximum number in this range as a <code>float</code>.</p>
252      * 
253      * <p>This conversion can lose information for large values.</p>
254      * 
255      * @return The maximum number in this range as a <code>float</code>.
256      */
257     public float getMaximumFloat() {
258         return max;
259     }
260 
261     // Tests
262     //--------------------------------------------------------------------
263     
264     /**
265      * <p>Tests whether the specified <code>number</code> occurs within
266      * this range using <code>long</code> comparison.</p>
267      * 
268      * <p><code>null</code> is handled and returns <code>false</code>.</p>
269      *
270      * @param number  the number to test, may be <code>null</code>
271      * @return <code>true</code> if the specified number occurs within this range
272      */
273     public boolean containsNumber(Number   number) {
274         if (number == null) {
275             return false;
276         }
277         return containsLong(number.longValue());
278     }
279 
280     /**
281      * <p>Tests whether the specified <code>long</code> occurs within
282      * this range using <code>long</code> comparison.</p>
283      * 
284      * <p>This implementation overrides the superclass for performance as it is
285      * the most common case.</p>
286      * 
287      * @param value  the long to test
288      * @return <code>true</code> if the specified number occurs within this
289      *  range by <code>long</code> comparison
290      */
291     public boolean containsLong(long value) {
292         return value >= min && value <= max;
293     }
294 
295     // Range tests
296     //--------------------------------------------------------------------
297 
298     /**
299      * <p>Tests whether the specified range occurs entirely within this range
300      * using <code>long</code> comparison.</p>
301      * 
302      * <p><code>null</code> is handled and returns <code>false</code>.</p>
303      *
304      * @param range  the range to test, may be <code>null</code>
305      * @return <code>true</code> if the specified range occurs entirely within this range
306      * @throws IllegalArgumentException if the range is not of this type
307      */
308     public boolean containsRange(Range range) {
309         if (range == null) {
310             return false;
311         }
312         return containsLong(range.getMinimumLong()) &&
313                containsLong(range.getMaximumLong());
314     }
315 
316     /**
317      * <p>Tests whether the specified range overlaps with this range
318      * using <code>long</code> comparison.</p>
319      * 
320      * <p><code>null</code> is handled and returns <code>false</code>.</p>
321      *
322      * @param range  the range to test, may be <code>null</code>
323      * @return <code>true</code> if the specified range overlaps with this range
324      */
325     public boolean overlapsRange(Range range) {
326         if (range == null) {
327             return false;
328         }
329         return range.containsLong(min) ||
330                range.containsLong(max) || 
331                containsLong(range.getMinimumLong());
332     }
333 
334     // Basics
335     //--------------------------------------------------------------------
336 
337     /**
338      * <p>Compares this range to another object to test if they are equal.</p>.
339      * 
340      * <p>To be equal, the class, minimum and maximum must be equal.</p>
341      *
342      * @param obj the reference object with which to compare
343      * @return <code>true</code> if this object is equal
344      */
345     public boolean equals(Object   obj) {
346         if (obj == this) {
347             return true;
348         }
349         if (obj instanceof LongRange == false) {
350             return false;
351         }
352         LongRange range = (LongRange) obj;
353         return min == range.min && max == range.max;
354     }
355 
356     /**
357      * <p>Gets a hashCode for the range.</p>
358      *
359      * @return a hash code value for this object
360      */
361     public int hashCode() {
362         if (hashCode == 0) {
363             hashCode = 17;
364             hashCode = 37 * hashCode + getClass().hashCode();
365             hashCode = 37 * hashCode + ((int) (min ^ (min >> 32)));
366             hashCode = 37 * hashCode + ((int) (max ^ (max >> 32)));
367         }
368         return hashCode;
369     }
370 
371     /**
372      * <p>Gets the range as a <code>String</code>.</p>
373      *
374      * <p>The format of the String is 'Range[<i>min</i>,<i>max</i>]'.</p>
375      *
376      * @return the <code>String</code> representation of this range
377      */
378     public String   toString() {
379         if (toString == null) {
380             StringBuffer   buf = new StringBuffer  (32);
381             buf.append("Range[");
382             buf.append(min);
383             buf.append(',');
384             buf.append(max);
385             buf.append(']');
386             toString = buf.toString();
387         }
388         return toString;
389     }
390 
391 }
392
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags