# as-bigint

> AssemblyScript package for math with arbitrarily large integers

Latest version **0.5.3** (published 2022-03-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install as-bigint
pnpm add as-bigint
yarn add as-bigint
bun add as-bigint
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.5.3 |
| Published | 2022-03-03 |
| First published | 2021-04-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 124.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 18 |
| Maintainers | krisbitney |

## Links

- npm: https://www.npmjs.com/package/as-bigint
- Repository: https://github.com/polywrap/as-bigint
- npm.io page: https://npm.io/package/as-bigint

## Recent versions

- 0.5.3 (latest) — 2022-03-03
- 0.5.2 — 2022-03-02
- 0.5.1 — 2022-02-25
- 0.5.0 — 2022-02-25
- 0.4.0 — 2021-11-28
- 0.3.2 — 2021-11-16
- 0.3.1 — 2021-11-16
- 0.3.0 — 2021-11-16
- 0.2.4 — 2021-04-27
- 0.2.3 — 2021-04-21
- 0.2.2 — 2021-04-21
- 0.2.1 — 2021-04-21
- 0.2.0 — 2021-04-20
- 0.1.3 — 2021-04-15
- 0.1.2 — 2021-04-07
- … 2 more at https://npm.io/package/as-bigint/versions

## README

# BigInt
BigInt is an AssemblyScript class for math with arbitrarily large integers.

## Features

- Fast arithmetic operations
- Lightweight
- Immutable instances
- Core operations thoroughly tested

## Getting Started

### Installation
`npm install as-bigint`  
or  
`yarn add as-bigint`

### Quick start

```typescript
import { BigInt } from "as-bigint"

// generic constructor supports string and all native integer types
const generic: BigInt = BigInt.from(42);
// read BigInt from string
const a: BigInt = BigInt.fromString("19374529734987892634530927528739060327972904713094389147895891798347509179347517");
// fromString and toString methods optionally take a radix argument
const b: BigInt = BigInt.fromString("9F59E5Ed123C10D57E92629612511b14628D2799", 16);
// for hex strings, a radix argument is not required if value is prefixed by 0x (or -0x for negative numbers)
const fromHex: BigInt = BigInt.fromString("0x9F59E5Ed123C10D57E92629612511b14628D2799");

// arithmetic (operator overloads: +, -, *, /, %, **)
const sum: BigInt = a.add(b);
const difference: BigInt = a.sub(b);
const product: BigInt = a.mul(b);
const quotient: BigInt = a.div(b);
const remainder: BigInt = a.mod(b);
const exponential: BigInt = a.pow(3);
const squared: BigInt = a.square();
const squareRoot: BigInt = a.sqrt();
const roundedQuotient: BigInt = a.roundedDiv(b);

// faster operations when right-side variable is a 32 bit unsigned integer:
const c: u32 = 1234;
const intSum: BigInt = a.addInt(c);
const intDifference: BigInt = a.subInt(c);
const intProduct: BigInt = a.mulInt(c);
const intQuotient: BigInt = a.divInt(c);
const intRemainder: BigInt = a.modInt(c);
const intRoundedQuotient: BigInt = a.roundedDivInt(c);

// fast multiply and divide by 2 or power of 2
const mulByTwo: BigInt = a.mul2();
const mulByEight: BigInt = a.mulPowTwo(3);
const divBuTwo: BigInt = a.div2();
const divBySixteen: BigInt = a.divPowTwo(4);

// signed arithmetic bit shifts (operator overloads: <<, >>)
const shiftLeft3bits: BigInt = a.leftShift(3);
const shiftRight4bits: BigInt = a.rightShift(4);

// bitwise operations (operator overloads: ~, &, |, ^)
const not: BigInt = BigInt.bitwiseNot(bigIntA);
const and: BigInt = BigInt.bitwiseAnd(bigIntA, bigIntB);
const or: BigInt = BigInt.bitwiseOr(bigIntA, bigIntB);
const xor: BigInt = BigInt.bitwiseXor(bigIntA, bigIntB);

// comparison operations (operator overloads: ==, !=, <, <=, >, >=)
const isEqual: boolean = a.eq(b);
const isNotEqual: boolean = a.ne(b);
const isLessThan: boolean = a.lt(b);
const isLessThanOrEqualTo: boolean = a.lte(b);
const isGreaterThan: boolean = a.gt(b);
const isGreaterThanOrEqualTo: boolean = a.gte(b);

// binary arithmetic, comparison, and bitwise operators also have static implementations
const staticProduct: BigInt = BigInt.mul(a, b);
const staticIsEqual: boolean = BigInt.eq(a, b);
const staticAnd: boolean = BigInt.bitwiseAnd(a, b);

// instantiate new copy, absolute value, or opposite
const sameNumber: BigInt = a.copy();
const positiveNumber: BigInt = a.abs();
const oppositeSign: BigInt = a.opposite();

// convenience functions
const sizeOfNumber: i32 = a.countBits();
const isZeroNumber: boolean = a.isZero();
const zero: BigInt = BigInt.ZERO;
const one: BigInt = BigInt.ONE;
const negOne: BigInt = BigInt.NEG_ONE;

// even faster constructors for small numbers (max values shown here)
const verySmall: BigInt = BigInt.fromUInt16(65535);
const verySmallSigned: BigInt = BigInt.fromInt16(-65535);
const prettySmall: BigInt = BigInt.fromUInt32(4294967295);
const prettySmallSigned: BigInt = BigInt.fromInt32(-4294967295);
const stillSmall: BigInt = BigInt.fromUInt64(18446744073709551615);
const stillSmallSigned: BigInt = BigInt.fromInt64(-18446744073709551615);

// output to integers
const myInt32: i32 = BigInt.toInt32();
const myInt64: i64 = BigInt.toInt64();
const myUInt32: u32 = BigInt.toUInt32();
const myUInt64: u64 = BigInt.toUInt64();
```

## Development Status & Roadmap
![CI](https://github.com/polywrap/as-bigint/actions/workflows/ci.yaml/badge.svg?branch=main)

### Current Status
Operation | Tests | Optimization
--- | --- | ---
Addition | Implemented | Complete
Subtraction | Implemented | Complete
Multiplication | Implemented | Up to ~1,500 bit numbers
Exponentiation | Implemented | Complete
Division | Implemented | Incomplete
Remainder | Implemented | Incomplete
Square root | Implemented | Complete
Modular reduction | N/A | Not implemented
Random number generation | N/A | Not implemented
Cryptographic functions | N/A | Not implemented

Note that operator overloads `<<`, `>>`, and `**` only support right-hand operands that fit in an i32--i.e. between the range (0, 2147483647].

### TODO List
*Priority based on blockchain-related use case; 1 is highest priority, 5 is lowest*
Task | Description | Priority
--- | --- | ---
Division optimization | A faster division algorithm is needed | 1
Modular reduction methods | Currently using division remainder for modulus; Implement Barret reduction, Montgomery reduction, Diminished Radix algorithms | 3
Random number generation | Implement function to generate random integers of arbitrary size | 4
Cryptographic algorithms | Implement functions used for cryptography (e.g., Greatest common divisor, primality tests, sha3) | 5
More multiplication optimization | Implement Karatsuba and Tom-Cook three-way multiplication for faster multiplication of numbers larger than 1,500 bits | 5

## Contributing  

### Build  
`yarn build`  

### Test  
`yarn test`  

### Lint
`yarn lint`

To autofix lint errors:
`yarn lint:fix`

## Handling decimal numbers

If you need to work with arbitrarily large decimal numbers, check out as-bignumber: https://github.com/polywrap/as-bignumber. The BigNumber class is built on top of BigInt for high-performance decimal arithmetic.

## Handling fractions

If you need to work with numbers represented as fractions, check out as-fraction: https://github.com/polywrap/as-fraction. The Fraction class is built on top of BigInt for high-performance fraction arithmetic.

## Acknowledgements

Polywrap developed BigInt to use in the development tools we produce for fast, language-agnostic decentralized API development. Polywrap allows developers to interact with any web3 protocol from any language, making between-protocol composition easy. Learn more at https://polywrap.io.

The BigInt method implementations are largely based on *BigNum Math: Implementing Cryptographic Multiple Precision Arithmetic 1st Edition*
by Tom St Denis.

All bitwise operation methods are based on Google's [JSBI](https://github.com/GoogleChromeLabs/jsbi/blob/main/lib/jsbi.ts).

## Contact
Please create an issue in this repository or email kris@dorg.tech

---
_Source: https://npm.io/package/as-bigint · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._