<commit_before>Big UInteger Formatter 
====
[![Build Status](https://travis-ci.org/T-PWK/biguint-format.png?branch=master)](https://travis-ci.org/T-PWK/biguint-format)  [![NPM version](https://badge.fury.io/js/biguint-format.png)](http://badge.fury.io/js/biguint-format) [![Total views](https://sourcegraph.com/api/repos/github.com/T-PWK/biguint-format/counters/views.png)](https://sourcegraph.com/github.com/T-PWK/biguint-format) 

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

JavaScript uses [IEEE 754 double-precision floats](http://en.wikipedia.org/wiki/IEEE_floating_point) 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.

```js
(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:
```js
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
```

## Usage ##

The `biguint-format` module has `format(number, format [, options])` function 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](http://nodejs.org/api/buffer.html) 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`
<commit_msg>Documentation update<commit_after>Big UInteger Formatter 
====
[![Build Status](https://travis-ci.org/T-PWK/biguint-format.png?branch=master)](https://travis-ci.org/T-PWK/biguint-format)  [![NPM version](https://badge.fury.io/js/biguint-format.png)](http://badge.fury.io/js/biguint-format) [![Total views](https://sourcegraph.com/api/repos/github.com/T-PWK/biguint-format/counters/views.png)](https://sourcegraph.com/github.com/T-PWK/biguint-format) 

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

JavaScript uses [IEEE 754 double-precision floats](http://en.wikipedia.org/wiki/IEEE_floating_point) 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.

```js
(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:
```js
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
```

## Usage ##

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](http://nodejs.org/api/buffer.html) 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`

{'fraction_non_alphanumeric': 0.12838095238095237, 'fraction_numerical': 0.08, 'mean_word_length': 4.751369112814896, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 10, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1475912', 'n_tokens_mistral': 2047, 'n_tokens_neox': 1751, 'n_words': 554}