arithmetica

is an implementation of arithmetic operators for Float and Rational numbers

A Rational is a number that can be expressed as a fraction of two integers. It includes also repeating decimals hence is a super-set of floating point numbers.

ToC

• Installation
• Usage
• Types:
  • Float
  • Rational
• Type guards:
  • isFloat
  • isRational
• Operators:
  • eq: equality
  • add: addition
  • sub: subtraction
  • neg: negation
  • mul: multiplication
  • div: division
  • inv: inversion
  • lt: less than
  • gt: greater than
• Utils:
  • coerceToFloat
  • coerceToRational
  • rationalToNumber
• License

Installation

With npm do

npm install arithmetica

This package is implemented with ECMAScript modules. CommonJS is not supported.

No dependencies are used at all.

Usage

import { add } from 'arithmetica/float.js';

add('0.1', '0.2'); // '0.3'

The size of a bundle minified with esbuild including only arithmetica/float.js is 1.9kb.

NOTA BENE: there is no runtime check on types! Consumers are responsible to feed inputs that are actual Rational types, for instance using isRational type-guard.

If you need repeating decimals you can import only floating point operators with something like

import { add } from 'arithmetica/rational.js';

add(1, 2n); // '3'

// Here 0._3 represents 0.3333333333333333...
add('0._3', 1)); // '1._3'

Types

Float

A Float can be:

• a number, must be finite (Infinity is not a Float)
• a bigint
• a string that expresses a decimal representation of a number

In case it is a string:

• Decimal separator is . character.
• Exponential notation is not allowed.
• Integer part can be omitted.

For example:

• '0'
• '1.2'
• '-0.42'
• '.123'

Rational

A Rational includes every Float plus repeating decimals that are decimal representation of a number whose digits are periodic.

A repeating decimal is represented by a string like:

• '0._3': represents fraction 1/3, that is 0.33333...
• '0.123_456': represents number 0.123456456456456456456456...

Type guards

isFloat

isFloat(arg: unknown): arg is Float

Use isFloat type-guard to check if some value belongs to Float type.

import { Float, isFloat, sub } from 'arithmetica/float.js';

function minusOne (a: string | number | bigint): Float {
  if (isFloat(String(a))) return sub(a, '1');
  throw new TypeError(`Argument is not a Float ${a}`);
}

Of course it can be used also on an ECMAScript runtime.

import { isFloat, mul } from 'arithmetica/float.js';

function timesTen (a) {
  if (isFloat(a)) return mul(a, '10');
  throw new TypeError('Argument is not a Float');
}

isRational

isRational(arg: unknown): arg is Rational

Use isRational type-guard to check if some data belongs to Rational type.

import { Rational, isRational, add } from 'arithmetica/rational.js';

function plusOneThird (a: string | number | bigint): Rational {
  if (isRational(String(a))) return add(a, '0._3');
  throw new TypeError(`Argument is not a Rational ${a}`);
}

Operators

Every operator exported by arithmetica/float.js has the same signature as its homonym operator provided by arithmetica/rational.js, but of course with type Rational instead of a Float in its signature.

eq

Implements equality operator.

import { eq } from 'arithmetica/float.js';

eq('1', '2'); // false
eq(42, '42.0'); // true

add

Implements addition operator.

import { add } from 'arithmetica/float.js';

add('1', '2'); // '3'

sub

Implements subtraction operator.

import { sub } from 'arithmetica/float.js';

sub('1', '2'); // '-1'

neg

Implements negation operator.

import { neg } from 'arithmetica/float.js';

neg('1'); // '-1'
neg('-42'); // '42'

mul

Implements multiplication operator.

import { mul } from 'arithmetica/float.js';

mul('2', '-3'); // '-6'

div

Implements division operator.

It throws an error if denominator is zero.

import { div } from 'arithmetica/float.js';

div('-10', '2'); // '-5'

try {
  div('2', '0');
} catch (err) {
  console.error(err); // Error: Division by zero
}

inv

Implements inversion operator.

import { inv } from 'arithmetica/float.js';

inv('2'); // '0.5'

lt

Implements less then operator.

Notice that lt is not implemented by arithmetica/float.js: use the < operator.

import { lt } from 'arithmetica/rational.js';

lt('-2', '1'); // true

gt

Implements greater then operator.

Notice that gt is not implemented by arithmetica/float.js: use the > operator.

import { gt } from 'arithmetica/rational.js';

gt('-2', '1'); // false

Utils

rationalToNumber

Converts a Rational to a number.

rationalToNumber(rational: Rational, mantissaLen?: number): number

Notice that mantissaLen argument is optional: it set the number of digits of the decimal part, max is 16. Output is rounded.

import { rationalToNumber } from 'arithmetica/rational.js';

rationalToNumber('0.10'); // 0.1
rationalToNumber('0._3', 8); // 0.33333333
rationalToNumber('0.456', 2); // 0.46

License

MIT