Nail Polish Makeover

    intn

    1.0.0 • Public • Published

    IntN.js - Arbitrary byte size integers in JavaScript

    IntN.js is a library for representing and working with arbitrary byte size two's complement integers in JavaScript, both signed and unsigned. Its purpose is to provide a robust and convenient way to work with data types that are not available in JavaScript natively, like 64 bit longs.

    Usage

    The module exports a function that creates singleton classes representing integers of the specified size in bits (positive multiple of 8). It is compatible with CommonJS and AMD loaders and is exposed globally as dcodeIO.IntN if neither is available.

    var IntN  = require("intn");
     
    var Int8  = IntN(8),
        Int16 = IntN(16),
        Int24 = IntN(24),
        Int32 = IntN(32),
        ...
        Int64 = IntN(64),
        ...

    Important: The following API documentation references the usage of the classes created by the exported function.

    API

    Instances are immutable and all methods that return another instance are chainable. Instance values are easily interchangeable using their bytes property or the fromInts and toInts methods.

    new IntN(bytes, unsigned=)

    Constructs a new IntN, where N is the number of bits represented by this class.

    Parameter Type Description
    bytes !Array.<number> | number Byte values, least significant first
    unsigned boolean Whether unsigned or signed, defaults to false for signed

    IntN.BITS

    Number of bits represented by this IntN class.

    @type number
    @access public const

    IntN.BYTES

    Number of bytes represented by this IntN class.

    @type number
    @access public const

    IntN.MAX_UNSIGNED_VALUE

    Maximum unsigned value.

    @type !IntN
    @access public const

    IntN.MAX_VALUE

    Maximum signed value.

    @type !IntN
    @access public const

    IntN.MIN_VALUE

    Minimum signed value.

    @type !IntN
    @access public const

    IntN.NEG_ONE

    Negative signed one.

    @type !IntN
    @access public const

    IntN.ONE

    Signed one.

    @type !IntN
    @access public const

    IntN.UONE

    Unsigned one.

    @type !IntN
    @access public const

    IntN.UZERO

    Unsigned zero.

    @type !IntN
    @access public const

    IntN.ZERO

    Signed zero.

    @type !IntN
    @access public const

    IntN.add(augend, addend)

    Adds the specified IntNs. Does not type check arguments.

    Parameter Type Description
    augend !IntN Augend
    addend !IntN Addend
    @returns !IntN Sum

    IntN.divide(dividend, divisor)

    Divides the specified dividend by the specified divisor and returns both the quotient and the remainder. Does not type check arguments.

    Parameter Type Description
    dividend !IntN Dividend
    divisor !IntN Divisor
    @returns !{quotient: !IntN, remainder: !IntN} Quotient and remainder

    IntN.fromInt(value, unsigned=)

    Constructs an IntN from a 32 bit integer value.

    Parameter Type Description
    value number Integer value
    unsigned boolean Whether unsigned or not, defaults to false for signed
    @returns !IntN

    IntN.fromInts(ints, unsigned=)

    Reassembles an IntN from an array of 32 bit integers, least significant first.

    Parameter Type Description
    ints !Array.<number> Array of 32 bit integers
    unsigned boolean Whether unsigned or not, defaults to false for signed
    @returns !IntN

    IntN.fromNumber(value, unsigned=)

    Constructs an IntN from a number (double, 52 bit mantissa) value. This differs from IntN.fromInt in using arithmetic operations on numbers instead of logical operations on 32 bit integers, which works reliably up to a maximum positive or negative value of 2^53-1.

    Parameter Type Description
    value number Number value
    unsigned boolean Whether unsigned or not, defaults to false for signed
    @returns !IntN
    @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MIN_SAFE_INTEGER
    @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER

    IntN.fromString(value, unsigned=, radix=)

    Converts a string using the specified radix to an IntN.

    Parameter Type Description
    value string String
    unsigned boolean | number Whether unsigned or not, defaults to false for signed (omittable)
    radix number Radix (2-36), defaults to 10
    @returns !IntN
    @throws RangeError If radix is out of range
    @throws Error If value contains illegal characters

    IntN.isIntN(obj)

    Tests if an object is an N bit integer, where N is this class's number of bits.

    Parameter Type Description
    obj *** Object to test
    @returns boolean true if it is an N bit integer, otherwise false

    IntN.multiply(multiplicand, multiplier)

    Multiplies the specified IntNs and returns the product. Does not type check arguments.

    Parameter Type Description
    multiplicand !IntN Multiplicand
    multiplier !IntN Multiplier
    @returns !IntN Product

    IntN.subtract(minuend, subtrahend)

    Subtracts the second from the first specified IntN. Does not type check arguments.

    Parameter Type Description
    minuend !IntN Minuend
    subtrahend !IntN Subtrahend
    @returns !IntN Difference

    IntN.valueOf(val)

    Converts the specified value to an IntN.

    Parameter Type Description
    val !IntN | number | string | !{bytes: !Array.<number>, unsigned: boolean} | {low: number, high: number, unsigned: boolean} Value
    @returns !IntN

    IntN#bytes

    Represented byte values, least significant first.

    @type !Array.<number>

    IntN#unsigned

    Whether unsigned or otherwise signed.

    @type boolean

    IntN#absolute()

    Returns this IntN's absolute value as an unsigned IntN.

    Parameter Type Description
    @returns !IntN Absolute

    IntN#add(addend)

    Adds the specified to this IntN.

    Parameter Type Description
    addend !IntN | number | string Addend
    @returns !IntN Sum

    IntN#and(other)

    Performs a bitwise and (&) operation and returns the resulting Int.

    Parameter Type Description
    other !IntN | number | string Other number
    @returns !IntN

    IntN#cast(TargetIntN, unsigned=)

    Casts this IntN of size N to the specified target IntN of size M.

    Parameter Type Description
    TargetIntN !Function Target IntN class
    unsigned boolean Whether unsigned or not, defaults to this' IntN#unsigned
    @returns !IntN

    IntN#compare(other)

    Compares this IntN with the specified.

    Parameter Type Description
    other !IntN | number | string Other value
    @returns number 0 if both are the same, 1 if this is greater and -1 if the specified is greater

    IntN#divide(divisor)

    Divides this IntN by the specified and returns the quotient.

    Parameter Type Description
    divisor !IntN | number | string Divisor
    @returns !IntN Quotient

    IntN#equals(other)

    Tests if this IntN equals the specified.

    Parameter Type Description
    other !IntN | number | string Other value
    @returns boolean

    IntN#greaterThan(other)

    Tests if this IntN is greater than (>) the specified.

    Parameter Type Description
    other !IntN | number | string Other value
    @returns boolean

    IntN#greaterThanEqual(other)

    Tests if this IntN is greater than or equal (>=) the specified.

    Parameter Type Description
    other !IntN | number | string Other value
    @returns boolean

    IntN#isEven()

    Tests if this IntN is even.

    Parameter Type Description
    @returns boolean

    IntN#isNegative()

    Tests if this IntN is (signed and) negative.

    Parameter Type Description
    @returns boolean

    IntN#isOdd()

    Tests if this IntN is odd.

    Parameter Type Description
    @returns boolean

    IntN#isPositive()

    Tests if this IntN is (unsigned or) positive.

    Parameter Type Description
    @returns boolean

    IntN#isSet(i)

    Evaluates the bit at the specified position. Using this method is usually much faster than alternative ways.

    Parameter Type Description
    i number Position (0 to (N-1))
    @returns boolean true if the bit is 1, false if it is 0

    IntN#isSigned()

    Tests if this IntN is signed.

    Parameter Type Description
    @returns boolean

    IntN#isUnsigned()

    Tests if this IntN is unsigned.

    Parameter Type Description
    @returns boolean

    IntN#isZero()

    Tests if this IntN is zero.

    Parameter Type Description
    @returns boolean

    IntN#lessThan(other)

    Tests if this IntN is less than (<) the specified.

    Parameter Type Description
    other !IntN | number | string Other value
    @returns boolean

    IntN#lessThanEqual(other)

    Tests if this IntN is less than or equal (<=) the specified.

    Parameter Type Description
    other !IntN | number | string Other value
    @returns boolean

    IntN#modulo(divisor)

    Divides this IntN by the specified and returns the remainder.

    Parameter Type Description
    divisor !IntN | number | string Divisor
    @returns !IntN Remainder

    IntN#multiply(multiplier)

    Multiplies this IntN with the specified and returns the product.

    Parameter Type Description
    multiplier !IntN | number | string Multiplier
    @returns !IntN Product

    IntN#negate()

    Negates this IntN (*-1).

    Parameter Type Description
    @returns !IntN Negation

    IntN#not()

    Performs a bitwise not (~) operation and returns the result.

    Parameter Type Description
    @returns !IntN

    IntN#notEquals(other)

    Tests if this IntN does not equal the specified.

    Parameter Type Description
    other !IntN | number | string Other value
    @returns boolean

    IntN#or(other)

    Performs a bitwise or (|) operation and returns the resulting Int.

    Parameter Type Description
    other !IntN | number | string Other number
    @returns !IntN

    IntN#set(i, isSet)

    Sets the bit at the specified position and returns the result. Using this method is usually much faster than alternative ways.

    Parameter Type Description
    i number Position (0 to (N-1))
    isSet boolean true to set the bit to 1, false to set it to 0
    @returns !IntN

    IntN#shiftLeft(numBits)

    Performs a shift left (<<) operation and returns the result.

    Parameter Type Description
    numBits !IntN | number Number of bits
    @returns !IntN

    IntN#shiftRight(numBits, logical=)

    Performs a shift right (>>, >>>) operation and returns the result.

    Parameter Type Description
    numBits !IntN | number Number of bits
    logical boolean Whether to perform a logical (>>>) shift right, defaults to false for an arithmetic shift right (>>)
    @returns !IntN

    IntN#shiftRightUnsigned(numBits)

    Performs an unsigned shift right (>>>) operation and returns the result.

    Parameter Type Description
    numBits !IntN | number Number of bits
    @returns !IntN Shifted

    IntN#size()

    Returns the number of bits required to fully represent this IntN's value.

    Parameter Type Description
    @returns number Shift of the most significant bit (0 to N)

    IntN#subtract(subtrahend)

    Subtracts the specified from this IntN and returns the difference.

    Parameter Type Description
    subtrahend !IntN | number | string Subtrahend
    @returns !IntN Difference

    IntN#toDebug(addSpaces=)

    Converts this IntN to its full binary representation. This returns N (number of bits) binary digits for testing and debugging, followed by the character U if unsigned.

    Parameter Type Description
    addSpaces boolean Whether to insert spaces between bytes, defaults to false
    @returns string

    IntN#toInt(unsigned=)

    Converts this IntN to a 32 bit integer.

    Parameter Type Description
    unsigned boolean Whether unsigned or not, defaults to this' IntN#unsigned
    @returns number

    IntN#toInts()

    Disassembles this IntN into an array of 32 bit integers, least significant first.

    Parameter Type Description
    @returns !Array.<number>

    IntN#toNumber()

    Converts this IntN to a number (double, 52 bit mantissa) value. This differs from IntN#toInt in using arithmetic operations on numbers instead of logical operations on 32 bit integers, which works reliably up to a maximum positive or negative value of 2^53-1. A maximum of 56 bits is evaluated.

    Parameter Type Description
    @returns number
    @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MIN_SAFE_INTEGER
    @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER

    IntN#toSigned()

    Converts this IntN to signed and returns the result.

    Parameter Type Description
    @returns !IntN

    IntN#toString(radix)

    Converts this IntN to a string of the specified radix.

    Parameter Type Description
    radix !IntN | number | string Radix (2-36), defaults to 10
    @returns string
    @throws RangeError If radix is out of range

    IntN#toUnsigned()

    Converts this IntN to unsigned and returns the result.

    Parameter Type Description
    @returns !IntN

    IntN#xor(other)

    Performs a bitwise xor (^) operation and returns the result.

    Parameter Type Description
    other !IntN | number | string Other number
    @returns !IntN

    Aliases

    Most of the methods have a couple of aliases to maintain compatibility with other libraries, to make it more convenient to use or simply to keep your code small:

    General utility:
    • isIntN: isInt[NBITS] with [NBITS] being the number of bits provided to IntN (e.g. 32)
    Arithmetic evaluation:
    • compare: comp
    • equals: eq, equal, ==
    • notEquals: ne, notEqual, !=
    • lessThan: lt, less, <
    • lessThanEqual: lte, lessThanOrEqual, <=
    • greaterThan: gt, greater, >
    • greaterThanEqual: gte, greaterThanOrEqual, >=
    Bitwise operations:
    • not: ~
    • and: &
    • or: |
    • xor: ^
    • shiftLeft: lsh, leftShift, <<
    • shiftRight: rsh, rightShift, >>
    • shiftRightUnsigned: rshu, rightShiftUnsigned, >>>
    Arithmetic operations:
    • add: plus, +
    • negate: neg, !
    • subtract: sub, minus, -
    • absolute: abs, ||
    • multiply: mult, *
    • divide: div, /
    • modulo: mod, %

    If you like it rather formal:

    var a = Int32.fromNumber(1),
        b = Int32.fromNumber(2);
        
    var c = a['+'](b)['/'](3);

    Downloads

    License: Apache License, Version 2.0

    Install

    npm i intn

    DownloadsWeekly Downloads

    28

    Version

    1.0.0

    License

    Apache-2.0

    Last publish

    Collaborators

    • dcode