biguint-format

An arbitrary length unsigned integer formatter library for Node.js

``npm install biguint-format``

Big UInteger Formatter

An arbitrary length unsigned integer formatter library for Node.js.

JavaScript uses IEEE 754 double-precision floats to represents numbers. That works perfectly fine for small numbers, however, it is an issue for big integers. This means they lose integer precision for values beyond `+/- 2 pow 53`

Problem

Presentation of small integer in decimal format works fine (e.g. `0x1FF`). However, we can see an issue when we try to convert big integers like `0x1234567890abcdeffedcba908765421` to string decimal.

``````(0x1FF).toString(10) // returns '511' - correct
(0x1234567890abcdeffedcba908765421).toString(10)

// output is '1.5123660750094533e+36' - incorrect - lose integer precision
``````

Solution

Node.js `biguint-format` module has been built in order to help display very large (arbitrary lengh) unsigned integers without any integer precision lose.

Example:

``````var biguint  = require('biguint-format');

// 0x1234567890abcdeffedcba908765421 split into bytes
biguint.format([0x1, 0x23, 0x45, 0x67, 0x89, 0x0a, 0xbc, 0xde, 0xff, 0xed, 0xcb, 0xa9, 0x08, 0x76, 0x54, 0x21], 'dec')

// output value is '1512366075009453296626403467035300897' - no integer precision lose
``````

Instalation

``````\$ npm install biguint-format
``````

API

The `biguint-format` module is a function (`fn(number, format [, options])`) which performs number conversion to the required string format.

The `number` argument represents an arbitrary lenght unsigned integer number to be converted to string. It can be provided in one of the following formats:

• Node.js Buffer e.g. `new Buffer([0x1, 0xFF])`
• An array of bytes (values from `0x00` to `0xFF`) e.g. `[0x1, 0xFF]`.
• A string with a number in a hexadecimal format e.g. `0x1FF0A` or `1FF0A`

The `format` argument represents output string format and it can be one of the following options:

• `dec` - convertion to decimal format e.g. `123324884`
• `bin` - conversion to binary format e.g. `1100101010`
• `hex` - conversion to hexadecimal format e.g. `0xADFFAA11`
• `oct` - conversion to octet format e.g. `07771`

The `options` argument (optional) is an object which provides some additional conversion details:

• `format` - specifies format of the input number. It can be either `BE` for Big Endian or `LE` for Little Endian. `BE` is a default value. Check wikipedia for more details.
• `prefix` - output string prefix. Note that this option is not supported by `dec` conversion.
• `groupsize` - splits output string into groups of `groupsize` lenght characters.
• `delimiter` - specifes delimiter string to be inserted in between character groups. Default value is space. It is quite handy option when dealing with large numbers.
• `trim` - (works only with `bin` formatting) specifies if the leading 0's should be trimmed.
• `padstr` - string used for right-padding of the fomratted string if its length (inlucing prefix and grouping) is less than value of `size` parameter.
• `size` - determines formatted string size. That opiton has effect only with `padstr` option. Note that the formatted string is not trimmed if its length is longer than value of `size` parameter.

Examples

``````var format = require('biguint-format');

var buffer1 = new Buffer([0x63, 0xA7, 0x27]);
var buffer2 = new Buffer([0x27, 0xA7, 0x63]);

format(buffer1, 'dec', {format:'LE'})   // returns '2598755'
format(buffer2, 'dec', {format:'BE'})   // returns '2598755'
format(buffer2, 'dec')                  // returns '2598755'

format(buffer1, 'hex', {format:'LE'})   // returns '27a763'
format(buffer2, 'hex', {format:'BE'})   // returns '27a763'
format(buffer2, 'hex', {prefix:'0x'})   // returns '0x27a763'

format(buffer2, 'bin')                  // 001001111010011101100011
format(buffer2, 'bin', {groupsize:8})   // 00100111 10100111 01100011
format(buffer2, 'oct')                  // 11723543
format(buffer2, 'oct', {prefix:'0'})    // 011723543
``````

Use of `delimiter` option which helps with large numbers e.g.

``````var format = require('biguint-format');

format([0x2A, 0xFF, 0x1E, 0x22, 0x11, 0x30, 0x12, 0x2F], 'bin')
format([0x2A, 0xFF, 0x1E, 0x22, 0x11, 0x30, 0x12, 0x2F], 'bin', {groupsize:8})

// returned values
0010101011111111000111100010001000010001001100000001001000101111        // no delimiter
00101010 11111111 00011110 00100010 00010001 00110000 00010010 00101111 // with delimiter
``````

Example of `trim` option which works only with binary formatter

``````var format = require('biguint-format');
var buffer = new Buffer([0x1, 0xA7, 0x63]);

format(buffer, 'bin');              // returns 000000011010011101100011
format(buffer, 'bin', {trim:true}); // returns 11010011101100011
``````

Example of `padstr` and `size` options

``````var format = require('biguint-format');
var buffer = new Buffer([0x1, 0xA7, 0x63]);

format(buffer, 'dec'); // returns 108387
format(buffer, 'oct'); // returns 323543
format(buffer, 'hex'); // returns 1a763

format(buffer, 'oct', {padstr:'0', size:10}); // returns 0000323543
format(buffer, 'hex', {padstr:'0', size:6});  // returns 01a763
``````

Author

Writen by Tom Pawlak - Blog