# DynamicDateFormat

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/DynamicDateFormat.kt+class:androidx.wear.protolayout.expression.util.DynamicDateFormat) Added in [1.3.0](https://developer.android.com/jetpack/androidx/releases/wear-protolayout#1.3.0)

*** ** * ** ***

<br />

```
@RequiresSchemaVersion(major = 1, minor = 300)
class DynamicDateFormat
```

<br />

*** ** * ** ***

Equivalent to `https://developer.android.com/reference/android/icu/text/SimpleDateFormat.html`, but generates a `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/DynamicBuilders.DynamicString` based on a `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/DynamicBuilders.DynamicInstant`.

See `https://developer.android.com/reference/android/icu/text/SimpleDateFormat.html` documentation for the pattern syntax.

Literal patterns are fully supported, including quotes (`'`) or non-letters (e.g. `:`).

Currently this implementation only supports hour (`HKhk`), minute (`m`), and AM/PM (`a`) patterns. Every other letter will throw `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-argument-exception/index.html`.

NOTE: `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/util/DynamicDateFormat` uses `Locale.getDefault(Locale.Category.FORMAT)` at the time of calling `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/util/DynamicDateFormat#format(androidx.wear.protolayout.expression.DynamicBuilders.DynamicInstant)` for AM/PM markers. This can change on the remote side, which would cause a mismatch between the locally-formatted AM/PM and the remotely-formatted numbers, unless the provider sends a newly formatted `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/DynamicBuilders.DynamicString` (using a new invocation of `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/util/DynamicDateFormat#format(androidx.wear.protolayout.expression.DynamicBuilders.DynamicInstant)`).

Example usage:

```kotlin
// This statement:
DynamicDateFormat(pattern = "HH:mm", timeZone = zone).format(dynamicInstant)
// Generates an equivalent of:
dynamicInstant
  .getHour(zone)
  .format(DynamicInt32.IntFormatter.Builder().setMinIntegerDigits(2).build())
  .concat(DynamicString.constant(":"))
  .concat(
    dynamicInstant.getMinute(zone)
      .format(DynamicInt32.IntFormatter.Builder().setMinIntegerDigits(2).build())
  )
```

## Summary

| ### Public constructors |
|---|
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/util/DynamicDateFormat#DynamicDateFormat(kotlin.String,java.time.ZoneId)(pattern: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, timeZone: https://developer.android.com/reference/java/time/ZoneId.html)` Constructs a `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/util/DynamicDateFormat`. |

| ### Public functions |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/DynamicBuilders.DynamicString` | `@https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/RequiresSchemaVersion(major = 1, minor = 300) https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/util/DynamicDateFormat#format(androidx.wear.protolayout.expression.DynamicBuilders.DynamicInstant)(instant: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/DynamicBuilders.DynamicInstant)` Formats the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/DynamicBuilders.DynamicInstant` into a date/time `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/DynamicBuilders.DynamicString`. |

| ### Public properties |
|---|---|
| `https://developer.android.com/reference/java/time/ZoneId.html` | `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/util/DynamicDateFormat#timeZone()` The time zone used when extracting time parts from the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/DynamicBuilders.DynamicInstant` provided to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/util/DynamicDateFormat#format(androidx.wear.protolayout.expression.DynamicBuilders.DynamicInstant)`, defaults to `https://developer.android.com/reference/java/time/ZoneId.html#systemDefault()`. |

## Public constructors

### DynamicDateFormat

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

```
DynamicDateFormat(
    pattern: String,
    timeZone: ZoneId = ZoneId.systemDefault()
)
```

Constructs a `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/util/DynamicDateFormat`.

| Parameters |
|---|---|
| `pattern: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | The pattern to use when calling `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/util/DynamicDateFormat#format(androidx.wear.protolayout.expression.DynamicBuilders.DynamicInstant)`, see `https://developer.android.com/reference/android/icu/text/SimpleDateFormat.html` for general syntax and `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/util/DynamicDateFormat` for the supported subset of features. |
| `timeZone: https://developer.android.com/reference/java/time/ZoneId.html = ZoneId.systemDefault()` | The time zone used when extracting time parts from the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/DynamicBuilders.DynamicInstant` provided to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/util/DynamicDateFormat#format(androidx.wear.protolayout.expression.DynamicBuilders.DynamicInstant)`, defaults to `https://developer.android.com/reference/java/time/ZoneId.html#systemDefault()`. |

## Public functions

### format

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

```
@RequiresSchemaVersion(major = 1, minor = 300)
fun format(
    instant: DynamicBuilders.DynamicInstant = DynamicInstant.platformTimeWithSecondsPrecision()
): DynamicBuilders.DynamicString
```

Formats the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/DynamicBuilders.DynamicInstant` into a date/time `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/DynamicBuilders.DynamicString`.

| Parameters |
|---|---|
| `instant: https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/DynamicBuilders.DynamicInstant = DynamicInstant.platformTimeWithSecondsPrecision()` | The `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/DynamicBuilders.DynamicInstant` to format, defaults to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/DynamicBuilders.DynamicInstant#platformTimeWithSecondsPrecision()`. |

## Public properties

### timeZone

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

```
var timeZone: ZoneId
```

The time zone used when extracting time parts from the `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/DynamicBuilders.DynamicInstant` provided to `https://developer.android.com/reference/kotlin/androidx/wear/protolayout/expression/util/DynamicDateFormat#format(androidx.wear.protolayout.expression.DynamicBuilders.DynamicInstant)`, defaults to `https://developer.android.com/reference/java/time/ZoneId.html#systemDefault()`.