tessl/npm-bignumber-js

A JavaScript library for arbitrary-precision decimal and non-decimal arithmetic

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Precision and Rounding

Name: tessl/npm-bignumber-js
Author: tessl

Precision control and rounding operations for decimal places, significant digits, and decimal point manipulation.

Capabilities

Decimal Places

Gets the number of decimal places or rounds to specified decimal places.

/**
 * Returns number of decimal places, or rounds to specified decimal places
 * @param decimalPlaces - Number of decimal places (0 to 1e9, optional)
 * @param roundingMode - Rounding mode (0-8, optional)
 * @returns Number of decimal places, or new rounded BigNumber
 */
decimalPlaces(): number | null;
decimalPlaces(decimalPlaces: number, roundingMode?: BigNumber.RoundingMode): BigNumber;

// Alias
dp(): number | null;
dp(decimalPlaces: number, roundingMode?: BigNumber.RoundingMode): BigNumber;

Usage Examples:

import BigNumber from "bignumber.js";

const x = new BigNumber(1234.56);
x.decimalPlaces();              // 2
x.dp();                         // 2 (alias)

// Rounding to decimal places
x.decimalPlaces(1);             // "1234.6"
x.dp(1);                        // "1234.6" (alias)
x.decimalPlaces(2);             // "1234.56"
x.decimalPlaces(10);            // "1234.56" (no change needed)
x.decimalPlaces(0, 1);          // "1234" (ROUND_DOWN)
x.decimalPlaces(0, 6);          // "1235" (ROUND_HALF_EVEN -> ROUND_UP)
x.decimalPlaces(1, 1);          // "1234.5" (ROUND_DOWN)
x.dp(1, BigNumber.ROUND_HALF_EVEN); // "1234.6"

// Special values
const y = new BigNumber('9.9e-101');
y.decimalPlaces();              // 102

const inf = new BigNumber(Infinity);
inf.decimalPlaces();            // null

const nan = new BigNumber(NaN);
nan.decimalPlaces();            // null

Precision (Significant Digits)

Gets the number of significant digits or rounds to specified precision.

/**
 * Returns number of significant digits, or rounds to specified precision
 * @param significantDigits - Number of significant digits (1 to 1e9, optional)
 * @param roundingMode - Rounding mode (0-8, optional)
 * @returns Number of significant digits, or new rounded BigNumber
 */
precision(includeZeros?: boolean): number | null;
precision(significantDigits: number, roundingMode?: BigNumber.RoundingMode): BigNumber;

// Alias
sd(includeZeros?: boolean): number | null;
sd(significantDigits: number, roundingMode?: BigNumber.RoundingMode): BigNumber;

Usage Examples:

const x = new BigNumber(9876.54321);
x.precision();                  // 9
x.sd();                         // 9 (alias)

// Trailing zeros in integers
const y = new BigNumber(987000);
y.precision(false);             // 3 (trailing zeros not counted)
y.precision(true);              // 6 (trailing zeros counted)
y.sd(false);                    // 3 (alias)
y.sd(true);                     // 6 (alias)

// Rounding to significant digits
x.precision(6);                 // "9876.54"
x.sd(6);                        // "9876.54" (alias)
x.precision(6, BigNumber.ROUND_UP); // "9876.55"
x.precision(2);                 // "9900"
x.precision(2, 1);              // "9800" (ROUND_DOWN)

// Original value unchanged
console.log(x.toString());      // "9876.54321"

Integer Value

Rounds BigNumber to an integer using specified rounding mode.

/**
 * Returns BigNumber rounded to integer using specified rounding mode
 * @param roundingMode - Rounding mode (0-8, optional, defaults to ROUNDING_MODE)
 * @returns New BigNumber with integer value
 */
integerValue(roundingMode?: BigNumber.RoundingMode): BigNumber;

Usage Examples:

const x = new BigNumber(123.456);
x.integerValue();               // "123" (default rounding mode)
x.integerValue(BigNumber.ROUND_CEIL);  // "124"

const y = new BigNumber(-12.7);
y.integerValue();               // "-13" (default ROUND_HALF_UP)
y.integerValue(BigNumber.ROUND_DOWN);  // "-12"
y.integerValue(BigNumber.ROUND_FLOOR); // "-13"
y.integerValue(BigNumber.ROUND_CEIL);  // "-12"

// Rounding mode constants
const modes = [
  BigNumber.ROUND_UP,           // 0 - Away from zero
  BigNumber.ROUND_DOWN,         // 1 - Towards zero
  BigNumber.ROUND_CEIL,         // 2 - Towards +Infinity
  BigNumber.ROUND_FLOOR,        // 3 - Towards -Infinity
  BigNumber.ROUND_HALF_UP,      // 4 - To nearest, ties away from zero
  BigNumber.ROUND_HALF_DOWN,    // 5 - To nearest, ties towards zero
  BigNumber.ROUND_HALF_EVEN,    // 6 - To nearest, ties to even
  BigNumber.ROUND_HALF_CEIL,    // 7 - To nearest, ties towards +Infinity
  BigNumber.ROUND_HALF_FLOOR    // 8 - To nearest, ties towards -Infinity
];

const test = new BigNumber(2.5);
modes.forEach((mode, index) => {
  console.log(`Mode ${index}: ${test.integerValue(mode)}`);
});

Shifted By

Shifts the decimal point by specified number of places.

/**
 * Returns BigNumber with decimal point shifted by n places
 * @param n - Number of places to shift (-9007199254740991 to 9007199254740991)
 * @returns New BigNumber with shifted decimal point
 */
shiftedBy(n: number): BigNumber;

Usage Examples:

const x = new BigNumber(1.23);
x.shiftedBy(3);                 // "1230" (shift right = multiply by 10^3)
x.shiftedBy(-3);                // "0.00123" (shift left = divide by 10^3)

// Equivalent operations
const y = new BigNumber(100);
y.shiftedBy(2);                 // "10000"
y.times(100);                   // "10000" (same result)

const z = new BigNumber(12345);
z.shiftedBy(-2);                // "123.45"
z.dividedBy(100);               // "123.45" (same result)

// Large shifts
const big = new BigNumber('1.23456789');
big.shiftedBy(100);             // "1.23456789e+100"
big.shiftedBy(-100);            // "1.23456789e-100"

Rounding Examples

Comprehensive examples showing different rounding behaviors.

Usage Examples:

// Rounding mode comparison
const testValues = [2.4, 2.5, 2.6, -2.4, -2.5, -2.6];
const roundingModes = [
  { name: 'ROUND_UP', value: BigNumber.ROUND_UP },
  { name: 'ROUND_DOWN', value: BigNumber.ROUND_DOWN },
  { name: 'ROUND_CEIL', value: BigNumber.ROUND_CEIL },
  { name: 'ROUND_FLOOR', value: BigNumber.ROUND_FLOOR },
  { name: 'ROUND_HALF_UP', value: BigNumber.ROUND_HALF_UP },
  { name: 'ROUND_HALF_DOWN', value: BigNumber.ROUND_HALF_DOWN },
  { name: 'ROUND_HALF_EVEN', value: BigNumber.ROUND_HALF_EVEN },
  { name: 'ROUND_HALF_CEIL', value: BigNumber.ROUND_HALF_CEIL },
  { name: 'ROUND_HALF_FLOOR', value: BigNumber.ROUND_HALF_FLOOR }
];

testValues.forEach(val => {
  const bn = new BigNumber(val);
  console.log(`Value: ${val}`);
  roundingModes.forEach(mode => {
    console.log(`  ${mode.name}: ${bn.integerValue(mode.value)}`);
  });
});

// Precision vs decimal places
const x = new BigNumber('123.456789');

// Precision (significant digits)
x.precision(4);                 // "123.5" (4 significant digits)
x.precision(6);                 // "123.457" (6 significant digits)

// Decimal places  
x.decimalPlaces(2);             // "123.46" (2 decimal places)
x.decimalPlaces(4);             // "123.4568" (4 decimal places)

// Global configuration affects operations
BigNumber.config({ 
  DECIMAL_PLACES: 5,
  ROUNDING_MODE: BigNumber.ROUND_HALF_UP 
});

const a = new BigNumber(1);
const b = new BigNumber(3);
a.dividedBy(b);                 // "0.33333" (5 decimal places)

// Override global settings
a.dividedBy(b).decimalPlaces(2, BigNumber.ROUND_DOWN); // "0.33"

Configuration Impact

Precision and rounding operations are affected by global BigNumber configuration settings.

Usage Examples:

// Default configuration
BigNumber.config(); // Returns current settings

// Set precision for division operations
BigNumber.config({
  DECIMAL_PLACES: 10,
  ROUNDING_MODE: BigNumber.ROUND_HALF_EVEN
});

const x = new BigNumber(2);
const y = new BigNumber(3);
x.dividedBy(y);                 // "0.6666666667" (10 decimal places)

// POW_PRECISION affects exponentiation
BigNumber.config({ POW_PRECISION: 20 });
new BigNumber(2).pow(0.5);      // Limited to 20 significant digits

// MODULO_MODE affects modulo operations
BigNumber.config({ MODULO_MODE: BigNumber.EUCLID });
new BigNumber(-1).mod(3);       // "2" (Euclidean modulo)

Types

type BigNumber.RoundingMode = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;

// Rounding mode constants
const ROUND_UP = 0;           // Round away from zero
const ROUND_DOWN = 1;         // Round towards zero
const ROUND_CEIL = 2;         // Round towards +Infinity
const ROUND_FLOOR = 3;        // Round towards -Infinity
const ROUND_HALF_UP = 4;      // Round to nearest, ties away from zero
const ROUND_HALF_DOWN = 5;    // Round to nearest, ties towards zero
const ROUND_HALF_EVEN = 6;    // Round to nearest, ties to even
const ROUND_HALF_CEIL = 7;    // Round to nearest, ties towards +Infinity
const ROUND_HALF_FLOOR = 8;   // Round to nearest, ties towards -Infinity