A format style that refers to a date using the most natural
phrasing based on how much time separates it from the current time.
`DateReference` adapts its output based on how far the
referenced date is from the input (which is typically the
current time). Close dates use a relative representation,
while distant dates switch to an absolute one.
```swift
// Displays "in 5 minutes", "tomorrow", "June 2019", etc.
Text(.currentDate, format: .reference(to: eventDate))
```
### Relative vs. absolute representation
The style uses a relative format ("in 2 hours", "3 days ago")
when the referenced date is within the threshold distance.
Beyond that threshold, it switches to an absolute format
("Monday, June 3", "June 2019").
The `thresholdField` parameter controls where this switch
happens. With the default value of `.day`, the style uses
the relative format as long as the date falls within
approximately one month of the reference date:
| Distance | Style | Output |
|----------|-------|--------|
| < 1 min | Relative | `now` |
| 5 min | Relative | `in 5 minutes` |
| 3 hours | Relative | `in 3 hours` |
| 1 day | Relative | `tomorrow` |
| 3 days | Relative | `3 days ago` |
| 27 days | Relative | `27 days ago` |
| > 1 month | Absolute | `Monday, June 3` |
| > 1 year | Absolute | `June 2019` |
### Controlling the absolute representation
The `maxFieldCount` parameter determines how many date
components appear in the absolute representation:
```swift
// maxFieldCount: 2 (default)
// Output for a date in a different year: "June 2019"
// maxFieldCount: 3
.reference(to: date, maxFieldCount: 3)
// Output: "June 3, 2019"
```
The style automatically removes higher-order fields that
match the reference date. For a date within the same year,
the year field is dropped, leaving room for day-level detail:
```swift
// Same year as reference date, maxFieldCount: 2
// Output: "Monday, June 3" (instead of "June 2019")
```
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 format style that refers to a comparison date
using natural language.
- Parameters:
- date: The date this format references.
- allowedFields: The units of time that may appear in the
relative representation. The style always includes the
`thresholdField` regardless of this set.
- maxFieldCount: The maximum number of fields the style
shows in the absolute representation. The style excludes
more significant fields whose value matches the reference
date, making room for less significant ones.
- thresholdField: The time unit that tells the style when
to switch from relative to absolute representation. For
example, if you provide `.minute` and the time difference
extends to hours or days, the style switches from
relative to absolute.
The next input value after the given input.
Use this function to determine if the return value provided by ``discreteInput(before:)`` is
precise enough for your use case for any input `y`:
```swift
guard let x = style.discreteInput(before: y) else {
return
}
let z = style.input(after: x) ?? y
```
If the distance between `x` and `z` is too large for the precision you require, you may want
to manually probe ``FormatStyle/format(_:)`` at a higher rate in that interval, as there is
no guarantee for what the output will be in that interval.
- Returns: The next "greater" input value that can be represented by
``FormatStyle/FormatInput`` or an underlying representation the format style uses
internally.
The next input value before the given input.
Use this function to determine if the return value provided by ``discreteInput(after:)`` is
precise enough for your use case for any input `y`:
```swift
guard let x = style.discreteInput(after: y) else {
return
}
let z = style.input(before: x) ?? y
```
If the distance between `z` and `x` is too large for the precision you require, you may want
to manually probe ``FormatStyle/format(_:)`` at a higher rate in that interval, as there is
no guarantee for what the output will be in that interval.
- Returns: The next "smalller" input value that can be represented by
``FormatStyle/FormatInput`` or an underlying representation the format style uses
internally.
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.
