@synap/sig-fig-calculator

SigFig Calculator

This is a library aimed at automating significant figure math.

Installation

Install with npm i @synap/sig-fig-calculator or yarn add @synap/sig-fig-calculator.

Getting Started

To get started using SigFig in your project:

import { SigFig } from '@synap/sig-fig-calculator';

SigFig.toParsed('-1.2345');
// { value: -1.2345, precision: { total: 5, index: 4, decimal: 4 } }

SigFig.multiply('-1.2345', '+1.00e-1').toString();
// '-0.123'

Vocabulary & Concepts

There are a couple of words worth pointing out up front:

• "total" precision is the number of significant digits when represented in scientific notation
• "decimal" precision is the number of digits shown to the right of the decimal point
• "index" precision is the index, relative to the decimal point, at which the last significant digit appears which means this value can be negative unlike the "decimal" precision
• an "exact" number is one which has infinite significance; e.g., constants, fractions, or conversion factors
• when multiplying or dividing by an exact number, the user must be explicit about whether to do so "as a ratio" or "as a conversion"; e.g., '1.200' * 100 = '120.000' when treated as ratio multiplication but '1.200' * 100 = '120.0' when treated as conversion multiplication, or in more technical terms, multiplying "as a ratio" will hold the index precision constant while multiplying "as a conversion" will hold the total precision constant

API

This module mainly exports the SigFig class, although it also exports various constants and functions.

SigFig Class

This class can create instances (prefer SigFig.from) but also has various static utilities that may achieve what you want.

Instance Utilities

Here is a list of the public properties and methods available when you create a SigFig instance.

• The following examples assume const sf = SigFig.from('1.23e-4')

  • value:number

    • returns the numerical value extracted from the input
    • e.g. sf.value => 1.23e-4

  • get precision():{ total:number, index:number, decimal:number }

    • returns info about the precision of the input
    • e.g. sf.precision => { total: 3, index: 6, decimal: 6 }

  • get parsed():{ value: number, precision: { total: number, decimal: number } }

    • returns all the information about the input
    • e.g. sf.parsed => { value: 0.000123, precision: { total: 3, index: 6, decimal: 6 } }

  • add|divide|multiply|subtract(b:number|SigFig.Type):this

    • adds, divides, multiplies, or subtracts the input against itself and returns itself; number inputs have no significant figures, and the rules of significant figures will be followed in all cases
    • e.g. sf.add(2).toString() => '2.000123'
    • e.g. sf.add('2').toString() => '2'
    • e.g. sf.divide(2).toString() => '0.0000615'
    • e.g. sf.divide('2').toString() => '0.00006'
    • e.g. sf.multiply(2).toString() => '0.000246'
    • e.g. sf.multiply('2').toString() => '0.0002'
    • e.g. sf.subtract(2).toString() => '-1.999877'
    • e.g. sf.subtract('2').toString() => '-2'

  • toFixed():string

    • returns the string which results from calling .toFixed() on the numerical value with the decimal precision as the argument; this should never show scientific notation
    • e.g. sf.toFixed() => '0.000123'

  • toJSON():string

    • returns this.toPrecision() so sig fig objects can be easily serialized in JSON
    • e.g. JSON.stringify({ sigFig: sf }) => '{"sigFig":"0.000123"}'

  • toPrecision():string

    • returns the string which results from calling .toPrecision() on the numerical value with the total precision as the argument; in some cases it may resort to scientific notation to avoid ambiguity
    • e.g. sf.toPrecision() => '0.000123'

  • toString():string

    • return this.toPrecision() so sig fig objects can be easily interpolated within strings; if you prefer values to be shown without scientific notation, you may want to use .toFixed()
    • e.g. 'the value is ' + sf => 'the value is 0.000123'

  • updatePrecision(precision:{ total:number }|{ index:number }|{ decimal:number }):this

    • allows for updating the number of significant figures; supply either decimal or total, not both, as the other will automatically be calculated appropriately
    • e.g. sf.updatePrecision({ decimal: 8 }).toString() => '0.00012300'
    • e.g. sf.updatePrecision({ total: 4 }).toString() => '0.0001230'

Static Utilities

Here is a list of the most important public static properties and methods available when you import the SigFig class. Other properties and methods are available, but less common, and can thus be read about in the documentation comments.

• SigFig

  • static add|divide|multiply|subtract(a:SigFig.Type, b:number|SigFig.Type):SigFig

    • this is equivalent to SigFig.from(a).add|divide|multiply|subtract(b)

  • static isType(obj:any):obj is SigFig.Type

    • this will check an input to see if it can be parsed by the SigFig class

  • static toParsed(measurement:SigFig.Type):{ value: number, precision: { total:number, index:number, decimal:number } }

    • this is equivalent to SigFig.from(measurement).parsed

Constants

The following constants are available as a matter of convenience, but are mainly used internally.

rJsonNumber:RegExp

This RegExp is used internally to extract various details from a significant figure string.

rJsonNumber.exec('1.1234e-4');
// => [ '1.1234e-4', '1', '.123', '4', '-4', index: 0, input: '1.1234e-4', groups: undefined ]

NOTE: this RegExp is also exported on the class itself as SigFig.rSigFigString.

Functions

The following functions are available as a matter of convenience, but are mainly used internally.

getPrecisionInfo(value:string):{ decimal:number, total:number }

Use this function to quickly extract the precision info from a number stored as a string.

getPrecisionInfo('1.234');
// => { total: 4, index: 3, decimal: 3 }

isInteger(value:any):value is number

Function is mainly for internal use. It checks if the input is a number and if it can be evenly divided by 1. It also acts as a type guard.

isInteger(3.0); // => true
isInteger(3.3); // => false

isValidTotalPrecision(value:any):value is number

Function is mainly for internal use. It checks if the input is an integer in the mathematical set [1,100]. It also acts as a type guard.

isValidTotalPrecision(0); // => false
isValidTotalPrecision(50); // => true

isValidFixedPrecision(value:any):value is number

Function is mainly for internal use. It checks if the input is an integer in the mathematical set [0,100]. It also acts as a type guard.

isValidFixedPrecision(-1); // => false
isValidFixedPrecision(0); // => false
isValidFixedPrecision(50); // => true