public final class DynamicFormatter

Equivalent to Formatter, but supports DynamicTypes and generates a DynamicString.

See Formatter documentation for the format string syntax.

Argument index options (%s, %2$s, and %<s) are fully supported.

These are the supported conversions and options:

Non-DynamicType DynamicBool DynamicFloat DynamicInt32 DynamicString Other DynamicType
%% See Formatter Yes Yes Yes Yes Yes
%n See Formatter Yes Yes Yes Yes Yes
%s See Formatter Yes, no options Yes, no options Yes, no options Yes, no options No
%S See Formatter Yes, no options Yes, no options Yes, no options No No
%b See Formatter Yes, no options Yes, no options Yes, no options Yes, no options Yes, no options
%B See Formatter Yes, no options Yes, no options Yes, no options Yes, no options Yes, no options
%d See Formatter No Yes, width Yes, width No No
%f See Formatter No Yes, width and precision Yes, width and precision No No
... See Formatter No No No No No

NOTE 1: %f has a default precision of 6..6 in Formatter, which is different from DynamicFloat.format which defaults to 0..3. DynamicFormatter behaves like Formatter and defaults to 6..6.

NOTE 2: DynamicFormatter uses Locale.getDefault(Locale.Category.FORMAT) at the time of calling format for non-DynamicType arguments. This can change on the remote side which, would cause a mismatch between the locally-formatted arguments and the remotely-formatted arguments, unless the provider sends a newly formatted DynamicString (using a new invocation of format).

Example usage:

DynamicFormatter().format(
  "%s has walked %d steps. %1$s has also walked %.2f meters.",
  "John", PlatformHealthSources.dailySteps(), PlatformHealthSources.dailyDistanceMeters()
)
// Generates an equivalent of:
DynamicString.constant("John has walked ")
  .concat(PlatformHealthSources.dailySteps().format())
  .concat(DynamicString.constant(" steps. John has also walked "))
  .concat(
    PlatformHealthSources.dailyMeters()
      .format(FloatFormatter.Builder().setMaxFractionDigits(2).build())
  )
  .concat(DynamicString.constant(" meters."))

Summary

Public constructors

Public methods
final @NonNull DynamicBuilders.DynamicString
@RequiresSchemaVersion(major = 1, minor = 200)
format(@NonNull String format, Object args)

Generates a DynamicString with args embedded into the format, based on the syntax rules of Formatter.

Public constructors

DynamicFormatter

Added in 1.3.0-alpha03
public DynamicFormatter()

Public methods

format

Added in 1.3.0-alpha03
@RequiresSchemaVersion(major = 1, minor = 200)
public final @NonNull DynamicBuilders.DynamicString format(@NonNull String format, Object args)

Generates a DynamicString with args embedded into the format, based on the syntax rules of Formatter.

Non-DynamicType args use Formatter, whereas DynamicTypes are implemented here. Not all conversions are supported, either because of limitations of DynamicType or because of unimplemented features. Any unsupported feature will throw UnsupportedOperationException.

Throws
java.util.IllegalFormatException

if the format string contains an illegal syntax
java.util.MissingFormatArgumentException

if the argument index is does not correspond to an available argument
kotlin.UnsupportedOperationException

if the format string is allowed by Formatter, but not implemented by DynamicFormatter