intn v1.0.0

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.

IntN.BITS

Number of bits represented by this IntN class.

IntN.BYTES

Number of bytes represented by this IntN class.

IntN.MAX_UNSIGNED_VALUE

Maximum unsigned value.

IntN.MAX_VALUE

Maximum signed value.

IntN.MIN_VALUE

Minimum signed value.

IntN.NEG_ONE

Negative signed one.

IntN.ONE

Signed one.

IntN.UONE

Unsigned one.

IntN.UZERO

Unsigned zero.

IntN.ZERO

Signed zero.

IntN.add(augend, addend)

Adds the specified IntNs. Does not type check arguments.

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.

IntN.fromInt(value, unsigned=)

Constructs an IntN from a 32 bit integer value.

IntN.fromInts(ints, unsigned=)

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

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.

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

Converts a string using the specified radix to an IntN.

IntN.isIntN(obj)

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

IntN.multiply(multiplicand, multiplier)

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

IntN.subtract(minuend, subtrahend)

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

IntN.valueOf(val)

Converts the specified value to an IntN.

IntN#bytes

Represented byte values, least significant first.

IntN#unsigned

Whether unsigned or otherwise signed.

IntN#absolute()

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

IntN#add(addend)

Adds the specified to this IntN.

IntN#and(other)

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

IntN#cast(TargetIntN, unsigned=)

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

IntN#compare(other)

Compares this IntN with the specified.

IntN#divide(divisor)

Divides this IntN by the specified and returns the quotient.

IntN#equals(other)

Tests if this IntN equals the specified.

IntN#greaterThan(other)

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

IntN#greaterThanEqual(other)

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

IntN#isEven()

Tests if this IntN is even.

IntN#isNegative()

Tests if this IntN is (signed and) negative.

IntN#isOdd()

Tests if this IntN is odd.

IntN#isPositive()

Tests if this IntN is (unsigned or) positive.

IntN#isSet(i)

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

IntN#isSigned()

Tests if this IntN is signed.

IntN#isUnsigned()

Tests if this IntN is unsigned.

IntN#isZero()

Tests if this IntN is zero.

IntN#lessThan(other)

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

IntN#lessThanEqual(other)

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

IntN#modulo(divisor)

Divides this IntN by the specified and returns the remainder.

IntN#multiply(multiplier)

Multiplies this IntN with the specified and returns the product.

IntN#negate()

Negates this IntN (*-1).

IntN#not()

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

IntN#notEquals(other)

Tests if this IntN does not equal the specified.

IntN#or(other)

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

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.

IntN#shiftLeft(numBits)

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

IntN#shiftRight(numBits, logical=)

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

IntN#shiftRightUnsigned(numBits)

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

IntN#size()

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

IntN#subtract(subtrahend)

Subtracts the specified from this IntN and returns the 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.

IntN#toInt(unsigned=)

Converts this IntN to a 32 bit integer.

IntN#toInts()

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

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.

IntN#toSigned()

Converts this IntN to signed and returns the result.

IntN#toString(radix)

Converts this IntN to a string of the specified radix.

IntN#toUnsigned()

Converts this IntN to unsigned and returns the result.

IntN#xor(other)

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

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: isIntNBITS 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