or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

arithmetic.mdcomparison.mdconfiguration.mdconstructor.mdconversion.mdindex.mdprecision.md
tile.json

constructor.mddocs/

Constructor and Creation

Core BigNumber constructor and instance creation functionality with support for different bases, input types, and special values.

Capabilities

BigNumber Constructor

Creates a new BigNumber instance from various input types with optional base specification.

/**
 * Creates a new BigNumber instance
 * @param n - Numeric value (string, number, bigint, or BigNumber instance)
 * @param base - Number base (2-36, defaults to 10)
 * @returns New BigNumber instance
 */
new BigNumber(n: BigNumber.Value, base?: number): BigNumber;

// Constructor can also be called without 'new'
BigNumber(n: BigNumber.Value, base?: number): BigNumber;

Usage Examples:

import BigNumber from "bignumber.js";

// From string (recommended for precision)
const a = new BigNumber('123.456789');
const b = new BigNumber('1.23e+5');
const c = new BigNumber('-42.7e-10');

// From number (precision may be lost)
const d = new BigNumber(123.456789);
const e = new BigNumber(-42);

// From bigint (Node.js/modern browsers)
const f = new BigNumber(123456789012345678901234567890n);

// From another BigNumber
const g = new BigNumber(a);

// With different bases
const hex = new BigNumber('ff.8', 16);        // 255.5 in decimal
const binary = new BigNumber('1011.101', 2);  // 11.625 in decimal
const base36 = new BigNumber('zz.9', 36);     // 1295.25 in decimal

// Without 'new' keyword
const h = BigNumber('999.999');

Special Values

BigNumber supports JavaScript's special numeric values with proper handling.

// Special values are supported
new BigNumber('Infinity');      // Positive infinity
new BigNumber('-Infinity');     // Negative infinity  
new BigNumber('NaN');           // Not a Number
new BigNumber(NaN);             // Not a Number
new BigNumber(-0);              // Negative zero (preserved)

Usage Examples:

// Special values
const infinity = new BigNumber('Infinity');
const negInfinity = new BigNumber('-Infinity');
const notANumber = new BigNumber('NaN');
const negZero = new BigNumber(-0);

console.log(infinity.toString());     // "Infinity"
console.log(negInfinity.toString());  // "-Infinity"
console.log(notANumber.toString());   // "NaN"
console.log(negZero.valueOf());       // "-0"

Input Validation

BigNumber handles invalid inputs gracefully, returning NaN unless debug mode is enabled.

// Invalid inputs return BigNumber NaN (unless DEBUG = true)
new BigNumber('invalid');       // BigNumber NaN
new BigNumber('1.2.3');         // BigNumber NaN
new BigNumber(9, 2);            // BigNumber NaN (9 is not valid in base 2)

Debug Mode:

// Enable debug mode for error throwing
BigNumber.DEBUG = true;

try {
  new BigNumber('invalid');
} catch (error) {
  console.log(error.message); // "[BigNumber Error] Not a number"
}

try {
  new BigNumber(9, 2);
} catch (error) {
  console.log(error.message); // "[BigNumber Error] Not a base 2 number"
}

Precision Considerations

When creating BigNumbers from JavaScript numbers, precision may be lost due to floating-point limitations.

Usage Examples:

// Precision loss from numeric literals
new BigNumber(1.0000000000000001);         // "1" (precision lost)
new BigNumber(99999999999999999999);       // "100000000000000000000"

// Use strings to preserve precision
new BigNumber('1.0000000000000001');       // "1.0000000000000001"
new BigNumber('99999999999999999999');     // "99999999999999999999"

// Floating-point arithmetic issues
new BigNumber(0.1 + 0.2);                  // "0.30000000000000004"
new BigNumber('0.1').plus('0.2');          // "0.3"

Object Literal Construction

BigNumber instances can be created from object literals with coefficient, exponent, and sign properties.

/**
 * Create BigNumber from object literal (advanced usage)
 * @param obj - Object with c (coefficient), e (exponent), s (sign) properties
 */
new BigNumber({
  c: number[] | null,      // Coefficient array (base 1e14)
  e: number | null,        // Exponent (-1e9 to 1e9)
  s: number | null,        // Sign (-1, 1, or null)
  _isBigNumber: true       // Internal identifier
}): BigNumber;

Usage Examples:

// Object literal construction (advanced)
const x = new BigNumber({
  s: 1,
  e: 2,
  c: [777, 12300000000000],
  _isBigNumber: true
});
console.log(x.toString()); // "777.123"

// Verify object is well-formed
console.log(BigNumber.isBigNumber(x)); // true

Types

type BigNumber.Value = string | number | bigint | BigNumber.Instance;

interface BigNumber.Instance {
  readonly c: number[] | null;    // Coefficient array
  readonly e: number | null;      // Exponent value
  readonly s: number | null;      // Sign value
  [key: string]: any;
}