Numeric API - Documentation | www.HtmlElements.com

Numeric API

Overview

Standard numeric format strings are used to format common numeric types. A standard numeric format string takes the form Axx, where:

  • A is a single alphabetic character called the format specifier.
  • xx is an optional integer called the precision specifier. The precision specifier ranges from 0 to 99 and affects the number of digits in the result. Note that the precision specifier controls the number of digits in the string representation of a number. It does not round the number itself.

Use

To format a number using one of the available format strings, the formatNumber method has to be used. It is part of the NumberRenderer class which has to be instantiated before the method is invoked.

To instantiate a NumberRenderer object and use the formatNumber method, the user has to include the following files to the head of the page:

  • smart.element.js - the base class
  • smart.numeric.js - the JS file containing the class NumberRenderer and the method formatNumber.
  • smart.math.js - the JS file that enables the processing of large numbers (i.e. 64-bit integers).
  • smart.complex.js (optional) - the JS file that enables the processing of complex numbers.

Here is an example showing how to format a number in the Currency format:

  1. <!DOCTYPE html>
  2. <html lang="en">
  3. <head>
  4.     <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/webcomponentsjs/1.0.22/webcomponents-lite.js"></script>
  5.     <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/webcomponentsjs/1.0.22/webcomponents-loader.js"></script>
  6.     <script type="text/javascript" src="../../source/smart.element.js"></script>
  7.     <script type="text/javascript" src="../../source/smart.numeric.js"></script>
  8.     <script type="text/javascript" src="../../source/smart.math.js"></script>
  9.     <script type="text/javascript">
  10.         window.onload = function () {
  11.             const renderer = new Smart.Utilities.NumberRenderer(),
  12.                 formattedNumber = renderer.formatNumber(40.987, 'C2');
  13.             console.log(formattedNumber);
  14.         }
  15.     </script>
  16. </head>
  17. <body>
  18. </body>
  19. </html>

Above code will log

$40.99

in the browser console.

formatNumber also supports formatting 64-bit integer numbers and complex numbers:

  1. <!DOCTYPE html>
  2. <html lang="en">
  3. <head>
  4.     <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/webcomponentsjs/1.0.22/webcomponents-lite.js"></script>
  5.     <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/webcomponentsjs/1.0.22/webcomponents-loader.js"></script>
  6.     <script type="text/javascript" src="../../source/smart.element.js"></script>
  7.     <script type="text/javascript" src="../../source/smart.numeric.js"></script>
  8.     <script type="text/javascript" src="../../source/smart.math.js"></script>
  9.     <script type="text/javascript" src="../../source/smart.complex.js"></script>
  10.     <script type="text/javascript">
  11.         window.onload = function () {
  12.             const renderer = new Smart.Utilities.NumberRenderer(),
  13.                 int64Number = new Smart.Utilities.BigNumber('9223372036854775807'),
  14.                 formattedInt64Number = renderer.formatNumber(int64Number, 'X16', 'int64'),
  15.                 complexNumber = new NIComplex('15000000 - 0.0037i'),
  16.                 formattedComplexNumber = renderer.formatNumber(complexNumber, 'N3');
  17.             console.log(formattedInt64Number);
  18.             console.log(formattedComplexNumber);
  19.         }
  20.     </script>
  21. </head>
  22. <body>
  23. </body>
  24. </html>

Above code will log the Hexadecimal representation of the number 9223372036854775807 and the complex number 15000000 - 0.0037i (with precision of three decimal digits applied to its real and imaginary parts) in the browser console:

7FFFFFFFFFFFFFFF
15,000,000.000 - 0.004i

All supported numeric format strings are listed below.

Please note that "C"/"c", "D"/"d", "P"/"p", "X"/"x", "B"/"b", and "O"/"o" are not applicable to complex numbers.

Currency ("C" or "c")

The result after applying this format string is a currency value. The precision specifier determines the number of decimal digits.

Code Result
formatNumber(123.456, 'C') $123.46
formatNumber(123.456, 'C') (localized) 123,46 €
formatNumber(-123.456, 'C3') -$123.456
formatNumber(-123.456, 'C3') (localized) -123,456 €
formatNumber(new Smart.Utilities.BigNumber('-9223372036854775808'), 'C3') -$9,223,372,036,854,775,808.000
formatNumber(new Smart.Utilities.BigNumber('1234'), 'C3') $1,234.000
formatNumber(new Smart.Utilities.BigNumber('9223372036854775807'), 'C3') $9,223,372,036,854,775,807.000

Decimal ("D" or "d")

The result after applying this format string is integer digits with optional negative sign. The precision specifier determines the minimum number of digits. If required, the number is padded with zeros to its left to produce the number of digits given by the precision specifier.

Code Result
formatNumber(1234, 'D') 1234
formatNumber(-1234, 'D6') -001234
formatNumber(new Smart.Utilities.BigNumber('-9223372036854775808'), 'D20') -09223372036854775808
formatNumber(new Smart.Utilities.BigNumber('1234'), 'D20') 00000000000000001234
formatNumber(new Smart.Utilities.BigNumber('9223372036854775807'), 'D20') 09223372036854775807

Exponential/Scientific ("E" or "e")

The result after applying this format string is in exponential notation. The precision specifier determines the desired number of digits after the decimal point. If the precision specifier is omitted, a default of six digits after the decimal point is used.

The case of the format specifier indicates whether to prefix the exponent with an "E" or an "e". The exponent always consists of a plus or minus sign and a minimum of three digits. The exponent is padded with zeros to meet this minimum, if required.

Code Result
formatNumber(1052.0329112756, 'E') 1.052033E+003
formatNumber(1052.0329112756, 'e') (localized) 1,052033e+003
formatNumber(-1052.0329112756, 'e2') -1.05e+003
formatNumber(-1052.0329112756, 'E2') (localized) -1,05E+003
formatNumber(new Smart.Utilities.BigNumber('-9223372036854775808'), 'E') -9.223372E+018
formatNumber(new Smart.Utilities.BigNumber('1234'), 'E') 1.234000E+003
formatNumber(new Smart.Utilities.BigNumber('9223372036854775807'), 'E') 9.223372E+018
formatNumber(new NIComplex('15000000 - 0.0037i'), 'e2') 1.50e+007 - 3.70e-003i

Fixed-point ("F" or "f")

The result after applying this format string is integer and decimal digits with optional negative sign. The precision specifier determines the number of decimal digits.

Code Result
formatNumber(1234.567, 'F') 1234.57
formatNumber(1234.567, 'F') (localized) 1234,57
formatNumber(1234, 'F1') 1234.0
formatNumber(1234, 'F1') (localized) 1234,0
formatNumber(-1234.56, 'F4') -1234.5600
formatNumber(-1234.56, 'F4') (localized) -1234,5600
formatNumber(new Smart.Utilities.BigNumber('-9223372036854775808'), 'F4') -9223372036854775808.0000
formatNumber(new Smart.Utilities.BigNumber('1234'), 'F4') 1234.0000
formatNumber(new Smart.Utilities.BigNumber('9223372036854775807'), 'F4') 9223372036854775807.0000
formatNumber(new NIComplex('15000000 - 0.0037i'), 'F3') 15000000.000 - 0.004i

General ("G" or "g")

The result after applying this format string is the more compact of either fixed-point or scientific notation. The precision specifier determines the number of significant digits.

If scientific notation is used, the exponent in the result is prefixed with "E" if the format specifier is "G", or "e" if the format specifier is "g". The exponent contains a minimum of two digits.

Code Result
formatNumber(-123.456, 'G') -123.456
formatNumber(-123.456, 'G') (localized) -123,456
formatNumber(123.4546, 'G4') 123.5
formatNumber(123.4546, 'G4') (localized) 123,5
formatNumber(-1.234567890e-25, 'G') -1.23456789E-25
formatNumber(-1.234567890e-25, 'G') (localized) -1,23456789E-25
formatNumber(new Smart.Utilities.BigNumber('-9223372036854775808'), 'g', 'int64') -9223372036854775808
formatNumber(new Smart.Utilities.BigNumber('1234'), 'g', 'int64') 1234
formatNumber(new Smart.Utilities.BigNumber('9223372036854775807'), 'g', 'int64') 9223372036854775807
formatNumber(new NIComplex('15000000 - 0.0037i'), 'g') 1.5e+07 - 0.0037i

Number ("N" or "n")

The result after applying this format string is integer and decimal digits, thousands separators, and a decimal separator with optional negative sign. The precision specifier determines the number of decimal digits.

Code Result
formatNumber(1234.567, 'N') 1,234.57
formatNumber(1234.567, 'N') (localized) 1 234,57
formatNumber(1234, 'N1') 1,234.0
formatNumber(1234, 'N1') (localized) 1 234,0
formatNumber(-1234.56, 'N4') -1,234.5600
formatNumber(-1234.56, 'N4') (localized) -1 234,5600
formatNumber(new Smart.Utilities.BigNumber('-9223372036854775808'), 'N4') -9,223,372,036,854,775,808.0000
formatNumber(new Smart.Utilities.BigNumber('1234'), 'N4') 1,234.0000
formatNumber(new Smart.Utilities.BigNumber('9223372036854775807'), 'N4') 9,223,372,036,854,775,807.0000
formatNumber(new NIComplex('15000000 - 0.0037i'), 'N3') 15,000,000.000 - 0.004i

Percent ("P" or "p")

The result after applying this format string is the number multiplied by 100 and displayed with a percent symbol. The precision specifier determines the number of decimal digits.

Code Result
formatNumber(1, 'P') 100.00 %
formatNumber(1, 'P') (localized) 100,00 %
formatNumber(-0.39678, 'P1') -39.7 %
formatNumber(-0.39678, 'P1') (localized) -39,7 %
formatNumber(new Smart.Utilities.BigNumber('-9223372036854775808'), 'P') -922,337,203,685,477,580,800.00 %
formatNumber(new Smart.Utilities.BigNumber('1234'), 'P') 123,400.00 %
formatNumber(new Smart.Utilities.BigNumber('9223372036854775807'), 'P') 922,337,203,685,477,580,700.00 %

Hexadecimal ("X" or "x")

The result after applying this format string is a hexadecimal string. The precision specifier indicates the minimum number of digits desired in the resulting string. If required, the number is padded with zeros to its left to produce the number of digits given by the precision specifier.

The case of the format specifier indicates whether to use uppercase or lowercase characters for hexadecimal digits that are greater than 9.

Code Result
formatNumber(255, 'X') (32-bit) FF
formatNumber(-1, 'x', 'int8') (8-bit) ff
formatNumber(255, 'x4') (32-bit) 00ff
formatNumber(-1, 'X4', 'int8') (8-bit) 00FF
formatNumber(new Smart.Utilities.BigNumber('-9223372036854775808'), 'X16', 'int64') (64-bit) 8000000000000000
formatNumber(new Smart.Utilities.BigNumber('1234'), 'X16', 'int64') (64-bit) 00000000000004D2
formatNumber(new Smart.Utilities.BigNumber('9223372036854775807'), 'X16', 'int64') (64-bit) 7FFFFFFFFFFFFFFF

Binary ("B" or "b")

The result after applying this format string is a binary string. The precision specifier indicates the minimum number of digits desired in the resulting string. If required, the number is padded with zeros to its left to produce the number of digits given by the precision specifier.

Code Result
formatNumber(255, 'B') (32-bit) 11111111
formatNumber(-1, 'b', 'int8') (8-bit) 11111111
formatNumber(255, 'b16') (32-bit) 0000000011111111
formatNumber(-1, 'B16', 'int8') (8-bit) 0000000011111111
formatNumber(new Smart.Utilities.BigNumber('-9223372036854775808'), 'B64', 'int64') (64-bit) 1000000000000000000000000000000000000000000000000000000000000000
formatNumber(new Smart.Utilities.BigNumber('1234'), 'B64', 'int64') (64-bit) 0000000000000000000000000000000000000000000000000000010011010010
formatNumber(new Smart.Utilities.BigNumber('9223372036854775807'), 'B64', 'int64') (64-bit) 0111111111111111111111111111111111111111111111111111111111111111

Octal ("O" or "o")

The result after applying this format string is an octal string. The precision specifier indicates the minimum number of digits desired in the resulting string. If required, the number is padded with zeros to its left to produce the number of digits given by the precision specifier.

Code Result
formatNumber(255, 'O') (32-bit) 377
formatNumber(-1, 'o', 'int8') (8-bit) 377
formatNumber(255, 'o6') (32-bit) 000377
formatNumber(-1, 'O6', 'int8') (8-bit) 000377
formatNumber(new Smart.Utilities.BigNumber('-9223372036854775808'), 'O21', 'int64') (64-bit) 1000000000000000000000
formatNumber(new Smart.Utilities.BigNumber('1234'), 'O21', 'int64') (64-bit) 000000000000000002322
formatNumber(new Smart.Utilities.BigNumber('9223372036854775807'), 'O21', 'int64') (64-bit) 777777777777777777777

SI/System of Units Notation ("S" or "s")

The result after applying this format string is the shortest representation of the number after applying a metric (SI) prefix. The supported prefixes are: Y (1024), Z (1021), E (1018), P (1015), T (1012), G (109), M (106), k (103), c (10-2), m (10-3), u (10-6), n (10-9), p (10-12), f (10-15), a (10-18), z (10-21), y (10-24). The precision specifier determines the number of decimal digits.

Code Result
formatNumber(150000000, 'S0') 150M
formatNumber(-0.0000012, 'S') -1.20u
formatNumber(1255, 'S2') 1.25k
formatNumber(80000000000, 'S0') 80G
formatNumber(new Smart.Utilities.BigNumber('-9223372036854775808'), 'S5') -9.22337E
formatNumber(new Smart.Utilities.BigNumber('1234'), 'S5') 1.23400k
formatNumber(new Smart.Utilities.BigNumber('9223372036854775807'), 'S5') 9.22337E
formatNumber(new NIComplex('15000000 - 0.0037i'), 'S') (64-bit) 15.00M - 3.70mi