rof v1.0.1

Rule of Four

Determine the most reasonable display format for a given numeric value or set of numeric values. Using a modified version of the rule of four and other methods.

Introduction

Ideally, when working numeric data, one should know the precision of the underlying data and display those values appropriately. However, when developing software it is not always possible to pre-determine the precision. In addition, when using JavaScript, numbers are not often displayed as one would expect. Take for example the following values and three common methods for generating a display string in JavaScript.

Some issues we notices are:

• toLocaleString has inconsistent precision. In many cases (for example 0.00255 and 2.00001) toLocaleString provides too low precision, in others (for example 1234567891234) the precision is unnecessarily high.
• All three methods make no distinction between integers, decimal, and floating point values.
• toLocaleString highly has inconsistent string size. For example, displaying 1.2e+21 as a decimal results in an unnecessarily long string.

Additionally, given a set of values, the values should be formatted consistently for comparison to each other.

Therefore, the goals of this project are:

• Determine the display precision in a predictable manner.
• Preserve (as much as possible) display for integers, decimals, and floats.
• Display the smallest string necessary for the value.
• Given a set of values, determine the most consistent display format across the set.

To this end, this library makes use or the "rule of four" described in Setting number of decimal places for reporting risk ratios: rule of four. The rule of four is a simple method for determining appropriate number of decimal places to use when reporting risk ratios. The rule states “Round the risk ratio to two significant digits if the leading non-zero digit is four or more, otherwise round to three;”. We extend the rule here to other values.

Getting Started

Installing

npm install rof

The core formatting methods (with default options) can be imported directly:

import { ruleOfFour, format, formatInteger, formatDecimal, formatFloat, pickFormat } from '.';

Summary of Methods

ruleOfFour: Formats a value as a decimal using the strict rule of four to determine the precision.

formatFloat: Formats a value as a float (exponential) using the rule of four to determine the precision.

formatInteger: Formats a value as an integer or float (using formatFloat) for large values.

formatDecimal: Formats a value as a decimal or float (using formatFloat) for large or small values.

format: Formats a value as an integer (using formatInteger) or a decimal (using formatDecimal) if the value is not an integer.

pickFormat: Given an array of values, returns the best formatter method, from among the following three methods: formatFloat, formatInteger, and formatDecimal.

API Reference

ruleOfFour(x: number): string

Formats a value as a decimal using the strict rule of four to determine the precision.

formatFloat(x: number): string

Returns the value formatted as a floating point value using the following rules:

• If x === -0 returns -0.00e+0
• otherwise returns x.toExponential(N) (where N is the precision following the rule of four)

formatInteger(x: number): string

Returns the value formatted as an integer using with the following rules:

• If the Math.round(x) === -0 returns -0
• if the resulting character length is <= 9 returns Math.round(x).toLocaleString()
• otherwise, formatFloat(Math.round(x))

formatDecimal(x: number): string

Returns the value formatted as a decimal using with the following rules:

• If the value is -0, returns -0.00
• if Math.abs(x) < 0.4 and the resulting character length is <= 9, returns x.toPrecision(N) (where N is the precision following the rule of four)
• if Math.abs(x) >= 0.4 and the resulting character length is <= 9, returns x.toLocaleString(locales, {minimumFractionDigits: 2, maximumFractionDigits: 2})
• otherwise, returns formatFloat(x).

format(x: number): string

Returns the value formatted with the following rules:

• If x is an integer (within a given threshold) returns formatInteger(x) .
• otherwise, returns formatDecimal(x).

Other sample outputs below:

Integers

Decimals and Floats

Special

pickFormat(arr: number[]): function

Given an array of values, returns the best formatting method using the following rules:

• If all values are integers:
  • and the maximum Log10 of the values is <= 6, returns formatInteger.
  • otherwise, returns formatFloat.
• If not all values are integers:
  • and the maximum Log10 of the values is >= 6 or minimum Log10 of the values <= -6, returns formatFloat
  • otherwise, returns formatDecimal

RofFormat class

The RofFormat object is a constructor encapsulating the methods above and allowing customization.

new RofFormat(locales?: string | string[], options?: RofFormatOptions)

locales parameter is a string or array passed to internal usage of NumberFormat.

options operator is an object with some or all of the following properties:

minimumSignificantDigits The minimum number of integer digits to use. The default is 2.

maximumSignificantDigits The maximum number of significant digits to use. The default is minimumSignificantDigits + 1

integerThreshold The threshold used to determine if a value is an integer. The default is Number.EPSILON.

Other options values are passed to internal usage of NumberFormat.

License

This project is licensed under the MIT License - see the LICENSE file for details