n64

Optimized int64 object for javascript.

---

There are a few different int64 libraries which currently exist for javascript.
Some native, some non-native. Most are lacking test coverage. n64 gives you a
native and non-native version which both have full test coverage.

Install

`` bash
$ npm install n64
`

Usage

` js
const {U64, I64} = require('n64');

console.log(U64(0x12345678900).muln(0x12345678));
console.log(I64(0x12345678900).muln(0x12345678));
`

Outputs:

`


`

API

n64 tries to mimic the [bn.js] API as much as possible. Like bn.js, each
method follows a pattern of (i?)(operation)(n?).

$3

- i - Perform the operation in-place.

$3

- n - Function must be passed a 32 bit javascript number.

For example, a.add(b) will clone the current object, do the addition, and
return a new object. a.iadd(b) will do the addition _in place_. a.addn(b)
will do the "cloned" addition with b being a 32 bit JS number, and
a.iaddn(b) will do the same thing _in-place_.

$3

There are two constructors: U64 and I64, both containing the same methods.
The N64 object documented below applies to both n64.U64 and n64.I64.

- new N64() - Instantiate.
- new N64(num) - Instantiate from JS number.
- new N64(bool) - Instantiate from boolean.
- new N64(hi, lo) - Instantiate from hi/lo bits.
- new N64(obj) - Instantiate from object (hi & lo).
- new N64(str, base?) - Instantiate from string.
- new N64(bn) - Instantiate from bn.js bignumber.
- new N64(data) - Instantiate from bytes (little endian).

$3

- hi - Internal hi bits (int32).
- lo - Internal lo bits (int32).
- sign - Whether the int64 is signed (0 or 1).

$3

- N64.min(a, b) - Pick min value.
- N64.max(a, b) - Pick max value.
- N64.random() - Instantiate random int64.
- N64.pow(num, exp) - Instantiate from number and power.
- N64.shift(num, bits) - Instantiate from left shift.
- N64.readLE(data, off) - Instantiate from data at off (little endian).
- N64.readBE(data, off) - Instantiate from data at off (big endian).
- N64.readRaw(data, off) - Instantiate from data at off (little endian).
- N64.fromNumber(num) - Instantiate from JS number.
- N64.fromInt(lo) - Instantiate from lo bits.
- N64.fromBool(value) - Instantiate from boolean.
- N64.fromBits(hi, lo) - Instantiate from hi/lo bits.
- N64.fromObject(obj) - Instantiate from object (hi & lo).
- N64.fromString(str, base?) - Instantiate from string.
- N64.fromJSON(json) - Instantiate from JSON.
- N64.fromBN(bn) - Instantiate from bn.js bignumber.
- N64.fromLE(data) - Instantiate from bytes (little endian).
- N64.fromBE(data) - Instantiate from bytes (big endian).
- N64.fromRaw(data) - Instantiate from bytes (little endian).
- N64.from() - Instantiate.
- N64.from(num) - Instantiate from JS number.
- N64.from(bool) - Instantiate from boolean.
- N64.from(hi, lo) - Instantiate from hi/lo bits.
- N64.from(obj) - Instantiate from object (hi & lo).
- N64.from(str, base?) - Instantiate from string.
- N64.from(bn) - Instantiate from bn.js bignumber.
- N64.from(data) - Instantiate from bytes (little endian).
- N64.isN64(obj) - Test instanceof N64.
- N64.isU64(obj) - Test instanceof U64.
- N64.isI64(obj) - Test instanceof I64.

$3

#### Arithmetic

- N64#iadd(obj) - In-place addition with another int64.
- N64#iaddn(num) - In-place addition with a JS number.
- N64#add(obj) - Cloned addition with another int64.
- N64#addn(num) - Cloned addition with a JS number.
- N64#isub(obj) - In-place subtraction with another int64.
- N64#isubn(num) - In-place subtraction with a JS number.
- N64#sub(obj) - Cloned subtraction with another int64.
- N64#subn(num) - Cloned subtraction with a JS number.
- N64#imul(obj) - In-place multiplication with another int64.
- N64#imuln(num) - In-place multiplication with a JS number.
- N64#mul(obj) - Cloned multiplication with another int64.
- N64#muln(num) - Cloned multiplication with a JS number.
- N64#idiv(obj) - In-place division with another int64.
- N64#idivn(num) - In-place division with a JS number.
- N64#div(obj) - Cloned division with another int64.
- N64#divn(num) - Cloned division with a JS number.
- N64#imod(obj) - In-place modulo with another int64.
- N64#imodn(num) - In-place modulo with a JS number.
- N64#mod(obj) - Cloned modulo with another int64.
- N64#modn(num) - Cloned modulo with a JS number.
- N64#ipow(obj) - In-place exponentiation with another int64.
- N64#ipown(num) - In-place exponentiation with a JS number.
- N64#pow(obj) - Cloned exponentiation with another int64.
- N64#pown(num) - Cloned exponentiation with a JS number.
- N64#isqr() - Square number in-place.
- N64#sqr() - Clone and square number.

#### Bitwise

- N64#iand(obj) - In-place AND with another int64.
- N64#iandn(num) - In-place AND with a JS number.
- N64#and(obj) - Cloned AND with another int64.
- N64#andn(num) - Cloned AND with a JS number.
- N64#ior(obj) - In-place OR with another int64.
- N64#iorn(num) - In-place OR with a JS number.
- N64#or(obj) - Cloned OR with another int64.
- N64#orn(num) - Cloned OR with a JS number.
- N64#ixor(obj) - In-place XOR with another int64.
- N64#ixorn(num) - In-place XOR with a JS number.
- N64#xor(obj) - Cloned XOR with another int64.
- N64#xorn(num) - Cloned XOR with a JS number.
- N64#inot() - In-place NOT.
- N64#not() - Cloned NOT.
- N64#ishl(obj) - In-place left-shift with another int64.
- N64#ishln(num) - In-place left-shift with a JS number.
- N64#shl(obj) - Cloned left-shift with another int64.
- N64#shln(num) - Cloned left-shift with a JS number.
- N64#ishr(obj) - In-place right-shift with another int64.
- N64#ishrn(num) - In-place right-shift with a JS number.
- N64#shr(obj) - Cloned right-shift with another int64.
- N64#shrn(num) - Cloned right-shift with a JS number.
- N64#iushr(obj) - In-place unsigned right-shift with another int64.
- N64#iushrn(num) - In-place unsigned right-shift with a JS number.
- N64#ushr(obj) - Cloned unsigned right-shift with another int64.
- N64#ushrn(num) - Cloned unsigned right-shift with a JS number.
- N64#setn(bit, val) - Set specified bit to val (in-place).
- N64#testn(bit) - Test whether a bit is set.
- N64#setb(pos, ch) - Set byte ch at position pos (in-place).
- N64#orb(pos, ch) - OR byte ch at position pos (in-place).
- N64#getb(pos) - Get byte at position pos.
- N64#imaskn(bit) - Clear bits higher or equal to bit (in-place).
- N64#maskn(bit) - Clear bits higher or equal to bit.
- N64#andln(num) - Perform AND on lo 32 bits (returns JS number).

#### Negation

- N64#ineg() - In-place negation.
- N64#neg() - Cloned negation.
- N64#iabs() - In-place absolute.
- N64#abs() - Cloned absolute.

#### Comparison

- N64#cmp(obj) - Compare to another int64.
- N64#cmpn(num) - Compare to a JS number.
- N64#eq(obj) - Test equality against another int64.
- N64#eqn(num) - Test equality against a JS number.
- N64#gt(obj) - Greater than (int64).
- N64#gtn(num) - Greater than (JS number).
- N64#gte(obj) - Greater than or equal to (int64).
- N64#gten(num) - Greater than or equal to (JS number).
- N64#lt(obj) - Less than (int64).
- N64#ltn(num) - Less than (JS number).
- N64#lte(obj) - Less than or equal to (int64).
- N64#lten(num) - Less than or equal to (JS number).
- N64#isZero() - Test whether int64 is zero.
- N64#isNeg() - Test whether int64 is negative.
- N64#isOdd() - Test whether int64 is odd.
- N64#isEven() - Test whether int64 is even.

#### Helpers

- N64#clone() - Clone and return a new int64.
- N64#inject(obj) - Inject properties from int64.
- N64#set(num) - Set the int64 to a JS number value.
- N64#join(hi, lo) - Join hi and lo bits.
- N64#bitLength() - Count number of bits.
- N64#byteLength() - Count number of bytes.
- N64#isSafe() - Test whether the number is less than or equal to 53 bits.
- N64#inspect() - Inspect number.

#### Encoding

- N64#readLE(data, off) - Read number from data at off (little endian).
- N64#readBE(data, off) - Read number from data at off (big endian).
- N64#readRaw(data, off) - Read number from data at off (little endian).
- N64#writeLE(data, off) - Write number to data at off (little endian).
- N64#writeBE(data, off) - Write number to data at off (big endian).
- N64#writeRaw(data, off) - Write number to data at off (little endian).

#### Conversion

- N64#toU64() - Cast to unsigned. Returns a U64.
- N64#toI64() - Cast to signed. Returns an I64.
- N64#toNumber() - Convert int64 to a JS number (throws on >53 bits).
- N64#toDouble() - Convert int64 to a JS number.
- N64#toInt() - Convert lo bits to a JS number.
- N64#toBool() - Convert to a boolean.
- N64#toBits() - Convert to an array containing hi and lo bits.
- N64#toObject() - Convert to an object containing hi and lo bits.
- N64#toString(base?, pad?) - Convert to string of base. Optional padding.
- N64#toJSON() - Convert to hex string.
- N64#toBN(BN) - Convert to bn.js big number (must pass BN constructor).
- N64#toLE(ArrayLike) - Convert to ArrayLike instance (little endian).
- N64#toBE(ArrayLike) - Convert to ArrayLike instance (big endian).
- N64#toRaw(ArrayLike) - Convert to ArrayLike instance (little endian).

$3

- U64.ULONG_MIN - Unsigned int32 minimum (number).
- U64.ULONG_MAX - Unsigned int32 maximum (number).
- U64.UINT32_MIN - Unsigned int32 minimum (U64).
- U64.UINT32_MAX - Unsigned int32 maximum (U64).
- U64.UINT64_MIN - Unsigned int64 minimum (U64).
- U64.UINT64_MAX - Unsigned int64 maximum (U64).
- I64.LONG_MIN - Int32 minimum (number).
- I64.LONG_MAX - Int32 maximum (number).
- I64.INT32_MIN - Int32 minimum (I64).
- I64.INT32_MAX - Int32 maximum (I64).
- I64.INT64_MIN - Int64 minimum (I64).
- I64.INT64_MAX - Int64 maximum (I64).

Casting

With mixed types, the left operand will cast the right operand to its sign.

With the n-postfix methods, numbers passed into them will be cast to 32 bit
integers. If the left had operand is signed, the number is cast to an
int32_t. If unsigned, the number is cast to an uint32_t.

$3

In JS:

` js
const a = I64(1);
const b = U64('ffffffffffffffff', 16);
const r = a.add(b);
console.log(r.toString());
`

In C:

` c
int64_t a = 1;
uint64_t b = 0xffffffffffffffff;
int64_t r = a + (int64_t)b;
printf("%lld\n", r);
`

Outputs 0, as (int64_t)ULLONG_MAX == -1LL.

---

In JS:

` js
const a = I64(0);
const r = a.addn(0xffffffff);
console.log(r.toString());
`

In C:

` c
int64_t a = 0;
int64_t r = a + (int32_t)0xffffffff;
printf("%lld\n", r);
`

Outputs -1.

---

In JS:

` js
const a = U64(0);
const r = a.addn(-1);
console.log(r.toString());
`

In C:

` c
uint64_t a = 0;
uint64_t r = a + (uint32_t)-1;
printf("%llu\n", r);
`

Outputs 4294967295.

Testing

` bash
$ npm test
`

This should run all test vectors for both the native and non-native backend.

Fuzzing

A fuzzer is present for testing of operations vs. actual machine operations.

` bash
$ node test/fuzz.js
`

Benchmarks

Benchmarks are run against bn.js.

` bash
$ node bench
`

Contribution and License Agreement

If you contribute code to this project, you are implicitly allowing your code
to be distributed under the MIT license. You are also implicitly verifying that
all code is your original work. `

License

- Copyright (c) 2017, Christopher Jeffrey. (MIT License)

See LICENSE for more info.

[bn.js]: https://github.com/indutny/bn.js