formatNumber method

String formatNumber(double number, { int? decimalPlaces, int? significantDigits, int? minimumFractionDigits, int? maximumFractionDigits, bool useGrouping = true, bool displayTrailingZeros = true, bool asPercentage = false, String? forceLocale, })

Format a number using the regional settings.

Returns a formatted String representation of the number with the platform's regional settings preferences applied, including any custom settings chosen by the device user. Separator characters and grouping styles are determined by the device's locale and region settings.

If none of decimalPlaces, minimumFractionDigits, or maximumFractionDigits are specified, the number is formatted according to locale defaults.

Before using this method, ensure that getSettings has been called to load the platform settings.

If forceLocale is provided, the number will be formatted using that locale instead of the device's locale settings.

Parameters:

• number - The number to format.
• decimalPlaces - Specify an exact number of decimal places to show. If this is specified, it overrides minimumFractionDigits and maximumFractionDigits.
• significantDigits - Specify the number of significant digits.
• minimumFractionDigits - Specify minimum decimal places to show.
• maximumFractionDigits - Specify maximum decimal places to show.
• useGrouping - Separate into groups (e.g. thousands). Defaults to true.
• displayTrailingZeros - Display trailing zeros, potentially overriding minimumFractionDigits. Defaults to true.
• asPercentage - Formats the number as a percentage. Defaults to false.
• forceLocale - Optionally force a specific locale for formatting.

Implementation

String formatNumber(
  double number, {
  int? decimalPlaces,
  int? significantDigits,
  int? minimumFractionDigits,
  int? maximumFractionDigits,
  bool useGrouping = true,
  bool displayTrailingZeros = true,
  bool asPercentage = false,
  String? forceLocale,
}) {
  assert(decimalPlaces == null || decimalPlaces >= 0,
      'decimalPlaces must be a non-negative integer');
  assert(significantDigits == null || significantDigits >= 0,
      'significantDigits must be a non-negative integer');
  assert(minimumFractionDigits == null || minimumFractionDigits >= 0,
      'minimumFractionDigits must be a non-negative integer');
  assert(maximumFractionDigits == null || maximumFractionDigits >= 0,
      'maximumFractionDigits must be a non-negative integer');
  assert(
    minimumFractionDigits == null ||
        maximumFractionDigits == null ||
        minimumFractionDigits <= maximumFractionDigits,
    'minimumFractionDigits must not be greater than maximumFractionDigits',
  );

  // Ensure the number symbols are configured before we attempt to use them
  _setNumberSymbols(
      locale, icuNumberFormat, decimalSeparator, groupSeparator);

  // Allow locale override
  String numberLocale =
      (forceLocale != null && numberFormatSymbols.containsKey(forceLocale))
          ? forceLocale
          : _numberSymbolsName;

  NumberFormat formatter = NumberFormat(
    icuNumberFormat + (asPercentage ? '%' : ''),
    numberLocale,
  );
  if (decimalPlaces != null) {
    formatter.minimumFractionDigits = decimalPlaces;
    formatter.maximumFractionDigits = decimalPlaces;
  } else {
    if (minimumFractionDigits != null) {
      formatter.minimumFractionDigits = minimumFractionDigits;
    }
    if (maximumFractionDigits != null) {
      formatter.maximumFractionDigits = maximumFractionDigits;
    }
  }
  if (significantDigits != null) {
    formatter.significantDigitsInUse = true;
    formatter.significantDigits = significantDigits;
  }
  if (!displayTrailingZeros) {
    formatter.minimumFractionDigits = 0;
  }
  if (!useGrouping) {
    formatter.turnOffGrouping();
  }

  return formatter.format(number);
}