New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updates bytes to use ISO/IEC 80000-13:2008 units #36

Closed
wants to merge 3 commits into
base: 3.0
from
Jump to file or symbol
Failed to load files and symbols.
+547 −118
Diff settings

Always

Just for now

Copy path View file
@@ -2,6 +2,8 @@
===
* Remove support for ComponentJS
* Adds ISO/IEC 80000-13:2008 format
- Adds compatibility mode for parsing older programs
* Stricter parsing of bytes
- String is only parsed if units are recognized
Copy path View file
170 Readme.md
@@ -4,19 +4,75 @@
[![NPM Downloads][downloads-image]][downloads-url]
[![Build Status][travis-image]][travis-url]
Utility to parse a string bytes (ex: `1TB`) to bytes (`1099511627776`) and vice-versa.
Utility to parse a string bytes (ex: `1TB`) to bytes (`1,000,000,000,000`) and vice-versa.
This uses the byte units defined in ISO/IEC 80000-13:2008, both the binary prefixes and the original SI units.
## Supported Units
Supported units and abbreviations are as follows and are case-insensitive:
### Metric/Decimal Prefixes
| Value | Abbr | Name |
| ---------------- | ---- | --------- |
| 1 | B | byte |

This comment has been minimized.

@dougwilson

dougwilson Aug 18, 2016

Contributor

Why not 1000<sup>0</sup> to keep with the same pattern? Also, using HTML is hard to read in text editors, so I would say if you can not use HTML in the MD, that would be best...

This comment has been minimized.

@Saevon

Saevon Aug 18, 2016

as a readme that would very likely be read on a browser I figured using math notation would be best, but we could do 1000^1 if you wish

This comment has been minimized.

@Saevon

Saevon Nov 1, 2016

@dougwilson: ^^^^ Waiting for an answer here
Also, 1000^0 actually seems weird, just 1 would make more sense at first glance for newcomers.

| 1000<sup>1</sup> | kB | kilobyte |
| 1000<sup>2</sup> | MB | megabyte |
| 1000<sup>3</sup> | GB | gigabyte |
| 1000<sup>4</sup> | TB | terabyte |
| 1000<sup>5</sup> | PB | petabyte |
| 1000<sup>6</sup> | EB | exabyte |
| 1000<sup>7</sup> | ZB | zettabyte |
| 1000<sup>8</sup> | YB | yottabyte |
### Binary Prefixes:
| Value | Abbr | Name |
| ---------------- | ---- | --------- |
| 1 | B | byte |
| 1024<sup>1</sup> | KiB | kibibyte |
| 1024<sup>2</sup> | MiB | mebibyte |
| 1024<sup>3</sup> | GiB | gibibyte |
| 1024<sup>4</sup> | TiB | tebibyte |
| 1024<sup>5</sup> | PiB | pebibyte |
| 1024<sup>6</sup> | EiB | exbibyte |
| 1024<sup>7</sup> | ZiB | zebibite |
| 1024<sup>8</sup> | YiB | yobibite |
### Compatibility Binary Prefixes
Overwrites the lower units of the metric system with the commonly misused prefixes
| Value | Abbr | Name |
| ---------------- | ---- | --------- |
| 1000<sup>1</sup> | kB | kilobyte |
| 1000<sup>2</sup> | MB | megabyte |
| 1000<sup>3</sup> | GB | gigabyte |
| 1000<sup>4</sup> | TB | terabyte |
## Usage
```js
var bytes = require('bytes');
```
#### bytes.format(number value, [options]): string|null
#### bytes.format(value, [options]): string|null
Format the given value in bytes into a string. If the value is negative, it is kept as such. If it is a float, it is
rounded.
It supports the following output formats:
* `binary`: uses the binary prefixes (KiB, MiB...)
* `decimal`|`metric`: uses the metric system (decimal) prefixes (kB, MB...)
* `compatibility`: uses the binary units, but the metric prefixes (kB == 1024B, MB...)
**Arguments**
| Name | Type | Description |
@@ -28,11 +84,12 @@ Format the given value in bytes into a string. If the value is negative, it is k
| Property | Type | Description |
|-------------------|--------|-----------------------------------------------------------------------------------------|
| decimalPlaces | `number`&#124;`null` | Maximum number of decimal places to include in output. Default value to `2`. |
| fixedDecimals | `boolean`&#124;`null` | Whether to always display the maximum number of decimal places. Default value to `false` |
| thousandsSeparator | `string`&#124;`null` | Example of values: `' '`, `','` and `.`... Default value to `' '`. |
| unitSeparator | `string`&#124;`null` | Separator to use between number and unit. Default value to `''`. |
| decimalPlaces | `number`&#124;`null` | Maximum number of decimal places to include in output. Default value is `2`. |
| fixedDecimals | `boolean`&#124;`null` | Whether to always display the maximum number of decimal places. Default value is `false` |
| thousandsSeparator | `string`&#124;`null` | Example of values: `' '`, `','` and `.`... Default value is `' '`. |
| unitSeparator | `string`&#124;`null` | Separator to use between number and unit. Default value is `''`. |
| mode | `string`&124;`null` | Which format to output: `binary`, `metric`, `decimal`, `compatibility`. Default value is `metric` |
| unit | `string`&#124;`null` | A specific unit to convert to. Default value is `''`. |
**Returns**
| Name | Type | Description |
@@ -42,42 +99,53 @@ Format the given value in bytes into a string. If the value is negative, it is k
**Example**
```js
bytes(1024);
// output: '1kB'
bytes(1000);
// output: '1000B'
// output: '1kB'
bytes(1000, {thousandsSeparator: ' '});
// output: '1 000B'
bytes(1024);
// output: '1.02kB'
bytes(1024 * 1.7, {decimalPlaces: 0});
// output: '2kB'
bytes(1024, {unitSeparator: ' '});
bytes(1000, {unitSeparator: ' '});
// output: '1 kB'
bytes(2048, {mode: 'binary'});
// output: '2 KiB'
bytes(1024 * 1024 * 2, {unit: 'KiB'});
// output: '2048 KiB'
bytes(1024 * 1024 * 2, {unit: 'KB'});
// output: '2097.152 KB'
bytes(1024 * 1024 * 2, {unit: 'KB', mode: 'compatibility'});
// output: '2048 KB'
```
#### bytes.parse(string value): number|null
Parse the string value into an integer in bytes. If no unit is given, it is assumed the value is in bytes.
Supported units and abbreviations are as follows and are case-insensitive:
* "b" for bytes
* "kb" for kilobytes
* "mb" for megabytes
* "gb" for gigabytes
* "tb" for terabytes
If the unit given has partial bytes, they are dropped (rounded down).
The units are in powers of two, not ten. This means 1kb = 1024b according to this parser.
**Arguments**
| Name | Type | Description |
|---------------|--------|--------------------|
| value | `string` | String to parse. |
| Name | Type | Description |
|---------------|----------|--------------------|
| value | `string` | String to parse. |
| options | `Object` | Conversion options |
| Property | Type | Description |
| -------------------- | --------------------- | ----------- |
| mode | `string`&#124;`null` | Which mode to use (see `bytes.format`) |
**Returns**
@@ -89,19 +157,73 @@ The units are in powers of two, not ten. This means 1kb = 1024b according to thi
```js
bytes('1kB');
// output: 1000
bytes('1KiB');
// output: 1024
bytes('1024');
// output: 1024
bytes('1.0001 kB');
// output: 1000
bytes('1.0001 KiB');
// output: 1024
bytes('1kB', {mode: compatibility});
// output: 1024
```
#### bytes.withDefaultMode(string mode): object
Returns a new module which acts like the `bytes` module, except with the given mode as the default.
**Arguments**
| Name | Type | Description |
|---------------|----------|--------------------|
| mode | `string` | Default mode to use |
**Returns**
| Name | Type | Description |
|---------|-------------|-------------------------|
| results | `object` | Returns the byte.js module, with a default mode |
**Example**
```js
var bytes = require('bytes').withDefaultMode('compatibility');
bytes('1kB');
// output: 1024
bytes('1KiB');
// output: 1024
bytes(1024);
// output: 1 kB
bytes(1024, {mode: 'metric'});
// output: 1.02kB
bytes('1kB', {mode: 'metric'});
// output: 1000
```
## Installation
```bash
npm install bytes --save
```
## License
## License
[![npm](https://img.shields.io/npm/l/express.svg)](https://github.com/visionmedia/bytes.js/blob/master/LICENSE)
Oops, something went wrong.
ProTip! Use n and p to navigate between commits in a pull request.