A format style that displays elapsed time as a precision
stopwatch counting up from zero.
`Stopwatch` produces output in a time-pattern format that
includes hundredths of a second by default, making it suitable
for use cases such as athletic timing where sub-second
precision matters.
```swift
let startDate = Date.now
Text(.currentDate, format: .stopwatch(startingAt: startDate))
// Output: "00:05.23" (after 5.23 seconds)
```
### Output format progression
The stopwatch automatically adds an hours field when the
elapsed time reaches one hour:
| Elapsed | Output |
|---------|--------|
| Under 1 min | `00:05.23` |
| Under 1 hour | `45:30.12` |
| 1 hour or more | `01:00:00.00` |
| Over 25 hours | `25:01:01.00` |
### Adjusting precision
Control the displayed precision with the `maxPrecision`
parameter:
```swift
// Whole-second precision (no fractional digits)
.stopwatch(startingAt: start, maxPrecision: .seconds(1))
// Output: "01:23"
// Tenth-of-a-second precision (one fractional digit)
.stopwatch(startingAt: start, maxPrecision: .milliseconds(100))
// Output: "01:23.4"
// Minute-only precision
.stopwatch(startingAt: start, maxPrecision: .seconds(60))
// Output: "1 hour" or "23 minutes"
```
### Controlling field count
The `maxFieldCount` parameter limits how many fields appear:
```swift
// At 1 hour, 23 minutes, 45.67 seconds elapsed:
// maxFieldCount: 4 (default): "01:23:45.67"
// maxFieldCount: 3: "01:23:45"
// maxFieldCount: 2: "1:23" (hours and minutes only)
```
Creates a stopwatch format style that starts counting up
from zero from the date you provide.
- Parameters:
- startDate: The date at which the stopwatch starts
counting. Any input date before this shows `00:00.00`.
- showsHours: If `true`, the stopwatch shows hours as a
separate element once the elapsed time reaches one
hour. If `false`, minutes accumulate beyond 60 (for
example, `75:30.00`).
- maxFieldCount: The maximum number of fields shown at
once. With the default of 4, output includes hours,
minutes, seconds, and hundredths. Reducing this value
removes fields starting from the least significant.
- maxPrecision: The smallest time interval between
display updates. Defaults to 10 milliseconds (two
fractional digits).
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`.
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.
