Arithmetic Operations

/**
 * Performs addition
 * @param number - Value to add (number, bigint, string, or BigInteger)
 * @returns New BigInteger with the sum
 */
add(number: BigNumber): BigInteger;

// Alias
plus(number: BigNumber): BigInteger;

const bigInt = require('big-integer');

// Simple addition
bigInt(5).add(7);  // 12

// Large number addition
const a = bigInt("999999999999999999999");
const b = bigInt("1");
a.add(b);  // 1000000000000000000000

// Method chaining
bigInt(10).add(5).add(3);  // 18

/**
 * Performs subtraction
 * @param number - Value to subtract
 * @returns New BigInteger with the difference
 */
subtract(number: BigNumber): BigInteger;

// Alias
minus(number: BigNumber): BigInteger;

// Simple subtraction
bigInt(10).subtract(3);  // 7

// Negative results
bigInt(3).subtract(5);  // -2

// Method chaining
bigInt(100).minus(30).minus(20);  // 50

/**
 * Performs multiplication
 * @param number - Value to multiply by
 * @returns New BigInteger with the product
 */
multiply(number: BigNumber): BigInteger;

// Alias
times(number: BigNumber): BigInteger;

// Simple multiplication
bigInt(111).multiply(111);  // 12321

// Large number multiplication
const big = bigInt("123456789012345678901234567890");
big.multiply(2);  // 246913578024691357802469135780

// Method chaining
bigInt(5).times(10).times(2);  // 100

/**
 * Squares the number (equivalent to multiply(this) but optimized)
 * @returns New BigInteger with the square
 */
square(): BigInteger;

// Square a number
bigInt(3).square();  // 9

// Large squares
bigInt("12345").square();  // 152399025

/**
 * Performs integer division (discards remainder)
 * @param number - Divisor
 * @returns New BigInteger with the quotient
 */
divide(number: BigNumber): BigInteger;

// Alias
over(number: BigNumber): BigInteger;

// Integer division
bigInt(59).divide(5);  // 11 (remainder 4 is discarded)

// Negative division
bigInt(-10).divide(3);  // -3

/**
 * Performs division and returns the remainder
 * The sign of the remainder matches the sign of the dividend
 * @param number - Divisor
 * @returns New BigInteger with the remainder
 */
mod(number: BigNumber): BigInteger;

// Alias
remainder(number: BigNumber): BigInteger;

// Modulo operation
bigInt(59).mod(5);  // 4

// Negative dividend
bigInt(-5).mod(2);  // -1 (sign matches dividend)

// Large modulo
bigInt("123456789").mod(1000);  // 789

/**
 * Performs division and returns both quotient and remainder
 * The sign of the remainder matches the sign of the dividend
 * @param number - Divisor
 * @returns Object with quotient and remainder properties
 */
divmod(number: BigNumber): { quotient: BigInteger, remainder: BigInteger };

// Get both quotient and remainder
const result = bigInt(59).divmod(5);
result.quotient;   // 11
result.remainder;  // 4

// Negative dividend
const neg = bigInt(-5).divmod(2);
neg.quotient;   // -2
neg.remainder;  // -1 (sign matches dividend)

// Destructuring
const { quotient, remainder } = bigInt(100).divmod(7);
// quotient: 14, remainder: 2

/**
 * Performs exponentiation
 * Returns 0 for negative exponents
 * bigInt.zero.pow(0) returns 1
 * @param number - Exponent
 * @returns New BigInteger raised to the power
 */
pow(number: BigNumber): BigInteger;

// Basic exponentiation
bigInt(2).pow(10);  // 1024

// Large exponents
bigInt(2).pow(100);  // 1267650600228229401496703205376

// Zero base
bigInt.zero.pow(0);  // 1

// Negative exponent returns 0
bigInt(5).pow(-2);  // 0

/**
 * Takes the number to the power exp modulo mod
 * Efficient for cryptographic operations
 * @param exp - Exponent
 * @param mod - Modulus
 * @returns (this ^ exp) mod mod
 */
modPow(exp: BigNumber, mod: BigNumber): BigInteger;

// Modular exponentiation
bigInt(10).modPow(3, 30);  // 10 (since 1000 mod 30 = 10)

// Cryptographic use case
bigInt(2).modPow(1000, 97);  // 36

// Large exponents stay efficient
const base = bigInt(7);
const exp = bigInt("1234567890");
const mod = bigInt(1000000);
base.modPow(exp, mod);  // Result computed efficiently

/**
 * Finds the multiplicative inverse of the number modulo mod
 * Returns x such that (this * x) mod mod = 1
 * @param mod - Modulus
 * @returns Modular multiplicative inverse
 */
modInv(mod: BigNumber): BigInteger;

// Find modular inverse
bigInt(3).modInv(11);  // 4 (because 3 * 4 mod 11 = 1)

// Cryptographic use case
bigInt(42).modInv(2017);  // 1969

// Verification
const a = bigInt(3);
const m = bigInt(11);
const inv = a.modInv(m);
a.multiply(inv).mod(m);  // 1 (verification)

/**
 * Returns the absolute value
 * @returns New BigInteger with absolute value
 */
abs(): BigInteger;

bigInt(-45).abs();  // 45
bigInt(45).abs();   // 45
bigInt.zero.abs();  // 0

/**
 * Reverses the sign of the number
 * @returns New BigInteger with opposite sign
 */
negate(): BigInteger;

bigInt(10).negate();   // -10
bigInt(-10).negate();  // 10
bigInt.zero.negate();  // 0

/**
 * Adds one to the number
 * @returns New BigInteger incremented by 1
 */
next(): BigInteger;

/**
 * Subtracts one from the number
 * @returns New BigInteger decremented by 1
 */
prev(): BigInteger;

// Increment
bigInt(6).next();  // 7
bigInt(-1).next(); // 0

// Decrement
bigInt(6).prev();  // 5
bigInt(0).prev();  // -1

// Chaining
bigInt(10).next().next();  // 12