<!--
{
  "availability" : [
    "iOS: 15.0.0 -",
    "iPadOS: 15.0.0 -",
    "macCatalyst: 15.0.0 -",
    "macOS: 12.0.0 -",
    "tvOS: 15.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 8.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Foundation",
  "identifier" : "/documentation/Foundation/Date/FormatStyle",
  "metadataVersion" : "0.1.0",
  "role" : "Structure",
  "symbol" : {
    "kind" : "Structure",
    "modules" : [
      "Foundation"
    ],
    "preciseIdentifier" : "s:10Foundation4DateV11FormatStyleV"
  },
  "title" : "Date.FormatStyle"
}
-->

# Date.FormatStyle

A structure that creates a locale-appropriate string representation of a date instance and converts strings of dates and times into date instances.

```
struct FormatStyle
```

## Overview

A date format style shares the date and time formatting pattern preferred by the user’s locale for formatting and parsing.

When you want to apply a specific formatting style to a single [`Date`](/documentation/Foundation/Date) instance, use [`Date.FormatStyle`](/documentation/Foundation/Date/FormatStyle). For other instances, use the following:

- When working with date representations in ISO 8601 format, use [`Date.ISO8601FormatStyle`](/documentation/Foundation/Date/ISO8601FormatStyle).
- To represent an interval between two date instances, use [`Date.RelativeFormatStyle`](/documentation/Foundation/Date/RelativeFormatStyle).
- To represent two dates as a pair, for example to get output that looks like `10/21/1985 1:45 PM - 9/13/2015 6:33 PM`, use [`Date.IntervalFormatStyle`](/documentation/Foundation/Date/IntervalFormatStyle).

### Formatting String Representations of Dates and Times

[`Date.FormatStyle`](/documentation/Foundation/Date/FormatStyle) provides a variety of localized presets and configuration options to create user-visible representations of dates and times from instances of [`Date`](/documentation/Foundation/Date).

When displaying a date to a user, use the [`formatted(date:time:)`](/documentation/Foundation/Date/formatted(date:time:)) instance method. Set the date and time styles of the date format style separately, according to your particular needs.

For example, to create a string with a full date and no time representation, set the [`Date.FormatStyle.DateStyle`](/documentation/Foundation/Date/FormatStyle/DateStyle) to [`complete`](/documentation/Foundation/Date/FormatStyle/DateStyle/complete) and the [`Date.FormatStyle.TimeStyle`](/documentation/Foundation/Date/FormatStyle/TimeStyle) to [`omitted`](/documentation/Foundation/Date/FormatStyle/TimeStyle/omitted). Conversely, to create a string representing only the time for the current locale and time zone, set the date style to [`omitted`](/documentation/Foundation/Date/FormatStyle/DateStyle/omitted) and the time style to [`complete`](/documentation/Foundation/Date/FormatStyle/TimeStyle/complete), as the following code illustrates:

```swift
let birthday = Date()

birthday.formatted(date: .complete, time: .omitted) // Sunday, January 17, 2021
birthday.formatted(date: .omitted, time: .complete) // 4:03:12 p.m. CST
```

The results shown are for locale set to `en_US` and time zone set to `CST`.

You can create string representations of a [`Date`](/documentation/Foundation/Date) instance with various levels of brevity using preset date and time styles. The following example shows date styles of [`long`](/documentation/Foundation/Date/FormatStyle/DateStyle/long), [`abbreviated`](/documentation/Foundation/Date/FormatStyle/DateStyle/abbreviated), and [`numeric`](/documentation/Foundation/Date/FormatStyle/DateStyle/numeric), and time styles of [`shortened`](/documentation/Foundation/Date/FormatStyle/TimeStyle/shortened), [`standard`](/documentation/Foundation/Date/FormatStyle/TimeStyle/standard), and [`complete`](/documentation/Foundation/Date/FormatStyle/TimeStyle/complete):

```swift
let birthday = Date()

birthday.formatted(date: .long, time: .shortened) // January 17, 2021, 4:03 PM
birthday.formatted(date: .abbreviated, time: .standard) // Jan 17, 2021, 4:03:12 PM
birthday.formatted(date: .numeric, time: .complete) // 1/17/2021, 4:03:12 PM CST

birthday.formatted() // Jan 17, 2021, 4:03 PM
```

The default date style is [`abbreviated`](/documentation/Foundation/Date/FormatStyle/DateStyle/abbreviated) and the default time style is [`shortened`](/documentation/Foundation/Date/FormatStyle/TimeStyle/shortened).

For full customization of the string representation of a date, use the [`formatted(_:)`](/documentation/Foundation/Date/formatted(_:)) instance method of [`Date`](/documentation/Foundation/Date) and provide a [`Date.FormatStyle`](/documentation/Foundation/Date/FormatStyle) instance.

You can apply more customization of the date and time components and their representation in your app by appying a series of convenience modifiers to your format style. The following example applies a series of modifiers to the format style to precisely define the formatting of the year, month, day, hour, minute, and timezone components of the resulting string. The ordering of the date and time modifiers has no impact on the string produced.

```swift
// Call the .formatted method on an instance of Date passing in an instance of Date.FormatStyle.

let birthday = Date()

birthday.formatted(
    Date.FormatStyle()
        .year(.defaultDigits)
        .month(.abbreviated)
        .day(.twoDigits)
        .hour(.defaultDigits(amPM: .abbreviated))
        .minute(.twoDigits)
        .timeZone(.identifier(.long))
        .era(.wide)
        .dayOfYear(.defaultDigits)
        .weekday(.abbreviated)
        .week(.defaultDigits)
) 
// Sun, Jan 17, 2021 Anno Domini (week: 4), 11:18 AM America/Chicago
```

[`Date.FormatStyle`](/documentation/Foundation/Date/FormatStyle) provides a convenient factory variable, [`dateTime`](/documentation/Foundation/FormatStyle/dateTime), used to shorten the syntax when applying date and time modifiers to customize the format, as in the following example:

```swift
let localeArray = ["en_US", "sv_SE", "en_GB", "th_TH", "fr_BE"]
for localeID in localeArray {
    print(meetingDate.formatted(.dateTime
             .day(.twoDigits)
             .month(.wide)
             .weekday(.short)
             .hour(.conversationalTwoDigits(amPM: .wide))
             .locale(Locale(identifier: localeID))))
}

// Th, November 12, 7 PM
// to 12 november 19
// Th 12 November, 19
// พฤ. 12 พฤศจิกายน 19
// je 12 novembre, 19 h
```

### Parsing Dates and Times

To parse a [`Date`](/documentation/Foundation/Date) instance from an input string, use a date parse strategy. For example:

```swift
let inputString = "Archive for month 8, archived on day 23 - complete."
let strategy = Date.ParseStrategy(format: "Archive for month \(month: .defaultDigits), archived on day \(day: .twoDigits) - complete.", locale: Locale(identifier: "en_US"), timeZone: TimeZone(abbreviation: "CDT")!)
if let date = try? Date(inputString, strategy: strategy) {
   print(date.formatted()) // "Aug 23, 2000 at 12:00 AM"
}
```

The time defaults to midnight local time unless explicitly defined.

The parse instance method attempts to parse a provided string into an instance of date using the source date format style. The function throws an error if it can’t parse the input string into a date instance.

You can use [`Date.FormatStyle`](/documentation/Foundation/Date/FormatStyle) for round-trip formatting and parsing in a locale-aware manner. This date format style guides parsing the date instance from an input string, as the following code demonstrates:

```swift
let birthdayFormatStyle = Date.FormatStyle()
    .year(.defaultDigits)
    .month(.abbreviated)
    .day(.twoDigits)
    .hour(.defaultDigits(amPM: .abbreviated))
    .minute(.twoDigits)
    .timeZone(.identifier(.long))
    .era(.abbreviated)
    .weekday(.abbreviated)

let yourBirthdayString = "Mon, Feb 17, 1997 AD, 1:27 AM America/Chicago"

// Create a date instance from a string representation of a date.
let yourBirthday = try? birthdayFormatStyle.parse(yourBirthdayString)
// Feb 17, 1997 at 1:27 AM
```

The following round-trip date formatting example uses a date format style to create a locale-aware string representation of a date instance. Then, the date format style guides parsing the newly created string into a new date instance.

```swift
let myFormat = Date.FormatStyle()
    .year()
    .day()
    .month()
    .locale(Locale(identifier: "en_US"))
    
let dateString = Date().formatted(myFormat)
// "Feb 17, 2021" for the "en_US" locale

print(dateString) // Feb 17, 2021

if let anniversary = try? Date(dateString, strategy: myFormat) {
    print(anniversary.formatted(myFormat)) // Feb 17, 2021
    print(anniversary.formatted()) // 2/17/2021, 12:00 AM
} else {
    print("Can't parse string into date with this format.")
}
```

After this code executes, `anniversary` contains a [`Date`](/documentation/Foundation/Date) instance parsed from `dateString`.

### Applying Format Styles Repeatedly

Once you create a date format style, you can use it to format dates multiple times.

You can use a format style to parse a set of date instances from a set of string representations of dates. Then, use another format style, applied repeatedly, to produce more detailed string representations of those dates for a different locale. For example:

```swift
func formatIntroDates() {
   let inputFormat = Date.FormatStyle()
      .locale(Locale(identifier: "en_GB"))
      .year()
      .month()
      .day()
    // Parse string inputs into date instances.
    guard let productIntroDate = try? Date("9 Jan 2007", strategy: inputFormat) else { return }
    guard let anotherIntroDate = try? Date("27 Jan 2010", strategy: inputFormat) else { return }
    guard let conferenceDate = try? Date("7 Jun 2021", strategy: inputFormat) else { return }

    let outputFormat = Date.FormatStyle() // Define format style for string output.
        .locale(Locale(identifier: "en_US"))
        .year()
        .month(.wide)
        .day(.twoDigits)
        .weekday(.abbreviated)

    // Apply the output format on the three dates below.
    print(outputFormat.format(conferenceDate)) // Mon, June 07, 2021
    print(outputFormat.format(anotherIntroDate)) // Wed, January 27, 2010
    print(outputFormat.format(productIntroDate)) // Tue, January 09, 2007
}
```

## Topics

### Creating a Date Format Style

[`init(date:time:locale:calendar:timeZone:capitalizationContext:)`](/documentation/Foundation/Date/FormatStyle/init(date:time:locale:calendar:timeZone:capitalizationContext:))

Creates an instance using the provided date, time, locale, calendar, time zone, and capitalization context.

### Using Pre-Defined Format Styles

### Specifying the Date Format

[`day(_:)`](/documentation/Foundation/Date/FormatStyle/day(_:))

Modifies the date format style to use the specified day format style.

[`dayOfYear(_:)`](/documentation/Foundation/Date/FormatStyle/dayOfYear(_:))

Modifies the date format style to use the specified day of the year format style.

[`era(_:)`](/documentation/Foundation/Date/FormatStyle/era(_:))

Modifies the date format style to use the specified era format style.

[`month(_:)`](/documentation/Foundation/Date/FormatStyle/month(_:))

Modifies the date format style to use the specified month format style.

[`quarter(_:)`](/documentation/Foundation/Date/FormatStyle/quarter(_:))

Modifies the date format style to use the specified quarter format style.

[`week(_:)`](/documentation/Foundation/Date/FormatStyle/week(_:))

Modifies the date format style to use the specified week format style.

[`weekday(_:)`](/documentation/Foundation/Date/FormatStyle/weekday(_:))

Modifies the date format style to use the specified weekday format style.

[`year(_:)`](/documentation/Foundation/Date/FormatStyle/year(_:))

Modifies the date format style to use the specified year format style.

[`DateStyle`](/documentation/Foundation/Date/FormatStyle/DateStyle)

Type that defines date styles varied in length or components included.

### Specifying the Time Format

[`hour(_:)`](/documentation/Foundation/Date/FormatStyle/hour(_:))

Modifies the date format style to use the specified hour format style.

[`minute(_:)`](/documentation/Foundation/Date/FormatStyle/minute(_:))

Modifies the date format style to use the specified minute format style.

[`second(_:)`](/documentation/Foundation/Date/FormatStyle/second(_:))

Modifies the date format style to use the specified second format style.

[`secondFraction(_:)`](/documentation/Foundation/Date/FormatStyle/secondFraction(_:))

Modifies the date format style to use the specified second fraction format style.

[`timeZone(_:)`](/documentation/Foundation/Date/FormatStyle/timeZone(_:))

Modifies the date format style to use the specified time zone format style.

[`TimeStyle`](/documentation/Foundation/Date/FormatStyle/TimeStyle)

Type that defines time styles varied in length or components included.

### Modifying a Date Format Style

[`locale(_:)`](/documentation/Foundation/Date/FormatStyle/locale(_:))

Modifies the date format style to use the specified locale.

[`timeZone`](/documentation/Foundation/Date/FormatStyle/timeZone)

The time zone to use when formatting the date and time components.

[`calendar`](/documentation/Foundation/Date/FormatStyle/calendar)

The calendar to use when formatting the date.

[`capitalizationContext`](/documentation/Foundation/Date/FormatStyle/capitalizationContext)

The capitalization context to use when formatting the date.

[`locale`](/documentation/Foundation/Date/FormatStyle/locale)

The locale to use when formatting the date and time components.

### Applying Visual Attributes to Dates

[`attributed`](/documentation/Foundation/Date/FormatStyle/attributed-swift.property)

An attributed format style created from the date format style.

[`AttributedStyle`](/documentation/Foundation/Date/AttributedStyle)

A structure that creates a locale-appropriate attributed string representation of a date instance.

### Applying a Format Style

[`format(_:)`](/documentation/Foundation/Date/FormatStyle/format(_:))

Creates a locale-aware string representation from a date value.

### Parsing Dates

[`parse(_:)`](/documentation/Foundation/Date/FormatStyle/parse(_:))

Parses a string into a date.

[`parseStrategy`](/documentation/Foundation/Date/FormatStyle/parseStrategy)

The strategy used to parse a string into a date.

[`ParseStrategy`](/documentation/Foundation/Date/ParseStrategy)

Options for parsing string representations of dates to create a `Date` instance.

### Selecting a Parse Strategy

### Supporting Types

### Comparing Date Format Styles

[`==(_:_:)`](/documentation/Foundation/Date/==(_:_:))

Returns true if the two `Date` values represent the same point in time.

### Supporting Symbols

[`Symbol`](/documentation/Foundation/Date/FormatStyle/Symbol)

Types that customize formatting templates either by using the date format style’s modifier functions or by constructing fixed-pattern date format strings.

## Relationships

### Conforms To

[`DiscreteFormatStyle`](/documentation/Foundation/DiscreteFormatStyle)

[`Encodable`](/documentation/Swift/Encodable)

[`RegexComponent`](/documentation/Swift/RegexComponent)

[`Escapable`](/documentation/Swift/Escapable)

[`CustomConsumingRegexComponent`](/documentation/Swift/CustomConsumingRegexComponent)

[`Decodable`](/documentation/Swift/Decodable)

[`SendableMetatype`](/documentation/Swift/SendableMetatype)

[`Sendable`](/documentation/Swift/Sendable)

[`FormatStyle`](/documentation/Foundation/FormatStyle)

[`Hashable`](/documentation/Swift/Hashable)

[`ParseStrategy`](/documentation/Foundation/ParseStrategy)

[`Equatable`](/documentation/Swift/Equatable)

[`ParseableFormatStyle`](/documentation/Foundation/ParseableFormatStyle)

[`Copyable`](/documentation/Swift/Copyable)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)