Package Exports

bn-str-256

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (bn-str-256) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

build status

bn-str-256

A simple, functional library for big number math, with up to 80 digits of precision, suitable for 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'

// 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
`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`
`max(a, b)`	Take the maximum of `a` and `b`
`min(a, b)`	Take the minimum of `a` and `b`
`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 either truncate or left-pad it to `length` digits
`toOctal(x)`	Convert `x` to an octal string (e.g., `04335`)
`toOctal(x, length)`	Convert `x` to an octal string and either truncate or left-pad it to `length` digits
`toBinary(x)`	Convert `x` to a binary string (e.g., `0b10111010`)
`toBinary(x, length)`	Convert `x` to a binary string and either truncate or left-pad it to `length` digits
`toBuffer(x)`	Convert `x` to a `Buffer` object
`toBuffer(x, size)`	Convert `x` to a `Buffer` object, and either truncate or left-pad it to `size` bytes
`toNumber(x)`	Convert `x` to a native `Number` type. Precision loss may occur.
`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 either truncate or left-pad it to `length` digits
`fromBits(bits)`	Convert a `bits` array of `1`s and `0`s to a number