包详细信息

xbytes

miraclx73.5kApache-2.01.9.1

Parse bytes to human readable sizes (4747) → ('4.75 KB') and vice versa.

convert, size, bytes, bits

自述文件

ByteParser (xbytes)

NodeJS Byte Parser Parse bytes to human readable sizes (4747) → ('4.75 KB') and vice versa.

NPM Version NPM Downloads

NPM

Installing

Via [NPM][npm]:

npm install xbytes

Usage

// Node CommonJS
const xbytes = require('xbytes');
// Or Node ES6 Modules
import xbytes from 'xbytes';
// Or TypeScript
import * as xbytes from 'xbytes';

<!-- Or in the Browser -->
<script src="xbytes/dist/index.js"></script>

Examples

xbytes(4747); // '4.75 KB'
xbytes(-3946); // '-3.95 KB'
xbytes(34.724e+4); // '347.24 KB'
xbytes(32000000000); // '32.00 GB'
xbytes(21474836480, {iec: true}); // '20.00 GiB'
xbytes.parseSize('10 GB'); // 10000000
xbytes.parseSize('-50 GiB'); // -53687091200

IEC Specification*

xbytes(5242880, {iec: true}); // '5 MiB'

xbytes.parseSize('10 GiB'); // 10485760

API

xbytes(byte[, options])

Parse byte to human readable size. If byte is not a number or an number-like string, return null appropriately.

xbytes(2472946)
// << '2.47 MB'
xbytes(49392123904, {iec: true})
// << '46.00 GiB'

xbytes.parseSize(str[, config])

Parse human readable size to bytes

xbytes.parseSize('15.967 MB')
// << 15967000
xbytes.parseSize('5.97 PiB')
// << 6721622443850465

xbytes.parse(size)

Create a ByteUnitObject around the specified HybridByte

xbytes.parse('10 MiB')
// << ByteUnitObject { bytes: 10485760 }
xbytes.parse('10 MiB').add('20 MiB')
// << ByteUnitObject { bytes: 31457280 }
xbytes.parse('10 MiB').add('20 MiB').toIECBytes()
// << '30.00 MiB'

xbytes.isBytes(str)

Check if the provided string is a ByteString

xbytes.isBytes('10 MiB')
// << true
xbytes.isBytes('Hello')
// << false
xbytes.isBytes('10 iB')
// << false
xbytes.isBytes('10b')
// << true

xbytes.isUnit(str)

Check if the provided string is an UnitString

xbytes.isUnit('GB')
// << true
xbytes.isUnit('giB')
// << true
xbytes.isUnit('iB')
// << false
xbytes.isUnit('BB')
// << false

xbytes.isParsable(input)

Check if the provided argument is parsable i.e raw_bytes (number) or ByteString.

xbytes.relative(size[, options])

xbytes.relative.bits(size[, options])

Show the input size in relation to its bit format

xbytes.relative.bytes(size[, options])

Show the input size in relation to its byte format

xbytes.relative.iecBits(size[, options])

Show the input size in relation to its bit format under IEC Standards

xbytes.relative.iecBytes(size[, options])

Show the input size in relation to its bytes format under IEC Standards

xbytes.relative.size(size[, unit[, options]])

xbytes.parseString(str)

Parse a human readable byte into its components

xbytes.parseBytes(str, options)

Parse a human readable byte into its components. Extended from parseString(), but with a few extra properties. And flexibility to use parse either an integer byte value or a ByteString resulting in the same object.

xbytes.extractBytes(str)

Extract all ByteStrings within a string into an array, alternative to str.match(xbytes.byteFilter)

xbytes.createByteParser(config)

Construct a static ByteParser with predefined configurations

xbytes.createSizeParser(config)

Construct a static SizeParser with predefined configurations

xbytes.createRelativeSizer(unit[, config])

Create a RelativeSizer for converting a hybrid byte into any set unit under predefined configuration

xbytes.unitMatcher: RegExp

The raw Regular expression used in scanning all string byte units.

xbytes.genericMatcher: RegExp

The raw regular expression used in scanning all byte containing strings.

xbytes.byteFilter: RegExp

An regular expression extension of genericMatcher with the 'i' flag.

xbytes.globalByteFilter: RegExp

An regular expression extension of genericMatcher with the 'gi' flags.

UnitString: String

Supported Unit Strings

Index Prefix Decimal Bits Binary Bits ([IEC][]) Decimal Bytes Binary Bytes ([IEC][])
0 - b (Bits) b (Bits) b (Bits) b (Bits)
0 - B (Bytes) B (Bytes) B (Bytes) B (Bytes)
1 K Kb (KiloBits) Kib (KiloBits) KB (KiloBytes) KiB (KibiBytes)
2 M Mb (MegaBits) Mib (MebiBits) MB (MegaBytes) MiB (MebiBytes)
3 G Gb (GigaBits) Gib (GibiBits) GB (GigaBytes) GiB (GibiBytes)
4 T Tb (TeraBits) Tib (TebiBits) TB (TeraBytes) TiB (TebiBytes)
5 P Pb (PetaBits) Pib (PebiBits) PB (PetaBytes) PiB (PebiBytes)
6 E Eb (ExaBits) Eib (ExbiBits) EB (ExaBytes) EiB (ExbiBytes)
7 Z Zb (ZettaBits) Zib (ZebiBits) ZB (ZettaBytes) ZiB (ZebiBytes)
8 Y Yb (YottaBits) Yib (YobiBits) YB (YottaBytes) YiB (YobiBytes)

ByteString: String

A stringed byte representation. The result of a parsed byte value.

  • '5 MB'
  • '10 GiB'
  • '0.67 Tb'
  • '-50 KB'
  • '2e+15 KB'
  • '-9e-4 GB'

HybridByte: Number|ByteString

Used to identify a variable thats either a ByteString or a number

  • '47 MiB'
  • '50kb'
  • 74753
  • '105'

ByteOptions: Object

  • iec: <boolean> Whether or not to parse under the [IEC standard][IEC] i.e in terms of 1024. Default: true
  • bits: <boolean> Whether or not to convert inputed bytes to bits and parse in terms of bits [1 byte = 8 bits]. Default: false.
  • fixed: <number> Number of digits to include after decimal point. Default: 2.
  • short: <boolean> Whether or not to shorten unit String [short: 'MB', long: 'MegaBytes']. Default: true.
  • space: <boolean> Whether or not to include a white space inbetween value and unit. Default: true.
  • sticky: <boolean> Whether or not to retain unit on max unit values. e.g '1024.00 GiB' instead of '1.00 TiB'. Default: false.
  • prefixIndex: <number> The index of unit relativity [See UnitString].

ParseOptions: Object

  • iec: <boolean> Whether or not to enforce compliance to [IEC standard][IEC]s. Default: true.
  • bits: <boolean> Whether or not to parse a lower case 'b' in bit format. Default: true.

ByteParser: Function

Byte parser with predefined configuration. Result of createByteParser.

SizeParser: Function

ByteString parser with predefined configuration. Result of createSizeParser.

RelativeSizer: Function

HybridByte parser with predefined configuration. Result of createRelativeSizer.

ParsedUnit: Object

  • iec: <boolean> Whether or not the byte is represented under the [IEC standard][IEC] i.e in terms of 1024.
    • true in '7 TiB'
    • false in '3 TB'
  • type: <string> Whether the size is represented as bits(b) or bytes(B).
    • 'b' in '499Yb'
    • 'B' in '7 MB'
  • bits: <boolean> Whether or not the size is specifically represented as a bit.
    • true in 84 Yb
    • false in 278.58 KB
  • bytes: <boolean> Whether or not the size is specifically represented as a byte.
    • true in 92 EB
    • false in 28 Mb
  • unit: <UnitString> Re-parsed UnitString of inputUnit, fixing formatting.
    • 'TB' if 'TB'
    • 'Gib' if 'gib'
  • inputUnit: <UnitString> The unparsed String as was provided.
    • '47TB' in '47TB'
  • prefix: <string> The prefix of the size string.
    • 'K' in 'KB'
  • prefixIndex: <number> The index of the size unit [See UnitString].
    • 3 in 'GB'

ParsedByteString extends ParsedUnit: Object

  • input: <ByteString> The unparsed String as was provided.
    • '47TB' in '47TB'
  • value: <number> The value for the size.
    • 83 in '83MB'

ParsedBytes extends ParsedByteString: Object

  • input: <HybridByte> The unparsed String as was provided.
    • 1024 in 1024
    • '47TB' in '47TB'
  • size: <ByteString> The value for the size.
    • 83 in '83MB'
  • bytes: <number> The value for the size.
    • 10485760 from '10 MiB'

class ByteUnitObject

  • bytes: <number> Internal byte value.

Wrap a HybridByte in a chainable, transformative object.

new ByteUnitObject('10 MiB')
// << ByteUnitObject { bytes: 10485760 }
new ByteUnitObject('10 MiB').add('20 MiB')
// << ByteUnitObject { bytes: 31457280 }
new ByteUnitObject('10 MiB').add('20 MiB').toIECBytes()
// << '30.00 MiB'

ByteUnitObject().add(bytes)

Add byte(s) to the internal bytes, resulting in a new ByteUnitObject object with the value

ByteUnitObject().subtract(bytes)

Subtract byte(s) from the internal bytes, resulting in a new ByteUnitObject object with the value

ByteUnitObject().multiply(bytes)

Multiply byte(s) with the internal bytes, resulting in a new ByteUnitObject object with the value

ByteUnitObject().divide(bytes)

Divide internal bytes by byte(s) specified, resulting in a new ByteUnitObject object with the value

ByteUnitObject().convertTo(unit)

Parse the internal byte into any unit, following the relativity.

new ByteUnitObject('10 MiB')
// >> ByteUnitObject { bytes: 10485760 }
new ByteUnitObject('10 MiB').convertTo('MB')
// >> '10.49 MB'
new ByteUnitObject('10 MiB').add('50 MB').convertTo('KB')
    '60485.76 KB'

ByteUnitObject().objectify(opts)

Parse the internal bytes property to a byte object.

ByteUnitObject().checkInternalByteVal(bytes)

Method to check integrity of internal bytes. Throw if there's an error somewhere.

HybridByteRelations: Object

More Examples

Check out some examples in the examples folder

$ node examples/index.js 'Hey, its 6GB, but my 8 TB flash drive is better'
┌─────────┬──────────┬───────────┬────────┬───────────┬────────────┬────────────┬─────────────┐
│ (index) │  parsed  │   size    │  raw   │   bytes   │  iecBytes  │    bits    │   iecBits   │
├─────────┼──────────┼───────────┼────────┼───────────┼────────────┼────────────┼─────────────┤
│    0    │ [Object] │ '6.00 GB' │ '6GB'  │ '6.00 GB' │ '5.59 GiB' │ '48.00 Gb' │ '44.70 Gib' │
│    1    │ [Object] │ '8.00 TB' │ '8 TB' │ '8.00 TB' │ '7.28 TiB' │ '64.00 Tb' │ '58.21 Tib' │
└─────────┴──────────┴───────────┴────────┴───────────┴────────────┴────────────┴─────────────┘
$ node examples/parse.js 'The 10GB file was downloaded in 50MB/s'
The 10737418240 file was downloaded in 52428800/s
$ node examples/relative.js mb '10GiB, 1mb 6   gb'
85899.35 Mb, 1.00 Mb 6000.00 Mb
$ node examples/random.js 10 // Parse 10 random bytes
[tabular data]
$ node examples/extract.js 'Hey, its 6GB, but my 8 TB flash drive is better'
┌─────────┬────────┬───────────────┐
│ (index) │  size  │     bytes     │
├─────────┼────────┼───────────────┤
│    0    │ '6GB'  │  6000000000   │
│    1    │ '8 TB' │ 8000000000000 │
└─────────┴────────┴───────────────┘

Features

Compatible with all versions of NodeJS (tested from v1.8.4)

$ nvm exec v1.8.4 node -pe 'require(".")(3748587)'
"3.75 MB"
$ nvm exec v5.12.0 node -pe 'require(".").parseSize("476 TiB")'
523367534821376
$ nvm exec v11.10.0 node -e '
  let xbytes = require("./dist");
  let str = "My 10GB drive transmits at 250MiB/sec"
  console.log(str.replace(xbytes.globalByteFilter, xbytes.relative.bits))
'
"My 80.00 Gb drive transmits at 2.10 Gb/sec"

Decimal parsing

xbytes(524334545.847775856); // 524.33 MB
xbytes.parseSize('665.284 TiB'); // 731487493773328.4

xbytes(.24283884748955); // 0.24 B
xbytes.parseSize('.295 MB'); // 295000

Parse human readable sizes in binary ([IEC][]) format to bytes

xbytes.parseSize('1 MiB'); // 1048576

Parse byte values to extended human readable sizes

xbytes(50000000, {short: false}); // '50.00 MegaBytes'

Match or extract ByteStrings in a string

let data = 'My 16GB flash drive has a 4GB Zip Archive and a 5MB JavaScript file';
xbytes.extractBytes(data);
  //> [ '16GB', '4GB', '5MB' ]
data.match(xbytes.globalByteFilter)
  //> [ '16GB', '4GB', '5MB' ]
data.replace(xbytes.globalByteFilter, xbytes.parseSize)
  //> 'My 16000000000 flash drive has a 4000000000 Zip Archive and a 5000000 JavaScript file'
data.replace(xbytes.globalByteFilter, xbytes.createSizeParser({ iec: false }))
  //> 'My 17179869184 flash drive has a 4294967296 Zip Archive and a 5242880 JavaScript file'

Decimal and Binary Unit Relativity

import { parseSize, relative } from 'xbytes';

relative('35 TiB').bits // '307.86 Tb'
relative('35 TiB').bytes // '38.48 TB'
relative('35 TiB').iecBits // '280.00 Tib'
relative('35 TiB').iecBytes // '35.00 TiB'

parseSize(relative('35 TiB', {fixed: 20}).bits);
  //> 38482906972160
parseSize(relative('35 TiB', {fixed: 20}).bytes);
  //> 38482906972160
parseSize(relative('35 TiB', {fixed: 20}).iecBits);
  //> 38482906972160
parseSize(relative('35 TiB', {fixed: 20}).iecBytes);
  //> 38482906972160

Development

Building

Feel free to clone, use in adherance to the license and perhaps send pull requests

git clone https://github.com/miraclx/xbytes.git
cd xbytes
npm install
# hack on code
npm run build
npm test

Testing

Tests are executed with [Jest][jest]. To use it, simple run npm install, it will install Jest and its dependencies in your project's node_modules directory followed by npm run build and finally npm test.

To run the tests:

npm install
npm run build
npm test

License

[Apache 2.0][license] © Miraculous Owonubi (@miraclx) <omiraculous@gmail.com>

[IEC]: https://en.wikipedia.org/wiki/Units_of_information#Systematic_multiples 'International Electrotechnical Commission' [npm]: https://github.com/npm/cli 'The Node Package Manager' [jest]: https://github.com/facebook/jest 'Delightful JavaScript Testing' [license]: LICENSE 'Apache 2.0 License'