bytes-iec

(IEC) Utility to parse a string bytes to bytes and vice-versa

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
bytes-iec
403.1.13 years ago6 years agoMinified + gzip package size for bytes-iec in KB

Readme

Bytes utility
!NPM Versionnpm-imagenpm-url !NPM Downloadsdownloads-imagedownloads-url !Build Statustravis-imagetravis-url Utility to parse a size string in bytes (e.g. '1kB', '2KiB') to numeric (1000, 2048) and vice-versa.
This is a fork of the bytesbytes-url module, except it
supports all of both the binary and decimal prefixes defined by ISO/IEC 80000-13:2008binary-wiki supports JEDECjedec-wiki, a legacy mode in which metric units have binary values uses decimal metric units by default, which can be overridden per call or by default
TypeScript definitions included.

Supported Units

Supported units are as follows and are case-insensitive. Note that only the abbreviation will be parsed/formatted, the full names are for the reader's understanding only.

Metric

Also referred to as SI. See Compatibility Binary
for legacy definitions.
| Value | Abbr | Name | | ---------------- | ---- | --------- | | 1 | B | byte | | 10001 | kB | kilobyte | | 10002 | MB | megabyte | | 10003 | GB | gigabyte | | 10004 | TB | terabyte | | 10005 | PB | petabyte | | 10006 | EB | exabyte | | 10007 | ZB | zettabyte | | 10008 | YB | yottabyte |
More infometric-wiki

Binary

| Value | Abbr | Name | | ---------------- | ---- | --------- | | 1 | B | byte | | 10241 | KiB | kibibyte | | 10242 | MiB | mebibyte | | 10243 | GiB | gibibyte | | 10244 | TiB | tebibyte | | 10245 | PiB | pebibyte | | 10246 | EiB | exbibyte | | 10247 | ZiB | zebibite | | 10248 | YiB | yobibite |
More infobinary-wiki

Compatibility Binary

Also referred to as JEDEC or legacy units.
Overwrites the lower units of the metric system with the commonly misused values, i.e. metric units will be binary instead of decimal. This is the behavior of e.g. the Windows OS and bytesbytes-url. Units greater than terabyte are not supported.
| Value | Abbr | Name | | ---------------- | ---- | --------- | | 10241 | kB | kilobyte | | 10242 | MB | megabyte | | 10243 | GB | gigabyte | | 10244 | TB | terabyte |
More infojedec-wiki
Installation
This is a Node.js module available through the npm registry. Installation is done using the npm install command:
npm install bytes-iec
Usage
var bytes = require('bytes-iec');

Modes

Passing a unit type as mode parameter in API calls determines
the set of units that will be favored by autodetection when no unit is specified the value/size of metric units: Compatibility mode makes them base-2 instead of base-10
| Unit type | mode | | --------------------------------------------- | ------------------------------ | | Metric | 'metric' or 'decimal' | | Binary | 'binary' | | Compatibility Binary | 'compatibility' or 'jedec' |

bytes.format(number value, options): string|null

Format the given value in bytes into a string. If the value is negative, it's kept as such. If it's a float, it's rounded.
Arguments
| Name | Type | Description | |---------|----------|--------------------| | value | number | Value in bytes | | options | Object | Conversion options |
Options
| Property | Type | Description | Default | | ------------------ | ----------------- | --------------------------------------------------------------------------------------------- | ----------------- | | decimalPlaces | numbernull | Maximum number of decimal places to include in output | 2 | | fixedDecimals | booleannull | Whether to always display the maximum number of decimal places, i.e. preserve trailing zeroes | false | | thousandsSeparator | stringnull | What to separate large numbers with, e.g. ',', '.', ' ', ... | '' | | unit | stringnull | The unit in which the result will be returned: 'B', 'kB', 'KiB', ... | '' (autodetect) | | unitSeparator | stringnull | Separator between numeric value and unit | '' | | mode | stringnull | Which mode to use (see Modes) | 'metric' |
Returns
| Name | Type | Description | |---------|------------------|-------------------------------------------------| | results | stringnull | Returns null upon error, string value otherwise. |
Example
bytes(1000);
// output: '1kB'

bytes(1000, {thousandsSeparator: ' '});
// output: '1 000B'

bytes(1024);
// output: '1.02kB'

bytes(1024 * 1.7, {decimalPlaces: 0});
// output: '2KB'

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|number value): number|null

Parse the string value into an integer in bytes. If no unit is given, or value is a number, it is assumed the value is in bytes.
If the value given has partial bytes, it's truncated (rounded down).
Arguments
| Name | Type | Description | |---------------|--------|--------------------| | value | stringnumber | String to parse, or number in bytes | | options | Object | Conversion options |
| Property | Type | Description | Default | | -------------------- | --------------------- | ----------- |---------| | mode | stringnull | Which mode to use (see Modes) | 'metric' |
Returns
| Name | Type | Description | |---------|-------------|-------------------------| | results | numbernull | Returns null upon error, value in bytes otherwise. |
Example
bytes('1kB');
// output: 1024

bytes('1024');
// output: 1024

bytes('1.0001 kB');
// output: 1000
bytes('1.0001 KiB');
// output: 1024

bytes('1kB', {mode: 'jedec'});
// output: 1024

bytes.withDefaultMode(string mode): object

Returns a new copy of the bytes-iec module, but with the given mode as the default.
Arguments
| Name | Type | Description | |---------------|----------|--------------------| | mode | string | Default mode to use (see Modes) |
Returns
| Name | Type | Description | |---------|-------------|-------------------------| | results | object | Returns the byte.js module, with a default mode. |
Example
var bytes = require('bytes').withDefaultMode('jedec');

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
License
MIT