BigFraction.java
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.numbers.fraction;
import java.io.Serializable;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.math.RoundingMode;
import java.util.Objects;
import org.apache.commons.numbers.core.NativeOperators;
/**
* Representation of a rational number using arbitrary precision.
*
* <p>The number is expressed as the quotient {@code p/q} of two {@link BigInteger}s,
* a numerator {@code p} and a non-zero denominator {@code q}.
*
* <p>This class is immutable.
*
* <a href="https://en.wikipedia.org/wiki/Rational_number">Rational number</a>
*/
public final class BigFraction
extends Number
implements Comparable<BigFraction>,
NativeOperators<BigFraction>,
Serializable {
/** A fraction representing "0". */
public static final BigFraction ZERO = new BigFraction(BigInteger.ZERO);
/** A fraction representing "1". */
public static final BigFraction ONE = new BigFraction(BigInteger.ONE);
/** Serializable version identifier. */
private static final long serialVersionUID = 20190701L;
/** The default iterations used for convergence. */
private static final int DEFAULT_MAX_ITERATIONS = 100;
/** Message for non-finite input double argument to factory constructors. */
private static final String NOT_FINITE = "Not finite: ";
/** The overflow limit for conversion from a double (2^31). */
private static final long OVERFLOW = 1L << 31;
/** The numerator of this fraction reduced to lowest terms. */
private final BigInteger numerator;
/** The denominator of this fraction reduced to lowest terms. */
private final BigInteger denominator;
/**
* Private constructor: Instances are created using factory methods.
*
* <p>This constructor should only be invoked when the fraction is known
* to be non-zero; otherwise use {@link #ZERO}. This avoids creating
* the zero representation {@code 0 / -1}.
*
* @param num Numerator, must not be {@code null}.
* @param den Denominator, must not be {@code null}.
* @throws ArithmeticException if the denominator is zero.
*/
private BigFraction(BigInteger num, BigInteger den) {
if (den.signum() == 0) {
throw new FractionException(FractionException.ERROR_ZERO_DENOMINATOR);
}
// reduce numerator and denominator by greatest common denominator
final BigInteger gcd = num.gcd(den);
if (BigInteger.ONE.compareTo(gcd) < 0) {
numerator = num.divide(gcd);
denominator = den.divide(gcd);
} else {
numerator = num;
denominator = den;
}
}
/**
* Private constructor: Instances are created using factory methods.
*
* <p>This sets the denominator to 1.
*
* @param num Numerator (must not be null).
*/
private BigFraction(BigInteger num) {
numerator = num;
denominator = BigInteger.ONE;
}
/**
* Create a fraction given the double value and either the maximum
* error allowed or the maximum number of denominator digits.
*
* <p>
* NOTE: This method is called with:
* </p>
* <ul>
* <li>EITHER a valid epsilon value and the maxDenominator set to
* Integer.MAX_VALUE (that way the maxDenominator has no effect)
* <li>OR a valid maxDenominator value and the epsilon value set to
* zero (that way epsilon only has effect if there is an exact
* match before the maxDenominator value is reached).
* </ul>
* <p>
* It has been done this way so that the same code can be reused for
* both scenarios. However this could be confusing to users if it
* were part of the public API and this method should therefore remain
* PRIVATE.
* </p>
*
* <p>
* See JIRA issue ticket MATH-181 for more details:
* https://issues.apache.org/jira/browse/MATH-181
* </p>
*
* @param value Value to convert to a fraction.
* @param epsilon Maximum error allowed.
* The resulting fraction is within {@code epsilon} of {@code value},
* in absolute terms.
* @param maxDenominator Maximum denominator value allowed.
* @param maxIterations Maximum number of convergents.
* @return a new instance.
* @throws IllegalArgumentException if the given {@code value} is NaN or infinite.
* @throws ArithmeticException if the continued fraction failed to converge.
*/
private static BigFraction from(final double value,
final double epsilon,
final int maxDenominator,
final int maxIterations) {
if (!Double.isFinite(value)) {
throw new IllegalArgumentException(NOT_FINITE + value);
}
if (value == 0) {
return ZERO;
}
// Remove sign, this is restored at the end.
// (Assumes the value is not zero and thus signum(value) is not zero).
final double absValue = Math.abs(value);
double r0 = absValue;
long a0 = (long) Math.floor(r0);
if (a0 > OVERFLOW) {
throw new FractionException(FractionException.ERROR_CONVERSION_OVERFLOW, value, a0, 1);
}
// check for (almost) integer arguments, which should not go to iterations.
if (r0 - a0 <= epsilon) {
// Restore the sign.
if (value < 0) {
a0 = -a0;
}
return new BigFraction(BigInteger.valueOf(a0));
}
// Support 2^31 as maximum denominator.
// This is negative as an integer so convert to long.
final long maxDen = Math.abs((long) maxDenominator);
long p0 = 1;
long q0 = 0;
long p1 = a0;
long q1 = 1;
long p2 = 0;
long q2 = 1;
int n = 0;
boolean stop = false;
do {
++n;
final double r1 = 1.0 / (r0 - a0);
final long a1 = (long) Math.floor(r1);
p2 = (a1 * p1) + p0;
q2 = (a1 * q1) + q0;
if (Long.compareUnsigned(p2, OVERFLOW) > 0 ||
Long.compareUnsigned(q2, OVERFLOW) > 0) {
// In maxDenominator mode, fall-back to the previous valid fraction.
if (epsilon == 0) {
p2 = p1;
q2 = q1;
break;
}
throw new FractionException(FractionException.ERROR_CONVERSION_OVERFLOW, value, p2, q2);
}
final double convergent = (double) p2 / (double) q2;
if (n < maxIterations &&
Math.abs(convergent - absValue) > epsilon &&
q2 < maxDen) {
p0 = p1;
p1 = p2;
q0 = q1;
q1 = q2;
a0 = a1;
r0 = r1;
} else {
stop = true;
}
} while (!stop);
if (n >= maxIterations) {
throw new FractionException(FractionException.ERROR_CONVERSION, value, maxIterations);
}
// Use p2 / q2 or p1 / q1 if q2 has grown too large in maxDenominator mode
long num;
long den;
if (q2 <= maxDen) {
num = p2;
den = q2;
} else {
num = p1;
den = q1;
}
// Restore the sign.
if (Math.signum(num) * Math.signum(den) != Math.signum(value)) {
num = -num;
}
return new BigFraction(BigInteger.valueOf(num),
BigInteger.valueOf(den));
}
/**
* Create a fraction given the double value.
* <p>
* This factory method behaves <em>differently</em> to the method
* {@link #from(double, double, int)}. It converts the double value
* exactly, considering its internal bits representation. This works for all
* values except NaN and infinities and does not requires any loop or
* convergence threshold.
* </p>
* <p>
* Since this conversion is exact and since double numbers are sometimes
* approximated, the fraction created may seem strange in some cases. For example,
* calling {@code from(1.0 / 3.0)} does <em>not</em> create
* the fraction \( \frac{1}{3} \), but the fraction \( \frac{6004799503160661}{18014398509481984} \)
* because the double number passed to the method is not exactly \( \frac{1}{3} \)
* (which cannot be represented exactly in IEEE754).
* </p>
*
* @param value Value to convert to a fraction.
* @throws IllegalArgumentException if the given {@code value} is NaN or infinite.
* @return a new instance.
*
* @see #from(double,double,int)
*/
public static BigFraction from(final double value) {
if (!Double.isFinite(value)) {
throw new IllegalArgumentException(NOT_FINITE + value);
}
if (value == 0) {
return ZERO;
}
final long bits = Double.doubleToLongBits(value);
final long sign = bits & 0x8000000000000000L;
final long exponent = bits & 0x7ff0000000000000L;
final long mantissa = bits & 0x000fffffffffffffL;
// Compute m and k such that value = m * 2^k
long m;
int k;
if (exponent == 0) {
// Subnormal number, the effective exponent bias is 1022, not 1023.
// Note: mantissa is never zero as that case has been eliminated.
m = mantissa;
k = -1074;
} else {
// Normalized number: Add the implicit most significant bit.
m = mantissa | 0x0010000000000000L;
k = ((int) (exponent >> 52)) - 1075; // Exponent bias is 1023.
}
if (sign != 0) {
m = -m;
}
while ((m & 0x001ffffffffffffeL) != 0 &&
(m & 0x1) == 0) {
m >>= 1;
++k;
}
return k < 0 ?
new BigFraction(BigInteger.valueOf(m),
BigInteger.ZERO.flipBit(-k)) :
new BigFraction(BigInteger.valueOf(m).multiply(BigInteger.ZERO.flipBit(k)),
BigInteger.ONE);
}
/**
* Create a fraction given the double value and maximum error allowed.
* <p>
* References:
* <ul>
* <li><a href="http://mathworld.wolfram.com/ContinuedFraction.html">
* Continued Fraction</a> equations (11) and (22)-(26)</li>
* </ul>
*
* @param value Value to convert to a fraction.
* @param epsilon Maximum error allowed. The resulting fraction is within
* {@code epsilon} of {@code value}, in absolute terms.
* @param maxIterations Maximum number of convergents.
* @throws IllegalArgumentException if the given {@code value} is NaN or infinite;
* {@code epsilon} is not positive; or {@code maxIterations < 1}.
* @throws ArithmeticException if the continued fraction failed to converge.
* @return a new instance.
*/
public static BigFraction from(final double value,
final double epsilon,
final int maxIterations) {
if (maxIterations < 1) {
throw new IllegalArgumentException("Max iterations must be strictly positive: " + maxIterations);
}
if (epsilon >= 0) {
return from(value, epsilon, Integer.MIN_VALUE, maxIterations);
}
throw new IllegalArgumentException("Epsilon must be positive: " + maxIterations);
}
/**
* Create a fraction given the double value and maximum denominator.
*
* <p>
* References:
* <ul>
* <li><a href="http://mathworld.wolfram.com/ContinuedFraction.html">
* Continued Fraction</a> equations (11) and (22)-(26)</li>
* </ul>
*
* <p>Note: The magnitude of the {@code maxDenominator} is used allowing use of
* {@link Integer#MIN_VALUE} for a supported maximum denominator of 2<sup>31</sup>.
*
* @param value Value to convert to a fraction.
* @param maxDenominator Maximum allowed value for denominator.
* @throws IllegalArgumentException if the given {@code value} is NaN or infinite
* or {@code maxDenominator} is zero.
* @throws ArithmeticException if the continued fraction failed to converge.
* @return a new instance.
*/
public static BigFraction from(final double value,
final int maxDenominator) {
if (maxDenominator == 0) {
// Re-use the zero denominator message
throw new IllegalArgumentException(FractionException.ERROR_ZERO_DENOMINATOR);
}
return from(value, 0, maxDenominator, DEFAULT_MAX_ITERATIONS);
}
/**
* Create a fraction given the numerator. The denominator is {@code 1}.
*
* @param num
* the numerator.
* @return a new instance.
*/
public static BigFraction of(final int num) {
if (num == 0) {
return ZERO;
}
return new BigFraction(BigInteger.valueOf(num));
}
/**
* Create a fraction given the numerator. The denominator is {@code 1}.
*
* @param num Numerator.
* @return a new instance.
*/
public static BigFraction of(final long num) {
if (num == 0) {
return ZERO;
}
return new BigFraction(BigInteger.valueOf(num));
}
/**
* Create a fraction given the numerator. The denominator is {@code 1}.
*
* @param num Numerator.
* @return a new instance.
* @throws NullPointerException if numerator is null.
*/
public static BigFraction of(final BigInteger num) {
Objects.requireNonNull(num, "numerator");
if (num.signum() == 0) {
return ZERO;
}
return new BigFraction(num);
}
/**
* Create a fraction given the numerator and denominator.
* The fraction is reduced to lowest terms.
*
* @param num Numerator.
* @param den Denominator.
* @return a new instance.
* @throws ArithmeticException if {@code den} is zero.
*/
public static BigFraction of(final int num, final int den) {
if (num == 0) {
return ZERO;
}
return new BigFraction(BigInteger.valueOf(num), BigInteger.valueOf(den));
}
/**
* Create a fraction given the numerator and denominator.
* The fraction is reduced to lowest terms.
*
* @param num Numerator.
* @param den Denominator.
* @return a new instance.
* @throws ArithmeticException if {@code den} is zero.
*/
public static BigFraction of(final long num, final long den) {
if (num == 0) {
return ZERO;
}
return new BigFraction(BigInteger.valueOf(num), BigInteger.valueOf(den));
}
/**
* Create a fraction given the numerator and denominator.
* The fraction is reduced to lowest terms.
*
* @param num Numerator.
* @param den Denominator.
* @return a new instance.
* @throws NullPointerException if numerator or denominator are null.
* @throws ArithmeticException if the denominator is zero.
*/
public static BigFraction of(final BigInteger num, final BigInteger den) {
if (num.signum() == 0) {
return ZERO;
}
return new BigFraction(num, den);
}
/**
* Returns a {@code BigFraction} instance representing the specified string {@code s}.
*
* <p>If {@code s} is {@code null}, then a {@code NullPointerException} is thrown.
*
* <p>The string must be in a format compatible with that produced by
* {@link #toString() BigFraction.toString()}.
* The format expects an integer optionally followed by a {@code '/'} character and
* and second integer. Leading and trailing spaces are allowed around each numeric part.
* Each numeric part is parsed using {@link BigInteger#BigInteger(String)}. The parts
* are interpreted as the numerator and optional denominator of the fraction. If absent
* the denominator is assumed to be "1".
*
* <p>Examples of valid strings and the equivalent {@code BigFraction} are shown below:
*
* <pre>
* "0" = BigFraction.of(0)
* "42" = BigFraction.of(42)
* "0 / 1" = BigFraction.of(0, 1)
* "1 / 3" = BigFraction.of(1, 3)
* "-4 / 13" = BigFraction.of(-4, 13)</pre>
*
* <p>Note: The fraction is returned in reduced form and the numerator and denominator
* may not match the values in the input string. For this reason the result of
* {@code BigFraction.parse(s).toString().equals(s)} may not be {@code true}.
*
* @param s String representation.
* @return an instance.
* @throws NullPointerException if the string is null.
* @throws NumberFormatException if the string does not contain a parsable fraction.
* @see BigInteger#BigInteger(String)
* @see #toString()
*/
public static BigFraction parse(String s) {
final String stripped = s.replace(",", "");
final int slashLoc = stripped.indexOf('/');
// if no slash, parse as single number
if (slashLoc == -1) {
return of(new BigInteger(stripped.trim()));
}
final BigInteger num = new BigInteger(stripped.substring(0, slashLoc).trim());
final BigInteger denom = new BigInteger(stripped.substring(slashLoc + 1).trim());
return of(num, denom);
}
@Override
public BigFraction zero() {
return ZERO;
}
@Override
public BigFraction one() {
return ONE;
}
/**
* Access the numerator as a {@code BigInteger}.
*
* @return the numerator as a {@code BigInteger}.
*/
public BigInteger getNumerator() {
return numerator;
}
/**
* Access the numerator as an {@code int}.
*
* @return the numerator as an {@code int}.
*/
public int getNumeratorAsInt() {
return numerator.intValue();
}
/**
* Access the numerator as a {@code long}.
*
* @return the numerator as a {@code long}.
*/
public long getNumeratorAsLong() {
return numerator.longValue();
}
/**
* Access the denominator as a {@code BigInteger}.
*
* @return the denominator as a {@code BigInteger}.
*/
public BigInteger getDenominator() {
return denominator;
}
/**
* Access the denominator as an {@code int}.
*
* @return the denominator as an {@code int}.
*/
public int getDenominatorAsInt() {
return denominator.intValue();
}
/**
* Access the denominator as a {@code long}.
*
* @return the denominator as a {@code long}.
*/
public long getDenominatorAsLong() {
return denominator.longValue();
}
/**
* Retrieves the sign of this fraction.
*
* @return -1 if the value is strictly negative, 1 if it is strictly
* positive, 0 if it is 0.
*/
public int signum() {
return numerator.signum() * denominator.signum();
}
/**
* Returns the absolute value of this fraction.
*
* @return the absolute value.
*/
public BigFraction abs() {
return signum() >= 0 ?
this :
negate();
}
@Override
public BigFraction negate() {
return new BigFraction(numerator.negate(), denominator);
}
/**
* {@inheritDoc}
*
* <p>Raises an exception if the fraction is equal to zero.
*
* @throws ArithmeticException if the current numerator is {@code zero}
*/
@Override
public BigFraction reciprocal() {
return new BigFraction(denominator, numerator);
}
/**
* Returns the {@code double} value closest to this fraction.
*
* @return the fraction as a {@code double}.
*/
@Override
public double doubleValue() {
return Double.longBitsToDouble(toFloatingPointBits(11, 52));
}
/**
* Returns the {@code float} value closest to this fraction.
*
* @return the fraction as a {@code double}.
*/
@Override
public float floatValue() {
return Float.intBitsToFloat((int) toFloatingPointBits(8, 23));
}
/**
* Returns the whole number part of the fraction.
*
* @return the largest {@code int} value that is not larger than this fraction.
*/
@Override
public int intValue() {
return numerator.divide(denominator).intValue();
}
/**
* Returns the whole number part of the fraction.
*
* @return the largest {@code long} value that is not larger than this fraction.
*/
@Override
public long longValue() {
return numerator.divide(denominator).longValue();
}
/**
* Returns the {@code BigDecimal} representation of this fraction.
* This calculates the fraction as numerator divided by denominator.
*
* @return the fraction as a {@code BigDecimal}.
* @throws ArithmeticException
* if the exact quotient does not have a terminating decimal
* expansion.
* @see BigDecimal
*/
public BigDecimal bigDecimalValue() {
return new BigDecimal(numerator).divide(new BigDecimal(denominator));
}
/**
* Returns the {@code BigDecimal} representation of this fraction.
* This calculates the fraction as numerator divided by denominator
* following the passed rounding mode.
*
* @param roundingMode Rounding mode to apply.
* @return the fraction as a {@code BigDecimal}.
* @see BigDecimal
*/
public BigDecimal bigDecimalValue(RoundingMode roundingMode) {
return new BigDecimal(numerator).divide(new BigDecimal(denominator), roundingMode);
}
/**
* Returns the {@code BigDecimal} representation of this fraction.
* This calculates the fraction as numerator divided by denominator
* following the passed scale and rounding mode.
*
* @param scale
* scale of the {@code BigDecimal} quotient to be returned.
* see {@link BigDecimal} for more information.
* @param roundingMode Rounding mode to apply.
* @return the fraction as a {@code BigDecimal}.
* @throws ArithmeticException if {@code roundingMode} == {@link RoundingMode#UNNECESSARY} and
* the specified scale is insufficient to represent the result of the division exactly.
* @see BigDecimal
*/
public BigDecimal bigDecimalValue(final int scale, RoundingMode roundingMode) {
return new BigDecimal(numerator).divide(new BigDecimal(denominator), scale, roundingMode);
}
/**
* Adds the specified {@code value} to this fraction, returning
* the result in reduced form.
*
* @param value Value to add.
* @return {@code this + value}.
*/
public BigFraction add(final int value) {
return add(BigInteger.valueOf(value));
}
/**
* Adds the specified {@code value} to this fraction, returning
* the result in reduced form.
*
* @param value Value to add.
* @return {@code this + value}.
*/
public BigFraction add(final long value) {
return add(BigInteger.valueOf(value));
}
/**
* Adds the specified {@code value} to this fraction, returning
* the result in reduced form.
*
* @param value Value to add.
* @return {@code this + value}.
*/
public BigFraction add(final BigInteger value) {
if (value.signum() == 0) {
return this;
}
if (isZero()) {
return of(value);
}
return of(numerator.add(denominator.multiply(value)), denominator);
}
/**
* Adds the specified {@code value} to this fraction, returning
* the result in reduced form.
*
* @param value Value to add.
* @return {@code this + value}.
*/
@Override
public BigFraction add(final BigFraction value) {
if (value.isZero()) {
return this;
}
if (isZero()) {
return value;
}
final BigInteger num;
final BigInteger den;
if (denominator.equals(value.denominator)) {
num = numerator.add(value.numerator);
den = denominator;
} else {
num = (numerator.multiply(value.denominator)).add((value.numerator).multiply(denominator));
den = denominator.multiply(value.denominator);
}
if (num.signum() == 0) {
return ZERO;
}
return new BigFraction(num, den);
}
/**
* Subtracts the specified {@code value} from this fraction, returning
* the result in reduced form.
*
* @param value Value to subtract.
* @return {@code this - value}.
*/
public BigFraction subtract(final int value) {
return subtract(BigInteger.valueOf(value));
}
/**
* Subtracts the specified {@code value} from this fraction, returning
* the result in reduced form.
*
* @param value Value to subtract.
* @return {@code this - value}.
*/
public BigFraction subtract(final long value) {
return subtract(BigInteger.valueOf(value));
}
/**
* Subtracts the specified {@code value} from this fraction, returning
* the result in reduced form.
*
* @param value Value to subtract.
* @return {@code this - value}.
*/
public BigFraction subtract(final BigInteger value) {
if (value.signum() == 0) {
return this;
}
if (isZero()) {
return of(value.negate());
}
return of(numerator.subtract(denominator.multiply(value)), denominator);
}
/**
* Subtracts the specified {@code value} from this fraction, returning
* the result in reduced form.
*
* @param value Value to subtract.
* @return {@code this - value}.
*/
@Override
public BigFraction subtract(final BigFraction value) {
if (value.isZero()) {
return this;
}
if (isZero()) {
return value.negate();
}
final BigInteger num;
final BigInteger den;
if (denominator.equals(value.denominator)) {
num = numerator.subtract(value.numerator);
den = denominator;
} else {
num = (numerator.multiply(value.denominator)).subtract((value.numerator).multiply(denominator));
den = denominator.multiply(value.denominator);
}
if (num.signum() == 0) {
return ZERO;
}
return new BigFraction(num, den);
}
/**
* Multiply this fraction by the passed {@code value}, returning
* the result in reduced form.
*
* @param value Value to multiply by.
* @return {@code this * value}.
*/
@Override
public BigFraction multiply(final int value) {
if (value == 0 || isZero()) {
return ZERO;
}
return multiply(BigInteger.valueOf(value));
}
/**
* Multiply this fraction by the passed {@code value}, returning
* the result in reduced form.
*
* @param value Value to multiply by.
* @return {@code this * value}.
*/
public BigFraction multiply(final long value) {
if (value == 0 || isZero()) {
return ZERO;
}
return multiply(BigInteger.valueOf(value));
}
/**
* Multiply this fraction by the passed {@code value}, returning
* the result in reduced form.
*
* @param value Value to multiply by.
* @return {@code this * value}.
*/
public BigFraction multiply(final BigInteger value) {
if (value.signum() == 0 || isZero()) {
return ZERO;
}
return new BigFraction(value.multiply(numerator), denominator);
}
/**
* Multiply this fraction by the passed {@code value}, returning
* the result in reduced form.
*
* @param value Value to multiply by.
* @return {@code this * value}.
*/
@Override
public BigFraction multiply(final BigFraction value) {
if (value.isZero() || isZero()) {
return ZERO;
}
return new BigFraction(numerator.multiply(value.numerator),
denominator.multiply(value.denominator));
}
/**
* Divide this fraction by the passed {@code value}, returning
* the result in reduced form.
*
* @param value Value to divide by
* @return {@code this / value}.
* @throws ArithmeticException if the value to divide by is zero
*/
public BigFraction divide(final int value) {
return divide(BigInteger.valueOf(value));
}
/**
* Divide this fraction by the passed {@code value}, returning
* the result in reduced form.
*
* @param value Value to divide by
* @return {@code this / value}.
* @throws ArithmeticException if the value to divide by is zero
*/
public BigFraction divide(final long value) {
return divide(BigInteger.valueOf(value));
}
/**
* Divide this fraction by the passed {@code value}, returning
* the result in reduced form.
*
* @param value Value to divide by
* @return {@code this / value}.
* @throws ArithmeticException if the value to divide by is zero
*/
public BigFraction divide(final BigInteger value) {
if (value.signum() == 0) {
throw new FractionException(FractionException.ERROR_DIVIDE_BY_ZERO);
}
if (isZero()) {
return ZERO;
}
return new BigFraction(numerator, denominator.multiply(value));
}
/**
* Divide this fraction by the passed {@code value}, returning
* the result in reduced form.
*
* @param value Value to divide by
* @return {@code this / value}.
* @throws ArithmeticException if the value to divide by is zero
*/
@Override
public BigFraction divide(final BigFraction value) {
if (value.isZero()) {
throw new FractionException(FractionException.ERROR_DIVIDE_BY_ZERO);
}
if (isZero()) {
return ZERO;
}
// Multiply by reciprocal
return new BigFraction(numerator.multiply(value.denominator),
denominator.multiply(value.numerator));
}
/**
* Returns a {@code BigFraction} whose value is
* <code>this<sup>exponent</sup></code>, returning the result in reduced form.
*
* @param exponent exponent to which this {@code BigFraction} is to be raised.
* @return <code>this<sup>exponent</sup></code>.
* @throws ArithmeticException if the intermediate result would overflow.
*/
@Override
public BigFraction pow(final int exponent) {
if (exponent == 1) {
return this;
}
if (exponent == 0) {
return ONE;
}
if (isZero()) {
if (exponent < 0) {
throw new FractionException(FractionException.ERROR_ZERO_DENOMINATOR);
}
return ZERO;
}
if (exponent > 0) {
return new BigFraction(numerator.pow(exponent),
denominator.pow(exponent));
}
if (exponent == -1) {
return this.reciprocal();
}
if (exponent == Integer.MIN_VALUE) {
// MIN_VALUE can't be negated
return new BigFraction(denominator.pow(Integer.MAX_VALUE).multiply(denominator),
numerator.pow(Integer.MAX_VALUE).multiply(numerator));
}
// Note: Raise the BigIntegers to the power and then reduce.
// The supported range for BigInteger is currently
// +/-2^(Integer.MAX_VALUE) exclusive thus larger
// exponents (long, BigInteger) are currently not supported.
return new BigFraction(denominator.pow(-exponent),
numerator.pow(-exponent));
}
/**
* Returns the {@code String} representing this fraction.
* Uses:
* <ul>
* <li>{@code "0"} if {@code numerator} is zero.
* <li>{@code "numerator"} if {@code denominator} is one.
* <li>{@code "numerator / denominator"} for all other cases.
* </ul>
*
* @return a string representation of the fraction.
*/
@Override
public String toString() {
final String str;
if (isZero()) {
str = "0";
} else if (BigInteger.ONE.equals(denominator)) {
str = numerator.toString();
} else {
str = numerator + " / " + denominator;
}
return str;
}
/**
* Compares this object with the specified object for order using the signed magnitude.
*
* @param other {@inheritDoc}
* @return {@inheritDoc}
*/
@Override
public int compareTo(final BigFraction other) {
final int lhsSigNum = signum();
final int rhsSigNum = other.signum();
if (lhsSigNum != rhsSigNum) {
return (lhsSigNum > rhsSigNum) ? 1 : -1;
}
// Same sign.
// Avoid a multiply if both fractions are zero
if (lhsSigNum == 0) {
return 0;
}
// Compare absolute magnitude
final BigInteger nOd = numerator.abs().multiply(other.denominator.abs());
final BigInteger dOn = denominator.abs().multiply(other.numerator.abs());
return nOd.compareTo(dOn);
}
/**
* Test for equality with another object. If the other object is a {@code Fraction} then a
* comparison is made of the sign and magnitude; otherwise {@code false} is returned.
*
* @param other {@inheritDoc}
* @return {@inheritDoc}
*/
@Override
public boolean equals(final Object other) {
if (this == other) {
return true;
}
if (other instanceof BigFraction) {
// Since fractions are always in lowest terms, numerators and
// denominators can be compared directly for equality.
final BigFraction rhs = (BigFraction) other;
if (signum() == rhs.signum()) {
return numerator.abs().equals(rhs.numerator.abs()) &&
denominator.abs().equals(rhs.denominator.abs());
}
}
return false;
}
@Override
public int hashCode() {
// Incorporate the sign and absolute values of the numerator and denominator.
// Equivalent to:
// int hash = 1;
// hash = 31 * hash + numerator.abs().hashCode();
// hash = 31 * hash + denominator.abs().hashCode();
// hash = hash * signum()
// Note: BigInteger.hashCode() * BigInteger.signum() == BigInteger.abs().hashCode().
final int numS = numerator.signum();
final int denS = denominator.signum();
return (31 * (31 + numerator.hashCode() * numS) + denominator.hashCode() * denS) * numS * denS;
}
/**
* Calculates the sign bit, the biased exponent and the significand for a
* binary floating-point representation of this {@code BigFraction}
* according to the IEEE 754 standard, and encodes these values into a {@code long}
* variable. The representative bits are arranged adjacent to each other and
* placed at the low-order end of the returned {@code long} value, with the
* least significant bits used for the significand, the next more
* significant bits for the exponent, and next more significant bit for the
* sign.
*
* <p>Warning: The arguments are not validated.
*
* @param exponentLength the number of bits allowed for the exponent; must be
* between 1 and 32 (inclusive), and must not be greater
* than {@code 63 - significandLength}
* @param significandLength the number of bits allowed for the significand
* (excluding the implicit leading 1-bit in
* normalized numbers, e.g. 52 for a double-precision
* floating-point number); must be between 1 and
* {@code 63 - exponentLength} (inclusive)
* @return the bits of an IEEE 754 binary floating-point representation of
* this fraction encoded in a {@code long}, as described above.
*/
private long toFloatingPointBits(int exponentLength, int significandLength) {
// Assume the following conditions:
//assert exponentLength >= 1;
//assert exponentLength <= 32;
//assert significandLength >= 1;
//assert significandLength <= 63 - exponentLength;
if (isZero()) {
return 0L;
}
final long sign = (numerator.signum() * denominator.signum()) == -1 ? 1L : 0L;
final BigInteger positiveNumerator = numerator.abs();
final BigInteger positiveDenominator = denominator.abs();
/*
* The most significant 1-bit of a non-zero number is not explicitly
* stored in the significand of an IEEE 754 normalized binary
* floating-point number, so we need to round the value of this fraction
* to (significandLength + 1) bits. In order to do this, we calculate
* the most significant (significandLength + 2) bits, and then, based on
* the least significant of those bits, find out whether we need to
* round up or down.
*
* First, we'll remove all powers of 2 from the denominator because they
* are not relevant for the significand of the prospective binary
* floating-point value.
*/
final int denRightShift = positiveDenominator.getLowestSetBit();
final BigInteger divisor = positiveDenominator.shiftRight(denRightShift);
/*
* Now, we're going to calculate the (significandLength + 2) most
* significant bits of the fraction's value using integer division. To
* guarantee that the quotient of the division has at least
* (significandLength + 2) bits, the bit length of the dividend must
* exceed that of the divisor by at least that amount.
*
* If the denominator has prime factors other than 2, i.e. if the
* divisor was not reduced to 1, an excess of exactly
* (significandLength + 2) bits is sufficient, because the knowledge
* that the fractional part of the precise quotient's binary
* representation does not terminate is enough information to resolve
* cases where the most significant (significandLength + 2) bits alone
* are not conclusive.
*
* Otherwise, the quotient must be calculated exactly and the bit length
* of the numerator can only be reduced as long as no precision is lost
* in the process (meaning it can have powers of 2 removed, like the
* denominator).
*/
int numRightShift = positiveNumerator.bitLength() - divisor.bitLength() - (significandLength + 2);
if (numRightShift > 0 &&
divisor.equals(BigInteger.ONE)) {
numRightShift = Math.min(numRightShift, positiveNumerator.getLowestSetBit());
}
final BigInteger dividend = positiveNumerator.shiftRight(numRightShift);
final BigInteger quotient = dividend.divide(divisor);
int quotRightShift = quotient.bitLength() - (significandLength + 1);
long significand = roundAndRightShift(
quotient,
quotRightShift,
!divisor.equals(BigInteger.ONE)
).longValue();
/*
* If the significand had to be rounded up, this could have caused the
* bit length of the significand to increase by one.
*/
if ((significand & (1L << (significandLength + 1))) != 0) {
significand >>= 1;
quotRightShift++;
}
/*
* Now comes the exponent. The absolute value of this fraction based on
* the current local variables is:
*
* significand * 2^(numRightShift - denRightShift + quotRightShift)
*
* To get the unbiased exponent for the floating-point value, we need to
* add (significandLength) to the above exponent, because all but the
* most significant bit of the significand will be treated as a
* fractional part. To convert the unbiased exponent to a biased
* exponent, we also need to add the exponent bias.
*/
final int exponentBias = (1 << (exponentLength - 1)) - 1;
long exponent = (long) numRightShift - denRightShift + quotRightShift + significandLength + exponentBias;
final long maxExponent = (1L << exponentLength) - 1L; //special exponent for infinities and NaN
if (exponent >= maxExponent) { //infinity
exponent = maxExponent;
significand = 0L;
} else if (exponent > 0) { //normalized number
significand &= -1L >>> (64 - significandLength); //remove implicit leading 1-bit
} else { //smaller than the smallest normalized number
/*
* We need to round the quotient to fewer than
* (significandLength + 1) bits. This must be done with the original
* quotient and not with the current significand, because the loss
* of precision in the previous rounding might cause a rounding of
* the current significand's value to produce a different result
* than a rounding of the original quotient.
*
* So we find out how many high-order bits from the quotient we can
* transfer into the significand. The absolute value of the fraction
* is:
*
* quotient * 2^(numRightShift - denRightShift)
*
* To get the significand, we need to right shift the quotient so
* that the above exponent becomes (1 - exponentBias - significandLength)
* (the unbiased exponent of a subnormal floating-point number is
* defined as equivalent to the minimum unbiased exponent of a
* normalized floating-point number, and (- significandLength)
* because the significand will be treated as the fractional part).
*/
significand = roundAndRightShift(quotient,
(1 - exponentBias - significandLength) - (numRightShift - denRightShift),
!divisor.equals(BigInteger.ONE)).longValue();
exponent = 0L;
/*
* Note: It is possible that an otherwise subnormal number will
* round up to the smallest normal number. However, this special
* case does not need to be treated separately, because the
* overflowing highest-order bit of the significand will then simply
* become the lowest-order bit of the exponent, increasing the
* exponent from 0 to 1 and thus establishing the implicity of the
* leading 1-bit.
*/
}
return (sign << (significandLength + exponentLength)) |
(exponent << significandLength) |
significand;
}
/**
* Rounds an integer to the specified power of two (i.e. the minimum number of
* low-order bits that must be zero) and performs a right-shift by this
* amount. The rounding mode applied is round to nearest, with ties rounding
* to even (meaning the prospective least significant bit must be zero). The
* number can optionally be treated as though it contained at
* least one 0-bit and one 1-bit in its fractional part, to influence the result in cases
* that would otherwise be a tie.
* @param value the number to round and right-shift
* @param bits the power of two to which to round; must be positive
* @param hasFractionalBits whether the number should be treated as though
* it contained a non-zero fractional part
* @return a {@code BigInteger} as described above
* @throws IllegalArgumentException if {@code bits <= 0}
*/
private static BigInteger roundAndRightShift(BigInteger value, int bits, boolean hasFractionalBits) {
if (bits <= 0) {
throw new IllegalArgumentException("bits: " + bits);
}
BigInteger result = value.shiftRight(bits);
if (value.testBit(bits - 1) &&
(hasFractionalBits ||
value.getLowestSetBit() < bits - 1 ||
value.testBit(bits))) {
result = result.add(BigInteger.ONE); //round up
}
return result;
}
/**
* Returns true if this fraction is zero.
*
* @return true if zero
*/
private boolean isZero() {
return numerator.signum() == 0;
}
}