# DynamicFormatter

# 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)

*** ** * ** ***

Kotlin\|[Java](https://developer.android.com/reference/androidx/wear/protolayout/expression/util/DynamicFormatter "View this page in Java")

<br />

```
class DynamicFormatter
```

<br />

*** ** * ** ***

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

See[Formatter](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-[DynamicType](https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/DynamicBuilders.DynamicType) | [DynamicBool](https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/DynamicBuilders.DynamicBool) | [DynamicFloat](https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/DynamicBuilders.DynamicFloat) | [DynamicInt32](https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/DynamicBuilders.DynamicInt32) | [DynamicString](https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/DynamicBuilders.DynamicString) | Other[DynamicType](https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/DynamicBuilders.DynamicType) |
| %%  | See[Formatter](https://developer.android.com/reference/java/util/Formatter.html)                                                   | Yes                                                                                                                            | Yes                                                                                                                              | Yes                                                                                                                              | Yes                                                                                                                                | Yes                                                                                                                                 |
| %n  | See[Formatter](https://developer.android.com/reference/java/util/Formatter.html)                                                   | Yes                                                                                                                            | Yes                                                                                                                              | Yes                                                                                                                              | Yes                                                                                                                                | Yes                                                                                                                                 |
| %s  | See[Formatter](https://developer.android.com/reference/java/util/Formatter.html)                                                   | Yes, no options                                                                                                                | Yes, no options                                                                                                                  | Yes, no options                                                                                                                  | Yes, no options                                                                                                                    | No                                                                                                                                  |
| %S  | See[Formatter](https://developer.android.com/reference/java/util/Formatter.html)                                                   | Yes, no options                                                                                                                | Yes, no options                                                                                                                  | Yes, no options                                                                                                                  | No                                                                                                                                 | No                                                                                                                                  |
| %b  | See[Formatter](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[Formatter](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[Formatter](https://developer.android.com/reference/java/util/Formatter.html)                                                   | No                                                                                                                             | Yes, width                                                                                                                       | Yes, width                                                                                                                       | No                                                                                                                                 | No                                                                                                                                  |
| %f  | See[Formatter](https://developer.android.com/reference/java/util/Formatter.html)                                                   | No                                                                                                                             | Yes, width and precision                                                                                                         | Yes, width and precision                                                                                                         | No                                                                                                                                 | No                                                                                                                                  |
| ... | See[Formatter](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[Formatter](https://developer.android.com/reference/java/util/Formatter.html), which is different from[DynamicFloat.format](https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/DynamicBuilders.DynamicFloat#format())which defaults to 0..3.[DynamicFormatter](https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/util/DynamicFormatter)behaves like[Formatter](https://developer.android.com/reference/java/util/Formatter.html)and defaults to 6..6.

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

Example usage:  

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

|                                                                ### Public functions                                                                |
|----------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [DynamicBuilders.DynamicString](https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/DynamicBuilders.DynamicString) | `@`[RequiresSchemaVersion](https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/RequiresSchemaVersion)`(major = 1, minor = 200)` [format](https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/util/DynamicFormatter#format(kotlin.String,kotlin.Array))`(format: `[String](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)`, vararg args: `[Any](https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-any/index.html)`?)` Generates a[DynamicString](https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/DynamicBuilders.DynamicString)with[args](https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/util/DynamicFormatter#format(kotlin.String,kotlin.Array))embedded into the[format](https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/util/DynamicFormatter#format(kotlin.String,kotlin.Array)), based on the syntax rules of[Formatter](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)  

```
DynamicFormatter()
```  

## Public functions

### format

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

```
@RequiresSchemaVersion(major = 1, minor = 200)
fun format(format: String, vararg args: Any?): DynamicBuilders.DynamicString
```

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

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

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