# DynamicFormatter

Artifact: [androidx.wear.protolayout:protolayout-expression](https://developer.android.com/jetpack/androidx/releases/wear-protolayout) [View Source](https://cs.android.com/search?q=file:androidx/wear/protolayout/expression/util/DynamicFormatter.kt+class:androidx.wear.protolayout.expression.util.DynamicFormatter) Added in [1.3.0](https://developer.android.com/jetpack/androidx/releases/wear-protolayout#1.3.0)

*** ** * ** ***


```
public final class DynamicFormatter
```

<br />

*** ** * ** ***

Equivalent to `https://developer.android.com/reference/java/util/Formatter.html`, but supports `https://developer.android.com/reference/androidx/wear/protolayout/expression/DynamicBuilders.DynamicType`s and generates a `https://developer.android.com/reference/androidx/wear/protolayout/expression/DynamicBuilders.DynamicString`.

See `https://developer.android.com/reference/java/util/Formatter.html` 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-`https://developer.android.com/reference/androidx/wear/protolayout/expression/DynamicBuilders.DynamicType` | `https://developer.android.com/reference/androidx/wear/protolayout/expression/DynamicBuilders.DynamicBool` | `https://developer.android.com/reference/androidx/wear/protolayout/expression/DynamicBuilders.DynamicFloat` | `https://developer.android.com/reference/androidx/wear/protolayout/expression/DynamicBuilders.DynamicInt32` | `https://developer.android.com/reference/androidx/wear/protolayout/expression/DynamicBuilders.DynamicString` | Other `https://developer.android.com/reference/androidx/wear/protolayout/expression/DynamicBuilders.DynamicType` |
| %% | See `https://developer.android.com/reference/java/util/Formatter.html` | Yes | Yes | Yes | Yes | Yes |
| %n | See `https://developer.android.com/reference/java/util/Formatter.html` | Yes | Yes | Yes | Yes | Yes |
| %s | See `https://developer.android.com/reference/java/util/Formatter.html` | Yes, no options | Yes, no options | Yes, no options | Yes, no options | No |
| %S | See `https://developer.android.com/reference/java/util/Formatter.html` | Yes, no options | Yes, no options | Yes, no options | No | No |
| %b | See `https://developer.android.com/reference/java/util/Formatter.html` | Yes, no options | Yes, no options | Yes, no options | Yes, no options | Yes, no options |
| %B | See `https://developer.android.com/reference/java/util/Formatter.html` | Yes, no options | Yes, no options | Yes, no options | Yes, no options | Yes, no options |
| %d | See `https://developer.android.com/reference/java/util/Formatter.html` | No | Yes, width | Yes, width | No | No |
| %f | See `https://developer.android.com/reference/java/util/Formatter.html` | No | Yes, width and precision | Yes, width and precision | No | No |
| ... | See `https://developer.android.com/reference/java/util/Formatter.html` | No | No | No | No | No |

NOTE 1: `%f` has a default precision of 6..6 in `https://developer.android.com/reference/java/util/Formatter.html`, which is different from `https://developer.android.com/reference/androidx/wear/protolayout/expression/DynamicBuilders.DynamicFloat#format()` which defaults to 0..3. `https://developer.android.com/reference/androidx/wear/protolayout/expression/util/DynamicFormatter` behaves like `https://developer.android.com/reference/java/util/Formatter.html` and defaults to 6..6.

NOTE 2: `https://developer.android.com/reference/androidx/wear/protolayout/expression/util/DynamicFormatter` uses `Locale.getDefault(Locale.Category.FORMAT)` at the time of calling `https://developer.android.com/reference/androidx/wear/protolayout/expression/util/DynamicFormatter#format(kotlin.String,kotlin.Array)` for non-`https://developer.android.com/reference/androidx/wear/protolayout/expression/DynamicBuilders.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 `https://developer.android.com/reference/androidx/wear/protolayout/expression/DynamicBuilders.DynamicString` (using a new invocation of `https://developer.android.com/reference/androidx/wear/protolayout/expression/util/DynamicFormatter#format(kotlin.String,kotlin.Array)`).

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 |
|---|
| `https://developer.android.com/reference/androidx/wear/protolayout/expression/util/DynamicFormatter#DynamicFormatter()()` |

| ### Public methods |
|---|---|
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/wear/protolayout/expression/DynamicBuilders.DynamicString` | `@https://developer.android.com/reference/androidx/wear/protolayout/expression/RequiresSchemaVersion(major = 1, minor = 200) https://developer.android.com/reference/androidx/wear/protolayout/expression/util/DynamicFormatter#format(kotlin.String,kotlin.Array)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html format, https://developer.android.com/reference/java/lang/Object.html... args)` Generates a `https://developer.android.com/reference/androidx/wear/protolayout/expression/DynamicBuilders.DynamicString` with `https://developer.android.com/reference/androidx/wear/protolayout/expression/util/DynamicFormatter#format(kotlin.String,kotlin.Array)` embedded into the `https://developer.android.com/reference/androidx/wear/protolayout/expression/util/DynamicFormatter#format(kotlin.String,kotlin.Array)`, based on the syntax rules of `https://developer.android.com/reference/java/util/Formatter.html`. |

## Public constructors

### DynamicFormatter

Added in [1.3.0](https://developer.android.com/jetpack/androidx/releases/wear-protolayout#1.3.0)

```
public DynamicFormatter()
```

## Public methods

### format

Added in [1.3.0](https://developer.android.com/jetpack/androidx/releases/wear-protolayout#1.3.0)

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

Generates a `https://developer.android.com/reference/androidx/wear/protolayout/expression/DynamicBuilders.DynamicString` with `https://developer.android.com/reference/androidx/wear/protolayout/expression/util/DynamicFormatter#format(kotlin.String,kotlin.Array)` embedded into the `https://developer.android.com/reference/androidx/wear/protolayout/expression/util/DynamicFormatter#format(kotlin.String,kotlin.Array)`, based on the syntax rules of `https://developer.android.com/reference/java/util/Formatter.html`.

Non-`https://developer.android.com/reference/androidx/wear/protolayout/expression/DynamicBuilders.DynamicType` args use `https://developer.android.com/reference/java/util/Formatter.html`, whereas `https://developer.android.com/reference/androidx/wear/protolayout/expression/DynamicBuilders.DynamicType`s are implemented here. Not all conversions are supported, either because of limitations of `https://developer.android.com/reference/androidx/wear/protolayout/expression/DynamicBuilders.DynamicType` or because of unimplemented features. Any unsupported feature will throw `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unsupported-operation-exception/index.html`.

| Throws |
|---|---|
| `https://developer.android.com/reference/java/util/IllegalFormatException.html` | if the format string contains an illegal syntax |
| `https://developer.android.com/reference/java/util/MissingFormatArgumentException.html` | if the argument index is does not correspond to an available argument |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unsupported-operation-exception/index.html` | if the format string is allowed by `https://developer.android.com/reference/java/util/Formatter.html`, but not implemented by `https://developer.android.com/reference/androidx/wear/protolayout/expression/util/DynamicFormatter` |