diff options
Diffstat (limited to 'deps/npm/node_modules/byte-size/README.hbs')
| -rw-r--r-- | deps/npm/node_modules/byte-size/README.hbs | 136 |
1 files changed, 130 insertions, 6 deletions
diff --git a/deps/npm/node_modules/byte-size/README.hbs b/deps/npm/node_modules/byte-size/README.hbs index 8a57e4a9c7..5b677f2a98 100644 --- a/deps/npm/node_modules/byte-size/README.hbs +++ b/deps/npm/node_modules/byte-size/README.hbs @@ -1,13 +1,135 @@ -[](https://www.npmjs.org/package/byte-size) -[](https://www.npmjs.org/package/byte-size) +[](https://www.npmjs.org/package/byte-size) +[](https://www.npmjs.org/package/byte-size) +[](https://github.com/75lb/byte-size/network/dependents?dependent_type=REPOSITORY) +[](https://github.com/75lb/byte-size/network/dependents?dependent_type=PACKAGE) [](https://travis-ci.org/75lb/byte-size) -[](https://coveralls.io/github/75lb/byte-size?branch=master) -[](https://david-dm.org/75lb/byte-size) +[](https://coveralls.io/github/75lb/byte-size) [](https://github.com/feross/standard) +***Upgraders, please check the [release notes](https://github.com/75lb/byte-size/releases).*** + +# byte-size + +An isomorphic, load-anywhere function to convert a bytes value (e.g. `3456`) to a human-readable string (`'3.5 kB'`). Choose between [metric or IEC units](https://en.wikipedia.org/wiki/Gigabyte) (summarised below) or specify your own custom units. + +Value | Metric | Metric (octet) | +----- | ------------- | -------------- | +1000 | kB kilobyte | ko kilooctet | +1000^2 | MB megabyte | Mo megaoctet | +1000^3 | GB gigabyte | Go gigaoctet | +1000^4 | TB terabyte | To teraoctet | +1000^5 | PB petabyte | Po petaoctet | +1000^6 | EB exabyte | Eo exaoctet | +1000^7 | ZB zettabyte | Zo zettaoctet | +1000^8 | YB yottabyte | Yo yottaoctet | + +Value | IEC | IEC (octet) | +------ | ------------ | ------------- | +1024 | KiB kibibyte | Kio kibioctet | +1024^2 | MiB mebibyte | Mio mebioctet | +1024^3 | GiB gibibyte | Gio gibioctet | +1024^4 | TiB tebibyte | Tio tebioctet | +1024^5 | PiB pebibyte | Pio pebioctet | +1024^6 | EiB exbibyte | Eio exbioctet | +1024^7 | ZiB zebibyte | Zio zebioctet | +1024^8 | YiB yobibyte | Yio yobioctet | + +## Synopsis + +By default, `byteSize` converts the input number to a human readable string with metric units and a precision of 1. + +```js +> const byteSize = require('byte-size') + +> byteSize(1580) +{ value: '1.6', unit: 'kB', long: 'kilobytes' } +``` + +The object returned by `byteSize` defines a `toString` method therefore can be used directly in string context. + +```js +> `Filesize: ${byteSize(12400)}` +'Filesize: 12.4 kB' +``` + +Override the default `toString` behaviour by setting [`options.toStringFn`](#bytesizebytes-options--object-). + +```js +> function toStringFn () { + return `**${this.value}${this.unit}**` +} + +> `Filesize: ${byteSize(12400, { toStringFn })}` +'Filesize: **12.4kB**' +``` + +Beside the default of `metric`, there are three other built-in units available: `metric_octet`, `iec` and `iec_octet`. + +```js +> byteSize(1580, { units: 'iec' }) +{ value: '1.5', unit: 'KiB', long: 'kibibytes' } + +> byteSize(1580, { units: 'iec_octet' }) +{ value: '1.5', unit: 'Kio', long: 'kibioctets' } + +> byteSize(1580, { units: 'metric_octet' }) +{ value: '1.6', unit: 'ko', long: 'kilooctets' } +``` + +You can adjust the `precision`. + +```js +> byteSize(1580, { units: 'iec', precision: 3 }) +{ value: '1.543', unit: 'KiB', long: 'kibibytes' } + +> byteSize(1580, { units: 'iec', precision: 0 }) +{ value: '2', unit: 'KiB', long: 'kibibytes' } +``` + +Define custom units by passing an object containing one or more additional conversion tables to `options.customUnits`. In `options.units`, specify the name of a property from the `customUnits` object. + +```js +> const customUnits = { + simple: [ + { from: 0 , to: 1e3 , unit: '' }, + { from: 1e3 , to: 1e6 , unit: 'K', long: 'thousand' }, + { from: 1e6 , to: 1e9 , unit: 'Mn', long: 'million' }, + { from: 1e9 , to: 1e12, unit: 'Bn', long: 'billion' } + ] +} + +> const { value, unit } = byteSize(10000, { customUnits, units: 'simple' }) + +> `${value}${unit}` +'10.0K' +``` + +Override the built-in defaults for the duration of the process by passing an options object to `byteSize.defaultOptions()`. This results in cleaner code in cases where `byteSize` is used often with the same options. + +```js +> byteSize.defaultOptions({ + units: 'simple', + precision: 2, + customUnits: { + simple: [ + { from: 0, to: 1e3, unit: '' }, + { from: 1e3, to: 1e6, unit: 'k' }, + { from: 1e6, to: 1e9, unit: 'm' }, + { from: 1e9, to: 1e12, unit: 'bn' }, + ] + }, + toStringFn: function () { + return this.value + this.unit + } +}) + +> [2400, 16400, 3991200].map(byteSize).join(', ') +'2.40k, 16.40k, 3.99m' +``` + {{>main}} -### Load anywhere +## Load anywhere This library is compatible with Node.js, the Web and any style of module loader. It can be loaded anywhere, natively without transpilation. @@ -37,4 +159,6 @@ Old browser (adds `window.byteSize`): * * * -© 2014-18 Lloyd Brookes \<75pound@gmail.com\>. Documented by [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown). +© 2014-20 Lloyd Brookes \<75pound@gmail.com\>. + +Isomorphic test suite by [test-runner](https://github.com/test-runner-js/test-runner) and [web-runner](https://github.com/test-runner-js/web-runner). Documented by [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown). |