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.
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 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.
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);