format library

String formatting in two mini-languages over one engine: Python-style braces and printf-style conversions.

format('{:>8s} {:,d}', 'total', 1234567);  //    total 1,234,567
sprintf('%-8s %.2f', 'total', 12.5);       // total    12.50

format and formatWith read {...} placeholders, sprintf and vsprintf read %... conversions, and both dialects share the number formatting underneath. Every failure is a FormattingException carrying where in the template it happened; this hierarchy is separate from dart:core's FormatException.

The top-level functions use defaultFormat. Configure anything — a NumberLocale, a TextUnit for what width counts, a DoubleFormatMode for how double is rendered, or custom Formatters, AttributeLookups and Representations — by constructing a Format and calling the same methods on it, rather than by mutating global state.

Parsed templates are cached per isolate; templateCacheCapacity and templateCacheMemoryLimit bound that cache, and templateCacheSize with templateCacheMemory report it.

Classes

AttributeLookup<T>
A custom resolver for {value.attribute} field access.
CNumberLocale
The default locale: C-style ASCII symbols with grouping disabled for the n presentation type.
Format
An immutable formatting engine: brace and printf mini-languages under one configuration.
FormatExceptionContext
Where in a template a formatting failure happened.
FormatOptions
The parsed format specification options handed to a Formatter.
Formatter<T>
A custom formatter selected by {:name} in a brace template.
NumberLocale
Symbols and grouping rules for locale-aware number formatting.
Representation<T>
A custom !r/!a representation for values of type T.

Enums

DoubleFormatMode
Selects how decimal double values are converted to text.
DoubleSpecialValueSpelling
Selects the base spelling of non-finite double values.
TextUnit
The unit in which widths, precisions, and fills measure text.

Extensions

TextUnitOperations on TextUnit
Text measurement in terms of a TextUnit.

Properties

defaultFormat → Format
The default engine behind the top-level format, formatWith, sprintf, and vsprintf functions: C locale, Unicode scalars, Dart SDK double conversion, no custom extensions.
final
templateCacheCapacity ↔ int
How many parsed templates each mini-language keeps, 512 by default.
getter/setter pair
templateCacheMemory → int
The estimated memory resident templates hold, across both mini-languages, in the same units as templateCacheMemoryLimit.
no setter
templateCacheMemoryLimit ↔ int
How much memory the parsed templates of each mini-language may hold, eight mebibytes by default.
getter/setter pair
templateCacheSize → int
How many parsed templates are resident, across both mini-languages.
no setter

Functions

clearTemplateCache() → void
Discards every parsed template.
format(String template, [Object? value1 = _MissingValue.value, Object? value2 = _MissingValue.value, Object? value3 = _MissingValue.value, Object? value4 = _MissingValue.value, Object? value5 = _MissingValue.value, Object? value6 = _MissingValue.value, Object? value7 = _MissingValue.value, Object? value8 = _MissingValue.value, Object? value9 = _MissingValue.value, Object? value10 = _MissingValue.value]) → String
Formats template with Python-style braces and up to ten positional values.
formatWith(String template, {List<Object?> positional = const [], Map<String, Object?> named = const {}}) → String
Formats a brace template with positional and named value collections.
sprintf(String template, [Object? value1 = _MissingValue.value, Object? value2 = _MissingValue.value, Object? value3 = _MissingValue.value, Object? value4 = _MissingValue.value, Object? value5 = _MissingValue.value, Object? value6 = _MissingValue.value, Object? value7 = _MissingValue.value, Object? value8 = _MissingValue.value, Object? value9 = _MissingValue.value, Object? value10 = _MissingValue.value]) → String
Formats template with the printf mini-language and up to ten positional values.
vsprintf(String template, List<Object?> values) → String
Formats a printf template with a list of values.

Exceptions / Errors

AmbiguousFormatterException
More than one configured extension accepts the same value, so the engine cannot choose between them.
FormatConfigurationException
A Format instance was constructed with an invalid configuration, such as a reserved or duplicated custom formatter name.
FormatExtensionException
User-provided code threw during formatting: a custom formatter, lookup, representation, locale, or a value's own toString().
FormatLookupException
A .attribute or [key] step in a field access chain failed.
FormattingException
The base of every failure thrown by the formatting engine.
InvalidFormatException
The template itself does not parse: an unmatched brace, a bad field name, an unterminated or unknown printf conversion.
InvalidSpecifierException
The template parses, but a format specification is not valid: an unknown presentation type, an option that the type does not accept, or a width/precision outside the supported range.
MissingFormatArgumentException
A placeholder refers to an argument that was not supplied.
UnsupportedConversionException
A !s/!r/!a conversion (or a printf conversion) cannot be applied to the given value.
UnsupportedFormatValueException
A conversion or specification cannot render the value it was given: sprintf('%d', 1.5), sprintf('%d', 'text'), an out-of-range scalar for c, or a value no configured formatter accepts.