arbitrary-precision arithmetic operators for Rational numbers, supporting repeating decimals
npm install arithmetica> arbitrary-precision arithmetic operators for Rational numbers, supporting repeating decimals
ToC
- Installation
- Rational numbers
- Types
- Features
- Operators
- Utils
- License
With npm do
``sh`
npm install arithmetica
This package is implemented with ECMAScript modules. CommonJS is not supported.
No dependencies are used at all.
In Mathematics a Rational number is a number that can be expressed as a fraction of two integers, that is a/b where _a_ and _b_ are integers and _b_ is not zero.
A _Rational_ number can be represented by a string, for example:
- '1''-12'
- '0.5'
-
It may have repeating decimals, when the number of decimal digits in the decimal representation is infinite and periodic. For example 1/3 is 0.33333....
The Rational type is a string that represents a rational number, where:
- Decimal separator is . character.'1e3'
- Exponential notation is not allowed. Values like or '1.2e-3' are not valid.'.5'
- Integer part can be omitted. Values like or '-.5' are valid.
- Strings can be arbitrary long; the only limits are your computer's memory and the BigInt implementation.
Examples of (finite) rational numbers:
- '1''-12'
- '1.23456789'
-
A _repeating decimal_ is represented by a string like,
``
For example:
- '0._6': the fraction 1/6, that is 0.666666666666...'-1.23_456'
- : the number -1.23456456456456...
The MaybeRational type is the union of types that can be coerced to a Rational, i.e. string, number and bigint.
The Rational type is used by operators as return type.MaybeRational
The types is used by operators as argument.
You probably already aware of _floating point issues_ such as 0.1 + 0.2 != 0.3 or 0.1 * 0.2 != 0.02; this occurs in JavaScript as well as many other languages.arithmetica
Operators in the package implement arbitrary-precision arithmetic. For example:
`js
import { add, mul } from 'arithmetica';
add(0.1, 0.2); // '0.3'
mul(0.1, 0.2); // '0.02'
`
Arguments are coerced, you can pass a number, bigint or string.
`js`
add('1', 2n); // '3'
You can deal with _repeating decimals_.
`js
import { add, div } from 'arithmetica';
div(1, 3); // '0._3'
add('0._3', 1); // '1._3'
`
- Equality: eq(a: MaybeRational, b: MaybeRational): booleanadd(a: MaybeRational, b: MaybeRational): Rational
- Addition: sub(a: MaybeRational, b: MaybeRational): Rational
- Subtraction: neg(a: MaybeRational): Rational
- Negation: mul(a: MaybeRational, b: MaybeRational): Rational
- Multiplication: div(a: MaybeRational, b: MaybeRational): Rational
- Division: inv(a: MaybeRational): Rational
- Inversion: lt(a: MaybeRational, b: Rational): boolean
- Less than: gt(a: MaybeRational, b: MaybeRational): boolean
- Greater than:
Validates the argument and converts it to Rational
``
coerceToRational(arg: MaybeRational): Rational
Type guard. Check that the given argument is a valid Rational.
``
isRational(arg: unknown): arg is Rational
Converts a Rational to a number. The numDecimals defaults to 16.
```
rationalToNumber(arg: Rational, numDecimals?: number): number