001: /*
002: * JScience - Java(TM) Tools and Libraries for the Advancement of Sciences.
003: * Copyright (C) 2006 - JScience (http://jscience.org/)
004: * All rights reserved.
005: *
006: * Permission to use, copy, modify, and distribute this software is
007: * freely granted, provided that this notice is preserved.
008: */
009: package org.jscience.mathematics.number;
010:
011: import org.jscience.mathematics.structure.Ring;
012: import javolution.lang.Realtime;
013: import javolution.text.Text;
014: import javolution.xml.XMLSerializable;
015:
016: /**
017: * <p> This class represents a {@link javolution.lang.ValueType value-type}
018: * number.</p>
019: *
020: * @author <a href="mailto:jean-marie@dautelle.com">Jean-Marie Dautelle</a>
021: * @version 3.0, February 13, 2006
022: * @see <a href="http://en.wikipedia.org/wiki/Number">
023: * Wikipedia: Number</a>
024: */
025: public abstract class Number<T extends Number<T>> extends
026: java.lang.Number implements Ring<T>, Comparable<T>, Realtime,
027: XMLSerializable {
028:
029: /**
030: * Compares the magnitude of this number with that number.
031: *
032: * @return <code>|this| > |that|</code>
033: */
034: public abstract boolean isLargerThan(T that);
035:
036: /**
037: * Returns the value of this number as a <code>long</code>.
038: *
039: * @return the numeric value represented by this object after conversion
040: * to type <code>long</code>.
041: */
042: public abstract long longValue();
043:
044: /**
045: * Returns the value of this number as a <code>double</code>.
046: *
047: * @return the numeric value represented by this object after conversion
048: * to type <code>double</code>.
049: */
050: public abstract double doubleValue();
051:
052: /**
053: * Compares this number with the specified number for order. Returns a
054: * negative integer, zero, or a positive integer as this number is less
055: * than, equal to, or greater than the specified number.
056: * Implementation must ensure that this method is consistent with equals
057: * <code>(x.compareTo(y)==0) == (x.equals(y))</code>,
058: *
059: * @param that the number to be compared.
060: * @return a negative integer, zero, or a positive integer as this number
061: * is less than, equal to, or greater than the specified number.
062: */
063: public abstract int compareTo(T that);
064:
065: /**
066: * Indicates if this number is ordered before that number
067: * (convenience method).
068: *
069: * @param that the number to compare with.
070: * @return <code>this.compareTo(that) < 0</code>.
071: */
072: public final boolean isLessThan(T that) {
073: return this .compareTo(that) < 0;
074: }
075:
076: /**
077: * Indicates if this number is ordered after that number
078: * (convenience method).
079: *
080: * @param that the number to compare with.
081: * @return <code>this.compareTo(that) > 0</code>.
082: */
083: public final boolean isGreaterThan(T that) {
084: return this .compareTo(that) > 0;
085: }
086:
087: /**
088: * Returns the difference between this number and the one specified.
089: *
090: * @param that the number to be subtracted.
091: * @return <code>this - that</code>.
092: */
093: public T minus(T that) {
094: return this .plus(that.opposite());
095: }
096:
097: /**
098: * Returns this number raised at the specified positive exponent.
099: *
100: * @param exp the positive exponent.
101: * @return <code>this<sup>exp</sup></code>
102: * @throws IllegalArgumentException if <code>exp <= 0</code>
103: */
104: @SuppressWarnings("unchecked")
105: public T pow(int exp) {
106: if (exp <= 0)
107: throw new IllegalArgumentException("exp: " + exp
108: + " should be a positive number");
109: final T t = (T) this ;
110: if (exp == 1)
111: return t;
112: if (exp == 2)
113: return t.times(t);
114: if (exp == 3)
115: return t.times(t).times(t);
116: int halfExp = exp >> 1;
117: return this .pow(halfExp).times(this .pow(exp - halfExp));
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: /**
165: * Indicates if this number is equals to the specified object.
166: *
167: * @param obj the object to be compared with.
168: * @return <code>true</code> if this number and the specified argument
169: * represent the same number; <code>false</code> otherwise.
170: */
171: public abstract boolean equals(Object obj);
172:
173: /**
174: * Returns the hash code for this number (consistent with
175: * {@link #equals(Object)}.
176: *
177: * @return this number hash code.
178: */
179: public abstract int hashCode();
180:
181: /**
182: * Returns the textual representation of this real-time object
183: * (equivalent to <code>toString</code> except that the returned value
184: * can be allocated from the local context space).
185: *
186: * @return this object's textual representation.
187: */
188: public abstract Text toText();
189:
190: /**
191: * Returns a copy of this number
192: * {@link javolution.context.AllocatorContext allocated}
193: * by the calling thread (possibly on the stack).
194: *
195: * @return an identical and independant copy of this number.
196: */
197: public abstract Number<T> copy();
198:
199: /**
200: * Returns the text representation of this number as a
201: * <code>java.lang.String</code>.
202: *
203: * @return <code>toText().toString()</code>
204: */
205: public final String toString() {
206: return toText().toString();
207: }
208:
209: }
|