bn-str-256
v1.9.1
Published
Simple, functional big number library for up to 256-bit (32-byte) numbers that outputs decimal strings, with hex, binary, octal, and Buffer decoding/encoding.
Downloads
31,947
Maintainers
Readme
bn-str-256
A simple, functional library for big number math, with up to 120 digits of precision, more than suitable for working with 256-bit/32-byte numbers used in domains like blockchain.
What sets this apart from other big number libraries is a very simple
functional syntax where most operations result in a decimal
string (e.g., '412.959'
), which, depending on
your application, may be a more useful representation.
Additionally, all functions accept plain numbers, decimal strings, exponential
strings (e.g., '1.5e-8'
), hex (e.g., '0xf00b47'
),
binary (e.g., '0b10011'
), or octal (e.g., '04471'
) encodings,
as well as node Buffer
objects as input. The library can likewise convert
numbers to any of these encodings or Buffer
objects.
This library is built as a wrapper around the awesome decimal.js-light library.
Installation
npm install bn-str-256
# or
yarn add bn-str-256
Examples
const bn = require('bn-str-256');
// Add two numbers.
bn.add(1234, '0x4953'); // '20005'
// Subtract two numbers.
bn.sub(1234, '1.5e-3'); // '1233.9985''
// Multiply two numbers.
bn.mul('1234.521', '305'); // output '376528.905'
// Divide two numbers.
bn.div(1234, '0x4953'); // '0.06573970486...'
// Take the modulo of two numbers.
bn.mod('1.412e8', 33); // '29'
// Raise to a power.
bn.pow(1234, 8); // '5376767751082385640407296'
// Take the 3rd root.
bn.pow(1234, 1/3); // '10.7260146688...'
// Remove decimals.
bn.int(44.4121); // '44'
// Round.
bn.round(44.68); // '45'
// Count decimal places.
bn.dp(44.312); // 3
// Count significant digits.
bn.dp(44.312); // 5
// Truncate decimal places.
bn.dp(44.312, 2); // '44.31'
// Truncate significant digits.
bn.dp(44.312, 3); // '44.3'
// Get the sign of a number.
bn.sign('-31.4121'); // -1
// Work with some big numbers
bn.sub('0x8ffffffffffffffffffffffffffffffffffffff',
'1591029491249109201931039109512131121212') // '51380915346385064...'
// Compare numbers a variety of ways.
bn.cmp(1, 2); // -1
bn.gt(321, 321); // false
bn.gte(321, 321); // true
bn.lt(320, 321); // true
bn.lte(320, 321); // true
// Take the minimum of two values.
bn.min('1294.31221944', '5.421e6'); // '1294.31221944'
// Take the maximum of two values.
bn.min('1294.31221944', '5.421e6'); // '5421000'
// Clamp a value to within an interval.
bn.min('1600', '1294.31221944', '5.421e6'); // '1600'
// Just parse a hex value.
bn.parse('0x49121') // '299297'
// Just parse a binary value.
bn.parse('0b1001') // '9'
// Just parse a Buffer object.
bn.parse(Buffer.from('foo')); // 6713199
// Do some math and output a hex string.
bn.toHex(bn.mul('3043131212', '495')); // 0x15eb97423f4
// Left pad a hex string to 20 digits.
bn.toHex('4491959969129121', 20); // 0x0000000ff569ee4e22a1
// Convert to a buffer.
bn.toBuffer('99129129412'); // <Buffer 17 14 8e 79 c4>
// Convert to native javascript Number type.
bn.toNumber('0x491fc712d'); // 19629109549
// Split a number up into its parts.
bn.split('-34.99'); // { sign: '-', integer: '34', decimal: '99' }
All Functions
| name (alias) | description |
|----------------|-------------|
| parse(x)
(expand) | convert a Number, exponential string, hex/octal/binary-encoded string, or buffer object into a decimal string |
| add(a, b)
(plus) | Add a
and b
|
| sub(a, b)
(minus) | Subtract b
from a
|
| mul(a, b)
(times) | Multiply a
and b
|
| div(a, b)
(over) | Divide a
over b
|
| idiv(a, b)
| Divide a
by b
and return the integer portion |
| mod(a, b)
| a
modulo b
|
| pow(x, y)
(raise) | Raise x
to the y
power |
| log(x)
(ln) | Natural logarithm of x
|
| log(x, base)
| Logarithm of x
with base y
|
| int(x)
| Return the integer portion of x
(no rounding) |
| round(x)
| Round x
to an integer |
| sum(...args)
| Sum all arguments |
| neg(x)
(negate) | Negate x
|
| abs(x)
| Take the absolute value of x
|
| sqrt(x)
| Take the square root of x
|
| exp(y)
| Raise the mathematical constant e to y
|
| max(a, b)
| Take the maximum of a
and b
|
| min(a, b)
| Take the minimum of a
and b
|
| clamp(x, l, h)
| Clamp x
to be within l
and h
, inclusive |
| sd(x)
| Get the number of significant digits of x
|
| sd(x, n)
| Set the number of significant digits of x
to n
|
| dp(x)
| Get the number of decimal places of x
|
| dp(x, n)
| Set the number of decimal places of x
to n
|
| sign(x)
| Get the sign of x
(-1
if x < 0
, 1
otherwise) |
| cmp(a, b)
| Compare a
with b
(where -1
if a < b
, 0
if a == b
, 1
if a > b) |
| eq(a, b)
| Test if a == b
|
| ne(a, b)
| Test if a != b
|
| gt(a, b)
| Test if a > b
|
| lt(a, b)
| Test if a < b
|
| gte(a, b)
| Test if a >= b
|
| lte(a, b)
| Test if a <= b
|
| toHex(x)
| Convert x
to a hex string (e.g., 0xf3abb
) |
| toHex(x, length)
| Convert x
to a hex string and left truncate/pad it to length
digits. If length
is negative, the result will be right padded/truncated. |
| toOctal(x)
| Convert x
to an octal string (e.g., 04335
) |
| toOctal(x, length)
| Convert x
to an octal string and left truncate/pad it to length
digits. If length
is negative, the result will be right padded/truncated. |
| toBinary(x)
| Convert x
to a binary string (e.g., 0b10111010
)|
| toBinary(x, length)
| Convert x
to a binary string and left truncate/pad it to length
digits. If length
is negative, the result will be right padded/truncated. |
| toBuffer(x)
| Convert x
to a Buffer
object |
| toBuffer(x, size)
| Convert x
to a Buffer
object, and left truncate/pad it to size
bytes. If size
is negative, the result will be right padded/truncated. |
| toBits(x)
| Convert x
to an array of 1
s and 0
s representing its bits. |
| toBits(x, length)
| Convert x
to bit array and left truncate/pad it to length
digits. If length
is negative, the result will be right padded/truncated. |
| fromBits(bits)
| Convert a bits
array of 1
s and 0
s to a number |
| toNumber(x)
| Convert x
to a native Number
type. Precision loss may occur. |
| E
| The mathematical constant e (2.71828...
) |
| PI
| The mathematical constant π (3.1415926...
) |