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

• ZIP-Archive
• Tarball
• Distributions

License: Apache License, Version 2.0