Maven module :un.api : api-math :
Class : un.impl.math.Magnitude
Extends/Implements : -
Subclasses : -

Magnitude is an helper class used in LargeInteger and LargeDecimal.
It uses long arrays to make basic computations on very long integers. The
least significant long is at index 0 and the most significant long is at
index magnitude.length-1.
author  Bertrand COTE

Variables : -
Functions : toString, reductMagnitude, simplifyMagnitude, compareMagnitudes, compareMagnitudes, addMagnitudes, addMagnitudesBuffered, multMagnitudeByLong, multMagnitudeByLongBuffered, multMagnitude, divideSameOrderMagnitude, divideAndRemainderMagnitude, divide, not, and, andNot, or, orNot, xor, xorNot, shiftRight, shiftRightBuffered, shiftLeft, shiftLeftBuffered, toNegative, getBit, getByteLength, getBitLength


convert mag to its String representation.
param  mag
return
public String toString (long[] mag)


Remove all consecutive 0 elements in the end of the given array.
(If all elements are zeros, it returns the array { 0x0L })

@param mag
@return
public long[] reductMagnitude (long[] mag)


Computes n such that n is the higher integer such that mag can be
written as magResult*2.pow(n).(n is the count of 0 bits beginning mag)

(Used in simplifications in LargeDecimal)

@param mag
@return n the count of 0 bits beginning mag.
public int simplifyMagnitude (long[] mag)


Compares the two given magnitudes. (mag1 is shifted left by offset zeros longs)

@param mag0
@param mag1
@param offset
@return 0 if mag0 == mag1
1 if mag0 > mag1
-1 if mag0 < mag1
public int compareMagnitudes (long[] mag0, long[] mag1, int offset)


Compare the two given magnitudes.
The elements at index 0 in the arrays mag0 and mag1 mustn't be zero.
param  mag0 a magnitude.
param  mag1 a magnitude.
return
public int compareMagnitudes (long[] mag0, long[] mag1)


Computes and returns the sum of the two given magnitudes.
If add is true, mag1[0] is added to mag0[offset]...
If add is false, mag1[0] is subtracted from mag0[offset]...


WARNING: mag0 must be >= mag1*2.pow( 64*offset ) if add is false.

@param mag0
@param mag1
@param offset
@param makeAdd true for addition and false for subtraction.
@return
public long[] addMagnitudes (long[] mag0, long[] mag1, int offset, boolean makeAdd)


Computes and returns the sum of the two given magnitudes.
If add is true, magSource[0] is added to magBuffer[offset]. If add is false, magSource[0] is subtracted from magBuffer[offset].

WARNING: magBuffer must be >= magSource*2.pow( 64*offset ) if add is false.
WARNING: magBuffer.length must be Maths.max(magBuffer.length, offset+magSource.length)+1
param  magBuffer
param  magSource
param  offset
param  makeAdd true for addition and false for subtraction.
return  the carry.
public boolean addMagnitudesBuffered (long[] magSource, long[] magBuffer, int offset, boolean makeAdd)


Multiply the given magnitude with the given long multiplicator.
If the boolean isSignedLong is:


@param mag
@param multiplicator
@param offset
@param isSignedLong true if multiplicator must be considered as a signed long and false if multiplicator must be considered as unsigned long.
@return mag*multiplicator
public long[] multMagnitudeByLong (long[] mag, long multiplicator, int offset, boolean isSignedLong)


Computes mag*multiplicator and adds it to the buffer beginning at the given offset.
If the boolean isSignedLong is:


@param mag
@param multiplicator
@param buffer
@param offset
@param isSignedLong
@return
public long[] multMagnitudeByLongBuffered (long[] mag, long multiplicator, long[] buffer, int offset, boolean isSignedLong)


Multiply mag0 with mag1.
param  mag0
param  mag1
return  mag0*mag1.
public long[] multMagnitude (long[] mag0, long[] mag1)


Divides numerator by denominator.


WARNING:
numerator/denominator must be >=0 and <2⁶⁴ (ensure that the result
can be stored in only one unsigned long)

@param numerator
@param denominator
@return
public long divideSameOrderMagnitude (long[] numerator, long[] denominator)


Divides numerator by denominator and returns the quotient and the
remainder (Euclid algorithm).
param  numerator
param  denominator
return  { quotient, remainder }
public long[][] divideAndRemainderMagnitude (long[] numerator, long[] denominator)

public long[] divide (long[] numerator, long[] denominator)


Complements all values in mag.
param  mag
return
public long[] not (long[] mag)


Bitwise and between all values with the same index in mag0 and mag1.
param  mag0
param  mag1
return
public long[] and (long[] mag0, long[] mag1)

public long[] andNot (long[] mag0, long[] mag1)

public long[] or (long[] mag0, long[] mag1)

public long[] orNot (long[] mag0, long[] mag1)

public long[] xor (long[] mag0, long[] mag1)

public long[] xorNot (long[] mag0, long[] mag1)


Shifts mag n bits to the right. (unsigned shift).
param  mag
param  n shift in bits.
return  mag >>> n.
public long[] shiftRight (long[] mag, int n)


Shifts buffer n bits to the right. (unsigned shift).
param  buffer
param  n shift in bits.
public void shiftRightBuffered (long[] buffer, int n)


Shifts mag n bits to the left. If necessary mag length is increased.
param  mag
param  n shift in bits.
return  mag << n.
public long[] shiftLeft (long[] mag, int n)


Shifts buffer n bits to the left. buffer is never resized.
param  buffer
param  n shift in bits.
public void shiftLeftBuffered (long[] buffer, int n)


Computes the two's complemented value of mag.

@param mag
@param newLength
@return the two's complemented value of mag.
public long[] toNegative (long[] mag, int newLength)


Returns the state of the bit at index nBit.
param  sign used to compute the signed magnitude ( < 0 for negative ).
param  mag
param  index
return  false for 0 and true for 1.
public boolean getBit (int sign, long[] mag, int index)


Computes the number of bytes needed to encode mag.
param  mag
return  the number of bytes needed to encode mag.
public int getByteLength (long[] mag)


Computes the number of bits needed to encode mag.
param  mag
return  the number of bits needed to encode mag.
public int getBitLength (long[] mag)