<!--
{
  "availability" : [
    "iOS: 2.0.0 -",
    "iPadOS: 2.0.0 -",
    "macCatalyst: 13.0.0 -",
    "macOS: 10.0.0 -",
    "tvOS: 9.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 2.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Foundation",
  "identifier" : "/documentation/Foundation/DateFormatter",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Foundation"
    ],
    "preciseIdentifier" : "c:objc(cs)NSDateFormatter"
  },
  "title" : "DateFormatter"
}
-->

# DateFormatter

A formatter that converts between dates and their textual representations.

```
class DateFormatter
```

## Overview

Instances of [`DateFormatter`](/documentation/Foundation/DateFormatter) create string representations of [`NSDate`](/documentation/Foundation/NSDate) objects, and convert textual representations of dates and times into [`NSDate`](/documentation/Foundation/NSDate) objects. For user-visible representations of dates and times, [`DateFormatter`](/documentation/Foundation/DateFormatter) provides a variety of localized presets and configuration options. For fixed format representations of dates and times, you can specify a custom format string.

When working with date representations in ISO 8601 format, use [`ISO8601DateFormatter`](/documentation/Foundation/ISO8601DateFormatter) instead.

To represent an interval between two [`NSDate`](/documentation/Foundation/NSDate) objects, use [`DateIntervalFormatter`](/documentation/Foundation/DateIntervalFormatter) instead.

To represent a quantity of time specified by an [`NSDateComponents`](/documentation/Foundation/NSDateComponents) object, use [`DateComponentsFormatter`](/documentation/Foundation/DateComponentsFormatter) instead.

> Tip:
> In Swift, you can use ``doc://com.apple.foundation/documentation/Foundation/Date/FormatStyle`` or ``doc://com.apple.foundation/documentation/Foundation/Date/VerbatimFormatStyle`` rather than ``doc://com.apple.foundation/documentation/Foundation/DateFormatter``. The ``doc://com.apple.foundation/documentation/Foundation/FormatStyle`` API offers a declarative idiom for customizing the formatting of various types. Also, Foundation caches identical ``doc://com.apple.foundation/documentation/Foundation/FormatStyle`` instances, so you don’t need to pass them around your app, or risk wasting memory with duplicate formatters.

### Working With User-Visible Representations of Dates and Times

When displaying a date to a user, you set the [`dateStyle`](/documentation/Foundation/DateFormatter/dateStyle) and [`timeStyle`](/documentation/Foundation/DateFormatter/timeStyle) properties of the date formatter according to your particular needs. For example, if you want to show the month, day, and year without showing the time, you would set the [`dateStyle`](/documentation/Foundation/DateFormatter/dateStyle) property to [`DateFormatter.Style.long`](/documentation/Foundation/DateFormatter/Style/long) and the [`timeStyle`](/documentation/Foundation/DateFormatter/timeStyle) property to [`DateFormatter.Style.none`](/documentation/Foundation/DateFormatter/Style/none). Conversely, if you want to show only the time, you would set the `dateStyle` property to [`DateFormatter.Style.none`](/documentation/Foundation/DateFormatter/Style/none) and the [`timeStyle`](/documentation/Foundation/DateFormatter/timeStyle) property to [`DateFormatter.Style.short`](/documentation/Foundation/DateFormatter/Style/short). Based on the values of the [`dateStyle`](/documentation/Foundation/DateFormatter/dateStyle) and [`timeStyle`](/documentation/Foundation/DateFormatter/timeStyle) properties, [`DateFormatter`](/documentation/Foundation/DateFormatter) provides a representation of a specified date that is appropriate for a given locale.

```objc
NSDateFormatter *dateFormatter = [[NSDateFormatter alloc] init];
dateFormatter.dateStyle = NSDateFormatterMediumStyle;
dateFormatter.timeStyle = NSDateFormatterNoStyle;
 
NSDate *date = [NSDate dateWithTimeIntervalSinceReferenceDate:118800];
 
// US English Locale (en_US)
dateFormatter.locale = [[NSLocale alloc] initWithLocaleIdentifier:@"en_US"];
NSLog(@"%@", [dateFormatter stringFromDate:date]); // Jan 2, 2001
 
// French Locale (fr_FR)
dateFormatter.locale = [[NSLocale alloc] initWithLocaleIdentifier:@"fr_FR"];
NSLog(@"%@", [dateFormatter stringFromDate:date]); // 2 janv. 2001
 
// Japanese Locale (ja_JP)
dateFormatter.locale = [[NSLocale alloc] initWithLocaleIdentifier:@"ja_JP"];
NSLog(@"%@", [dateFormatter stringFromDate:date]); // 2001/01/02
```

If you need to define a format that cannot be achieved using the predefined styles, you can use the [`setLocalizedDateFormatFromTemplate(_:)`](/documentation/Foundation/DateFormatter/setLocalizedDateFormatFromTemplate(_:)) to specify a localized date format from a template.

```objc
NSDateFormatter *dateFormatter = [[NSDateFormatter alloc] init];
NSDate *date = [NSDate dateWithTimeIntervalSinceReferenceDate:410220000];
 
// US English Locale (en_US)
dateFormatter.locale = [[NSLocale alloc] initWithLocaleIdentifier:@"en_US"];
[dateFormatter setLocalizedDateFormatFromTemplate:@"MMMMd"]; // set template after setting locale
NSLog(@"%@", [dateFormatter stringFromDate:date]); // December 31
 
// British English Locale (en_GB)
dateFormatter.locale = [[NSLocale alloc] initWithLocaleIdentifier:@"en_GB"];
[dateFormatter setLocalizedDateFormatFromTemplate:@"MMMMd"]; // set template after setting locale
NSLog(@"%@", [dateFormatter stringFromDate:date]); // 31 December
```

### Working With Fixed Format Date Representations

> Important:
> In macOS 10.12 and later or iOS 10 and later, use the ``doc://com.apple.foundation/documentation/Foundation/ISO8601DateFormatter`` class when working with ISO 8601 date representations.

When working with fixed format dates, such as RFC 3339, you set the [`dateFormat`](/documentation/Foundation/DateFormatter/dateFormat) property to specify a format string. For most fixed formats, you should also set the [`locale`](/documentation/Foundation/DateFormatter/locale) property to a POSIX locale (`"en_US_POSIX"`), and set the [`timeZone`](/documentation/Foundation/DateFormatter/timeZone) property to UTC.

```objc
RFC3339DateFormatter = [[NSDateFormatter alloc] init];
RFC3339DateFormatter.locale = [NSLocale localeWithLocaleIdentifier:@"en_US_POSIX"];
RFC3339DateFormatter.dateFormat = @"yyyy-MM-dd'T'HH:mm:ssZZZZZ";
RFC3339DateFormatter.timeZone = [NSTimeZone timeZoneForSecondsFromGMT:0];
 
/* 39 minutes and 57 seconds after the 16th hour of December 19th, 1996 with an offset of -08:00 from UTC (Pacific Standard Time) */
NSString *string = @"1996-12-19T16:39:57-08:00";
NSDate *date = [RFC3339DateFormatter dateFromString:string];
```

For more information, see [Technical Q&A QA1480 “NSDateFormatter and Internet Dates”](https://developer.apple.com/library/mac/qa/qa1480/).

### Thread Safety

On iOS 7 and later `NSDateFormatter` is thread safe.

In macOS 10.9 and later `NSDateFormatter` is thread safe so long as you are using the modern behavior in a 64-bit app.

On earlier versions of the operating system, or when using the legacy formatter behavior or running in 32-bit in macOS, `NSDateFormatter` is not thread safe, and you therefore must not mutate a date formatter simultaneously from multiple threads.

## Topics

### Converting Objects

[`date(from:)`](/documentation/Foundation/DateFormatter/date(from:))

Returns a date representation of a specified string that the system interprets using the receiver’s current settings.

[`string(from:)`](/documentation/Foundation/DateFormatter/string(from:))

Returns a string representation of a specified date that the system formats using the receiver’s current settings.

[`localizedString(from:dateStyle:timeStyle:)`](/documentation/Foundation/DateFormatter/localizedString(from:dateStyle:timeStyle:))

Returns a string representation of a specified date, that the system formats for the current locale using the specified date and time styles.

[`getObjectValue(_:for:range:)`](/documentation/Foundation/DateFormatter/getObjectValue(_:for:range:))

Returns by reference a date representation of a specified string and its date range, as well as a Boolean value that indicates whether the system can parse the string.

### Managing Formats and Styles

[`dateStyle`](/documentation/Foundation/DateFormatter/dateStyle)

The date style of the receiver.

[`timeStyle`](/documentation/Foundation/DateFormatter/timeStyle)

The time style of the receiver.

[`dateFormat`](/documentation/Foundation/DateFormatter/dateFormat)

The date format string used by the receiver.

[`setLocalizedDateFormatFromTemplate(_:)`](/documentation/Foundation/DateFormatter/setLocalizedDateFormatFromTemplate(_:))

Sets the date format from a template using the specified locale for the receiver.

[`dateFormat(fromTemplate:options:locale:)`](/documentation/Foundation/DateFormatter/dateFormat(fromTemplate:options:locale:))

Returns a localized date format string representing the given date format components arranged appropriately for the specified locale.

[`formattingContext`](/documentation/Foundation/DateFormatter/formattingContext)

The capitalization formatting context used when formatting a date.

### Managing Attributes

[`calendar`](/documentation/Foundation/DateFormatter/calendar)

The calendar for the receiver.

[`defaultDate`](/documentation/Foundation/DateFormatter/defaultDate)

The default date for the receiver.

[`locale`](/documentation/Foundation/DateFormatter/locale)

The locale for the receiver.

[`timeZone`](/documentation/Foundation/DateFormatter/timeZone)

The time zone for the receiver.

[`twoDigitStartDate`](/documentation/Foundation/DateFormatter/twoDigitStartDate)

The earliest date that can be denoted by a two-digit year specifier.

[`gregorianStartDate`](/documentation/Foundation/DateFormatter/gregorianStartDate)

The start date of the Gregorian calendar for the receiver.

### Managing Behavior Version

[`formatterBehavior`](/documentation/Foundation/DateFormatter/formatterBehavior)

The formatter behavior for the receiver.

[`defaultFormatterBehavior`](/documentation/Foundation/DateFormatter/defaultFormatterBehavior)

Returns the default formatting behavior for instances of the class.

### Managing Natural Language Support

[`allowsNaturalLanguage`](/documentation/Foundation/NSDateFormatter/allowsNaturalLanguage)

Returns a Boolean value that indicates whether the receiver attempts to process dates entered as a vernacular string.

[`isLenient`](/documentation/Foundation/DateFormatter/isLenient)

A Boolean value that indicates whether the receiver uses heuristics when parsing a string.

[`doesRelativeDateFormatting`](/documentation/Foundation/DateFormatter/doesRelativeDateFormatting)

A Boolean value that indicates whether the receiver uses phrases such as “today” and “tomorrow” for the date component.

### Managing AM and PM Symbols

[`amSymbol`](/documentation/Foundation/DateFormatter/amSymbol)

The AM symbol for the receiver.

[`pmSymbol`](/documentation/Foundation/DateFormatter/pmSymbol)

The PM symbol for the receiver.

### Managing Weekday Symbols

[`weekdaySymbols`](/documentation/Foundation/DateFormatter/weekdaySymbols)

The array of weekday symbols for the receiver.

[`shortWeekdaySymbols`](/documentation/Foundation/DateFormatter/shortWeekdaySymbols)

The array of short weekday symbols for the receiver.

[`veryShortWeekdaySymbols`](/documentation/Foundation/DateFormatter/veryShortWeekdaySymbols)

The array of very short weekday symbols for the receiver.

[`standaloneWeekdaySymbols`](/documentation/Foundation/DateFormatter/standaloneWeekdaySymbols)

The array of standalone weekday symbols for the receiver.

[`shortStandaloneWeekdaySymbols`](/documentation/Foundation/DateFormatter/shortStandaloneWeekdaySymbols)

The array of short standalone weekday symbols for the receiver.

[`veryShortStandaloneWeekdaySymbols`](/documentation/Foundation/DateFormatter/veryShortStandaloneWeekdaySymbols)

The array of very short standalone weekday symbols for the receiver.

### Managing Month Symbols

[`monthSymbols`](/documentation/Foundation/DateFormatter/monthSymbols)

The month symbols for the receiver.

[`shortMonthSymbols`](/documentation/Foundation/DateFormatter/shortMonthSymbols)

The array of short month symbols for the receiver.

[`veryShortMonthSymbols`](/documentation/Foundation/DateFormatter/veryShortMonthSymbols)

The very short month symbols for the receiver.

[`standaloneMonthSymbols`](/documentation/Foundation/DateFormatter/standaloneMonthSymbols)

The standalone month symbols for the receiver.

[`shortStandaloneMonthSymbols`](/documentation/Foundation/DateFormatter/shortStandaloneMonthSymbols)

The short standalone month symbols for the receiver.

[`veryShortStandaloneMonthSymbols`](/documentation/Foundation/DateFormatter/veryShortStandaloneMonthSymbols)

The very short month symbols for the receiver.

### Managing Quarter Symbols

[`quarterSymbols`](/documentation/Foundation/DateFormatter/quarterSymbols)

The quarter symbols for the receiver.

[`shortQuarterSymbols`](/documentation/Foundation/DateFormatter/shortQuarterSymbols)

The short quarter symbols for the receiver.

[`standaloneQuarterSymbols`](/documentation/Foundation/DateFormatter/standaloneQuarterSymbols)

The standalone quarter symbols for the receiver.

[`shortStandaloneQuarterSymbols`](/documentation/Foundation/DateFormatter/shortStandaloneQuarterSymbols)

The short standalone quarter symbols for the receiver.

### Managing Era Symbols

[`eraSymbols`](/documentation/Foundation/DateFormatter/eraSymbols)

The era symbols for the receiver.

[`longEraSymbols`](/documentation/Foundation/DateFormatter/longEraSymbols)

The long era symbols for the receiver

### Deprecated

[`initWithDateFormat:allowNaturalLanguage:`](/documentation/Foundation/NSDateFormatter/initWithDateFormat:allowNaturalLanguage:)

Initializes and returns an `NSDateFormatter` instance that uses the OS X 10.0 formatting behavior and the given date format string in its conversions.

[`generatesCalendarDates`](/documentation/Foundation/DateFormatter/generatesCalendarDates)

Indicates whether the formatter generates the deprecated calendar date type.

### Constants

[`DateFormatter.Style`](/documentation/Foundation/DateFormatter/Style)

The following constants specify predefined format styles for dates and times.

[`DateFormatter.Behavior`](/documentation/Foundation/DateFormatter/Behavior)

Constants that specify the behavior `NSDateFormatter` should exhibit.


---

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)