Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/vxern/human_file_size
📏 Get a human representation of the size of your files.
https://github.com/vxern/human_file_size
binary bytes converter customizable dart decimal display file file-size flutter formatter string utility
Last synced: about 1 month ago
JSON representation
📏 Get a human representation of the size of your files.
- Host: GitHub
- URL: https://github.com/vxern/human_file_size
- Owner: vxern
- License: mit
- Created: 2024-08-28T20:32:38.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2024-11-23T14:24:43.000Z (about 2 months ago)
- Last Synced: 2024-12-01T04:38:47.951Z (about 1 month ago)
- Topics: binary, bytes, converter, customizable, dart, decimal, display, file, file-size, flutter, formatter, string, utility
- Language: Dart
- Homepage: https://pub.dev/packages/human_file_size
- Size: 143 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
## A robust, customisable package to get a human representation of the size of your files.
### Usage
`human_file_size` exposes a function `humanFileSize()` and extension method `num.humanFileSize()`.
The most basic usage is as follows:
```dart
// 0 bytes, shown in bits
humanFileSize(0); // 0 b
// Less than one byte
humanFileSize(0.75); // 6 b
// 8 bytes
humanFileSize(8); // 8 B
// 1.2 kilobytes in bytes
humanFileSize(1000 * 1.2); // 1.2 KB
// 3 gigabytes in bytes
humanFileSize(1000 * 1000 * 1000 * 3); // 3 GB
```
Or, using the extension method:
```dart
10.humanFileSize(); // 10 B
51.22.humanFileSize(); // 51.22 B
1234.humanFileSize(); // 1.234 KB
```
By default, `humanFileSize()` takes the size to be in bytes (`inputUnit: Unit.byte`). You may specify otherwise by passing a different value for `inputUnit`:
```dart
// 1000 bytes -> 1 kilobyte
humanFileSize(1000); // 1 KB
// 1 kilobit in bits
humanFileSize(1000, inputUnit: Unit.bit); // 1 Kb
// 1 megabit in kilobits
humanFileSize(1000, inputUnit: Unit.kilobit); // 1 Mb
```
The library provides decimal and binary units starting at bit and byte, then following through prefixes kilo-, mega-, giga-, tera-, peta-, exa-, zeta- and yotta-. Custom units are supported.
By default, `humanFileSize()` converts to the largest unit possible (`unitConversion: const BestFitUnitConversion()`). You may specify otherwise by passing a different value for `unitConversion`:
```dart
// 1000 bytes -> 1 kilobyte
humanFileSize(1000); // 1 Kb
// 1000 bytes -> 8000 bits
humanFileSize(
1000,
unitConversion: SpecificUnitConversion(unit: Unit.bit),
); // 8000 b
```
By default, `humanFileSize()` uses a simple strategy to format the quantity (`quantityDisplayMode: const SimpleQuantityDisplayMode()`). You may specify otherwise by passing a different value to `quantityDisplayMode`:
```dart
// `SimpleQuantityDisplayMode` is the default mode.
humanFileSize(1); // 1 B
// `IntlQuantityDisplayMode` can be used for localisation.
humanFileSize(
1.234,
quantityDisplayMode: IntlQuantityDisplayMode(
numberFormat: NumberFormat.decimalPattern('pl'),
),
); // 1,234 B
```
You may also specify the numeral system used when using `BestFitUnitConversion()`. The library has two built-in numeral systems: decimal and binary. To set the numeral system, pass a `numeralSystem` into `BestFitUnitConversion()`:
```dart
// 1024 bytes -> 1 kibibyte
humanFileSize(
1024,
unitConversion: const BestFitUnitConversion(
numeralSystem: BinaryNumeralSystem(),
),
); // 1 KiB
```
By default, `humanFileSize()` converts to the short, uppercase style (`unitStyle: const ShortUppercaseUnitStyle()`). You may specify otherwise by passing a different value to `unitStyle`:
```dart
humanFileSize(1, inputUnit: Unit.gigabit); // Gb
humanFileSize(
1,
inputUnit: Unit.gigabit,
unitStyle: const ShortLowercaseUnitStyle(),
); // gb
humanFileSize(
1,
inputUnit: Unit.gigabit,
unitStyle: const LongLowercaseUnitStyle(),
); // gbit
humanFileSize(
1,
inputUnit: Unit.gigabit,
unitStyle: const LongUppercaseUnitStyle(),
); // Gbit
```
To specify the method by which to obtain the output format, provide a value for `outputFormatter`. By default, the output format will be `{quantity} {unit}`.
```dart
humanFileSize(1); // 1 B
humanFileSize(
1,
outputFormatter: const SimpleOutputFormatter(includeSpace: false),
); // 1B
humanFileSize(
1,
outputFormatter: const SimpleOutputFormatter(unitFirst: true),
); // B 1
```
The library is resilient to funky quantities being passed in, with the output unit always being the given `inputUnit`:
```dart
// Negative sizes
humanFileSize(1000 * -2); // -2 KB
// Infinity
humanFileSize(double.infinity, inputUnit: Unit.gigabyte); // ∞ GB
// Negative infinity
humanFileSize(double.negativeInfinity, inputUnit: Unit.kilobit); // -∞ Kb
// NaN
humanFileSize(double.nan, inputUnit: Unit.exabit); // NaN Eb
```
You can perform size comparisons:
```dart
final byteCount = BigInt.from(50);
byteCount >= Unit.kilobit.bytes; // false
byteCount >= Unit.bit.bytes; // true
```
For more information, have a browse through the exposed symbols and through the documentation on each of them.