BigRational

Package

Class

Deprecated

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Class BigRational

java.lang.Object
  java.lang.Number
      BigRational

All Implemented Interfaces:: java.io.Serializable, java.lang.Cloneable, java.lang.Comparable<java.lang.Object>

public class BigRational
extends java.lang.Number
implements java.lang.Cloneable, java.lang.Comparable<java.lang.Object>
extends java.lang.Number
implements java.lang.Cloneable, java.lang.Comparable<java.lang.Object>

BigRational implements dynamically sized arbitrary precision immutable rational numbers.

Dynamically sized means that (provided enough memory) the BigRational numbers can't overflow (nor underflow); this characteristic is different from Java's data types int and long, but common with BigInteger (which however implements only integer numbers, i.e. no fractions) and BigDecimal (which however only implements precisely rational numbers with denominators that are products of 2 and 5 [and implied 10]). Arbitrary precision means that there is no loss of precision with common arithmetic operations such as addition, subtraction, multiplication, and division (BigDecimal loses precision with division, if factors other than 2 or 5 are involved). [Doubles and floats can overflow and underflow, have a limited precision, and only implement precisely rationals with a denominator that is a power of 2.]

BigRational provides most operations needed in rational number space calculations, including addition, subtraction, multiplication, division, integer power, remainder/modulus, comparison, and different roundings.

BigRational provides conversion methods to and from the native types long, int, short, and byte (including support for unsigned values), double (binary64), float (binary32), quad (binary128, quadruple), half (binary16), and BigInteger. BigRational can parse and print many string representations: rational, dot notations, with exponent, even mixtures thereof, and supports different radixes/bases (2 to typically 36 [limited by BigInteger parsing implementation]).

BigRational uses java.math.BigInteger (JDK 1.1 and later).

Binary operations (e.g. add, multiply) calculate their results from a BigRational object ('this') and one [BigRational or long] argument, returning a new immutable BigRational object. Both the original object and the argument are left unchanged (hence immutable). Unary operations (e.g. negate, invert) calculate their result from the BigRational object ('this'), returning a new immutable BigRational object. The original object is left unchanged.

Most operations are precise (i.e. without loss of precision); exceptions are the conversion methods to limited precision types (doubleValue, floatValue), rounding (round), truncation (bigIntegerValue, floor, ceiling, truncate), as well as obviously the printing methods that include a precision parameter (toStringDot, toStringDotRelative, toStringExponent).

BigRational doesn't provide a notion of "infinity" ([+-]Infinity) and "not a number" (NaN); IEEE 754 floating point Infinity and NaN are rejected (throwing a NumberFormatException). Operations such as 0/0 result in an ArithmeticException.

Some commonly used short function names (abs, ceil, div, inv, max, min, mod, mul, neg, pow, rem, sign, sub, trunc) are additionally defined as aliases to to the full function names (absolute, ceiling, divide, invert, maximum, minimum, modulus, multiply, negate, power, remainder, signum, subtract, truncate). [This makes the interface somewhat fatter.]

BigRational internally uses private proxy functions for BigInteger functionality, including scanning and multiplying, to enhance speed and to realize fast checks for common values (1, 0, etc.).

Constructor samples: normal rational form, abbreviated form, fixed point form, abbreviated fixed point form, [exponential] floating point form, different radixes/bases different from 10, doubles/floats:

        BigRational("-21/35"): rational -3/5
        BigRational("/3"): rational 1/3
        BigRational("3.4"): rational 17/5
        BigRational(".7"): 0.7, rational 7/10
        BigRational("-65.4E-3"): -327/5000
        BigRational("f/37", 0x10): 3/11
        BigRational("f.37", 0x10): 3895/256
        BigRational("-dcba.efgh", 23): -46112938320/279841
        BigRational("1011101011010110", 2): 47830
        BigRational(StrictMath.E): 6121026514868073/2251799813685248
        BigRational((float)StrictMath.E): 2850325/1048576

Also accepted are denormalized representations such as:

        BigRational("2.5/-3.5"): -5/7
        BigRational("12.34E-1/-56.78E-1"): -617/2839

Printing: rational form, fixed point (dot) forms with different absolute precisions (including negative precision), with relative precisions, exponential form, different radix:

        BigRational("1234.5678"): "6172839/5000"
        BigRational("1234.5678").toStringDot(6): "1234.567800"
        BigRational("1234.5678").toStringDot(2): "1234.57"
        BigRational("1234.5678").toStringDot(-2): "1200"
        BigRational("1234.5678").toStringDotRelative(6): "1234.57"
        BigRational("0.00012345678").toStringDotRelative(3): "0.000123"
        BigRational("1234.5678").toStringExponent(2): "1.2E3"
        BigRational("1011101011010110", 2).toString(0x10): "bad6"

Usage: BigRational operations can be conveniently chained (sample from BigRational internal conversion from IEEE 754 bits):

        BigRational.valueOf(2).power(exponent).multiply(fraction.add(
                BigRational.valueOfUnsigned(mantissa))).multiply(sign);

The BigRational source and documentation can typically be found at the author's (Eric Laroche) site, at http://www.lrdev.com/lr/java/BigRational.java (source) and http://www.lrdev.com/lr/java/BigRational.html (documentation).

Version:: @(#)$Id: BigRational.java,v 1.3 2010/03/24 20:11:34 laroche Exp $
Author:: Eric Laroche <laroche@lrdev.com>
See Also:: Serialized Form

Field Summary
`static int`	`DEFAULT_RADIX` Default radix, used in string printing and scanning, 10.
`static int`	`DEFAULT_ROUND_MODE` Default round mode, ROUND_HALF_UP.
`static BigRational`	`MINUS_ONE` The constant minus-one (-1).
`static BigRational`	`ONE` The constant one (1).
`static int`	`ROUND_CEILING` Rounding mode to round towards positive infinity.
`static int`	`ROUND_DOWN` Rounding mode to round towards zero.
`static int`	`ROUND_FLOOR` Rounding mode to round towards negative infinity.
`static int`	`ROUND_HALF_CEILING` Rounding mode to round towards nearest neighbor unless both neighbors are equidistant, in which case to round ceiling.
`static int`	`ROUND_HALF_DOWN` Rounding mode to round towards nearest neighbor unless both neighbors are equidistant, in which case to round down.
`static int`	`ROUND_HALF_EVEN` Rounding mode to round towards the nearest neighbor unless both neighbors are equidistant, in which case to round towards the even neighbor.
`static int`	`ROUND_HALF_FLOOR` Rounding mode to round towards nearest neighbor unless both neighbors are equidistant, in which case to round floor.
`static int`	`ROUND_HALF_ODD` Rounding mode to round towards the nearest neighbor unless both neighbors are equidistant, in which case to round towards the odd neighbor.
`static int`	`ROUND_HALF_UP` Rounding mode to round towards nearest neighbor unless both neighbors are equidistant, in which case to round up.
`static int`	`ROUND_UNNECESSARY` Rounding mode to assert that the requested operation has an exact result, hence no rounding is necessary.
`static int`	`ROUND_UP` Rounding mode to round away from zero.
`static BigRational`	`ZERO` The constant zero (0).

Constructor Summary
`BigRational(java.math.BigInteger n)` Construct a BigRational from a big number integer; denominator is 1.
`BigRational(java.math.BigInteger n, java.math.BigInteger q)` Construct a BigRational from numerator and denominator.
`BigRational(java.math.BigInteger unscaledValue, int scale)` Construct a BigRational from an unscaled value and a scale value, default radix (10).
`BigRational(java.math.BigInteger unscaledValue, int scale, int radix)` Construct a BigRational from an unscaled value and a scale value.
`BigRational(BigRational that)` Clone a BigRational.
`BigRational(double x)` Construct a BigRational from a [IEEE 754] double [size/precision] floating point number.
`BigRational(float x)` Construct a BigRational from a [IEEE 754] single [size/precision] floating point number.
`BigRational(long n)` Construct a BigRational from a long fix number integer.
`BigRational(long unscaledValue, int scale, int radix)` Construct a BigRational from an unscaled fix number value and a scale value.
`BigRational(long n, long q)` Construct a BigRational from long fix number integers representing numerator and denominator.
`BigRational(java.lang.String s)` Construct a BigRational from a string representation, with default radix (10).
`BigRational(java.lang.String s, int radix)` Construct a BigRational from a string representation.

Method Summary
`BigRational`	`abs()` An alias to absolute().
`BigRational`	`absolute()` Return a new BigRational with the absolute value of this BigRational.
`BigRational`	`add(BigRational that)` Add a BigRational to this BigRational and return a new BigRational.
`BigRational`	`add(long that)` Add a long fix number integer to this BigRational and return a new BigRational.
`java.math.BigInteger`	`bigIntegerValue()` Convert to BigInteger, by rounding.
`BigRational`	`ceil()` An alias to ceiling().
`BigRational`	`ceiling()` Ceiling, round towards positive infinity.
`int`	`compareTo(java.math.BigInteger that)` Compare this BigRational to a BigInteger.
`int`	`compareTo(BigRational that)` Compare this BigRational to another BigRational.
`int`	`compareTo(long that)` Compare this BigRational to a long.
`int`	`compareTo(java.lang.Object object)` Compare this BigRational to an Object.
`BigRational`	`div(BigRational that)` An alias to divide().
`BigRational`	`div(long that)` An alias to divide().
`BigRational`	`divide(BigRational that)` Divide this BigRational through another BigRational and return a new BigRational.
`BigRational`	`divide(long that)` Divide this BigRational through a long fix number integer and return a new BigRational.
`long`	`doubleBitsValue()` Convert to IEEE 754 double float bits.
`double`	`doubleValue()` Convert to double floating point value.
`boolean`	`equals(java.lang.Object object)` Compare object for equality.
`int`	`floatBitsValue()` Convert to IEEE 754 single float bits.
`float`	`floatValue()` Convert to single floating point value.
`BigRational`	`floor()` Floor, round towards negative infinity.
`BigRational`	`fractionalPart()` Fractional part.
`short`	`halfBitsValue()` Convert this BigRational to IEEE 754 half float (binary16) bits.
`int`	`hashCode()` Hash code.
`BigRational[]`	`integerAndFractionalPart()` Return an array of BigRationals with both integer and fractional part.
`BigRational`	`integerPart()` Integer part.
`int`	`intValue()` Convert to int, by rounding and delegating to BigInteger.
`int`	`intValueExact()` Convert this BigRational to an int, either returning an exact result (no rounding or truncation needed), or throw an ArithmeticException.
`BigRational`	`inv()` An alias to invert().
`BigRational`	`invert()` Return a new BigRational with the inverted (reciprocal) value of this.
`boolean`	`isInteger()` Integer predicate.
`boolean`	`isMinusOne()` Minus-one predicate.
`boolean`	`isNegative()` Negative predicate.
`boolean`	`isOne()` One predicate.
`boolean`	`isPositive()` Positive predicate.
`boolean`	`isZero()` Zero predicate.
`long`	`longValue()` Convert to long, by rounding and delegating to BigInteger.
`long`	`longValueExact()` Convert this BigRational to a long integer, either returning an exact result (no rounding or truncation needed), or throw an ArithmeticException.
`BigRational`	`max(BigRational that)` An alias to maximum().
`BigRational`	`max(long that)` An alias to maximum().
`BigRational`	`maximum(BigRational that)` Return the maximal value of two BigRationals.
`BigRational`	`maximum(long that)` Return the maximum value of a BigRational and a long fix number integer.
`BigRational`	`min(BigRational that)` An alias to minimum().
`BigRational`	`min(long that)` An alias to minimum().
`BigRational`	`minimum(BigRational that)` Return the minimal value of two BigRationals.
`BigRational`	`minimum(long that)` Return the minimal value of a BigRational and a long fix number integer.
`BigRational`	`mod(BigRational that)` An alias to modulus().
`BigRational`	`mod(long that)` An alias to modulus().
`BigRational`	`modulus(BigRational that)` Calculate the modulus of this BigRational and another BigRational and return a new BigRational.
`BigRational`	`modulus(long that)` Calculate the modulus of this BigRational and a long fix number integer and return a new BigRational.
`BigRational`	`mul(BigRational that)` An alias to multiply().
`BigRational`	`mul(long that)` An alias to multiply().
`BigRational`	`multiply(BigRational that)` Multiply a BigRational to this BigRational and return a new BigRational.
`BigRational`	`multiply(long that)` Multiply a long fix number integer to this BigRational and return a new BigRational.
`BigRational`	`neg()` An alias to negate().
`BigRational`	`negate()` Return a new BigRational with the negative value of this.
`BigRational`	`pow(int exponent)` An alias to power().
`BigRational`	`power(int exponent)` Calculate this BigRational's integer power and return a new BigRational.
`static boolean`	`quadBitsEqual(long[] a, long[] b)` Compare two IEEE 754 quad size (quadruple precision, binary128) floating point numbers (each represented as two longs).
`long[]`	`quadBitsValue()` Convert this BigRational to IEEE 754 quad float (binary128, quadruple) bits.
`BigRational`	`rem(BigRational that)` An alias to remainder().
`BigRational`	`rem(long that)` An alias to remainder().
`BigRational`	`remainder(BigRational that)` Calculate the remainder of this BigRational and another BigRational and return a new BigRational.
`BigRational`	`remainder(long that)` Calculate the remainder of this BigRational and a long fix number integer and return a new BigRational.
`BigRational`	`round()` Round by default mode (ROUND_HALF_UP).
`BigRational`	`round(int roundMode)` Round.
`int`	`sign()` An alias to signum().
`int`	`signum()` Signum.
`int`	`singleBitsValue()` An alias to floatBitsValue().
`BigRational`	`sub(BigRational that)` An alias to subtract().
`BigRational`	`sub(long that)` An alias to subtract().
`BigRational`	`subtract(BigRational that)` Subtract a BigRational from this BigRational and return a new BigRational.
`BigRational`	`subtract(long that)` Subtract a long fix number integer from this BigRational and return a new BigRational.
`static void`	`test()` Run tests.
`java.lang.String`	`toString()` BigRational string representation, format "[-]n[/q]", default radix (10).
`java.lang.String`	`toString(int radix)` BigRational string representation, format "[-]n[/q]".
`java.lang.String`	`toStringDot(int precision)` Dot-format "[-]i.f" string representation, with a precision, default radix (10).
`java.lang.String`	`toStringDot(int precision, int radix)` Fixed dot-format "[-]i.f" string representation, with a precision.
`java.lang.String`	`toStringDotRelative(int precision)` Dot-format "[-]i.f" string representation, with a relative precision, default radix (10).
`java.lang.String`	`toStringDotRelative(int precision, int radix)` Dot-format "[-]i.f" string representation, with a relative precision.
`java.lang.String`	`toStringExponent(int precision)` Exponent-format string representation, with a relative precision, default radix (10), "[-]i[.f]E[-]e" (where i is one digit other than 0 exactly; f has no trailing 0);
`java.lang.String`	`toStringExponent(int precision, int radix)` Exponent-format string representation, with a relative precision, "[-]i[.f]E[-]e" (where i is one digit other than 0 exactly; f has no trailing 0);
`BigRational`	`trunc()` An alias to truncate().
`BigRational`	`truncate()` Truncate, round towards zero.
`static BigRational`	`valueOf(java.math.BigInteger value)` Build a BigRational from a BigInteger.
`static BigRational`	`valueOf(BigRational value)` Convert this BigRational to its constant (ONE, ZERO, MINUS_ONE) if possible.
`static BigRational`	`valueOf(byte value)` Build a BigRational from a byte.
`static BigRational`	`valueOf(double value)` Build a BigRational from a [IEEE 754] double [size/precision] floating point number.
`static BigRational`	`valueOf(float value)` Build a BigRational from a [IEEE 754] single [size/precision] floating point number.
`static BigRational`	`valueOf(int value)` Build a BigRational from an int.
`static BigRational`	`valueOf(long value)` Build a BigRational from a long fix number integer.
`static BigRational`	`valueOf(short value)` Build a BigRational from a short.
`static BigRational`	`valueOf(java.lang.String value)` Build a BigRational from a String.
`static BigRational`	`valueOfDoubleBits(long value)` Build a BigRational from an IEEE 754 double size (double precision, binary64) floating point number represented as long.
`static BigRational`	`valueOfFloatBits(int value)` Build a BigRational from an IEEE 754 single size (single precision, binary32) floating point number represented as int.
`static BigRational`	`valueOfHalfBits(short value)` Build a BigRational from an IEEE 754 half size (half precision, binary16) floating point number represented as short.
`static BigRational`	`valueOfQuadBits(long[] value)` Build a BigRational from an IEEE 754 quad size (quadruple precision, binary128) floating point number represented as an array of two longs (big endian; higher significant long first).
`static BigRational`	`valueOfSingleBits(int value)` An alias to valueOfFloatBits().
`static BigRational`	`valueOfUnsigned(byte value)` Build a BigRational from an unsigned byte.
`static BigRational`	`valueOfUnsigned(int value)` Build a BigRational from an unsigned int.
`static BigRational`	`valueOfUnsigned(long value)` Build a BigRational from an unsigned long fix number integer.
`static BigRational`	`valueOfUnsigned(short value)` Build a BigRational from an unsigned short.

Methods inherited from class java.lang.Number
`byteValue, shortValue`

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Field Detail

DEFAULT_RADIX

public static final int DEFAULT_RADIX

Default radix, used in string printing and scanning, 10.

Default radix is decimal [of course].

See Also:: Constant Field Values

ZERO

public static final BigRational ZERO

The constant zero (0).

ONE

public static final BigRational ONE

The constant one (1).

MINUS_ONE

public static final BigRational MINUS_ONE

The constant minus-one (-1).

ROUND_UP

public static final int ROUND_UP

Rounding mode to round away from zero.

See Also:: Constant Field Values

ROUND_DOWN

public static final int ROUND_DOWN

Rounding mode to round towards zero.

See Also:: Constant Field Values

ROUND_CEILING

public static final int ROUND_CEILING

Rounding mode to round towards positive infinity.

See Also:: Constant Field Values

ROUND_FLOOR

public static final int ROUND_FLOOR

Rounding mode to round towards negative infinity.

See Also:: Constant Field Values

ROUND_HALF_UP

public static final int ROUND_HALF_UP

Rounding mode to round towards nearest neighbor unless both neighbors are equidistant, in which case to round up.

See Also:: Constant Field Values

ROUND_HALF_DOWN

public static final int ROUND_HALF_DOWN

Rounding mode to round towards nearest neighbor unless both neighbors are equidistant, in which case to round down.

See Also:: Constant Field Values

ROUND_HALF_EVEN

public static final int ROUND_HALF_EVEN

Rounding mode to round towards the nearest neighbor unless both neighbors are equidistant, in which case to round towards the even neighbor.

See Also:: Constant Field Values

ROUND_UNNECESSARY

public static final int ROUND_UNNECESSARY

Rounding mode to assert that the requested operation has an exact result, hence no rounding is necessary. If this rounding mode is specified on an operation that yields an inexact result, an ArithmeticException is thrown.

See Also:: Constant Field Values

ROUND_HALF_CEILING

public static final int ROUND_HALF_CEILING

Rounding mode to round towards nearest neighbor unless both neighbors are equidistant, in which case to round ceiling.

See Also:: Constant Field Values

ROUND_HALF_FLOOR

public static final int ROUND_HALF_FLOOR

Rounding mode to round towards nearest neighbor unless both neighbors are equidistant, in which case to round floor.

See Also:: Constant Field Values

ROUND_HALF_ODD

public static final int ROUND_HALF_ODD

Rounding mode to round towards the nearest neighbor unless both neighbors are equidistant, in which case to round towards the odd neighbor.

See Also:: Constant Field Values

DEFAULT_ROUND_MODE

public static final int DEFAULT_ROUND_MODE

Default round mode, ROUND_HALF_UP.

See Also:: Constant Field Values

Constructor Detail

BigRational

public BigRational(java.math.BigInteger n,
                   java.math.BigInteger q)

Construct a BigRational from numerator and denominator.

Both n and q may be negative. n/q may be denormalized (i.e. have common factors, or q being negative).

BigRational

public BigRational(java.math.BigInteger n)

Construct a BigRational from a big number integer; denominator is 1.

BigRational

public BigRational(long n,
                   long q)

Construct a BigRational from long fix number integers representing numerator and denominator.

BigRational

public BigRational(long n)

Construct a BigRational from a long fix number integer.

BigRational

public BigRational(BigRational that)

Clone a BigRational.

[As BigRationals are immutable, this copy-constructor is not that useful.]

BigRational

public BigRational(java.lang.String s,
                   int radix)

Construct a BigRational from a string representation.

The supported string formats are "[+-]n", "[+-]n/[+-]q", "[+-]i.f", "[+-]i", "[+-]iE[+-]e", "[+-]i.fE[+-]e" (latter two only with radix<=10, due to possible ambiguities); n and q can be any of the latter (i.e. mixed representations such as "-1.2E-3/-4.5E-6" are supported).

Samples: "-21/35", "3.4", "-65.4E-3", "f/37" (base 16), "1011101011010110" (base 2).

[Exponential representation wasn't supported in an earlier version.]

BigRational

public BigRational(java.lang.String s)

Construct a BigRational from a string representation, with default radix (10).

Samples: "-21/35", "3.4", "-65.4E-3", "f/37" (base 16), "1011101011010110" (base 2).

[Exponential representation wasn't supported in an earlier version.]

BigRational

public BigRational(java.math.BigInteger unscaledValue,
                   int scale,
                   int radix)

Construct a BigRational from an unscaled value and a scale value.

BigRational

public BigRational(java.math.BigInteger unscaledValue,
                   int scale)

Construct a BigRational from an unscaled value and a scale value, default radix (10).

BigRational

public BigRational(long unscaledValue,
                   int scale,
                   int radix)

Construct a BigRational from an unscaled fix number value and a scale value.

BigRational

public BigRational(double x)

Construct a BigRational from a [IEEE 754] double [size/precision] floating point number.

BigRational

public BigRational(float x)

Construct a BigRational from a [IEEE 754] single [size/precision] floating point number.

Method Detail

isPositive

public boolean isPositive()

Positive predicate.

Indicates whether this BigRational is larger than zero. Zero is not positive.

[For convenience.]

isNegative

public boolean isNegative()

Negative predicate.

Indicates whether this BigRational is smaller than zero. Zero isn't negative either.

[For convenience.]

isZero

public boolean isZero()

Zero predicate.

Indicates whether this BigRational is zero.

[For convenience and speed.]

isOne

public boolean isOne()

One predicate.

Indicates whether this BigRational is 1.

[For convenience and speed.]

isMinusOne

public boolean isMinusOne()

Minus-one predicate.

Indicates whether this BigRational is -1.

[For convenience and speed.]

isInteger

public boolean isInteger()

Integer predicate.

Indicates whether this BigRational convertible to a BigInteger without loss of precision. True iff quotient is one.

toString

public java.lang.String toString(int radix)

BigRational string representation, format "[-]n[/q]".

Sample output: "6172839/5000".

toString

public java.lang.String toString()

BigRational string representation, format "[-]n[/q]", default radix (10).

Default string representation, as rational, not using an exponent.

Sample output: "6172839/5000".

Overwrites Object.toString().

Overrides:: toString in class java.lang.Object

toStringDot

public java.lang.String toStringDot(int precision,
                                    int radix)

Fixed dot-format "[-]i.f" string representation, with a precision.

Precision may be negative, in which case the rounding affects digits left of the dot, i.e. the integer part of the number, as well.

Sample output: "1234.567800".

Possible loss of precision.

toStringDot

public java.lang.String toStringDot(int precision)

Dot-format "[-]i.f" string representation, with a precision, default radix (10). Precision may be negative.

Sample output: "1234.567800".

Possible loss of precision.

toStringDotRelative

public java.lang.String toStringDotRelative(int precision,
                                            int radix)

Dot-format "[-]i.f" string representation, with a relative precision.

If the relative precision is zero or negative, "0" will be returned (i.e. total loss of precision).

Possible loss of precision.

toStringDotRelative

public java.lang.String toStringDotRelative(int precision)

Dot-format "[-]i.f" string representation, with a relative precision, default radix (10).

If the relative precision is zero or negative, "0" will be returned (i.e. total loss of precision).

Possible loss of precision.

toStringExponent

public java.lang.String toStringExponent(int precision,
                                         int radix)

Exponent-format string representation, with a relative precision, "[-]i[.f]E[-]e" (where i is one digit other than 0 exactly; f has no trailing 0);

Sample output: "1.2E3".

Possible loss of precision.

toStringExponent

public java.lang.String toStringExponent(int precision)

Exponent-format string representation, with a relative precision, default radix (10), "[-]i[.f]E[-]e" (where i is one digit other than 0 exactly; f has no trailing 0);

Sample output: "1.2E3".

Possible loss of precision.

add

public BigRational add(BigRational that)

Add a BigRational to this BigRational and return a new BigRational.

If one of the operands is zero, [as an optimization] the other BigRational is returned.

add

public BigRational add(long that)

Add a long fix number integer to this BigRational and return a new BigRational.

subtract

public BigRational subtract(BigRational that)

Subtract a BigRational from this BigRational and return a new BigRational.

If the second operand is zero, [as an optimization] this BigRational is returned.

subtract

public BigRational subtract(long that)

Subtract a long fix number integer from this BigRational and return a new BigRational.

sub

public BigRational sub(BigRational that)

An alias to subtract().

sub

public BigRational sub(long that)

An alias to subtract().

multiply

public BigRational multiply(BigRational that)

Multiply a BigRational to this BigRational and return a new BigRational.

If one of the operands is one, [as an optimization] the other BigRational is returned.

multiply

public BigRational multiply(long that)

Multiply a long fix number integer to this BigRational and return a new BigRational.

mul

public BigRational mul(BigRational that)

An alias to multiply().

mul

public BigRational mul(long that)

An alias to multiply().

divide

public BigRational divide(BigRational that)

Divide this BigRational through another BigRational and return a new BigRational.

If the second operand is one, [as an optimization] this BigRational is returned.

divide

public BigRational divide(long that)

Divide this BigRational through a long fix number integer and return a new BigRational.

div

public BigRational div(BigRational that)

An alias to divide().

div

public BigRational div(long that)

An alias to divide().

power

public BigRational power(int exponent)

Calculate this BigRational's integer power and return a new BigRational.

The integer exponent may be negative.

If the exponent is one, [as an optimization] this BigRational is returned.

pow

public BigRational pow(int exponent)

An alias to power().

remainder

public BigRational remainder(BigRational that)

Calculate the remainder of this BigRational and another BigRational and return a new BigRational.

The remainder result may be negative.

The remainder is based on round down (towards zero) / truncate. 5/3 == 1 + 2/3 (remainder 2), 5/-3 == -1 + 2/-3 (remainder 2), -5/3 == -1 + -2/3 (remainder -2), -5/-3 == 1 + -2/-3 (remainder -2).

remainder

public BigRational remainder(long that)

Calculate the remainder of this BigRational and a long fix number integer and return a new BigRational.

rem

public BigRational rem(BigRational that)

An alias to remainder().

rem

public BigRational rem(long that)

An alias to remainder().

modulus

public BigRational modulus(BigRational that)

Calculate the modulus of this BigRational and another BigRational and return a new BigRational.

The modulus result may be negative.

Modulus is based on round floor (towards negative). 5/3 == 1 + 2/3 (modulus 2), 5/-3 == -2 + -1/-3 (modulus -1), -5/3 == -2 + 1/3 (modulus 1), -5/-3 == 1 + -2/-3 (modulus -2).

modulus

public BigRational modulus(long that)

Calculate the modulus of this BigRational and a long fix number integer and return a new BigRational.

mod

public BigRational mod(BigRational that)

An alias to modulus().

mod

public BigRational mod(long that)

An alias to modulus().

signum

public int signum()

Signum. -1, 0, or 1.

If this BigRational is negative, -1 is returned; if it is zero, 0 is returned; if it is positive, 1 is returned.

sign

public int sign()

An alias to signum().

absolute

public BigRational absolute()

Return a new BigRational with the absolute value of this BigRational.

If this BigRational is zero or positive, [as an optimization] this BigRational is returned.

abs

public BigRational abs()

An alias to absolute(). [Name: see classes Math, BigInteger.]

negate

public BigRational negate()

Return a new BigRational with the negative value of this. [Name: see class BigInteger.]

neg

public BigRational neg()

An alias to negate().

invert

public BigRational invert()

Return a new BigRational with the inverted (reciprocal) value of this.

inv

public BigRational inv()

An alias to invert().

minimum

public BigRational minimum(BigRational that)

Return the minimal value of two BigRationals.

minimum

public BigRational minimum(long that)

Return the minimal value of a BigRational and a long fix number integer.

min

public BigRational min(BigRational that)

An alias to minimum(). [Name: see classes Math, BigInteger.]

min

public BigRational min(long that)

An alias to minimum().

maximum

public BigRational maximum(BigRational that)

Return the maximal value of two BigRationals.

maximum

public BigRational maximum(long that)

Return the maximum value of a BigRational and a long fix number integer.

max

public BigRational max(BigRational that)

An alias to maximum(). [Name: see classes Math, BigInteger.]

max

public BigRational max(long that)

An alias to maximum().

equals

public boolean equals(java.lang.Object object)

Compare object for equality. Overwrites Object.equals(). Semantic of equality to non-BigRational changed from earlier version: only BigRationals can be equal. Never throws.

Overwrites Object.equals(Object).

Overrides:: equals in class java.lang.Object

hashCode

public int hashCode()

Hash code. Overwrites Object.hashCode().

Overwrites Object.hashCode().

Overrides:: hashCode in class java.lang.Object

compareTo

public int compareTo(BigRational that)

Compare this BigRational to another BigRational.

compareTo

public int compareTo(java.math.BigInteger that)

Compare this BigRational to a BigInteger.

compareTo

public int compareTo(long that)

Compare this BigRational to a long.

Bytes, shorts, and ints can use this by being promoted to long.

compareTo

public int compareTo(java.lang.Object object)

Compare this BigRational to an Object.

Object can be BigRational/BigInteger/Long/Integer/Short/Byte.

Implements Comparable.compareTo(Object) (JDK 1.2 and later).

A sample use is with a sorted map or set, e.g. TreeSet.

Only BigRational/BigInteger/Long/Integer objects allowed, method will throw otherwise.

For backward compatibility reasons we keep compareTo(Object) additionally to compareTo(BigRational). Comparable<Object> is declared to be implemented rather than Comparable<BigRational>.

Specified by:: compareTo in interface java.lang.Comparable<java.lang.Object>

bigIntegerValue

public java.math.BigInteger bigIntegerValue()

Convert to BigInteger, by rounding.

Possible loss of precision.

longValue

public long longValue()

Convert to long, by rounding and delegating to BigInteger. Implements Number.longValue(). As described with BigInteger.longValue(), this just returns the low-order [64] bits (losing information about magnitude and sign).

Possible loss of precision.

Overwrites Number.longValue().

Specified by:: longValue in class java.lang.Number

intValue

public int intValue()

Convert to int, by rounding and delegating to BigInteger. Implements Number.intValue(). As described with BigInteger.longValue(), this just returns the low-order [32] bits (losing information about magnitude and sign).

Possible loss of precision.

Overwrites Number.intValue().

Specified by:: intValue in class java.lang.Number

doubleValue

public double doubleValue()

Convert to double floating point value. Implements Number.doubleValue().

Possible loss of precision.

Overwrites Number.doubleValue().

Specified by:: doubleValue in class java.lang.Number

floatValue

public float floatValue()

Convert to single floating point value. Implements Number.floatValue().

Note that BigRational's [implicit] [default] rounding mode that applies [too] on indirect double to BigRational to float rounding (round-half-up) may differ from what's done in a direct cast/coercion from double to float (e.g. round-half-even).

Possible loss of precision.

Overwrites Number.floatValue().

Specified by:: floatValue in class java.lang.Number

doubleBitsValue

public long doubleBitsValue()

Convert to IEEE 754 double float bits. The bits can be converted to a double by Double.longBitsToDouble().

Possible loss of precision.

floatBitsValue

public int floatBitsValue()

Convert to IEEE 754 single float bits. The bits can be converted to a float by Float.intBitsToFloat().

Possible loss of precision.

singleBitsValue

public int singleBitsValue()

An alias to floatBitsValue().

Possible loss of precision.

halfBitsValue

public short halfBitsValue()

Convert this BigRational to IEEE 754 half float (binary16) bits.

As a short value is returned rather than a int, care has to be taken no unwanted sign expansion happens in subsequent operations, e.g. by masking (x.halfBitsValue()&0xffffl) or similar (x.halfBitsValue()==(short)0xbc00).

Possible loss of precision.

quadBitsValue

public long[] quadBitsValue()

Convert this BigRational to IEEE 754 quad float (binary128, quadruple) bits.

The bits are returned in an array of two longs, big endian (higher significant long first).

Possible loss of precision.

longValueExact

public long longValueExact()

Convert this BigRational to a long integer, either returning an exact result (no rounding or truncation needed), or throw an ArithmeticException.

intValueExact

public int intValueExact()

Convert this BigRational to an int, either returning an exact result (no rounding or truncation needed), or throw an ArithmeticException.

valueOf

public static BigRational valueOf(BigRational value)

Convert this BigRational to its constant (ONE, ZERO, MINUS_ONE) if possible.

valueOf

public static BigRational valueOf(java.lang.String value)

Build a BigRational from a String.

[Roughly] equivalent to new BigRational(value).

valueOf

public static BigRational valueOf(java.math.BigInteger value)

Build a BigRational from a BigInteger.

Equivalent to new BigRational(value).

valueOf

public static BigRational valueOf(long value)

Build a BigRational from a long fix number integer.

[Roughly] equivalent to new BigRational(value).

As an optimization, commonly used numbers are returned as a reused constant.

valueOf

public static BigRational valueOf(int value)

Build a BigRational from an int.

valueOf

public static BigRational valueOf(short value)

Build a BigRational from a short.

valueOf

public static BigRational valueOf(byte value)

Build a BigRational from a byte.

valueOf

public static BigRational valueOf(double value)

Build a BigRational from a [IEEE 754] double [size/precision] floating point number.

valueOf

public static BigRational valueOf(float value)

Build a BigRational from a [IEEE 754] single [size/precision] floating point number.

valueOfUnsigned

public static BigRational valueOfUnsigned(long value)

Build a BigRational from an unsigned long fix number integer.

The resulting BigRational is positive, i.e. the negative longs are mapped to 2**63..2**64 (exclusive).

valueOfUnsigned

public static BigRational valueOfUnsigned(int value)

Build a BigRational from an unsigned int.

The resulting BigRational is positive, i.e. the negative ints are mapped to 2**31..2**32 (exclusive).

valueOfUnsigned

public static BigRational valueOfUnsigned(short value)

Build a BigRational from an unsigned short.

The resulting BigRational is positive, i.e. the negative shorts are mapped to 2**15..2**16 (exclusive).

valueOfUnsigned

public static BigRational valueOfUnsigned(byte value)

Build a BigRational from an unsigned byte.

The resulting BigRational is positive, i.e. the negative bytes are mapped to 2**7..2**8 (exclusive).

valueOfDoubleBits

public static BigRational valueOfDoubleBits(long value)

Build a BigRational from an IEEE 754 double size (double precision, binary64) floating point number represented as long.

An IEEE 754 double size (binary64) number uses 1 bit for the sign, 11 bits for the exponent, and 52 bits (plus 1 implicit bit) for the fraction/mantissa. The minimal exponent encodes subnormal nubers; the maximal exponent encodes Infinities and NaNs.

Infinities and NaNs are not supported as BigRationals.

The conversion from the bits to a BigRational is done without loss of precision.

valueOfFloatBits

public static BigRational valueOfFloatBits(int value)

Build a BigRational from an IEEE 754 single size (single precision, binary32) floating point number represented as int.

An IEEE 754 single size (binary32) number uses 1 bit for the sign, 8 bits for the exponent, and 23 bits (plus 1 implicit bit) for the fraction/mantissa. The minimal exponent encodes subnormal nubers; the maximal exponent encodes Infinities and NaNs.

Infinities and NaNs are not supported as BigRationals.

The conversion from the bits to a BigRational is done without loss of precision.

valueOfSingleBits

public static BigRational valueOfSingleBits(int value)

An alias to valueOfFloatBits().

valueOfHalfBits

public static BigRational valueOfHalfBits(short value)

Build a BigRational from an IEEE 754 half size (half precision, binary16) floating point number represented as short.

An IEEE 754 half size (binary16) number uses 1 bit for the sign, 5 bits for the exponent, and 10 bits (plus 1 implicit bit) for the fraction/mantissa. The minimal exponent encodes subnormal nubers; the maximal exponent encodes Infinities and NaNs.

Infinities and NaNs are not supported as BigRationals.

The conversion from the bits to a BigRational is done without loss of precision.

valueOfQuadBits

public static BigRational valueOfQuadBits(long[] value)

Build a BigRational from an IEEE 754 quad size (quadruple precision, binary128) floating point number represented as an array of two longs (big endian; higher significant long first).

An IEEE 754 quad size (binary128, quadruple) number uses 1 bit for the sign, 15 bits for the exponent, and 112 bits (plus 1 implicit bit) for the fraction/mantissa. The minimal exponent encodes subnormal nubers; the maximal exponent encodes Infinities and NaNs.

Infinities and NaNs are not supported as BigRationals.

The conversion from the bits to a BigRational is done without loss of precision.

quadBitsEqual

public static boolean quadBitsEqual(long[] a,
                                    long[] b)

Compare two IEEE 754 quad size (quadruple precision, binary128) floating point numbers (each represented as two longs). NaNs are not considered; comparison is done by bits. [Convenience method.]

round

public BigRational round(int roundMode)

Round.

Round mode is one of {ROUND_UP, ROUND_DOWN, ROUND_CEILING, ROUND_FLOOR, ROUND_HALF_UP, ROUND_HALF_DOWN, ROUND_HALF_EVEN, ROUND_HALF_CEILING, ROUND_HALF_FLOOR, ROUND_HALF_ODD, ROUND_UNNECESSARY, DEFAULT_ROUND_MODE (==ROUND_HALF_UP)}.

If rounding isn't necessary, i.e. this BigRational is an integer, [as an optimization] this BigRational is returned.

Possible loss of precision.

round

public BigRational round()

Round by default mode (ROUND_HALF_UP).

Possible loss of precision.

floor

public BigRational floor()

Floor, round towards negative infinity.

Possible loss of precision.

ceiling

public BigRational ceiling()

Ceiling, round towards positive infinity.

Possible loss of precision.

ceil

public BigRational ceil()

An alias to ceiling().

Possible loss of precision.

truncate

public BigRational truncate()

Truncate, round towards zero.

Possible loss of precision.

trunc

public BigRational trunc()

An alias to truncate().

Possible loss of precision.

integerPart

public BigRational integerPart()

Integer part.

Possible loss of precision.

fractionalPart

public BigRational fractionalPart()

Fractional part.

Possible loss of precision.

integerAndFractionalPart

public BigRational[] integerAndFractionalPart()

Return an array of BigRationals with both integer and fractional part.

Integer part is returned at offset 0; fractional part at offset 1.

test

public static void test()

Run tests.

Implementation is commented out at distribution time; run at development and integration time.

Asserts conditions; use '-ea' java startup option to enable asserts.

Package

Class

Deprecated

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD