Decimal Class

The Decimal class is designed for precise handling of decimal values in JavaScript. It uses BigInt and other mathematical operations to ensure accuracy and avoid common issues with floating-point arithmetic.

Installation

npm install exframe-decimal

Usage

import Decimal from 'decimal-class';

// Create a decimal instance
const decimal = new Decimal(1.23);

// Perform arithmetic operations
const sum = decimal.add(2.45);
const product = decimal.multiply(3.14);
const quotient = decimal.divide(0.5);
const difference = decimal.subtract(0.8);

// Convert decimal to other types
const numberValue = decimal.toNumber();
const stringValue = decimal.toString();

// Specify precision
const rounded = decimal.toDecimalPlaces(2);

// Get absolute value
const absoluteValue = decimal.absolute();

API

new Decimal(value, options?)

Create an instance of the Decimal class. The class is immutable, all operations will return a new insatnce of the Decimal class.

| Parameter | Type | Description | |-----------|-------------------------------|-------------------------------------------------------------| | value | Number \| Decimal \| String | The decimal value. | | options | { precision?: Number = 4, roundingMode?: String = Decimal.ROUND_HALF_EVEN }? | Optional options to configure the precision and rounding mode of the Decimal. |

When value is itself a Decimal, the explicit precision/roundingMode options take precedence over the source instance's settings; otherwise the source instance's settings are inherited.

Rounding Modes

The rounding mode controls how a value is rounded whenever a digit must be dropped — on construction, on every arithmetic result, and in toDecimalPlaces. The mode is instance state: it is inherited by every result of an operation, and binary operations adopt the receiver's (this) mode.

| Constant | Value | Behavior | |---------------------------|----------------------|--------------------------------------------------------------------------| | Decimal.ROUND_HALF_EVEN | 'ROUND_HALF_EVEN' | Default. Round to nearest; on an exact tie, round to the even neighbour (banker's rounding). | | Decimal.ROUND_HALF_UP | 'ROUND_HALF_UP' | Round to nearest; on an exact tie, round away from zero. |

import Decimal from 'exframe-decimal';

// Default (half-even): a 2.5 tie rounds to the even neighbour, 2.
new Decimal(2.5).toDecimalPlaces(0).toNumber(); // 2

// Half-up: ties round away from zero, for positive AND negative values.
new Decimal(2.5, { roundingMode: Decimal.ROUND_HALF_UP }).toDecimalPlaces(0).toNumber();  // 3
new Decimal(-2.5, { roundingMode: Decimal.ROUND_HALF_UP }).toDecimalPlaces(0).toNumber(); // -3

// The mode propagates to operation results.
new Decimal(0.5, { precision: 1, roundingMode: Decimal.ROUND_HALF_UP }).multiply(0.5).toNumber(); // 0.3

Supplying any unsupported mode (to the constructor or to toDecimalPlaces) throws an Error echoing the offending value.

multiply(decimal: Decimal)

Returns the product of the multiplication of the current and the given Decimal values.

| Parameter | Type | Description | |-----------|----------|--------------------------| | decimal | Decimal| The second operand. |

divide(decimal: Decimal)

Returns the quotient of the division of the current and the given Decimal values.

| Parameter | Type | Description | |-----------|----------|--------------------------| | decimal | Decimal| The second operand. |

add(decimal: Decimal)

Returns the sum of the addition of the current and the given Decimal values.

| Parameter | Type | Description | |-----------|----------|--------------------------| | decimal | Decimal| The second operand. |

subtract(decimal: Decimal)

Returns the difference of the subtraction of the current and the given Decimal values.

| Parameter | Type | Description | |-----------|----------|--------------------------| | decimal | Decimal| The second operand. |

toDecimalPlaces(precision?: Number, options?)

Rounds the current value to the desired precision. If the value is greater than the current precision, it multiplies by 10^difference.

| Parameter | Type | Description | |------------|----------|------------------------------------------------------------------------------| | precision| Number | The desired precision. | | options | { truncate?: Boolean = false, roundingMode?: String = this.roundingMode }? | Optional options to configure the rounding behavior. roundingMode overrides the instance's mode for this call only; truncate takes precedence over both. |

truncate()

Truncates the current value to a precision of 0.

absolute()

Returns the absolute value of the current decimal value.

negative()

Returns the inverse of the current decimal value.