[SR-14793] Default ISO8601 Date formatter style is not in common use

[subdigital]

Previous ID	SR-14793
Radar	rdar://FB9198760
Original Reporter	@subdigital
Type	Improvement

Additional Detail from JIRA

Votes	7
Component/s	Foundation
Labels	Improvement
Assignee	None
Priority	Medium

md5: 5aed7eda3fe782930b44c5d2635950e5

Issue Description:

Using the new formatted() API, the `.iso8601` style produces a separator-less representation. I've personally never seen this in the wild and was surprised by it.

Adding the dash and colon separators for the more common format is quite verbose.

import Foundation

let date = Date()
date.formatted(.iso8601) // "20210618T191800Z"
date.formatted(.iso8601.year().month().day().dateSeparator(.dash)) // "2021-06-18"
date.formatted(.iso8601.dateSeparator(.dash).timeSeparator(.colon)) // "2021-06-18T19:18:00Z"

Would it be possible to change this to have a `.separatorStyle(.none)` option instead and keep dash/colon separators as the default?

Inspired by:

https://twitter.com/olebegemann/status/1405970447053864972

[typesanitizer]

Since Foundation is one of the frameworks that is part of the SDKs shipped with Xcode, please file a feedback using feedbackassistant.apple.com to follow up on this issue.

[subdigital]

Filed FB9198760

[NachoSoto]

For those at Apple still unaware, many of us are (and have been for a long time) over filing Radars: https://twitter.com/olebegemann/status/1405971193648328713?s=21

[dhoepfl]

I wrote most of the following before Varun Gandhi's comment. I still would like to share my thoughts here since FB is a black hole to most of the API users. Posting it here allows others to give additional feedback and that might be useful to those at Apple that work on the date formatter.

Let’s start with …

date.formatted(.iso8601.dateSeparator(.dash)) // "2021-06-08T181205Z"

… which is not valid according to ISO 8601.

I know this sounds harsh but Date.ISO8601FormatStyle does not look like it actually implements ISO8601. It’s more like it implements a date formatter that most of the time produces something that looks like something that might have been produced by an ISO8601 date formatter.

I’d make ISO8601FormatStyle have a .basic and an .extended style (later being the default, automatically falling back to .basic if extended format is not applicable):

date.formatted(.iso8601)                  // "2021-06-08T18:12:05Z"
date.formatted(.iso8601.style(.extended)) // "2021-06-08T18:12:05Z"
date.formatted(.iso8601.style(.basic))    // "20210608T181205Z"

Instead of .year() …, I’d provide .accuracy() that takes .century….millisecond and .representation() to choose the format variant used:

date.formatted(.iso8601.accuracy(.minutes).representation(.weekDate(.utc))) // "2021-W23-2T18:12Z"

I’s use associated enum values (.weekDate(.utc)) to combine time and date representation since there are date representations that do not support times (e.g. .week for "2021-W23"). This problem exists between .accuracy and .representation, too. But in this case, using the less specific one is a logical automatism. .accuracy(.year).representation(.week) would act as .representation(.year), .accuracy(.minutes).representation(.week) would work as is an accuracy was .week. (Edge case: representation(.time) with .accuracy() less than .hour returns an empty string.)

Representations/accuracy could be something like this:

enum Accuracy {
   case century
   case year
   case month
   case week
   case hour
   case minute
   case second
   case millisecond // == .fractionOfSecond(maxDigits = 3)

   case fractionOfSecond(maxDigits: UInt8)
}

enum TimeRepresentationFraction {
   // 'T'HH[:]MM[:]SS
   case none

   // 'T'HH,H
   case hours

   // 'T'HH[:]MM,M
   case minutes

   // 'T'HH[:]MM[:]SS,S
   case seconds
}

enum TimeRepresentation {
   // <time>'±'HH[:]MM
   case local(_ timeFraction: TimeRepresentationFraction = .none)

   // <time>'±'HH, if MM == 00, otherwise like .local
   case compactLocal(_ timeFraction: TimeRepresentationFraction = .none)

   // <time>Z
   case utc(_ timeFraction: TimeRepresentationFraction = .none)

   // like local but does not include time zone information in output
   case transparent(_ timeFraction: TimeRepresentationFraction = .none)
}

enum DateRepresentation {
   // '+'YY
   case century

   // YYYY
   case year

   // YYYY[-]MM
   case month

   // YYYY[-]'W'ww
   case week

   // YYYY[-]'W'ww[-]D<time>
   case weekDate(_ timeRepresentation: TimeRepresentation = .utc())

   // YYYY[-]ooo<time>
   case ordinal(_ timeRepresentation: TimeRepresentation = .utc())

   // default for .representation():
   // YYYY[-]mm[-]dd<time>
   case complete(_ timeRepresentation: TimeRepresentation = .utc())

   // Time only, no date:
   // <time>
   case time(_ timeRepresentation: TimeRepresentation = .utc())
}

For expanded year formats (more than 2 digits for century), there would be a property of the formatter (e.g. .expandedCenturyLength = 2 to get “+002021-06-18T19:1800Z”).

The formatter should never create a string that is not a valid according to ISO8601.

Parsing should accept all valid ISO8601 date strings. Accepting time only strings must be limited to when .representation() is set to .time(). This is required since e.g. "1528" might be both, a year-only-date and a time. Since this style is for Date instances, parsing should use reasonable defaults for unspecified fields. There should probably be an Date.ISO8601ComponentsFormatStyle that works with DateComponents.

I completely ignored time intervals and durations.