Библиотека JavaScript для арифметических операций с произвольной точностью

A JavaScript library for arbitrary-precision decimal and non-decimal arithmetic.

Особенности:

• Целые и десятичные числа;
• Простой API, но полнофункциональный;
• Быстрее, меньше и, возможно, проще в использовании, чем JavaScript-версии Java BigDecimal;
• 8 КБ в минифицированном и сжатом виде;
• Воспроизводит методы toExponential, toFixed, toPrecision и toString типа Number в JavaScript;
• Включает метод toFraction и правильно округлённый метод squareRoot;
• Поддерживает криптографически безопасное псевдослучайное числовое поколение;
• Без зависимостей;
• Широкая совместимость платформ: использует только функции JavaScript 1.5 (ECMAScript 3);
• Полная документация и тестовый набор.

Если требуется меньшая и более простая библиотека, см. big.js. Она меньше половины размера, но работает только с десятичными числами и имеет только половину методов. Также она не допускает NaN или Infinity и не имеет параметров конфигурации этой библиотеки.

Также см. decimal.js, который, помимо прочего, добавляет поддержку нецелых степеней и выполняет все операции до указанного количества значащих цифр.

Загрузка

Библиотека представляет собой один файл JavaScript bignumber.js (или минифицированный bignumber.min.js).

В браузере:

<script src='path/to/bignumber.js'></script>

Node.js:

$ npm install bignumber.js

const BigNumber = require('bignumber.js');

Модуль ES6:

import BigNumber from "./bignumber.mjs"

Библиотеки загрузчиков AMD, такие как requireJS:

require(['bignumber'], function(BigNumber) {
    // Используйте здесь BigNumber в локальной области видимости. Глобального BigNumber нет.
});

Использование

Библиотека экспортирует единственную функцию-конструктор BigNumber, которая принимает значение типа Number, String или BigNumber.

let x = new BigNumber(123.4567);
let y = BigNumber('123456.7e-3');
let z = new BigNumber(x);
x.isEqualTo(y) && y.isEqualTo(z) && x.isEqualTo(z);      // true

Чтобы получить строковое значение BigNumber, используйте toString() или toFixed(). Использование toFixed() предотвращает возврат экспоненциальной записи, независимо от того, насколько велико или мало значение.

let x = new BigNumber('1111222233334444555566');
x.toString();                       // "1.111222233334444555566e+21"
x.toFixed();                        // "1111222233334444555566"

Если ограниченная точность значений Number плохо понимается, рекомендуется создавать BigNumbers из строковых значений, а не из значений Number, чтобы избежать потенциальной потери точности. Текст запроса написан на языке JavaScript.

Вот перевод текста запроса на русский язык:

Затем передайте значение toString(2) числа и укажите основание 2.

new BigNumber(Number.MAX_VALUE.toString(2), 2)

BigNumbers можно создавать из значений в базах от 2 до 36. См. ALPHABET, чтобы расширить этот диапазон.

a = new BigNumber(1011, 2)          // "11"
b = new BigNumber('zz.9', 36)       // "1295.25"
c = a.plus(b)                       // "1306.25"

Производительность будет выше, если не указывать базу 10 для десятичных значений. Указывайте базу 10 только тогда, когда желательно ограничить количество знаков после запятой входного значения текущим параметром DECIMAL_PLACES.

BigNumber является неизменным в том смысле, что его методы не изменяют его.

0.3 - 0.1                           // 0.19999999999999998
x = new BigNumber(0.3)
x.minus(0.1)                        // "0.2"
x                                   // "0.3"

Методы, возвращающие BigNumber, могут быть связаны.

x.dividedBy(y).plus(z).times(9)
x.times('1.23456780123456789e+9').plus(9876.5432321).dividedBy('4444562598.111772').integerValue()

Некоторые из более длинных имён методов имеют более короткий псевдоним.

x.squareRoot().dividedBy(y).exponentiatedBy(3).isEqualTo(x.sqrt().div(y).pow(3))    // true
x.modulo(y).multipliedBy(z).eq(x.mod(y).times(z))                                   // true

Как и в случае с типом Number в JavaScript, существуют методы toExponential, toFixed и toPrecision.

x = new BigNumber(255.5)
x.toExponential(5)                  // "2.55500e+2"
x.toFixed(5)                        // "255.50000"
x.toPrecision(5)                    // "255.50"
x.toNumber()                        //  255.5

Можно указать базу для toString. Производительность будет лучше, если не указывать основание 10, т. е. использовать toString(), а не toString(10). Указывайте основание 10 только в том случае, если желательно ограничить количество десятичных знаков текущим параметром DECIMAL_PLACES.

x.toString(16)                     // "ff.8"

Существует метод toFormat, который может быть полезен для интернационализации.

y = new BigNumber('1234567.898765')
y.toFormat(2)                       // "1,234,567.90"

Максимальное количество знаков после запятой результата операции деления (т. е. деления, извлечения квадратного корня, преобразования основания или операции отрицательной степени) устанавливается с помощью метода set или config конструктора BigNumber.

Другие арифметические операции всегда дают точный результат.

BigNumber.set({ DECIMAL_PLACES: 10, ROUNDING_MODE: 4 })

x = new BigNumber(2)
y = new BigNumber(3)
z = x.dividedBy(y)                        // "0.6666666667"
z.squareRoot()                            // "0.8164965809"
z.exponentiatedBy(-3)                     // "3.3749999995"
z.toString(2)                             // "0.1010101011"
z.multipliedBy(z)                         // "0.44444444448888888889"
z.multipliedBy(z).decimalPlaces(10)       // "0.4444444445"

Существует метод toFraction с необязательным аргументом максимальный знаменатель

y = new BigNumber(355)
pi = y.dividedBy(113)               // "3.1415929204"
pi.toFraction()                     // [ "7853982301", "2500000000" ]
pi.toFraction(1000)                 // [ "355", "113" ]

и методы isNaN и isFinite, поскольку NaN и Infinity являются допустимыми значениями BigNumber.

x = new BigNumber(NaN)                                           // "NaN"
y = new BigNumber(Infinity)                                      // "Infinity"
x.isNaN() && !y.isNaN() && !x.isFinite() && !y.isFinite()        // true

Значение BigNumber хранится в десятичном формате с плавающей точкой в виде коэффициента, экспоненты и знака.

x = new BigNumber(-123.456);
x.c                                 // [ 123, 45600000000000 ]  коэффициент (т.е. мантисса)
x.e                                 // 2                        экспонента
x.s                                 // -1                       знак

Для расширенного использования можно создать несколько конструкторов BigNumber, каждый со своей собственной независимой конфигурацией.

// Устанавливаем DECIMAL_PLACES для оригинального конструктора BigNumber
BigNumber.set({ DECIMAL_PLACES: 10 })

// Создаём ещё один конструктор BigNumber, опционально передавая объект конфигурации
BN = BigNumber.clone({ DECIMAL_PLACES: 5 })

x = new BigNumber(1)
y = new BN(1)

x.div(3)                            // '0.3333333333'
y.div(3)                            // '0.33333'

Дополнительную информацию см. в справочнике по API в каталоге doc.

Тест

Каталог test/modules содержит тестовые сценарии для каждого метода.

Тесты можно запустить с помощью Node.js или браузера. Для Node.js используйте

$ npm test

или

$ node test/test

Чтобы протестировать отдельный метод, используйте, например

$ node test/methods/toFraction

В браузере откройте test/test.html.

Сборка

Для Node, если установлен uglify-js

npm install uglify-js -g

затем

npm run build

будет создан файл bignumber.min.js.

Также будет создана карта источника в корневом каталоге.

Обратная связь

Откройте вопрос или напишите на электронную почту

Майклу

M8ch88l@gmail.com

Лицензия

Лицензия MIT.

См. LICENCE.