A format style that displays a countdown or count-up timer
within a bounded time interval.
`Timer` produces a time-pattern output (like `4:32` or
`1:23:45`) that progresses between zero and the interval's
total duration. Unlike ``SystemFormatStyle/Stopwatch``, a timer operates within
a defined start and end date and can count in either direction.
```swift
let start = Date.now
let end = start.addingTimeInterval(600)
// Countdown from 10:00 to 0:00
Text(.currentDate, format: .timer(countingDownIn: start..<end))
// Count up from 0:00 to 10:00
Text(.currentDate, format: .timer(countingUpIn: start..<end))
```
### Countdown behavior
A countdown timer starts at the total interval duration and
decreases to zero:
```swift
// 5-minute countdown
let start = Date.now
let end = start.addingTimeInterval(300)
Text(.currentDate, format: .timer(countingDownIn: start..<end))
```
| Elapsed since start | Output |
|--------------------|--------|
| 0 seconds | `5:00` |
| 1 minute | `4:00` |
| 4 min, 30 sec | `0:30` |
| 5 minutes | `0:00` |
### Count-up behavior
A count-up timer starts at zero and increases toward the total
interval duration:
```swift
// 1-hour count-up
let start = Date.now
let end = start.addingTimeInterval(3600)
Text(.currentDate, format: .timer(countingUpIn: start..<end))
```
| Elapsed since start | Output |
|--------------------|--------|
| 0 seconds | `0:00` |
| 30 seconds | `0:30` |
| 59 min, 59 sec | `59:59` |
| 1 hour | `1:00:00` |
### Hours display
When `showsHours` is `true` (the default), the hours field
appears once the displayed value reaches one hour. The
transition between formats happens cleanly:
```swift
// Countdown transition at the 1-hour boundary:
// "1:00:00" -> "59:59" -> "59:58" -> ...
```
When `showsHours` is `false`, minutes accumulate beyond 60:
```swift
.timer(countingDownIn: start..<end, showsHours: false)
// Output for 90 minutes remaining: "90:00"
```
### Precision control
The `maxPrecision` parameter determines the smallest displayed
unit:
```swift
// Default (1 second): "4:32"
.timer(countingDownIn: start..<end)
// Minute precision: shows "5 minutes", "4 minutes", etc.
.timer(countingDownIn: start..<end, maxPrecision: .seconds(60))
```
Creates a timer format style that counts up within the
interval you provide.
The timer displays the elapsed time, starting from zero
and increasing toward the total interval duration.
- Parameters:
- interval: The time interval during which the timer
counts up.
- showsHours: If `true`, hours appear as a separate
element when the elapsed time reaches one hour. If
`false`, minutes accumulate beyond 60.
- maxFieldCount: The maximum number of fields shown at
once. With the default of 3, output includes hours,
minutes, and seconds. With 2, it shows hours and
minutes once the time reaches hours.
- maxPrecision: The smallest time interval between
display updates. Defaults to 1 second.
The next discretization boundary after the given input.
Use this function to determine the next "greater" input that warrants updating the formatted output.
The following example prints all possible outputs the format style can produce upwards starting
from the `startInput`:
```swift
var previousInput = startInput
while let nextInput = style.discreteInput(after: previousInput) {
print(style.format(nextInput))
previousInput = nextInput
}
```
- Returns: For most `input`s, the method returns the "smallest" value "greater" than
`input` for which the style produces a different ``FormatStyle/FormatOutput``, or `nil`
if no such value exists. For some input values, the function may also return a value "greater" than
`input` for which the style still produces the same ``FormatStyle/FormatOutput`` as for
`input`.
The next discretization boundary before the given input.
Use this function to determine the next "smaller" input that warrants updating the formatted output.
The following example prints all possible outputs the format style can produce downwards starting
from the `startInput`:
```swift
var previousInput = startInput
while let nextInput = style.discreteInput(before: previousInput) {
print(style.format(nextInput))
previousInput = nextInput
}
```
- Returns: For most `input`s, the method returns the "greatest" value "smaller" than
`input` for which the style produces a different ``FormatStyle/FormatOutput``, or `nil`
if no such value exists. For some input values, the function may also return a value "smaller" than
`input` for which the style still produces the same ``FormatStyle/FormatOutput`` as for
`input`.
Creates a timer format style that counts down within the
interval you provide.
The timer displays the remaining time, starting from the
total interval duration and decreasing to zero.
- Parameters:
- interval: The time interval during which the timer
counts down.
- showsHours: If `true`, hours appear as a separate
element when the remaining time is at least one hour.
If `false`, minutes accumulate beyond 60.
- maxFieldCount: The maximum number of fields shown at
once. With the default of 3, output includes hours,
minutes, and seconds. With 2, it shows hours and
minutes once the time reaches hours.
- maxPrecision: The smallest time interval between
display updates. Defaults to 1 second.
Formats a value, using this style.
Use this method when you want to create a single style instance, and then use it to format
multiple values.
- Parameter value: The value to format.
- Returns: A representation of `value`, in the ``FormatOutput`` type, formatted according to
the style's configuration.
Modifies the format style to use the specified locale.
Use this format style to change the locale used by an existing format style.
- Parameter locale: The locale to apply to the format style.
- Returns: A format style modified to use the provided locale.
