Number


1   /*
2    * JScience - Java(TM) Tools and Libraries for the Advancement of Sciences.
3    * Copyright (C) 2006 - JScience (http://jscience.org/)
4    * All rights reserved.
5    * 
6    * Permission to use, copy, modify, and distribute this software is
7    * freely granted, provided that this notice is preserved.
8    */
9   package org.jscience.mathematics.numbers;
10  
11  import org.jscience.mathematics.structures.Ring;
12  import javolution.lang.Immutable;
13  import javolution.text.Text;
14  import javolution.context.RealtimeObject;
15  
16  /**
17   * <p> This class represents an immutable number.</p>
18   * 
19   * <p> Instances of this class are typically created using real-time 
20   *     {@link javolution.context.RealtimeObject.Factory factories}.</p>
21   *
22   * @author <a HREF="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
23   * @version 3.0, February 13, 2006
24   * @see <a HREF="http://en.wikipedia.org/wiki/Number">
25   *      Wikipedia: Number</a>
26   */
27  public abstract class Number<T extends Number  <T>> extends RealtimeObject
28          implements Ring<T>, Comparable  <T>, Immutable {
29  
30      /**
31       * Compares the magnitude of this number with that number.
32       *
33       * @return <code>|this| > |that|</code>
34       */
35      public abstract boolean isLargerThan(T that);
36  
37      /**
38       * Returns the value of this number as a <code>long</code>.
39       *
40       * @return  the numeric value represented by this object after conversion
41       *          to type <code>long</code>.
42       */
43      public abstract long longValue();
44  
45      /**
46       * Returns the value of this number as a <code>double</code>.
47       *
48       * @return  the numeric value represented by this object after conversion
49       *          to type <code>double</code>.
50       */
51      public abstract double doubleValue();
52  
53      /**
54       * Compares this number with the specified number for order.  Returns a
55       * negative integer, zero, or a positive integer as this number is less
56       * than, equal to, or greater than the specified number. 
57       * Implementation must ensure that this method is consistent with equals 
58       * <code>(x.compareTo(y)==0) == (x.equals(y))</code>,  
59       * 
60       * @param that the number to be compared.
61       * @return a negative integer, zero, or a positive integer as this number
62       *        is less than, equal to, or greater than the specified number.
63       */
64      public abstract int compareTo(T that);
65  
66      /**
67       * Indicates if this number is ordered before that number
68       * (convenience method).
69       *
70       * @return <code>this.compareTo(that) < 0</code>.
71       */
72      public final boolean isLessThan(T that) {
73          return this.compareTo(that) < 0;
74      }
75  
76      /**
77       * Indicates if this number is ordered after that number
78       * (convenience method).
79       *
80       * @return <code>this.compareTo(that) > 0</code>.
81       */
82      public final boolean isGreaterThan(T that) {
83          return this.compareTo(that) > 0;
84      }
85  
86      /**
87       * Returns the difference between this number and the one specified.
88       *
89       * @param  that the number to be subtracted.
90       * @return <code>this - that</code>.
91       */
92      public T minus(T that) {
93          return this.plus(that.opposite());
94      }
95  
96      /**
97       * Returns this number raised at the specified positive exponent.
98       *
99       * @param  exp the positive exponent.
100      * @return <code>this<sup>exp</sup></code>
101      * @throws IllegalArgumentException if <code>exp &lt;= 0</code> 
102      */
103     @SuppressWarnings  ("unchecked")
104     public T pow(int exp) {
105         if (exp <= 0)
106             throw new IllegalArgumentException  ("exp: " + exp
107                     + " should be a positive number");
108         T pow2 = (T) this;
109         T result = null;
110         while (exp >= 1) { // Iteration.
111             if ((exp & 1) == 1) {
112                 result = (result == null) ? pow2 : result.times(pow2);
113             }
114             pow2 = pow2.times(pow2);
115             exp >>>= 1;
116         }
117         return result;
118     }
119 
120     /**
121      * Returns the value of this number as a <code>byte</code>.
122      * This may involve rounding or truncation.
123      *
124      * @return  the numeric value represented by this object after conversion
125      *          to type <code>byte</code>.
126      */
127     public final byte byteValue() {
128         return (byte) longValue();
129     }
130 
131     /**
132      * Returns the value of this number as a <code>short</code>.
133      * This may involve rounding or truncation.
134      *
135      * @return  the numeric value represented by this object after conversion
136      *          to type <code>short</code>.
137      */
138     public final short shortValue() {
139         return (short) longValue();
140     }
141 
142     /**
143      * Returns the value of this number as an <code>int</code>.
144      * This may involve rounding or truncation.
145      *
146      * @return  the numeric value represented by this object after conversion
147      *          to type <code>int</code>.
148      */
149     public final int intValue() {
150         return (int) longValue();
151     }
152 
153     /**
154      * Returns the value of this number as a <code>float</code>.
155      * This may involve rounding.
156      *
157      * @return  the numeric value represented by this object after conversion
158      *          to type <code>float</code>.
159      */
160     public final float floatValue() {
161         return (float) doubleValue();
162     }
163     /**
164      * Indicates if this number is equals to the specified object.
165      *
166      * @param obj the object to be compared with.
167      * @return <code>true</code> if this number and the specified argument
168      *         represent the same number; <code>false</code> otherwise.
169      */
170     public abstract boolean equals(Object   obj);
171 
172     /**
173      * Returns the hash code for this number (consistent with 
174      * {@link #equals(Object)}.
175      *
176      * @return this number hash code.
177      */
178     public abstract int hashCode();
179 
180     /**
181      * Returns the textual representation of this real-time object
182      * (equivalent to <code>toString</code> except that the returned value
183      * can be allocated from the local context space).
184      * 
185      * @return this object's textual representation.
186      */
187     public abstract Text toText();
188 
189     /**
190      * Moves this real-time object to the specified object space.
191      * 
192      * @param os the object space to move this real-time object to.
193      * @return <code>true</code> if the move has to be propagated to 
194      *         external real-time references; <code>false</code> otherwise.
195      */
196     public boolean move(ObjectSpace os) {
197         return super.move(os);
198     }
199 
200 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags