Package org.apache.sis.math
Class Fraction
java.lang.Object
java.lang.Number
org.apache.sis.math.Fraction
- All Implemented Interfaces:
Serializable
,Comparable<Fraction>
A value class for rational numbers.
Fraction
objects are represented by a numerator and
a denominator stored at 32 bits integers. Fractions can be simplified.
All Fraction
instances are immutable and thus inherently thread-safe.- Since:
- 0.8
- Version:
- 1.0
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionfinal int
The b term in the a/b fraction.final int
The a term in the a/b fraction.private static final WeakHashSet
<Fraction> Pool of fractions for which theunique()
method has been invoked.private static final long
For cross-version compatibility.private static final char[][]
The matrix of Unicode symbols available for some fractions. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionReturns the simplified result of adding the given fraction to this fraction.byte
Returns this fraction rounded toward zero, if the result can be represented as a signed byte.int
ceil()
Returns this fraction rounded toward positive infinity.int
Compares this fraction with the given one for order.Returns the simplified result of dividing this fraction by the given fraction.double
Returns the fraction as a double-precision floating point number.boolean
Compares this fraction with the given object for equality.float
Returns the fraction as a single-precision floating point number.int
floor()
Returns this fraction rounded toward negative infinity.int
hashCode()
Returns a hash code value for this fraction.int
intValue()
Returns this fraction rounded toward zero.long
Returns this fraction rounded toward zero.Returns the simplified result of multiplying the given fraction with this fraction.negate()
Returns the negative value of this fraction.int
round()
Returns this fraction rounded toward nearest integer.short
Returns this fraction rounded toward zero, if the result can be represented as a short integer.int
signum()
Returns the sign of this fraction.simplify()
Returns a fraction equivalent tothis
but represented by the smallest possible numerator and denominator values.private static Fraction
Returns a fraction equivalent tonum
/den
after simplification.Returns the simplified result of subtracting the given fraction from this fraction.toString()
Returns a string representation of this fraction.unique()
Returns a unique fraction instance equals tothis
.static Fraction
valueOf
(double value) Converts the given IEEE 754 double-precision value to a fraction.
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDFor cross-version compatibility.- See Also:
-
POOL
Pool of fractions for which theunique()
method has been invoked. -
numerator
public final int numeratorThe a term in the a/b fraction. Can be positive, negative or zero.- See Also:
-
denominator
public final int denominatorThe b term in the a/b fraction. Can be positive, negative or zero. If zero, then the fraction floating point value will be positive infinity, negative infinity or NaN depending on the numerator value.- See Also:
-
UNICODES
private static final char[][] UNICODESThe matrix of Unicode symbols available for some fractions. Each row contains all symbols for the same numerator. For example, the first row contains the symbol of all fractions of the form 0/x, the second row all fractions of the form 1/x, etc.. In each row, the character at column i is for the fraction having the denominator i + (row index) + 1.
-
-
Constructor Details
-
Fraction
public Fraction(int numerator, int denominator) Creates a new fraction. This constructor stores the fraction exactly as specified; it does not simplify it. The fraction can be simplified after construction by a call tosimplify()
.- Parameters:
numerator
- the a term in the a/b fraction.denominator
- the b term in the a/b fraction.
-
Fraction
Creates a new fraction from the given text. This constructor is the converse oftoString()
method. It can parse single numbers like "3", fractions like "2/3", Unicode characters like "⅔" and infinity symbols "∞" and "−∞". The given text shall not contain spaces.- Parameters:
s
- the text to parse.- Throws:
NumberFormatException
- if the given text cannot be parsed.- Since:
- 1.0
-
-
Method Details
-
valueOf
Converts the given IEEE 754 double-precision value to a fraction. If successful, this method returns a fraction such asdoubleValue()
is equal to the given value in the sense ofDouble.equals(Object)
: infinities, positive and negative zeros are preserved, but various NaN values are collapsed to a single NaN value.Design note: this method does not return approximated values because it is difficult to choose which fraction is best. For example, choosing an approximated fraction for π value is quite arbitrary, and searching the fraction closer than any other fraction representable by this class is computationally expansive. Even with common fractions, the algorithm currently implemented in this class can detect that 1.6666666666666667 is equal to 5⁄3 but cannot detect easily that 1.66666666666666 (same number with two decimal digits dropped) is close to 5⁄3.This method accepts only values between -2147483648 and 2147483647 inclusive, i.e. values in the range of 32-bits integers. If the given value has fraction digits, then the validity range will be smaller depending on the denominator required for representing that value.- Parameters:
value
- the double-precision value to convert to a fraction.- Returns:
- a fraction such as
doubleValue()
is equal to the given value. - Throws:
IllegalArgumentException
- if the given value cannot be converted to a fraction.- Since:
- 1.0
-
unique
Returns a unique fraction instance equals tothis
. If this method has been invoked previously on anotherFraction
with the same value thanthis
, then that previous instance is returned (provided that it has not yet been garbage collected). Otherwise this method adds this fraction to the pool of fractions that may be returned in nextunique()
invocations, then returnsthis
.This method is useful for saving memory when a potentially large amount of
Fraction
instances will be kept for a long time and many instances are likely to have the same values. It is usually not worth to invoke this method for short-lived instances.- Returns:
- a unique instance of a fraction equals to
this
.
-
simplify
Returns a fraction equivalent tothis
but represented by the smallest possible numerator and denominator values. If this fraction cannot be simplified, then this method returnsthis
.- Returns:
- the simplest fraction equivalent to this fraction.
-
simplify
Returns a fraction equivalent tonum
/den
after simplification. If the simplified fraction is equal tothis
, then this method returnsthis
.The arguments given to this method are the results of multiplications and additions of
Above result still slightly smaller in magnitude thanint
values. This method fails if any argument value isLong.MIN_VALUE
because that value cannot be made positive. However, it should never happen. Even in the worst scenario:Long.MIN_VALUE
. -
negate
Returns the negative value of this fraction. This method does not simplify the fraction.- Returns:
- the result of
-this
. - Throws:
ArithmeticException
- if the result overflows.
-
add
Returns the simplified result of adding the given fraction to this fraction.- Parameters:
other
- the fraction to add to this fraction.- Returns:
- the simplified result of
this
+other
. - Throws:
ArithmeticException
- if the result overflows.
-
subtract
Returns the simplified result of subtracting the given fraction from this fraction.- Parameters:
other
- the fraction to subtract from this fraction.- Returns:
- the simplified result of
this
-other
. - Throws:
ArithmeticException
- if the result overflows.
-
multiply
Returns the simplified result of multiplying the given fraction with this fraction.- Parameters:
other
- the fraction to multiply with this fraction.- Returns:
- the simplified result of
this
×other
. - Throws:
ArithmeticException
- if the result overflows.
-
divide
Returns the simplified result of dividing this fraction by the given fraction.- Parameters:
other
- the fraction by which to divide this fraction.- Returns:
- the simplified result of
this
∕other
. - Throws:
ArithmeticException
- if the result overflows.
-
round
public int round()Returns this fraction rounded toward nearest integer. If the result is located at equal distance from the two nearest integers, then rounds to the even one.- Returns:
numerator
/denominator
rounded toward nearest integer.
-
floor
public int floor()Returns this fraction rounded toward negative infinity. This is different from the default operation on primitive types, which rounds toward zero.Tip: if the numerator and the denominator are both positive or both negative, then the result is positive and identical to
numerator / denominator
.- Returns:
numerator
/denominator
rounded toward negative infinity.
-
ceil
public int ceil()Returns this fraction rounded toward positive infinity. This is different from the default operation on primitive types, which rounds toward zero.- Returns:
numerator
/denominator
rounded toward positive infinity.
-
doubleValue
public double doubleValue()Returns the fraction as a double-precision floating point number. Special cases:- If the numerator and the denominator are both 0,
then this method returns
Double.NaN
. - If only the denominator is zero, then this method returns positive infinity or negative infinity accordingly the numerator sign.
- Specified by:
doubleValue
in classNumber
- Returns:
- this fraction as a floating point number.
- If the numerator and the denominator are both 0,
then this method returns
-
floatValue
public float floatValue()Returns the fraction as a single-precision floating point number. Special cases:- If the numerator and the denominator are both 0,
then this method returns
Float.NaN
. - If only the denominator is zero, then this method returns positive infinity or negative infinity accordingly the numerator sign.
- Specified by:
floatValue
in classNumber
- Returns:
- this fraction as a floating point number.
- If the numerator and the denominator are both 0,
then this method returns
-
longValue
public long longValue()Returns this fraction rounded toward zero. -
intValue
public int intValue()Returns this fraction rounded toward zero.- Specified by:
intValue
in classNumber
- Returns:
numerator
/denominator
rounded toward zero.- See Also:
-
shortValue
public short shortValue()Returns this fraction rounded toward zero, if the result can be represented as a short integer.- Overrides:
shortValue
in classNumber
- Returns:
- this fraction rounded toward zero.
- Throws:
ArithmeticException
- if the result cannot be represented as a short integer.
-
byteValue
public byte byteValue()Returns this fraction rounded toward zero, if the result can be represented as a signed byte.- Overrides:
byteValue
in classNumber
- Returns:
- this fraction rounded toward zero.
- Throws:
ArithmeticException
- if the result cannot be represented as a signed byte.
-
signum
public int signum()Returns the sign of this fraction. The return value is -1 if this fraction is negative; 0 if the numerator is zero; and 1 if this fraction is positive.- Returns:
- the sign of this fraction.
- Since:
- 1.0
- See Also:
-
compareTo
Compares this fraction with the given one for order.- Specified by:
compareTo
in interfaceComparable<Fraction>
- Parameters:
other
- the fraction to compare to this fraction for ordering.- Returns:
- a negative number if this fraction is smaller than the given fraction, a positive number if greater, or 0 if equals.
-
equals
Compares this fraction with the given object for equality. This method returnstrue
only if the two objects are fractions with same numerator and denominator values. Fractions with different values are not considered equal even if the two fraction are equivalent. -
hashCode
public int hashCode()Returns a hash code value for this fraction. -
toString
Returns a string representation of this fraction. This method returns Unicode symbol if possible.
-