11

I cannot find a list of the format specifiers allowed in the template argument of DateFormatter.dateFormat(fromTemplate:options:locale:).

  1. dateFormat directs me to...
  2. Date and Time Programming Guide. None of those pages lists the format specifiers. So I checked the suggested related documentation...
  3. Date and Time Programming Guide for Core Foundation doesn't have a list.
  4. Data Formatting Guide has a section title "Use Format Strings to Specify Custom Formats" but it just points me back to (1) above. None of the other pages in Data Formatting Guide have the format specifiers.

Does anyone know where Apple documents these specifiers?

Bob Peterson
  • 636
  • 7
  • 16
  • 2
    Huh? They're linked to right below the fourth heading you mention: _"The format string uses the format patterns from the Unicode Technical Standard #35. The version of the standard varies with release of the operating system: - OS X v10.9 and iOS 7 use [version tr35-31](http://www.unicode.org/reports/tr35/tr35-31/tr35-dates.html#Date_Format_Patterns). - OS X v10.8 and iOS 6 use [version tr35-25](http://www.unicode.org/reports/tr35/tr35-25.html#Date_Format_Patterns) ..."_. – jscs Mar 10 '19 at 19:22
  • 1
    Thanks. I overlooked it (yes, even right at the top of the page). I was looking for an actual table *in* Apple docs, not a reference to non-Apple docs. Plus it is prefaced by talking about setDateFormat, not dateFormat(fromTemplate...) – Bob Peterson Mar 10 '19 at 22:32
  • 1
    http://www.unicode.org/reports/tr35/tr35-dates.html#8-date-format-patterns – udi Sep 07 '22 at 05:31

1 Answers1

14

I'll expand on the answer in the comment with some examples. For iOS 7 and later the format codes are here: http://www.unicode.org/reports/tr35/tr35-31/tr35-dates.html#Date_Format_Patterns. The table is too big to copy it all here but here's a few that helped me get started. See that link for all of the formats and explanations.

  • era: G (AD), GGGG (Anno Domini)
  • year: y (1984), yy (84), yyyy (1984)
  • month: M, MM, MMM, MMMM, MMMMM. Also: L
  • day of month: d, dd
  • day name of week: E, EEEE, EEEEE, EEEEEE

Here's a playground fragment that I found helpful to explore these.

import Foundation

let components = DateComponents(
    calendar: Calendar(identifier: .gregorian), 
    timeZone: nil, 
    era: 1, 
    year: 1984, 
    month: 1, 
    day: 2, 
    hour: nil, minute: nil, second: nil, 
    nanosecond: nil, weekday: nil, 
    weekdayOrdinal: nil, quarter: nil, 
    weekOfMonth: nil, weekOfYear: nil, 
    yearForWeekOfYear: nil)
let aDate = Calendar(identifier: .gregorian).date(from: components)!
let en_US = Locale(identifier: "en_US")
var df = DateFormatter()
func formatdate(_ template: String) -> String {
    let custom = DateFormatter.dateFormat(fromTemplate: template, options: 0, locale: en_US)
    df.dateFormat = custom
    return df.string(from: aDate)
}

formatdate("Mdyyyy") // "1/2/1984"
formatdate("yyyyMMdd") // "01/02/1984"
formatdate("yyyyMMMdd") // "Jan 02, 1984"
formatdate("yyyyMMMMdd") // "January 02, 1984"
formatdate("yyyyMMMMMdd") // "J 02, 1984"
formatdate("yyyyG") // "1984 AD"
formatdate("yyyyGGGG") // "1984 Anno Domini"
formatdate("yyyyMMMddE") // "Mon, Jan 02, 1984"
formatdate("yyyyMMMddEEEE") // "Monday, Jan 02, 1984"
formatdate("yyyyMMMddEEEEE") // "M, Jan 02, 1984"

formatdate("MdYYYY") // "1/2/1984"
formatdate("YYYYMMdd") // "01/02/1984"
formatdate("YYYYMMMdd") // "Jan 02, 1984"
formatdate("YYYYMMMMdd") // "January 02, 1984"
formatdate("YYYYMMMMMdd") // "J 02, 1984"
formatdate("YYYYG") // "1984 AD"
formatdate("YYYYGGGG") // "1984 Anno Domini"
formatdate("YYYYMMMddE") // "Mon, Jan 02, 1984"
formatdate("YYYYMMMddEEEE") // "Monday, Jan 02, 1984"
formatdate("YYYYMMMddEEEEE") // "M, Jan 02, 1984"
Bob Peterson
  • 636
  • 7
  • 16
  • 1
    You'll want to use `yyyy` instead of `YYYY`: https://stackoverflow.com/a/15133617/2108547 – Daniel Storm Apr 22 '21 at 15:42
  • 1
    Oy vey. I thank the commenters for catching that silly omission. Fixed. I verified the output is still the same for those particular examples. Verified using Xcode 13.0 beta (1) on macOS 11.4. I'll point out the new Swift 5.5 formatters should be looked at first as they avoid formatting characters entirely. See [Date.formatted](https://developer.apple.com/documentation/foundation/date/3766588-formatted) and [What's New in Foundation WWDC 2021](https://developer.apple.com/wwdc21/10109) at around 14'30". – Bob Peterson Jun 23 '21 at 14:16