2.2 · Date, Calendar, Locale, TimeZone, FormatStyle

A Date is one instant. Everything people care about, such as the day, the hour, the week and the way it is written, comes from a calendar, a time zone and a locale applied to that instant.

Mental model. Keep the instant as the truth and apply calendar + time zone + locale only at the edges: when you do calendar maths, and when you show it.

What a Date is

An instant, plus the zone that gives it a wall-clock meaning.

  1. What is a Date in Foundation, and what does it not contain? 2.2.1 · L1
    Date is a single instant on the timeline, stored as a Double count of seconds since 1 January 2001, 00:00 UTC (the reference date). It has no time zone, no…
  2. How do you handle time zones: what do you store, send and show? 2.2.2 · L2
    Store and send instants: UTC timestamps, epoch seconds, or ISO 8601 with a zone. Convert to a zone only when you show a time or do calendar maths that means…

Calendar maths

Days that are not 24 hours, months that clamp, weeks that cross years.

  1. How do Calendar and DateComponents work, and why can YYYY give the wrong year? 2.2.3 · L1
    Calendar converts between an instant and its human parts. dateComponents(_:from:) pulls fields out of a Date; date(from:) builds a Date from fields.…
  2. Why is date + 86,400 seconds not tomorrow? 2.2.4 · L2
    A day is not always 24 hours. On a daylight-saving change a calendar day lasts 23 or 25 hours, and in rare zones a day can skip a whole stretch of local time.…
  3. How does Calendar handle “add a month”, “next Friday” and “start of the month”? 2.2.5 · L2
    Calendar maths is defined on fields, not seconds. date(byAdding: .month, value: 1, to:) moves the month and clamps the day if needed: 31 January plus one month…

Locale

Language is not region, and neither is a number format.

  1. What is a Locale, and how is it different from the user’s language? 2.2.6 · L2
    Locale bundles the conventions a person expects: language, region, calendar, decimal and grouping separators, currency, measurement system and first weekday. A…

Formatting and parsing

Turning dates into text and back without surprises.

  1. FormatStyle or DateFormatter: which do you reach for? 2.2.7 · L2
    FormatStyle (iOS 15) is the modern way. Styles are value types: composable (.dateTime.year().month(.abbreviated).day()), Sendable, Codable, and they take an…
  2. What goes wrong with DateFormatter, and how do you parse a fixed format safely? 2.2.8 · L2
    To parse or print a fixed format (an API timestamp) set three things: locale = en_US_POSIX, an explicit timeZone, and a dateFormat. Without the POSIX locale…

Measuring time

Elapsed time is a different problem from calendar time.

  1. How do you measure elapsed time, and how do you show a duration? 2.2.9 · L3
    Date is wall-clock time and can jump (clock changes, NTP), so subtracting two Date()s is not a reliable stopwatch. Use a monotonic clock: ContinuousClock keeps…

More in Foundation & stdlib