integer 

Native 64-bit signed integers in Node.js.

- All standard operators (arithmetic, bitwise, logical)
- Protection from overflow and unsafe numbers
- Always immutable
- Other useful utilities

Installation

``bash
npm install --save integer
`

> You must be using Node.js v10 or above. Prebuilt binaries are available for LTS versions + Linux/OSX.

Usage

`js
var Integer = require('integer');

var a = Integer('7129837312139827189');
var b = a.subtract(1).shiftRight(3);
assert(b.equals('891229664017478398'));
`

Overflow protection

We will not let you perform operations that would result in overflow. If you try to create an Integer that cannot be represented in 64-bits (signed), we will throw a RangeError.

`js
// These will each throw a RangeError
var tooBig = Integer(13897283129).multiply(13897283129);
var tooSmall = Integer.MIN_VALUE.subtract(1);
var divideByZero = Integer(123).divide(0);
var alsoTooBig = Integer('4029384203948203948923');

// You are also protected against two's complement overflow (this will throw a RangeError)
var twosComplement = Integer.MIN_VALUE.divide(-1);
`

Unsafe number protection

It's easy to convert between me and regular JavaScript numbers.

`js
var int = Integer(12345);
assert(int instanceof Integer);

var num = Number(int); // same as int.toNumber()
assert(typeof num === 'number');
`

However, we will prevent you from converting an Integer to an unsafe number, and vice-versa. To learn more about unsafe numbers, click here.

`js
// This will throw a RangeError
var unsafe = Integer(Number.MAX_SAFE_INTEGER + 1);

// This is okay
var int = Integer(Number.MAX_SAFE_INTEGER).plus(1);

// But this will throw a RangeError
var unsafe = int.toNumber();
`

API

$3

Casts a value to an Integer. If the value cannot be converted safely and losslessly, a RangeError is thrown.

`js
var a = Integer();
var b = Integer(12345);
var c = Integer('12345');
assert(a.equals(0));
assert(b.equals(c));
`

$3

Casts a regular number to an Integer.

If the number is unsafe the defaultValue is used instead (or a RangeError is thrown if no defaultValue was provided).

`js
Integer.fromNumber(12345, 0); // results in Integer(12345)
Integer.fromNumber(Number.MAX_SAFE_INTEGER + 1, 0); // results in Integer(0)
`

$3

Casts a string to an Integer. The string is assumed to be base-10 unless a different radix is specified.

If conversions fails the defaultValue is used instead (or a RangeError is thrown if no defaultValue was provided).

`js
var hexColor = 'ff55dd';
var int = Integer.fromString(hexColor, 16, 'ffffff');
`

$3

Creates an Integer by concatenating two regular 32-bit signed integers. The highBits are optional and default to 0.

`js
var int = Integer.fromBits(0x40, 0x20);
int.toString(16); // => '2000000040'
`

Arithmetic operations

####     .add/plus(other) -> Integer
####     .subtract/sub/minus(other) -> Integer
####     .multiply/mul/times(other) -> Integer
####     .divide/div/divideBy/dividedBy/over(other) -> Integer
####     .modulo/mod(other) -> Integer

Performs the arithmetic operation and returns a new Integer. The argument must either be a number, a base-10 string, or an Integer. If the operation results in overflow, a RangeError is thrown.

####     .negate/neg() -> Integer

Returns the unary negation (-value) of the Integer.

####     .abs/absoluteValue() -> Integer

Returns the absolute value of the Integer.

Bitwise operations

####     .and(other) -> Integer
####     .or(other) -> Integer
####     .xor(other) -> Integer
####     .not() -> Integer

Performs the bitwise operation and returns a new Integer. The argument must either be a number, a base-10 string, or an Integer.

####     .shiftLeft/shl(numberOfBits) -> Integer
####     .shiftRight/shr(numberOfBits) -> Integer

Shifts the Integer by specified number of bits and returns the result.

Logical operations

####     .equals/eq/isEqualTo(other) -> boolean
####     .notEquals/neq/isNotEqualTo/doesNotEqual(other) -> boolean
####     .greaterThan/gt/isGreaterThan(other) -> boolean
####     .lessThan/lt/isLessThan(other) -> boolean
####     .greaterThanOrEquals/gte/isGreaterThanOrEqualTo(other) -> boolean
####     .lessThanOrEquals/lte/isLessThanOrEqualTo(other) -> boolean

Performs the logical operation and returns true or false. The argument must either be a number, a base-10 string, or an Integer.

####     .compare(other) -> number

Compares the value of the Integer and other, resulting in:
- -1 if this is less than other
- 1 if this is greater than other
- 0 if this is equal to other

Converting to other values

####     .toString([radix]) -> string

Converts the Integer to a string. A base-10 string is returned unless a different radix is specified.

####     .valueOf/toNumber() -> number

Converts the Integer to a regular number. If the Integer is not within the safe range, a RangeError is thrown.

####     .toNumberUnsafe() -> number

Converts the Integer to a regular number, even if the conversion would result in a loss of precision. This method will never throw an error.

Other utility

####     .bitSizeAbs() -> number

Returns the number of bits necessary to hold the absolute value of the Integer.

`js
Integer(0).bitSizeAbs(); // => 1
Integer(128).bitSizeAbs(); // => 8
Integer(-255).bitSizeAbs(); // => 8
Integer.fromString('4fffffffffff', 16).bitSizeAbs(); // => 47
`

####     .isEven() -> boolean
####     .isOdd() -> boolean
####     .isPositive() -> boolean
####     .isNegative() -> boolean
####     .isZero() -> boolean
####     .isNonZero/isNotZero() -> boolean

These methods are self-explanatory.

####     .isSafe() -> boolean
####     .isUnsafe() -> boolean

Returns whether or not the Integer is within the safe range. If it's not within the safe range, trying to convert it to a regular number would result in a RangeError being thrown.

The safe range is defined as n >= Number.MIN_SAFE_INTEGER && n <= Number.MAX_SAFE_INTEGER.

#### Integer.isInstance(value) -> boolean

Determines if the given value is an Integer object.

#### Getters

- .low -> _number_ - the lower 32-bits of the Integer
- .high -> _number_ - the upper 32-bits of the Integer

#### Constants

- Integer.MAX_VALUE - maximum value of an Integer
- Integer.MIN_VALUE - minimum value of an Integer
- Integer.ZERO - an Integer with a value of 0
- Integer.ONE - an Integer with a value of 1
- Integer.NEG_ONE - an Integer with a value of -1`

License

MIT