format function

String format(num amount, { String locale = 'en', String formatString = defaultFormatString, String separator = defaultSeparator, AmountToString? customAmountTransformer, int minDecimals = 0, int maxDecimals = 2, int maxPrecision = -1, Unit unit = Unit.auto, UnitType unitType = UnitType.binary, })

Formats a byte amount as human readable string.

The only required parameter is amount, which is a number describing a amount of bytes. That amount is then formatted with appropriate binary Unit as determined by Unit.bestFor. If one prefers one can get a decimal based result by providing UnitType.decimal as the unitType parameter.

String output = format(3 * pow(1024, 3)) // 3 GiB

Simplest way to localize the output is to provide the function with the locale parameter. Currently supported locales are en, fi and ru.

String output = format(3 * pow(1024, 3), locale: 'ru') // 3 ГиБ

Output precision can be controlled with the parameters minDecimals, maxDecimals and maxPrecision which will be passed on to createPrecisionFormatter.

String output = format(1024, minDecimals: 1) // 1,0 KiB

To use a specific unit instead of automatically determined one, you can provide the wanted unit as the unit parameter.

String output = format(1024, unit: Unit.byte) // 1024 B

Custom formatting

It is also possible to define the formatting manually with formatString, separator and customAmountTransformer. formatString can contain the following placeholders %amount, %sep and %unit. separator overrides the default separator character used between the amount and the unit.

String output = format(1024,
  formatString: '%unit%sep%amount',
  separator: '__') // KiB__1

Providing a customAmountTransformer will override the default createPrecisionFormatter number to string transformer function.

String output = format(12.345e67,
  customAmountTransformer: (amount) { amount.toString() },
  unit: Unit.byte
) // 1.2345e+68 B

Custom unit can be used by providing a format string with the %unit placeholder hard coded in. In addition a custom Unit can be provided as the unit parameter.

String output = format(1024,
  formatString: '%amount half-KiB',
  unit: Unit('half-kibibyte', 512, UnitType.binary)) // 2 half-KiB

Will throw ArgumentError if any of the provided parameters is null, customAmountTransformer is a an exception and it can be and does default to null.

Implementation

String format(num amount,
    {String locale = 'en',
    String formatString = defaultFormatString,
    String separator = defaultSeparator,
    AmountToString? customAmountTransformer,
    int minDecimals = 0,
    int maxDecimals = 2,
    int maxPrecision = -1,
    Unit unit = Unit.auto,
    UnitType unitType = UnitType.binary}) {
  return _formatSafeParams(
      amount,
      locale,
      formatString,
      separator,
      customAmountTransformer,
      minDecimals,
      maxDecimals,
      maxPrecision,
      unit,
      unitType);
}