SystemFormatStyle.DateReference
A format style that refers to a date using the most natural phrasing based on how much time separates it from the current time.
Declaration
struct DateReferenceOverview
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.
// 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 |
|
5 min | Relative |
|
3 hours | Relative |
|
1 day | Relative |
|
3 days | Relative |
|
27 days | Relative |
|
> 1 month | Absolute |
|
> 1 year | Absolute |
|
Controlling the absolute representation
The maxFieldCount parameter determines how many date components appear in the absolute representation:
// 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:
// Same year as reference date, maxFieldCount: 2
// Output: "Monday, June 3" (instead of "June 2019")