A format style that forms locale-aware string representations of a relative date or time.
Use the strings that the format style produces, such as "1 hour ago", "in 2 weeks", "yesterday", and "tomorrow" as standalone strings. Embedding them in other strings may not be grammatically correct.
Express relative date formats in either ``Date/RelativeFormatStyle/Presentation/numeric`` or ``Date/RelativeFormatStyle/Presentation/named`` styles. For example:
```swift
if let past = Calendar.current.date(byAdding: .day, value: -7, to: Date()) {
var formatStyle = Date.RelativeFormatStyle()
formatStyle.presentation = .numeric
past.formatted(formatStyle) // "1 week ago"
formatStyle.presentation = .named
past.formatted(formatStyle) // "last week"
}
```
Use the convenient static factory method ``FormatStyle/relative(presentation:unitsStyle:)`` to shorten the syntax when applying presentation and units style modifiers to customize the format. For example:
```swift
if let past = Calendar.current.date(byAdding: .day, value: 7, to: Date()) {
past.formatted(.relative(presentation: .numeric)) // "in 1 week"
past.formatted(.relative(presentation: .named)) // "next week"
past.formatted(.relative(presentation: .named, unitsStyle: .wide)) // "next week"
past.formatted(.relative(presentation: .named, unitsStyle: .narrow)) // "next wk."
past.formatted(.relative(presentation: .named, unitsStyle: .abbreviated)) // "next wk."
past.formatted(.relative(presentation: .named, unitsStyle: .spellOut)) // "next week"
past.formatted(.relative(presentation: .numeric, unitsStyle: .wide)) // "in 1 week"
past.formatted(.relative(presentation: .numeric, unitsStyle: .narrow)) // "in 1 wk."
past.formatted(.relative(presentation: .numeric, unitsStyle: .abbreviated)) // "in 1 wk."
past.formatted(.relative(presentation: .numeric, unitsStyle: .spellOut)) // "in one week"
}
```
The ``FormatStyle/format(_:)`` instance method generates a string from the provided relative date. Once you create a style, you can use it to format relative dates multiple times.
The following example applies a format style repeatedly to produce string representations of relative dates:
```swift
if let pastWeek = Calendar.current.date(byAdding: .day, value: -7, to: Date()),
let pastDay = Calendar.current.date(byAdding: .day, value: -1, to: Date()) {
let formatStyle = Date.RelativeFormatStyle(
presentation: .named,
unitsStyle: .spellOut,
locale: Locale(identifier: "en_GB"),
calendar: Calendar.current,
capitalizationContext: .beginningOfSentence)
formatStyle.format(pastDay) // "Yesterday"
formatStyle.format(pastWeek) // "Last week"
}
```
Members (16)
get · iOS 15.0+
unitsStyle
TypeScript
get unitsStyle(): Date_RelativeFormatStyle_UnitsStyle
Swift declaration
var unitsStyle: Date.RelativeFormatStyle.UnitsStyle
The style to use when formatting the quantity or the name of the unit, such as "1 day ago" or "one day ago".
Express relative date format units in either `wide`, `narrow`,
`abbreviated`, or `spellOut` styles. For example:
```swift
if let past = Calendar.current.date(byAdding: .day, value: -14, to: Date()) {
past.formatted(.relative(presentation: .named, unitsStyle: .wide)) // "2 weeks ago"
past.formatted(.relative(presentation: .named, unitsStyle: .narrow)) // "2 wk. ago"
past.formatted(.relative(presentation: .named, unitsStyle: .abbreviated)) // "2 wk. ago"
past.formatted(.relative(presentation: .named, unitsStyle: .spellOut)) // "two weeks ago"
}
```
set · iOS 15.0+
unitsStyle
TypeScript
set unitsStyle(value: Date_RelativeFormatStyle_UnitsStyle)
Swift declaration
var unitsStyle: Date.RelativeFormatStyle.UnitsStyle
The style to use when formatting the quantity or the name of the unit, such as "1 day ago" or "one day ago".
Express relative date format units in either `wide`, `narrow`,
`abbreviated`, or `spellOut` styles. For example:
```swift
if let past = Calendar.current.date(byAdding: .day, value: -14, to: Date()) {
past.formatted(.relative(presentation: .named, unitsStyle: .wide)) // "2 weeks ago"
past.formatted(.relative(presentation: .named, unitsStyle: .narrow)) // "2 wk. ago"
past.formatted(.relative(presentation: .named, unitsStyle: .abbreviated)) // "2 wk. ago"
past.formatted(.relative(presentation: .named, unitsStyle: .spellOut)) // "two weeks ago"
}
```
Creates a relative date format style with the specified presentation, units, locale, calendar, and capitalization context.
The following example creates a format style applied to a relative
date to create a string representation.
```swift
if let past = Calendar.current.date(byAdding: .day, value: -7, to: Date()) {
let formatStyle = Date.RelativeFormatStyle(
presentation: .named,
unitsStyle: .abbreviated,
locale: Locale(identifier: "en_US"),
calendar: Calendar.current,
capitalizationContext: .beginningOfSentence)
print(past.formatted(formatStyle)) // "Last wk."
}
```
- Parameters:
- presentation: The style to use when describing a relative date, such as "1 day ago" or "yesterday".
- unitsStyle: The style to use when formatting the quantity or the name of the unit, such as "1 day ago" or "one day ago".
- locale: The locale to use when formatting the relative date.
- calendar: The calendar to use when formatting the relative date.
- capitalizationContext: The capitalization context to use when formatting the relative date.
get · iOS 15.0+
presentation
TypeScript
get presentation(): Date_RelativeFormatStyle_Presentation
Swift declaration
var presentation: Date.RelativeFormatStyle.Presentation
Specifies the style to use when describing a relative date, such as "1 day ago" or "yesterday".
Express relative date formats in either `numeric` or `named` styles.
For example:
```swift
if let past = Calendar.current.date(byAdding: .day, value: -7, to: Date()) {
var formatStyle = Date.RelativeFormatStyle()
formatStyle.presentation = .numeric
past.formatted(formatStyle) // "1 week ago"
formatStyle.presentation = .named
past.formatted(formatStyle) // "last week"
}
```
set · iOS 15.0+
presentation
TypeScript
set presentation(value: Date_RelativeFormatStyle_Presentation)
Swift declaration
var presentation: Date.RelativeFormatStyle.Presentation
Specifies the style to use when describing a relative date, such as "1 day ago" or "yesterday".
Express relative date formats in either `numeric` or `named` styles.
For example:
```swift
if let past = Calendar.current.date(byAdding: .day, value: -7, to: Date()) {
var formatStyle = Date.RelativeFormatStyle()
formatStyle.presentation = .numeric
past.formatted(formatStyle) // "1 week ago"
formatStyle.presentation = .named
past.formatted(formatStyle) // "last week"
}
```
get allowedFields(): Array<Date_ComponentsFormatStyle_Field>
Swift declaration
var allowedFields: Set<Date.RelativeFormatStyle.Field> { get set }
The fields that can be used in the formatted output.
set · iOS 18.0+
allowedFields
TypeScript
set allowedFields(value: Array<Date_ComponentsFormatStyle_Field>)
Swift declaration
var allowedFields: Set<Date.RelativeFormatStyle.Field> { get set }
The fields that can be used in the formatted output.
get · iOS 15.0+
capitalizationContext
TypeScript
get capitalizationContext(): FormatStyleCapitalizationContext
Swift declaration
var capitalizationContext: FormatStyleCapitalizationContext
The capitalization context to use when formatting the relative dates.
Setting the capitalization context to `beginningOfSentence` sets the
first word of the relative date string to upper-case. A capitalization
context set to `middleOfSentence` keeps all words in the string
lower-cased.
If you set this property to `nil`, the format style resets to using `unknown`.
set · iOS 15.0+
capitalizationContext
TypeScript
set capitalizationContext(value: FormatStyleCapitalizationContext)
Swift declaration
var capitalizationContext: FormatStyleCapitalizationContext
The capitalization context to use when formatting the relative dates.
Setting the capitalization context to `beginningOfSentence` sets the
first word of the relative date string to upper-case. A capitalization
context set to `middleOfSentence` keeps all words in the string
lower-cased.
If you set this property to `nil`, the format style resets to using `unknown`.
method · iOS 15.0+
format
TypeScript
format(destDate: globalThis.Date): string
Swift declaration
func format(_ destDate: Date) -> String
Creates a locale-aware string representation from a relative date value.
Once you create a style, you can use it to format relative dates
multiple times.
```swift
if let pastWeek = Calendar.current.date(byAdding: .day, value: -7, to: Date()),
let pastDay = Calendar.current.date(byAdding: .day, value: -1, to: Date()) {
let formatStyle = Date.RelativeFormatStyle(
presentation: .named,
unitsStyle: .spellOut,
locale: Locale(identifier: "en_GB"),
calendar: Calendar.current,
capitalizationContext: .beginningOfSentence)
formatStyle.format(pastDay) // "Yesterday"
formatStyle.format(pastWeek) // "Last week"
}
```
- Parameter destDate: The date to format.
- Returns: A string representation of the relative date.
get · iOS 15.0+
locale
TypeScript
get locale(): Locale
Swift declaration
var locale: Locale
The locale to use when formatting the relative date.
The default value is `autoupdatingCurrent`. If you set this property
to `nil`, the format style resets to using `autoupdatingCurrent`.
set · iOS 15.0+
locale
TypeScript
set locale(value: Locale)
Swift declaration
var locale: Locale
The locale to use when formatting the relative date.
The default value is `autoupdatingCurrent`. If you set this property
to `nil`, the format style resets to using `autoupdatingCurrent`.
Modifies the relative date format style to use the specified locale.
- Parameter locale: The locale to use when formatting relative dates.
- Returns: A relative date format style with the provided locale.
get · iOS 15.0+
calendar
TypeScript
get calendar(): Calendar
Swift declaration
var calendar: Calendar
The calendar to use when formatting relative dates.
Defaults to `autoupdatingCurrent`. If you set this property to `nil`,
the format style resets to using `autoupdatingCurrent`.
set · iOS 15.0+
calendar
TypeScript
set calendar(value: Calendar)
Swift declaration
var calendar: Calendar
The calendar to use when formatting relative dates.
Defaults to `autoupdatingCurrent`. If you set this property to `nil`,
the format style resets to using `autoupdatingCurrent`.
