1.0.0 • Published 12 years ago

intn

Licence

Apache-2.0

Version

1.0.0

Deps

Vulns

Weekly

Stars

Summary Dependency Versions

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

Keywords

math byte short integer long bitwise arithmetic signed unsigned