# BigNumbers

### Written by Andrew Graham

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

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.

Note that the Class Overview in the Android online documentation is incorrect and actually applies to
BigInteger, not BigDecimal.

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

#### Members description:

##### AbsAsBigDecimal
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.
Sets this BigDecimal to a value is this + augend.
Returns itself.
##### CompareTo (valAsBigDecimal) AsInt
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 (divisorAsBigDecimal) AsBigDecimal
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 (divisorAsBigDecimal, precisionAsInt, roundingAsInt) AsBigDecimal
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 (divisorAsBigDecimal)
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.
##### DoubleValueAsDouble
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.
##### Initialize (numberAsString)
Initialises the BigDecimal with the number provided.
Beware of using unquoted literals as parameters as they will be first converted to Double.
##### Initialize2 (number() AsChar)
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 (numberAsLong)
Initialises the BigDecimal with the number provided.
##### Initialize4 (unscaledValAsLong, scaleAsInt)
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 (valueAsBigDecimal)
Initialises the BigDecimal with the BigDecimal value provided.
##### Initialize6 (valueAsBigInteger)
Initialises the BigDecimal with the BigInteger value provided.
The scale of the BigDecimal is zero.
##### LongValueAsLong
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 (valAsBigDecimal) AsBigDecimal
Sets this BigDecimal to the maximum of this and val.
Returns itself.
##### Min (valAsBigDecimal) AsBigDecimal
Sets this BigDecimal to the minimum of this and val.
Returns itself
##### MovePointLeft (nAsInt) AsBigDecimal
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 (nAsInt) AsBigDecimal
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 (multiplicandAsBigDecimal) AsBigDecimal
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.
##### NegateAsBigDecimal
Sets this BigDecimal to a value that is -this.
The scale of the result is the same as the scale of this.
Returns itself
##### PlusAsBigDecimal
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 (nAsInt) AsBigDecimal
Sets this BigDecimal to a value that is this ^ n.
The scale of the result is n times the scales of this.
Returns itself.
##### PrecisionAsInt
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 (divisorAsBigDecimal) AsBigDecimal
Sets this BigDecimal to a value that is this % divisor.
Returns itself.
##### Round (precisionAsInt, roundingAsInt) AsBigDecimal
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_CEILINGAsInt
Rounding mode to round towards positive infinity.
For positive values this rounding mode behaves as ROUND_UP,
for negative values as ROUND_DOWN.
##### ROUND_DOWNAsInt
Rounding mode where the values are rounded towards zero.
##### ROUND_FLOORAsInt
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_DOWNAsInt
Rounding mode where values are rounded towards the nearest neighbor.
Ties are broken by rounding down.
##### ROUND_HALF_EVENAsInt
Rounding mode where values are rounded towards the nearest neighbor.
Ties are broken by rounding to the even neighbor.
##### ROUND_HALF_UPAsInt
Rounding mode where values are rounded towards the nearest neighbor.
Ties are broken by rounding up.
##### ROUND_UNNECESSARYAsInt
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_UPAsInt
Rounding mode where positive values are rounded towards positive infinity
and negative values towards negative infinity.
##### ScaleAsInt
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 (nAsInt) AsBigDecimal
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 (newScaleAsInt) AsBigDecimal
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 (newScaleAsInt, roundingAsInt) AsBigDecimal
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.
##### SignumAsInt
Returns the sign of this BigDecimal, -1 if this < 0, 0 if this == 0, 1 if this > 0.
##### StripTrailingZerosAsBigDecimal
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 (subtrahendAsBigDecimal) AsBigDecimal
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.
##### ToBigIntegerAsBigInteger
Returns this BigDecimal as a BigInteger instance. Any fractional part is discarded.
##### ToEngineeringStringAsString
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.
##### ToPlainStringAsString
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.
##### UnscaledValueAsBigInteger
Returns the unscaled value of this BigDecimal instance as a BigInteger.
The unscaled value can be computed as this * 10^(scale).
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.

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:

##### AbsAsBigInteger
Sets this BigInteger to a value that is the absolute value of this.
Returns itself.
Sets this BigInteger to a value of this + value.
Returns itself.
##### And (valueAsBigInteger) AsBigInteger
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 (valueAsBigInteger) AsBigInteger
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.
##### BitCountAsInt
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.
##### BitLengthAsInt
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 (nAsInt) AsBigInteger
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 (valueAsBigInteger) AsInt
Compares this BigInteger with value. Returns -1 if this < value, 0 if this == value
and 1 if this > value.
##### Divide (divisorAsBigInteger) AsBigInteger
Sets this BigInteger to a value of this / divisor.
Returns itself.
##### DoubleValueAsDouble
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.
##### FlipBit (nAsInt) AsBigInteger
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.
##### GetLowestSetBitAsInt
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 (numberAsString)
Initialises the BigDecimal with the number provided.
Beware of using unquoted literals as parameters as they will be first converted to Double.
##### Initialize2 (number() AsByte)
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 (numberAsLong)
Initialises the BigDecimal with the number provided.
##### Initialize4 (bitlengthAsInt)
Initialises the BigDecimal with a random BigInteger instance in the range
[0, pow(2, bitLength)-1].
##### Initialize5 (bitlengthAsInt, certaintyAsInt)
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 (valueAsBigDecimal)
Initialises the BigInteger with the BigDecimal value provided.
##### Initialize7 (valueAsBigInteger)
Initialises the BigInteger with the BigInteger value provided.
The scale of the BigDecimal is zero.
##### LongValueAsLong
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 (valueAsBigInteger) AsBigInteger
Sets this BigInteger to the maximum of this and value.
Returns itself.
##### Min (valueAsBigInteger) AsBigInteger
Sets this BigInteger to the minimum of this and value.
Returns itself.
##### Mod (mAsBigInteger) AsBigInteger
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 (mAsBigInteger) AsBigInteger
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 (exponentAsBigInteger, mAsBigInteger) AsBigInteger
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 (valueAsBigInteger) AsBigInteger
Sets this BigInteger to a value that is this * value.
Returns itself.
##### NextProbablePrimeAsBigInteger
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.
##### NotAsBigInteger
Sets this BigInteger to a value that is NOT(this). The result of this operation is -this-1.
Returns itself.
##### Or (valueAsBigInteger) AsBigInteger
Sets this BigInteger to a value that is this OR value.
Returns itself.
##### Pow (expAsInt) AsBigInteger
Sets this BigInteger to a value that is pow(this, exp).
Returns itself.
##### ProbablePrime (bitLengthAsInt) AsBigInteger
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 (divisorAsBigInteger) AsBigInteger
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 (nAsInt) AsBigInteger
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 (nAsInt) AsBigInteger
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 (nAsInt) AsBigInteger
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 (valueAsBigInteger) AsBigInteger
Sets this BigInteger to a value that is this - value.
Returns itself.
##### TestBit (nAsInt) AsBoolean
Tests whether the bit at position n in this BigInteger is set.
The result is equivalent to this & pow(2, n) != 0.
##### ToByteArrayAsByte()
Returns the two's complement representation of this BigInteger in a byte array.