Package javacardx.framework.math

Class BigNumber

  • public final class BigNumber
extends Object
    The BigNumber class encapsulates an unsigned number whose value is represented in internal hexadecimal format using an implementation specific maximum number of bytes. This class supports the BCD (binary coded decimal) format for I/O.
    Since:
    2.2.2

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static byte FORMAT_BCD
      Constant to indicate a BCD (binary coded decimal) data format.
      static byte FORMAT_HEX
      Constant to indicate a hexadecimal (simple binary) data format.

    • Constructor Summary

      Constructors 
      Constructor Description
      BigNumber​(short maxBytes)
      Creates a BigNumber instance with initial value 0.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void add​(byte[] bArray, short bOff, short bLen, byte arrayFormat)
      Increments the internal big number by the specified operand value
      byte compareTo​(byte[] bArray, short bOff, short bLen, byte arrayFormat)
      Compares the internal big number against the specified operand.
      byte compareTo​(BigNumber operand)
      Compares the internal big number against the specified operand.
      short getByteLength​(byte arrayFormat)
      Returns the number of bytes required to represent the big number using the desired format
      static short getMaxBytesSupported()
      This method returns the byte length of the hex array that can store the biggest BigNumber supported.
      void init​(byte[] bArray, short bOff, short bLen, byte arrayFormat)
      Initializes the big number using the input data
      void multiply​(byte[] bArray, short bOff, short bLen, byte arrayFormat)
      Multiplies the internal big number by the specified operand value
      void reset()
      Resets the big number to 0
      void setMaximum​(byte[] maxValue, short bOff, short bLen, byte arrayFormat)
      Sets the maximum value that the BigNumber may contain.
      void subtract​(byte[] bArray, short bOff, short bLen, byte arrayFormat)
      Decrements the internal big number by the specified operand value
      void toBytes​(byte[] outBuf, short bOff, short numBytes, byte arrayFormat)
      Writes the internal big number out in the desired format.

    • Field Detail

      • FORMAT_BCD

        public static final byte FORMAT_BCD
        Constant to indicate a BCD (binary coded decimal) data format. When this format is used a binary coded decimal digit is stored in 1 nibble (4 bits). A byte is packed with 2 BCD digits.
        See Also:
        Constant Field Values

      • FORMAT_HEX

        public static final byte FORMAT_HEX
        Constant to indicate a hexadecimal (simple binary) data format.
        See Also:
        Constant Field Values

    • Constructor Detail

      • BigNumber

        public BigNumber​(short maxBytes)
        Creates a BigNumber instance with initial value 0. All implementations must support at least 8 byte length internal representation capacity.
        Parameters:
        maxBytes - maximum number of bytes needed in the hexadecimal format for the largest unsigned big number. For example, maxBytes = 2 allows a big number representation range 0-65535.
        Throws:
        ArithmeticException - if maxBytes is 0, negative or larger than the supported maximum

    • Method Detail

      • setMaximum

        public void setMaximum​(byte[] maxValue,
                       short bOff,
                       short bLen,
                       byte arrayFormat)
        Sets the maximum value that the BigNumber may contain. Attempts to increase beyond the maximum results in an exception. If this method is not called, the maximum value is the maximum hex value that fits within the configured maximum number of bytes.

        Note:

        • This method may allocate internal storage to store the specified maximum value.

        Parameters:
        maxValue - input byte array
        bOff - offset within input byte array containing first byte (the high order byte)
        bLen - byte length of input data
        arrayFormat - indicates the format of the input data. Valid codes listed in FORMAT_* constants, for example FORMAT_BCD.
        Throws:
        NullPointerException - if maxValue is null
        ArrayIndexOutOfBoundsException - if accessing the input array would cause access of data outside array bounds or if bLen is negative
        ArithmeticException - for the following conditions:
        • if the specified maximum value is smaller than the encapsulated big number
        • if the specified maximum value is larger than will fit within the supported maximum number of bytes
        • if the input byte array format is not conformant with the specified arrayFormat parameter
        • if bLen is 0
        • if arrayFormat is not one of the FORMAT_ constants.

      • getMaxBytesSupported

        public static short getMaxBytesSupported()
        This method returns the byte length of the hex array that can store the biggest BigNumber supported. This number is the maximum number in hex byte representation. All implementations must support at least 8 bytes.
        Returns:
        the byte length of the biggest number supported

      • init

        public void init​(byte[] bArray,
                 short bOff,
                 short bLen,
                 byte arrayFormat)
          throws NullPointerException,
                 ArrayIndexOutOfBoundsException,
                 ArithmeticException
        Initializes the big number using the input data
        Parameters:
        bArray - input byte array
        bOff - offset within byte array containing first byte (the high order byte)
        bLen - byte length of input data
        arrayFormat - indicates the format of the input data. Valid codes listed in FORMAT_* constants, for example FORMAT_BCD.
        Throws:
        ArrayIndexOutOfBoundsException - if accessing the input array would cause access outside array bounds or if bLen is negative
        NullPointerException - if bArray is null
        ArithmeticException - for the following conditions:
        • if the input byte array format is not conformant with the specified arrayFormat parameter
        • if the specified input data represents a number which is larger than the maximum value configured or larger than will fit within the supported maximum number of bytes
        • if bLen is 0
        • if arrayFormat is not one of the FORMAT_ constants.

      • add

        public void add​(byte[] bArray,
                short bOff,
                short bLen,
                byte arrayFormat)
         throws NullPointerException,
                ArrayIndexOutOfBoundsException,
                ArithmeticException
        Increments the internal big number by the specified operand value
        Parameters:
        bArray - input byte array
        bOff - offset within input byte array containing first byte (the high order byte)
        bLen - byte length of input data
        arrayFormat - indicates the format of the input data. Valid codes listed in FORMAT_* constants, for example FORMAT_BCD.
        Throws:
        ArrayIndexOutOfBoundsException - if accessing the input array would cause access of data outside array bounds or if bLen is negative
        NullPointerException - if bArray is null
        ArithmeticException - for the following conditions:
        • if the input byte array format is not conformant with the specified arrayFormat parameter
        • if the result of the addition results in a big number which cannot be represented within the maximum supported bytes or is greater than the configured max value. The internal big number is left unchanged.
        • if bLen is 0
        • if arrayFormat is not one of the FORMAT_ constants

      • subtract

        public void subtract​(byte[] bArray,
                     short bOff,
                     short bLen,
                     byte arrayFormat)
              throws ArithmeticException
        Decrements the internal big number by the specified operand value
        Parameters:
        bArray - input byte array
        bOff - offset within input byte array containing first byte (the high order byte)
        bLen - byte length of input data
        arrayFormat - indicates the format of the input data. Valid codes listed in FORMAT_* constants, for example FORMAT_BCD.
        Throws:
        ArrayIndexOutOfBoundsException - if accessing the input array would cause access of data outside array bounds or if bLen is negative
        NullPointerException - if bArray is null
        ArithmeticException - for the following conditions:
        • if the input byte array format is not conformant with the specified arrayFormat parameter
        • if the result of the subtraction results in a negative number. The internal big number is left unchanged.
        • if bLen is 0
        • if arrayFormat is not one of the FORMAT_ constants.

      • multiply

        public void multiply​(byte[] bArray,
                     short bOff,
                     short bLen,
                     byte arrayFormat)
              throws ArithmeticException
        Multiplies the internal big number by the specified operand value
        Parameters:
        bArray - input byte array
        bOff - offset within input byte array containing first byte (the high order byte)
        bLen - byte length of input data
        arrayFormat - indicates the format of the input data. Valid codes listed in FORMAT_* constants, for example FORMAT_BCD.
        Throws:
        ArrayIndexOutOfBoundsException - if accessing the input array would cause access of data outside array bounds or if bLen is negative
        NullPointerException - if bArray is null
        ArithmeticException - for the following conditions:
        • if the input byte array format is not conformant with the specified arrayFormat parameter
        • if the result of the multiplication results in a big number which cannot be represented within the maximum supported bytes or is greater than the configured max value. The internal big number is left unchanged.
        • if bLen is 0
        • if arrayFormat is not one of the FORMAT_ constants.

      • compareTo

        public byte compareTo​(BigNumber operand)
        Compares the internal big number against the specified operand.

        In addition to returning a byte result, this method sets the result in an internal state which can be rechecked using assertion methods of the SensitiveResult class, if supported by the platform.

        Parameters:
        operand - contains the BigNumber operand
        Returns:
        the result of the comparison as follows:
        • 0 if equal
        • -1 if the internal big number is less than the specified operand
        • 1 if the internal big number is greater than the specified operand
        Throws:
        NullPointerException - if operand is null

      • compareTo

        public byte compareTo​(byte[] bArray,
                      short bOff,
                      short bLen,
                      byte arrayFormat)
        Compares the internal big number against the specified operand. The operand is specified in an input byte array.

        In addition to returning a byte result, this method sets the result in an internal state which can be rechecked using assertion methods of the SensitiveResult class, if supported by the platform.

        Parameters:
        bArray - input byte array
        bOff - offset within input byte array containing first byte (the high order byte)
        bLen - byte length of input data
        arrayFormat - indicates the format of the input data. Valid codes listed in FORMAT_* constants, for example FORMAT_BCD.
        Returns:
        the result of the comparison as follows:
        • 0 if equal
        • -1 if the internal big number is less than the specified operand
        • 1 if the internal big number is greater than the specified operand
        Throws:
        ArrayIndexOutOfBoundsException - if accessing the input array would cause access of data outside array bounds or if bLen is negative
        NullPointerException - if bArray is null
        ArithmeticException - for the following conditions:
        • if the input byte array format is not conformant with the specified arrayFormat parameter
        • if bLen is 0
        • if arrayFormat is not one of the FORMAT_ constants.

      • toBytes

        public void toBytes​(byte[] outBuf,
                    short bOff,
                    short numBytes,
                    byte arrayFormat)
             throws ArrayIndexOutOfBoundsException,
                    NullPointerException
        Writes the internal big number out in the desired format. Note that the value output into the specified byte array is right justified for the number of requested bytes. BCD 0 nibbles are prepended to the output BCD data written out.
        Parameters:
        outBuf - output byte array
        bOff - offset within byte array containing first byte (the high order byte)
        numBytes - number of output bytes required
        arrayFormat - indicates the format of the input data. Valid codes listed in FORMAT_* constants, for example FORMAT_BCD.
        Throws:
        ArrayIndexOutOfBoundsException - if accessing the output array would cause access of data outside array bounds or if numBytes is negative
        NullPointerException - if outBuf is null
        ArithmeticException - for the following conditions:
        • if numBytes is not sufficient to represent the big number in the desired format
        • if numBytes is 0
        • if arrayFormat is not one of the FORMAT_ constants.

      • getByteLength

        public short getByteLength​(byte arrayFormat)
        Returns the number of bytes required to represent the big number using the desired format
        Parameters:
        arrayFormat - indicates the format of the output data. Valid codes listed in FORMAT_* constants, for example FORMAT_BCD.
        Returns:
        the byte length of big number
        Throws:
        ArithmeticException - if arrayFormat is not one of the FORMAT_ constants.

      • reset

        public void reset()
        Resets the big number to 0