Package Exports
- integer
This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (integer) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.
Readme
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
npm install --save integer
You must be using Node.js v10 or above. Prebuilt binaries are available for LTS versions + Linux/OSX.
Usage
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
.
// 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.
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.
// 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
Integer(value) -> Integer
Casts a value to an Integer
. If the value cannot be converted safely and losslessly, a RangeError
is thrown.
var a = Integer();
var b = Integer(12345);
var c = Integer('12345');
assert(a.equals(0));
assert(b.equals(c));
Integer.fromNumber(number, [defaultValue]) -> Integer
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).
Integer.fromNumber(12345, 0); // results in Integer(12345)
Integer.fromNumber(Number.MAX_SAFE_INTEGER + 1, 0); // results in Integer(0)
Integer.fromString(string, [radix, [defaultValue]]) -> Integer
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).
var hexColor = 'ff55dd';
var int = Integer.fromString(hexColor, 16, 'ffffff');
Integer.fromBits(lowBits, [highBits]) -> Integer
Creates an Integer
by concatenating two regular 32-bit signed integers. The highBits
are optional and default to 0
.
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
ifthis
is less thanother
1
ifthis
is greater thanother
0
ifthis
is equal toother
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
.
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 of0
- Integer.ONE - an
Integer
with a value of1
- Integer.NEG_ONE - an
Integer
with a value of-1