@obinexusmk2/hypernum 0.1.0

package/src/operations/arithmetic.ts

@@ -0,0 +1,333 @@
+/**
+ * Arithmetic operations module for Hypernum library
+ * Provides high-precision arithmetic operations with BigInt support
+ */
+
+import {
+    validateNonNegative,
+    toBigInt,
+    checkAdditionOverflow,
+    checkMultiplicationOverflow,
+    checkPowerOverflow,
+    ValidationError,
+  } from '../utils/validation';
+  
+  import {
+    RoundingMode,
+    round,
+    scaledDivision,
+    normalizePrecision,
+  } from '../utils/precision';
+  
+  /**
+   * Options for arithmetic operations
+   */
+  export interface ArithmeticOptions {
+    precision?: number;
+    roundingMode?: RoundingMode;
+    checkOverflow?: boolean;
+  }
+  
+  const DEFAULT_OPTIONS: Required<ArithmeticOptions> = {
+    precision: 0,
+    roundingMode: RoundingMode.HALF_EVEN,
+    checkOverflow: true
+  };
+  
+  /**
+   * Adds two numbers with optional precision and overflow checking
+   */
+  export function add(
+    a: bigint | string | number,
+    b: bigint | string | number,
+    options: ArithmeticOptions = {}
+  ): bigint {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const bigA = toBigInt(a);
+    const bigB = toBigInt(b);
+  
+    if (opts.checkOverflow) {
+      checkAdditionOverflow(bigA, bigB);
+    }
+  
+    if (opts.precision === 0) {
+      return bigA + bigB;
+    }
+  
+    const [scaledA, scaledB] = normalizePrecision(bigA, bigB, opts.precision, opts.precision);
+    const result = scaledA + scaledB;
+    
+    return round(result, opts.precision, opts.roundingMode);
+  }
+  
+  /**
+   * Subtracts two numbers with optional precision and overflow checking
+   */
+  export function subtract(
+    a: bigint | string | number,
+    b: bigint | string | number,
+    options: ArithmeticOptions = {}
+  ): bigint {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const bigA = toBigInt(a);
+    const bigB = toBigInt(b);
+  
+    if (opts.checkOverflow) {
+      checkAdditionOverflow(bigA, -bigB);
+    }
+  
+    if (opts.precision === 0) {
+      return bigA - bigB;
+    }
+  
+    const [scaledA, scaledB] = normalizePrecision(bigA, bigB, opts.precision, opts.precision);
+    const result = scaledA - scaledB;
+    
+    return round(result, opts.precision, opts.roundingMode);
+  }
+  
+  /**
+   * Multiplies two numbers with optional precision and overflow checking
+   */
+  export function multiply(
+    a: bigint | string | number,
+    b: bigint | string | number,
+    options: ArithmeticOptions = {}
+  ): bigint {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const bigA = toBigInt(a);
+    const bigB = toBigInt(b);
+  
+    if (opts.checkOverflow) {
+      checkMultiplicationOverflow(bigA, bigB);
+    }
+  
+    const result = bigA * bigB;
+    if (opts.precision === 0) {
+      return result;
+    }
+  
+    return round(result, opts.precision, opts.roundingMode);
+  }
+  
+  /**
+   * Divides two numbers with specified precision and rounding
+   */
+  export function divide(
+    numerator: bigint | string | number,
+    denominator: bigint | string | number,
+    options: ArithmeticOptions = {}
+  ): bigint {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const bigNumerator = toBigInt(numerator);
+    const bigDenominator = toBigInt(denominator);
+  
+    if (bigDenominator === BigInt(0)) {
+      throw new ValidationError('Division by zero');
+    }
+  
+    return scaledDivision(
+      bigNumerator,
+      bigDenominator,
+      opts.precision,
+      opts.roundingMode
+    );
+  }
+  
+  /**
+   * Calculates remainder with optional precision
+   */
+  export function remainder(
+    a: bigint | string | number,
+    b: bigint | string | number,
+    options: ArithmeticOptions = {}
+  ): bigint {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const bigA = toBigInt(a);
+    const bigB = toBigInt(b);
+  
+    if (bigB === BigInt(0)) {
+      throw new ValidationError('Division by zero in remainder operation');
+    }
+  
+    if (opts.precision === 0) {
+      return bigA % bigB;
+    }
+  
+    const [scaledA, scaledB] = normalizePrecision(bigA, bigB, opts.precision, opts.precision);
+    const result = scaledA % scaledB;
+    
+    return round(result, opts.precision, opts.roundingMode);
+  }
+  
+  /**
+   * Raises a number to a power with optional precision
+   */
+  export function power(
+    base: bigint | string | number,
+    exponent: bigint | string | number,
+    options: ArithmeticOptions = {}
+  ): bigint {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const bigBase = toBigInt(base);
+    const bigExponent = toBigInt(exponent);
+  
+    if (opts.checkOverflow) {
+      checkPowerOverflow(bigBase, bigExponent);
+    }
+  
+    validateNonNegative(bigExponent);
+  
+    if (bigExponent === BigInt(0)) {
+      return BigInt(1);
+    }
+  
+    if (bigExponent === BigInt(1)) {
+      return bigBase;
+    }
+  
+    let result = bigBase;
+    let remaining = bigExponent - BigInt(1);
+  
+    while (remaining > BigInt(0)) {
+      if (opts.checkOverflow) {
+        checkMultiplicationOverflow(result, bigBase);
+      }
+      result *= bigBase;
+      remaining--;
+    }
+  
+    if (opts.precision > 0) {
+      return round(result, opts.precision, opts.roundingMode);
+    }
+  
+    return result;
+  }
+  
+  /**
+   * Calculates the square root with specified precision
+   */
+  export function sqrt(
+    value: bigint | string | number,
+    options: ArithmeticOptions = {}
+  ): bigint {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const bigValue = toBigInt(value);
+    validateNonNegative(bigValue);
+  
+    if (bigValue === BigInt(0)) {
+      return BigInt(0);
+    }
+  
+    // Scale up for precision
+    const scaleFactor = BigInt(10) ** BigInt(opts.precision * 2);
+    const scaled = bigValue * scaleFactor;
+  
+    // Newton's method for square root
+    let x = scaled;
+    let y = (x + scaled / x) >> BigInt(1);
+  
+    while (y < x) {
+      x = y;
+      y = (x + scaled / x) >> BigInt(1);
+    }
+  
+    return round(x, opts.precision, opts.roundingMode);
+  }
+  
+  /**
+   * Calculates the absolute value
+   */
+  export function abs(value: bigint | string | number): bigint {
+    const bigValue = toBigInt(value);
+    return bigValue < BigInt(0) ? -bigValue : bigValue;
+  }
+  
+  /**
+   * Returns the sign of a number (-1, 0, or 1)
+   */
+  export function sign(value: bigint | string | number): bigint {
+    const bigValue = toBigInt(value);
+    if (bigValue < BigInt(0)) return BigInt(-1);
+    if (bigValue > BigInt(0)) return BigInt(1);
+    return BigInt(0);
+  }
+  
+  /**
+   * Calculates the greatest common divisor of two numbers
+   */
+  export function gcd(
+    a: bigint | string | number,
+    b: bigint | string | number
+  ): bigint {
+    let bigA = abs(toBigInt(a));
+    let bigB = abs(toBigInt(b));
+  
+    while (bigB !== BigInt(0)) {
+      const temp = bigB;
+      bigB = bigA % bigB;
+      bigA = temp;
+    }
+  
+    return bigA;
+  }
+  
+  /**
+   * Calculates the least common multiple of two numbers
+   */
+  export function lcm(
+    a: bigint | string | number,
+    b: bigint | string | number
+  ): bigint {
+    const bigA = abs(toBigInt(a));
+    const bigB = abs(toBigInt(b));
+    
+    if (bigA === BigInt(0) || bigB === BigInt(0)) {
+      return BigInt(0);
+    }
+  
+    return abs(bigA * bigB) / gcd(bigA, bigB);
+  }
+  
+  // /**
+  //  * Calculates factorial of a number
+  //  */
+  // export function factorial(value: bigint | string | number): bigint {
+  //   const bigValue = toBigInt(value);
+  //   validateNonNegative(bigValue);
+  
+  //   if (bigValue > BigInt(1000)) {
+  //     throw new OverflowError('Factorial input too large');
+  //   }
+  
+  //   if (bigValue <= BigInt(1)) {
+  //     return BigInt(1);
+  //   }
+  
+  //   let result = BigInt(1);
+  //   let current = BigInt(2);
+  
+  //   while (current <= bigValue) {
+  //     result *= current;
+  //     current++;
+  //   }
+  
+  //   return result;
+  // }
+  
+  export default {
+    add,
+    subtract,
+    multiply,
+    divide,
+    remainder,
+    power,
+    sqrt,
+    abs,
+    sign,
+    gcd,
+    lcm, 
+    // factorial
+    };
+
+  

package/src/operations/bitwise.ts

@@ -0,0 +1,367 @@
+/**
+ * Bitwise operations module for Hypernum library
+ * Provides functions for bit-level manipulations of large numbers
+ */
+
+import {
+    toBigInt,
+    ValidationError,
+    validateNonNegative
+  } from '../utils/validation';
+  
+  /**
+   * Options for bitwise operations
+   */
+  export interface BitwiseOptions {
+    /** Maximum bits to consider in operations */
+    maxBits?: number;
+    /** Whether to throw on overflow */
+    strict?: boolean;
+  }
+  
+  const DEFAULT_OPTIONS: Required<BitwiseOptions> = {
+    maxBits: 1024,
+    strict: true
+  };
+  
+  /**
+   * Validates shift amount is within reasonable bounds
+   */
+  function validateShift(shift: bigint, options: Required<BitwiseOptions>): void {
+    if (shift < 0n) {
+      throw new ValidationError('Shift amount cannot be negative');
+    }
+    if (options.strict && shift >= BigInt(options.maxBits)) {
+      throw new ValidationError(`Shift amount exceeds maximum of ${options.maxBits} bits`);
+    }
+  }
+  
+  /**
+   * Performs bitwise AND operation
+   */
+  export function and(
+    a: bigint | string | number,
+    b: bigint | string | number
+  ): bigint {
+    const bigA = toBigInt(a);
+    const bigB = toBigInt(b);
+
+    return bigA & bigB;
+  }
+  
+  /**
+   * Performs bitwise OR operation
+   */
+  export function or(
+    a: bigint | string | number,
+    b: bigint | string | number
+  ): bigint {
+    const bigA = toBigInt(a);
+    const bigB = toBigInt(b);
+    
+    return bigA | bigB;
+  }
+  
+  /**
+   * Performs bitwise XOR operation
+   */
+  export function xor(
+    a: bigint | string | number,
+    b: bigint | string | number
+  ): bigint {
+    const bigA = toBigInt(a);
+    const bigB = toBigInt(b);
+    
+    return bigA ^ bigB;
+  }
+  
+  /**
+   * Performs bitwise NOT operation
+   */
+  export function not(
+    value: bigint | string | number
+  ): bigint {
+    const bigValue = toBigInt(value);
+    
+    return ~bigValue;
+  }
+  
+  /**
+   * Performs left shift operation
+   */
+  export function leftShift(
+    value: bigint | string | number,
+    shift: bigint | string | number,
+    options: BitwiseOptions = {}
+  ): bigint {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const bigValue = toBigInt(value);
+    const bigShift = toBigInt(shift);
+    
+    validateShift(bigShift, opts);
+    return bigValue << bigShift;
+  }
+  
+  /**
+   * Performs right shift operation
+   */
+  export function rightShift(
+    value: bigint | string | number,
+    shift: bigint | string | number,
+    options: BitwiseOptions = {}
+  ): bigint {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const bigValue = toBigInt(value);
+    const bigShift = toBigInt(shift);
+    
+    validateShift(bigShift, opts);
+    return bigValue >> bigShift;
+  }
+  
+  /**
+   * Performs unsigned right shift operation
+   * Note: BigInt doesn't have >>> operator, so we implement it manually
+   */
+  export function unsignedRightShift(
+    value: bigint | string | number,
+    shift: bigint | string | number,
+    options: BitwiseOptions = {}
+  ): bigint {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const bigValue = toBigInt(value);
+    const bigShift = toBigInt(shift);
+    
+    validateShift(bigShift, opts);
+    
+    if (bigValue >= 0n) {
+      return bigValue >> bigShift;
+    }
+    
+    // Handle negative numbers by first converting to positive
+    const mask = (1n << BigInt(opts.maxBits)) - 1n;
+    return (bigValue & mask) >> bigShift;
+  }
+  
+  /**
+   * Rotates bits left by specified amount
+   */
+  export function rotateLeft(
+    value: bigint | string | number,
+    rotation: bigint | string | number,
+    options: BitwiseOptions = {}
+  ): bigint {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const bigValue = toBigInt(value);
+    let bigRotation = toBigInt(rotation);
+    
+    validateNonNegative(bigRotation);
+    
+    // Normalize rotation to be within maxBits
+    if (bigRotation >= BigInt(opts.maxBits)) {
+      bigRotation = bigRotation % BigInt(opts.maxBits);
+    }
+    
+    if (bigRotation === 0n) {
+      return bigValue;
+    }
+    
+    const leftPart = leftShift(bigValue, bigRotation, opts);
+    const rightPart = unsignedRightShift(bigValue, BigInt(opts.maxBits) - bigRotation, opts);
+    
+    return leftPart | rightPart;
+  }
+  
+  /**
+   * Rotates bits right by specified amount
+   */
+  export function rotateRight(
+    value: bigint | string | number,
+    rotation: bigint | string | number,
+    options: BitwiseOptions = {}
+  ): bigint {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const bigValue = toBigInt(value);
+    let bigRotation = toBigInt(rotation);
+    
+    validateNonNegative(bigRotation);
+    
+    // Normalize rotation to be within maxBits
+    if (bigRotation >= BigInt(opts.maxBits)) {
+      bigRotation = bigRotation % BigInt(opts.maxBits);
+    }
+    
+    if (bigRotation === 0n) {
+      return bigValue;
+    }
+    
+    const rightPart = unsignedRightShift(bigValue, bigRotation, opts);
+    const leftPart = leftShift(bigValue, BigInt(opts.maxBits) - bigRotation, opts);
+    
+    return leftPart | rightPart;
+  }
+  
+  /**
+   * Counts number of set bits (1s)
+   */
+  export function popCount(
+    value: bigint | string | number,
+    options: BitwiseOptions = {}
+  ): bigint {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    let bigValue = toBigInt(value);
+    
+    let count = 0n;
+    while (bigValue !== 0n) {
+      count += bigValue & 1n;
+      bigValue = unsignedRightShift(bigValue, 1n, opts);
+    }
+    
+    return count;
+  }
+  
+  /**
+   * Returns number of trailing zero bits
+   */
+  export function trailingZeros(
+    value: bigint | string | number,
+    options: BitwiseOptions = {}
+  ): bigint {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    let bigValue = toBigInt(value);
+    
+    if (bigValue === 0n) {
+      return BigInt(opts.maxBits);
+    }
+    
+    let count = 0n;
+    while ((bigValue & 1n) === 0n) {
+      count++;
+      bigValue = unsignedRightShift(bigValue, 1n, opts);
+    }
+    
+    return count;
+  }
+  
+  /**
+   * Returns number of leading zero bits
+   */
+  export function leadingZeros(
+    value: bigint | string | number,
+    options: BitwiseOptions = {}
+  ): bigint {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    let bigValue = toBigInt(value);
+    
+    if (bigValue === 0n) {
+      return BigInt(opts.maxBits);
+    }
+    
+    let count = 0n;
+    const msb = 1n << BigInt(opts.maxBits - 1);
+    
+    while ((bigValue & msb) === 0n && count < BigInt(opts.maxBits)) {
+      count++;
+      bigValue = leftShift(bigValue, 1n, opts);
+    }
+    
+    return count;
+  }
+  
+  /**
+   * Returns bit at specified position
+   */
+  export function getBit(
+    value: bigint | string | number,
+    position: bigint | string | number,
+    options: BitwiseOptions = {}
+  ): boolean {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const bigValue = toBigInt(value);
+    const bigPosition = toBigInt(position);
+    
+    validateNonNegative(bigPosition);
+    if (opts.strict && bigPosition >= BigInt(opts.maxBits)) {
+      throw new ValidationError(`Bit position exceeds maximum of ${opts.maxBits} bits`);
+    }
+    
+    return (bigValue & (1n << bigPosition)) !== 0n;
+  }
+  
+  /**
+   * Sets bit at specified position
+   */
+  export function setBit(
+    value: bigint | string | number,
+    position: bigint | string | number,
+    options: BitwiseOptions = {}
+  ): bigint {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const bigValue = toBigInt(value);
+    const bigPosition = toBigInt(position);
+    
+    validateNonNegative(bigPosition);
+    if (opts.strict && bigPosition >= BigInt(opts.maxBits)) {
+      throw new ValidationError(`Bit position exceeds maximum of ${opts.maxBits} bits`);
+    }
+    
+    return bigValue | (1n << bigPosition);
+  }
+  
+  /**
+   * Clears bit at specified position
+   */
+  export function clearBit(
+    value: bigint | string | number,
+    position: bigint | string | number,
+    options: BitwiseOptions = {}
+  ): bigint {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const bigValue = toBigInt(value);
+    const bigPosition = toBigInt(position);
+    
+    validateNonNegative(bigPosition);
+    if (opts.strict && bigPosition >= BigInt(opts.maxBits)) {
+      throw new ValidationError(`Bit position exceeds maximum of ${opts.maxBits} bits`);
+    }
+    
+    return bigValue & ~(1n << bigPosition);
+  }
+  
+  /**
+   * Toggles bit at specified position
+   */
+  export function toggleBit(
+    value: bigint | string | number,
+    position: bigint | string | number,
+    options: BitwiseOptions = {}
+  ): bigint {
+    const opts = { ...DEFAULT_OPTIONS, ...options };
+    const bigValue = toBigInt(value);
+    const bigPosition = toBigInt(position);
+    
+    validateNonNegative(bigPosition);
+    if (opts.strict && bigPosition >= BigInt(opts.maxBits)) {
+      throw new ValidationError(`Bit position exceeds maximum of ${opts.maxBits} bits`);
+    }
+    
+    return bigValue ^ (1n << bigPosition);
+  }
+  
+  export default {
+    and,
+    or,
+    xor,
+    not,
+    leftShift,
+    rightShift,
+    unsignedRightShift,
+    rotateLeft,
+    rotateRight,
+    popCount,
+    trailingZeros,
+    leadingZeros,
+    getBit,
+    setBit,
+    clearBit,
+    toggleBit
+  };