Android Programming Press on the image to return to the main documentation page.

BigNumbers

Written by Andrew Graham

This library exposes the Java classes BigInteger and BigDecimal to Basic4android.

List of types:

BigDecimal
BigInteger

BigDecimal

This object provides arbitrary-precision signed decimal numbers. It is intended for use where absolute
accuracy is required, the classic example being financial computations where the intrinsic
approximations of Floats and Doubles to exact decimal values are unaccetable.

A BigDecimal consists of an arbitrary precision integer unscaled value, which is actually a
BigInteger, and a 32-bit integer scale. If zero or positive, the scale is the number of digits
to the right of the decimal point. If negative, the unscaled value of the number is multiplied by
ten to the power of the negation of the scale. The value of the number represented by the BigDecimal
is therefore (unscaledValue × 10-scale).

Note that the various Initializers do not offer initialization from Floats or Doubles.
This is a deliberate design choice as Floats and Doubles are inaccurate representations of most decimal values.
For example FloatVar = 0.1 will cause FloatVar to actually contain a value slightly larger than 0.1.
Also note that where a numeric unquoted literal is used in code as a parameter to Initialize
Basic4android converts it first to a Double and so a slightly inaccurate value may result.

Many of the operations return the BigDecimal itself so allowing operations to be chained.
For example "BigD1.Add(BigD2).Multiply(BigD3)". Such expressions are evaluated left to right.

The Java documentation should be studied for more information on BigDecimal.
Note that the Class Overview in the Android online documentation is incorrect and actually applies to
BigInteger, not BigDecimal.

Events:

None

Members:


  Abs As BigDecimal

  Add (augend As BigDecimal) As BigDecimal

  CompareTo (val As BigDecimal) As Int

  Divide (divisor As BigDecimal) As BigDecimal

  Divide2 (divisor As BigDecimal, precision As Int, rounding As Int) As BigDecimal

  DivideToIntegralValue (divisor As BigDecimal)

  DoubleValue As Double

  Equals (bigdecimal As BigDecimal) As Boolean

  Initialize (number As String)

  Initialize2 (number() As Char)

  Initialize3 (number As Long)

  Initialize4 (unscaledVal As Long, scale As Int)

  Initialize5 (value As BigDecimal)

  Initialize6 (value As BigInteger)

  LongValue As Long

  Max (val As BigDecimal) As BigDecimal

  Min (val As BigDecimal) As BigDecimal

  MovePointLeft (n As Int) As BigDecimal

  MovePointRight (n As Int) As BigDecimal

  Multiply (multiplicand As BigDecimal) As BigDecimal

  Negate As BigDecimal

  Plus As BigDecimal

  Pow (n As Int) As BigDecimal

  Precision As Int

  Remainder (divisor As BigDecimal) As BigDecimal

  Round (precision As Int, rounding As Int) As BigDecimal

  ROUND_CEILING As Int

  ROUND_DOWN As Int

  ROUND_FLOOR As Int

  ROUND_HALF_DOWN As Int

  ROUND_HALF_EVEN As Int

  ROUND_HALF_UP As Int

  ROUND_UNNECESSARY As Int

  ROUND_UP As Int

  Scale As Int

  ScaleByPowerOfTen (n As Int) As BigDecimal

  SetScale (newScale As Int) As BigDecimal

  SetScale2 (newScale As Int, rounding As Int) As BigDecimal

  Signum As Int

  StripTrailingZeros As BigDecimal

  Subtract (subtrahend As BigDecimal) As BigDecimal

  ToBigInteger As BigInteger

  ToEngineeringString As String

  ToPlainString As String

  ToString As String

  UnscaledValue As BigInteger

  Version As Double [read only]

Members description:

Abs As BigDecimal
Sets this BigDecimal to a value that is the absolute value of this.
The scale of the result is the same as the original scale of this.
Returns itself.
Add (augend As BigDecimal) As BigDecimal
Sets this BigDecimal to a value is this + augend.
Returns itself.
CompareTo (val As BigDecimal) As Int
Compares this BigDecimal with val. Returns one of the three values 1, 0, or -1.
The method behaves as if this.subtract(val) is computed.
If this difference is > 0 then 1 is returned, if the difference is < 0 then -1 is returned,
and if the difference is 0 then 0 is returned.

This means, that if two decimal instances are compared which are equal in value but differ in scale,
then these two instances are considered as equal unlike Equals().
Divide (divisor As BigDecimal) As BigDecimal
Sets this BigDecimal to a value of this / divisor.
The scale of the result is the difference of the scales of this and divisor.
If the exact result requires more digits, then the scale is adjusted accordingly.
For example, 1/128 = 0.0078125 which has a scale of 7 and precision 5.
Throws an ArithmeticException if the result cannot be represented exactly
because it has a non-terminating decimal expansion.
Returns itself.
Divide2 (divisor As BigDecimal, precision As Int, rounding As Int) As BigDecimal
Sets this BigDecimal to a value of this / divisor.
The result is rounded according to the passed parameters.
If the passed precision is 0, then this call is equivalent to Divide(divisor).
Returns itself.
DivideToIntegralValue (divisor As BigDecimal)
Sets thisBigDecimal to a value that is the integral part of this / divisor.
The quotient is rounded down towards zero to the next integer. For example, 0.5/0.2 = 2.
DoubleValue As Double
Returns this BigDecimal as a double value. If this is too big to be represented as a Double
then Double.POSITIVE_INFINITY or Double.NEGATIVE_INFINITY is returned.

Note that many BigDecimal values, such as 0.1, cannot be represented accurately by a Double.
Equals (bigdecimal As BigDecimal) As Boolean
Initialize (number As String)
Initialises the BigDecimal with the number provided.
Beware of using unquoted literals as parameters as they will be first converted to Double.
Initialize2 (number() As Char)
Initialises the BigDecimal with the number provided in the charcter array.
The array may contain the characters 0 to 9 and a decimal point.
The most significant digit of the number is at index 0 in the array.
Initialize3 (number As Long)
Initialises the BigDecimal with the number provided.
Initialize4 (unscaledVal As Long, scale As Int)
Initialises the BigDecimal whose value is equal to unscaledVal * 10^(-scale).
The scale of the result is scale, and its unscaled value is unscaledVal.
Initialize5 (value As BigDecimal)
Initialises the BigDecimal with the BigDecimal value provided.
Initialize6 (value As BigInteger)
Initialises the BigDecimal with the BigInteger value provided.
The scale of the BigDecimal is zero.
LongValue As Long
Returns this BigDecimal as an long value. Any fractional part is discarded.
If the integral part of this is too big to be represented as an long, then this % 2^64 is returned.
Max (val As BigDecimal) As BigDecimal
Sets this BigDecimal to the maximum of this and val.
Returns itself.
Min (val As BigDecimal) As BigDecimal
Sets this BigDecimal to the minimum of this and val.
Returns itself
MovePointLeft (n As Int) As BigDecimal
Sets this BigDecimal to a value where the decimal point has been moved n places to the left.
If n < 0 then the decimal point is moved -n places to the right.

The result is obtained by changing its scale. If the scale of the result becomes negative,
then its precision is increased such that the scale is zero.

Returns itself.
MovePointRight (n As Int) As BigDecimal
Sets this BigDecimal to a value where the decimal point has been moved n places to the right.
If n < 0 then the decimal point is moved -n places to the left.

The result is obtained by changing its scale. If the scale of the result becomes negative,
then its precision is increased such that the scale is zero.

Returns itself.
Multiply (multiplicand As BigDecimal) As BigDecimal
Sets this BigDecimal to a value of this * multiplicand.
The scale of the result is the sum of the scales of the two arguments.
Returns itself.
Negate As BigDecimal
Sets this BigDecimal to a value that is -this.
The scale of the result is the same as the scale of this.
Returns itself
Plus As BigDecimal
Sets this BigDecimal to a value that is +this.
The scale of the result is the same as the scale of this.
Returns itself.
Pow (n As Int) As BigDecimal
Sets this BigDecimal to a value that is this ^ n.
The scale of the result is n times the scales of this.
Returns itself.
Precision As Int
Returns the precision of this BigDecimal.
The precision is the number of decimal digits used to represent this decimal.
It is equivalent to the number of digits of the unscaled value.
The precision of 0 is 1 (independent of the scale).
Remainder (divisor As BigDecimal) As BigDecimal
Sets this BigDecimal to a value that is this % divisor.
Returns itself.
Round (precision As Int, rounding As Int) As BigDecimal
Sets this BigDecimal to a value that is this, rounded according to the passed precision
and ROUND_XXX type.
If precision = 0, then no rounding is performed.
If precision > 0 and = ROUND_UNNECESSARY, then an ArithmeticException is thrown if the result
cannot be represented exactly within the given precision.
Returns itself.
ROUND_CEILING As Int
Rounding mode to round towards positive infinity.
For positive values this rounding mode behaves as ROUND_UP,
for negative values as ROUND_DOWN.
ROUND_DOWN As Int
Rounding mode where the values are rounded towards zero.
ROUND_FLOOR As Int
Rounding mode to round towards negative infinity.
For positive values this rounding mode behaves as ROUND_DOWN,
for negative values as ROUND_UP.
ROUND_HALF_DOWN As Int
Rounding mode where values are rounded towards the nearest neighbor.
Ties are broken by rounding down.
ROUND_HALF_EVEN As Int
Rounding mode where values are rounded towards the nearest neighbor.
Ties are broken by rounding to the even neighbor.
ROUND_HALF_UP As Int
Rounding mode where values are rounded towards the nearest neighbor.
Ties are broken by rounding up.
ROUND_UNNECESSARY As Int
Rounding mode where the rounding operations throws an ArithmeticException for the case
that rounding is necessary, i.e. for the case that the value cannot be represented exactly.
ROUND_UP As Int
Rounding mode where positive values are rounded towards positive infinity
and negative values towards negative infinity.
Scale As Int
Returns the scale of this BigDecimal.
The scale is the number of digits behind the decimal point.
The value of this BigDecimal is the unsignedValue * 10^(-scale).
If the scale is negative, then this BigDecimal represents a big integer.
ScaleByPowerOfTen (n As Int) As BigDecimal
Sets this BigDecimal to a value that is this 10^n.
The scale of the result is this.scale() - n.
The precision of the result is the precision of this.
This method has the same effect as movePointRight(int), except that the precision is not changed.
Returns itself.
SetScale (newScale As Int) As BigDecimal
Sets the scale of this BigDecimal to the specified scale.
If the new scale is greater than the old scale, then additional zeros are added to the unscaled value.
If the new scale is smaller than the old scale, then trailing zeros are removed.
If the trailing digits are not zeros then an ArithmeticException is thrown.
If no exception is thrown, then the following equation holds: x.setScale(s).compareTo(x) = 0.
Returns itself.
SetScale2 (newScale As Int, rounding As Int) As BigDecimal
Sets the scale of this BigDecimal to the specified scale.
Returns itself.

If the new scale is greater than the old scale, then additional zeros are added to the unscaled value.
In this case no rounding is necessary.

If the new scale is smaller than the old scale, then trailing digits are removed.
If these trailing digits are not zero, then the remaining unscaled value has to be rounded.
For this rounding operation the specified rounding mode is used.

if rounding = ROUND_UNNECESSARY and rounding is necessary according to the given scale then
an ArithmeticException is thrown.
Signum As Int
Returns the sign of this BigDecimal, -1 if this < 0, 0 if this == 0, 1 if this > 0.
StripTrailingZeros As BigDecimal
Sets this BigDecimal to a value with the same value as before but with an unscaled value
where the trailing zeros have been removed.
If the unscaled value of this has n trailing zeros, then the scale and the precision
of the result has been reduced by n.
Returns itself.
Subtract (subtrahend As BigDecimal) As BigDecimal
Sets this BigDecimal to a value that is this - subtrahend.
The scale of the result is the maximum of the scales of the two arguments.
Returns itself.
ToBigInteger As BigInteger
Returns this BigDecimal as a BigInteger instance. Any fractional part is discarded.
ToEngineeringString As String
Returns a string representation of this BigDecimal.
This representation always prints all significant digits of this value.
If the scale is negative or if scale - precision >= 6 then engineering notation is used.
Engineering notation is similar to the scientific notation except that the exponent is
made to be a multiple of 3 such that the integer part is >= 1 and < 1000.
ToPlainString As String
Returns a string representation of this BigDecimal. No scientific notation is used.
This methods adds zeros where necessary.
If this string representation is used to create a new instance, this instance is
generally not identical to this as the precision changes.
ToString As String
UnscaledValue As BigInteger
Returns the unscaled value of this BigDecimal instance as a BigInteger.
The unscaled value can be computed as this * 10^(scale).
Version As Double [read only]
Returns the version of the library.

BigInteger

This object provides signed integers of arbitrary magnitude.

This implementation is efficient for operations traditionally used in cryptography,
such as the generation of large prime numbers and computation of the modular inverse.

This API includes operations for bitwise operations in two's complement representation.
Two's complement is not the internal representation used by this implementation, so such
methods may be inefficient.

Many of the operations return the BigInteger itself so allowing operations to be chained.
For example "BigI1.Add(BigI2).Multiply(BigI3)". Such expressions are evaluated left to right.

The Java documentation should be studied for more information on BigInteger.

Events:

None

Members:


  Abs As BigInteger

  Add (value As BigInteger) As BigInteger

  And (value As BigInteger) As BigInteger

  AndNot (value As BigInteger) As BigInteger

  BitCount As Int

  BitLength As Int

  ClearBit (n As Int) As BigInteger

  CompareTo (value As BigInteger) As Int

  Divide (divisor As BigInteger) As BigInteger

  DoubleValue As Double

  Equals (biginteger As BigInteger) As Boolean

  FlipBit (n As Int) As BigInteger

  GetLowestSetBit As Int

  Initialize (number As String)

  Initialize2 (number() As Byte)

  Initialize3 (number As Long)

  Initialize4 (bitlength As Int)

  Initialize5 (bitlength As Int, certainty As Int)

  Initialize6 (value As BigDecimal)

  Initialize7 (value As BigInteger)

  LongValue As Long

  Max (value As BigInteger) As BigInteger

  Min (value As BigInteger) As BigInteger

  Mod (m As BigInteger) As BigInteger

  ModInverse (m As BigInteger) As BigInteger

  ModPow (exponent As BigInteger, m As BigInteger) As BigInteger

  Multiply (value As BigInteger) As BigInteger

  NextProbablePrime As BigInteger

  Not As BigInteger

  Or (value As BigInteger) As BigInteger

  Pow (exp As Int) As BigInteger

  ProbablePrime (bitLength As Int) As BigInteger

  Remainder (divisor As BigInteger) As BigInteger

  SetBit (n As Int) As BigInteger

  ShiftLeft (n As Int) As BigInteger

  ShiftRight (n As Int) As BigInteger

  Subtract (value As BigInteger) As BigInteger

  TestBit (n As Int) As Boolean

  ToByteArray As Byte()

  ToString As String

  ToStringBase (radix As Int) As String

  Xor (value As BigInteger) As BigInteger

Members description:

Abs As BigInteger
Sets this BigInteger to a value that is the absolute value of this.
Returns itself.
Add (value As BigInteger) As BigInteger
Sets this BigInteger to a value of this + value.
Returns itself.
And (value As BigInteger) As BigInteger
Sets this BigInteger to a value of this AND value.
Usage of this method is not recommended as the current implementation is not efficient.
Returns itself.
AndNot (value As BigInteger) As BigInteger
Sets this BigInteger to a value that is this AND NOT(~value).
Usage of this method is not recommended as the current implementation is not efficient.
Returns itself.
BitCount As Int
Returns the number of bits in the two's complement representation of this which differ
from the sign bit. If this is negative, the result is equivalent to the number of bits
set in the two's complement representation of -this - 1.

Use bitLength() to find the length of the binary value in bits.
BitLength As Int
Returns the length of the value's two's complement representation without leading zeros for
positive numbers / without leading ones for negative values.
The two's complement representation of this will be at least bitLength() + 1 bits long.
The value will fit into an int if bitLength() < 32 or into a long if bitLength() < 64.
ClearBit (n As Int) As BigInteger
Sets this BigInteger to one that has the same binary representation as this but with
the bit at position n cleared. The result is equivalent to this AND NOT(pow(2, n)).
Returns itself.
CompareTo (value As BigInteger) As Int
Compares this BigInteger with value. Returns -1 if this < value, 0 if this == value
and 1 if this > value.
Divide (divisor As BigInteger) As BigInteger
Sets this BigInteger to a value of this / divisor.
Returns itself.
DoubleValue As Double
Returns this BigInteger as a double. If this is too big to be represented as a double,
then Double.POSITIVE_INFINITY or Double.NEGATIVE_INFINITY is returned.

Note that not all integers in the range [-Double.MAX_VALUE, Double.MAX_VALUE] can be
exactly represented as a double.
Equals (biginteger As BigInteger) As Boolean
FlipBit (n As Int) As BigInteger
Sets this BigInteger to one which has the same binary representation as this but with
the bit at position n flipped. The result is equivalent to this ^ pow(2, n).
Returns itself.
GetLowestSetBit As Int
Returns the position of the lowest set bit in the two's complement representation of
this BigInteger. If all bits are zero (this==0) then -1 is returned as result.
Initialize (number As String)
Initialises the BigDecimal with the number provided.
Beware of using unquoted literals as parameters as they will be first converted to Double.
Initialize2 (number() As Byte)
Initialises the BigDecimal with the twos complement number provided in the byte array.
The most significant digits of the number are at index 0 in the array.
Initialize3 (number As Long)
Initialises the BigDecimal with the number provided.
Initialize4 (bitlength As Int)
Initialises the BigDecimal with a random BigInteger instance in the range
[0, pow(2, bitLength)-1].
Initialize5 (bitlength As Int, certainty As Int)
Initialises the BigDecimal with a random BigInteger instance in the range
[0, pow(2, bitLength)-1] which is probably prime.
The probability that the returned BigInteger is prime is beyond 1 - 1/pow(2, certainty).
Initialize6 (value As BigDecimal)
Initialises the BigInteger with the BigDecimal value provided.
Initialize7 (value As BigInteger)
Initialises the BigInteger with the BigInteger value provided.
The scale of the BigDecimal is zero.
LongValue As Long
Returns this BigInteger as a long value.
If this is too big to be represented as a long, then this % pow(2, 64) is returned.
RTturns itself.
Max (value As BigInteger) As BigInteger
Sets this BigInteger to the maximum of this and value.
Returns itself.
Min (value As BigInteger) As BigInteger
Sets this BigInteger to the minimum of this and value.
Returns itself.
Mod (m As BigInteger) As BigInteger
Sets this BigInteger to a value is this mod m. The modulus m must be positive.
The result is guaranteed to be in the interval [0, m] (0 inclusive, m exclusive).
The behavior of this function is not equivalent to the behavior of the % operator
defined for the built-in int's.
Returns itself.
ModInverse (m As BigInteger) As BigInteger
Sets this BigInteger to a value that is 1/this mod m. The modulus m must be positive.
The result is guaranteed to be in the interval [0, m] (0 inclusive, m exclusive).
If this is not relatively prime to m, then an exception is thrown.
Returns itself.
ModPow (exponent As BigInteger, m As BigInteger) As BigInteger
Sets this BigInteger to a value that is pow(this, exponent) mod m. The modulus m must be positive.
The result is guaranteed to be in the interval [0, m] (0 inclusive, m exclusive).
If the exponent is negative, then pow(this.modInverse(m), -exponent) mod m is computed.
The inverse of this only exists if this is relatively prime to m, otherwise an exception is thrown.
Returns itself.
Multiply (value As BigInteger) As BigInteger
Sets this BigInteger to a value that is this * value.
Returns itself.
NextProbablePrime As BigInteger
Sets this BigInteger to the smallest integer x > this which is probably prime.
The probability that the returned BigInteger is prime is beyond 1 - 1/pow(2, 80).
Returns itself.
Not As BigInteger
Sets this BigInteger to a value that is NOT(this). The result of this operation is -this-1.
Returns itself.
Or (value As BigInteger) As BigInteger
Sets this BigInteger to a value that is this OR value.
Returns itself.
Pow (exp As Int) As BigInteger
Sets this BigInteger to a value that is pow(this, exp).
Returns itself.
ProbablePrime (bitLength As Int) As BigInteger
Sets this BigInteger to a random positive BigInteger in the range [0, pow(2, bitLength)-1]
which is probably prime.
The probability that the returned BigInteger is prime is beyond 1 - 1/pow(2, 80).
Returns itself.
Remainder (divisor As BigInteger) As BigInteger
Sets this BigInteger to a value that is this % divisor.
Regarding signs this methods has the same behavior as the % operator on ints:
The sign of the remainder is the same as the sign of this.
Returns itself.
SetBit (n As Int) As BigInteger
Sets this BigInteger to a value which has the same binary representation as this
but with the bit at position n set. The result is equivalent to this | pow(2, n).
Returns itself.
ShiftLeft (n As Int) As BigInteger
Sets this BigInteger to a value that is this << n.
The result is equivalent to this * pow(2, n) if n >= 0.
The shift distance may be negative which means that this is shifted right.
The result then corresponds to floor(this / pow(2, -n)).
Returns itself;
ShiftRight (n As Int) As BigInteger
Sets this BigInteger to a value that is this >> n.
For negative arguments, the result is also negative.
The shift distance may be negative which means that this is shifted left.
Returns itself.
Subtract (value As BigInteger) As BigInteger
Sets this BigInteger to a value that is this - value.
Returns itself.
TestBit (n As Int) As Boolean
Tests whether the bit at position n in this BigInteger is set.
The result is equivalent to this & pow(2, n) != 0.
ToByteArray As Byte()
Returns the two's complement representation of this BigInteger in a byte array.
ToString As String
ToStringBase (radix As Int) As String
Returns a string containing a string representation of this BigInteger with base radix. If radix < Character.MIN_RADIX or radix > Character.MAX_RADIX then a decimal representation is returned. The characters of the string representation are generated with method Character.forDigit.
Xor (value As BigInteger) As BigInteger
Sets this BigInteger to a value that is this XOR value.
Returns itself.
Top