Global Nerdy

If you’re just getting started with programming dates and times in Swift 5, you probably looked at Apple’s documentation and got confused. Let me reassure you that it isn’t your fault. For starters, Apple’s documentation hasn’t been very good lately, and I’m not the only developer who’s noticed this decline in quality.

There’s also the fact that working with dates and times in Swift 5 seems unnecessarily complicated. If you’ve come to Swift from other programming languages, such as JavaScript, which uses a single object type called Date, the idea of having this set of classes just to handle dates and times looks like overkill:

I promise you that there’s a method to this madness. The set of structs for working with dates and times in Swift 5 make for a super-flexible system that will let you keep store, calculate, and display dates and times no matter what time zone, calendar system, or language you use.

For example, with Swift, I can easily schedule an appointment for the third Wednesday of July at 3:30 p.m. Pacific and then display that date as it would appear in the Coptic Calendar system in Melbourne, Australia. If you had to do that in JavaScript, the only easy answer is “go away” (there are, of course, some less polite variations of that answer).

This series, Dates and times in Swift 5, will help you make sense of the set of classes that Swift provides for dealing with timekeeping and time calculations. It will do so with a lot of examples and experimentation. I strongly recommend that you fire up Xcode, open a Swift playground, and follow along.

In this article, I’ll show you the following:

• The Date struct, which stores date and times in Swift 5.
• The Calendar struct, which represents one of 16 different calendar systems, and provides a meaningful context for Dates.
• The DateComponents struct, which a collection of date and time components, such as years, months, days, hours, minutes, and so on.
• How to create a Date object representing the current date and time.
• How to create a Date object representing a given date and time.
• How to create a Date object based on criteria such as “the first Friday of June 2020.”
• How to extract the parts of a date, such as the year, month, day, time, and so on from a Date object.

The Date struct

The Date struct is used to represent dates and times in Swift 5, and it’s designed to do so in the most flexible way possible: as a number of seconds relative to the start of the Third Millennium, January 1, 2001, 00:00:00 UTC.

This approach allows Date to be independent of any time zone or any calendar system; you store it as an amount of time before or after the start of the Third Millennium and use other objects (which you’ll see soon) to convert into the appropriate calendar, time zone, and format.

To create a Date object containing the current date and time, simply create an instance of Date using the default, no-argument initializer.

Open a playground in Xcode and add the following:

// To create a Date representing the current date and time,
// simply initialize a new Date.
let now = Date()  // Contains the date and time that this object
                  // was instantiated.

To see the value stored inside the newly created Date object, use Date’s timeIntervalSinceReferenceDate property, which contains the number of seconds since the reference date.

Add the following to the playground, then run it:

// How many seconds have passed between the Date we just created
// and the reference date of January 1, 2001, 00:00:00 UTC?
print("It’s been \(now.timeIntervalSinceReferenceDate) seconds since the start of the Third Millennium.")

When I ran that line of code (just before 9:00 a.m. EDT on Tuesday, May 26, 2020), I got this output: It’s been 612190714.691352 seconds since the start of the Third Millennium.

To see the Date’s value in a more meaningful form, use Date’s description property to see it in “YYYY-MM-DD HH:MM:SS +HHMM” format, or the description(with:) method with a Locale instance to display its value using a specified locale.

Add the following to the playground, then run it:

// Use Date’s description property for debugging
print(now.description)                                      // YYYY-MM-DD HH:MM:SS +HHMM
print(now.description(with: Locale(identifier: "en-US")))   // US English
print(now.description(with: Locale(identifier: "en-GB")))   // UK English*
print(now.description(with: Locale(identifier: "es")))      // Spanish
print(now.description(with: Locale(identifier: "zh-Hans"))) // Simplified Chinese

// * Yes, I know that “gb” means “Great Britain” and that it’s not the same thing
// as the UK. I didn’t come up with these locale names!

To create a Date object containing a date and time that isn’t the current date and time, and without other helper objects, you have to use one of the following initializers:

Here are some examples showing these initializers in action — add the following to the playground, then run it:

// Date’s other initializers expect arguments of type TimeInterval,
// which is a typealias for Double.

// To create a Date a specified number of seconds before or after
// the current date and time, use the "timeIntervalSinceNow" initializer.
let fiveMinutesAgo = Date(timeIntervalSinceNow: -5 * 60)
let fiveMinutesFromNow = Date(timeIntervalSinceNow: 5 * 60)

// Martin Cooper made the first cellular phone call on April 3, 1973.
// We don't know the exact time the call was made, but it happened
// sometime during business hours in New York City, in the U.S. Eastern
// Time Zone (UTC-5).
//
// Let’s suppose that he made the call at 12:00 p.m.. That would mean that
// he made the call 875,602,800 seconds BEFORE the reference date and time.
let firstCellularCallDate = Date(timeIntervalSinceReferenceDate: -875_602_800)

// The "Stevenote" where the iPhone was introduced started on January 9, 2007,
// 10 a.m. Pacific time (UTC-7), 190,058,400 seconds AFTER the reference date and time.
let iPhoneStevenoteDate = Date(timeIntervalSinceReferenceDate: 190_058_400)

// Unix time (a.k.a. POSIX time or Epoch Time) is the way time is represented
// by Unix, Unix-like, and other operating systems. It defines time as a
// number of seconds after the Unix Epoch, January 1, 1970, 00:00:00 UTC.
// To create a Date relative to the Unix Epoch, use the
// "timeIntervalSince1970" initializer.
let oneYear = TimeInterval(60 * 60 * 24 * 365)
let newYears1971 = Date(timeIntervalSince1970: oneYear)
let newYears1969 = Date(timeIntervalSince1970: -oneYear)

// To create a Date relative to another Date, use the
// "timeInterval:Since:" initializer.
//
// The "Stevenote" where the iPad was introduced started on January 27, 2010,
// 10 a.m. Pacific time (UTC-7), 96,249,600 seconds after the start of the
// iPhone Stevenote three years earlier.
let secondsBetweeniPhoneAndiPadStevenote = TimeInterval(96_249_600)
let iPadStevenoteDate = Date(timeInterval: secondsBetweeniPhoneAndiPadStevenote,
                             since: iPhoneStevenoteDate)

Of course, we don’t think of dates and times in terms of seconds relative to the start of the Third Millennium, or the start of the Unix Epoch, or any other arbitrary date and time. That’s why dates and times in Swift 5 make use of a couple of other structs to help us make sense of Dates: Calendar and DateComponents. Calendars give dates context, and DateComponents let us assemble dates or break dates apart.

The Calendar struct

Think of the Calendar struct as a way to view Dates in a way that makes more sense to us: not as a number of seconds before or after January 1, 2001 00:00:00 UTC, but in terms of a date in a calendar system.

The Calendar struct supports 16 different calendar systems, including the Gregorian calendar (a.k.a. the Western or Christian calendar), which is likely the one you use the most.

The DateComponents struct

The DateComponents struct allows us to assemble a point in time or a length of time out of components such as year, month, day, hour, minute, and more. We’ll use DateComponents to construct a Date object using a year, month, day and time, and also deconstruct a Date object into a year, month, day and time.

Consider Swift’s reference date: January 1, 2001 at 00:00:00 UTC. Here are what its components are in various calendar systems:

Let’s use Calendar and DateComponents to make it easier to create Dates.

Creating known Dates with Calendar and DateComponents

Let’s create a Date based on the first moment in phone history: March 10, 1876, when Alexander Graham Bell made the first phone call. I don’t know what time he made the call on that day, so for this example, I’m going to assume that it happened at 1:00 p.m..

Add the following to the playground, then run it:

// 1
// To translate between Dates and DateComponents, you need a Calendar.
// The user's Calendar is probably the one you’ll use most often,
// as it incorporates the user's locale and time zone settings.
let userCalendar = Calendar.current


// March 10, 1876: The day Alexander Graham Bell
// made the first phone call
// ---------------------------------------------
// 2
// DateComponents' full initializer method is very thorough, but very long.
let firstLandLineCallDateComponents = DateComponents(
  calendar: nil,
  timeZone: TimeZone(secondsFromGMT: -18000),
  era: nil,
  year: 1876,
  month: 3,
  day: 10,
  hour: 13,
  minute: 00,
  second: 00,
  nanosecond: nil,
  weekday: nil,
  weekdayOrdinal: nil,
  quarter: nil,
  weekOfMonth: nil,
  weekOfYear: nil,
  yearForWeekOfYear: nil)

// 3
let firstLandLineCallDate = userCalendar.date(from: firstLandLineCallDateComponents)!

// 4
print("The first land line phone call happened on \(firstLandLineCallDate.description(with: Locale(identifier: "en-US"))).")
print("That’s \(firstLandLineCallDate.timeIntervalSinceReferenceDate) seconds since the start of the Third Millennium.")

In the code, we:

1. Get the user’s current Calendar.
2. Create a DateComponents struct, firstLandLineCallDateComponents, providing values for the timeZone:, year:, month:, and day:, hour:, minute:, and second: parameters, and nil for all the others.  Bell made the call in his laboratory in Boston, whose time zone is UTC-5. We construct the time zone using the TimeZone(secondsFromGMT:) constructor, which specifies how many seconds the given time zone is ahead or behind UTC (GMT — Greenwich Meridian Time — is the old name for UTC).
3. Use the user’s Calendar to create firstLandLineCallDate using firstLandLineCallDateComponents.
4. Print the date of the call using the American English format as well as in terms of seconds since the start of the Third Millennium. Since the call happened over a century before the Third Millennium, this number is negative.

On my computer, the output is:

The first land line phone call happened on Friday, March 10, 1876 at 12:03:58 PM GMT-04:56:02.
That’s -3938655600.0 seconds since the start of the Third Millennium.

Let’s create another date: December 9, 1968 at 3:45 p.m. Pacific, when Douglas Englebart changes the world of computing with his demonstration of the GUI, mouse, chording keyboard, hypertext links, and collaborative document editing — a session that would come to be called “The Mother of All Demos.”

Add the following to the playground, then run it:

// December 9, 1968, 3:45 p.m. Pacific Time:
// Douglas Englebart gives “The Mother of All Demos”
// -------------------------------------------------
// This time, we’ll use only the DateComponents initializer parameters we need.
// 1
let motherOfAllDemosDateComponents = DateComponents(
  timeZone: TimeZone(identifier: "America/Los_Angeles"),
  year: 1968,
  month: 12,
  day: 9,
  hour: 15,
  minute: 45
)

// 2
let motherOfAllDemosDate = userCalendar.date(from: motherOfAllDemosDateComponents)!

// 3
print("The Mother of All Demos happened on \(motherOfAllDemosDate.description(with: Locale(identifier: "en-US"))).")
print("That’s \(motherOfAllDemosDate.timeIntervalSince1970) seconds since the start of the Unix Epoch.")

In the code, we:

1. Create a DateComponents struct, motherOfAllDemosDateComponents, providing values for only the parameters that matter t us: timeZone:, year:, month:, and day:, hour:, and  minute:. This time, we construct the time zone using the TimeZone(identifier:) constructor, which specifies the time zone by the appropriate TZ database name.
2. Use the user’s Calendar (userCalendar, which we’ve already declared) to create motherOfAllDemosDate using motherOfAllDemosDateComponents.
3. Print the date of the call using the American English format as well as in terms of seconds since the start of the Unix Epoch. Since the call happened a little over a year before the Unix Epoch, this number is negative.

On my computer, the output is:

The Mother of All Demos happened on Monday, December 9, 1968 at 6:45:00 PM GMT-05:00.
That’s -33437700.0 seconds since the start of the Unix Epoch.

Let’s try creating another momentous date in phone history: the day when Martin Cooper made the first cellular phone call, April 3, 1973.

Add the following to the playground, then run it:

// April 3, 1973: Martin Cooper makes the first
// cellular phone call
// --------------------------------------------

// 1
var firstCellCallDateComponents = DateComponents()

// 2
firstCellCallDateComponents.year = 1973
firstCellCallDateComponents.month = 4
firstCellCallDateComponents.day = 3
firstCellCallDateComponents.timeZone = TimeZone(abbreviation: "EST")

// 3
let firstCellCallDate = userCalendar.date(from: firstCellCallDateComponents)!
print("Martin Cooper made the first cellular call on \(firstCellCallDate.description(with: Locale(identifier: "en-US"))).")
print("That’s \(firstCellCallDate.timeIntervalSince(motherOfAllDemosDate)) seconds since the Mother of All Demos.")

In the code, we:

1. Create an empty DateComponents struct, firstCellCallDateComponents. Note that we’re using var instead of let to declare it; that’s because we’re going to set its properties after it’s been declared, and you can’t do that to a struct declared with let.
2. Set the year, month, and day properties of firstCellCallDateComponents to correspond to the date April 3, 1973 in Eastern Standard Time. This time, we construct the time zone using the TimeZone(abbreviation:) constructor, which specifies the time zone by the appropriate time zone abbreviation.
3. Use the user’s Calendar to create firstCellCallDate using firstCellCallDateComponents.

On my computer, the output is:

Martin Cooper made the first cellular call on Tuesday, April 3, 1973 at 12:00:00 AM Eastern Standard Time.
That’s 136098900.0 seconds since the Mother of All Demos.

Note that in the absence of a specified time, the assumed time is 00:00:00.

Discovering Dates with Calendar and DateComponents

So far, we’ve created Dates based on known dates and times — March 10, 1876, December 9, 1968, and April 3, 1973. How about Dates where we don’t have a specific date, but have enough criteria to specify a date? The great thing about working with dates and times in Swift 5 is that the Calendar class is that it does its best to work with the DateComponents that you give it, and DateComponents gives you all sorts of ways to specify a date.

Having come from Canada, the country with the world’s highest per capita donut shop concentration and the people who eat the most donuts per capita, I can assure you that National Donut Day has been a real thing since 1938, and it takes place on the first Friday in June. We can find out what date it falls on in 2020 — or any other year — through the judicious use of DateComponents properties.

Add the following to the playground, then run it:

// The first Friday in June, 2020:
// National Donut Day
// -------------------------------
let donutDay2020Components = DateComponents(
  year: 2020,         // We want a date in 2020,
  month: 6,           // in June.
  weekday: 6,         // We want a Friday;
  weekdayOrdinal: 1   // the first one.
)

let donutDay2020 = userCalendar.date(from: donutDay2020Components)!
print("Donut Day 2020 happens on \(donutDay2020Date.description(with: Locale(identifier: "en-US"))).")

You should be familiar with the year and month DayComponents properties by now, and we’re using a couple that may be new to you:

• weekday: Specifies a day of the week. With the Gregorian calendar, valid values are 1 through 7, where 1 is Sunday, 2 is Monday, 3 is Tuesday, and so on. Since we’re looking for a Friday, we’ve set this value to 6.
• weekdayOrdinal: Specifies the order of the given weekday in the next larger specified calendar unit. Since we set weekday to 6 and set this value to 1, and since the next largest specified calendar unit was month, we’ll get the date of the first Friday of the month.

On my computer, the output is:

Donut Day 2020 happens on Friday, June 5, 2020 at 12:00:00 AM Eastern Daylight Time.

Note that in the absence of a specified time zone, the assumed time zone is the system time zone, which in my case is Eastern Daylight Time (UTC-4).

In the spirit of the fake book cover shown above, let’s see what happens when we use Donut Day 2020’s components, except for the month.

Add the following to the playground, then run it:

// Mystery Friday 2020
// -------------------------------
let mysteryFridayDateComponents = DateComponents(
  year: 2020,         // We want a date in 2020:
  weekday: 6,         // A Friday;
  weekdayOrdinal: 1   // the first one.
)

let mysteryFridayDate = userCalendar.date(from: mysteryFridayDateComponents)!
print("Mystery Friday happens on \(mysteryFridayDate.description(with: Locale(identifier: "en-US"))).")

On my computer, the output is:

Mystery Friday happens on Friday, January 3, 2020 at 12:00:00 AM Eastern Standard Time.

That makes sense: By specifying year 2020, weekday 6 and weekday ordinal 1, we just asked for the first Friday of the year.

Suppose you’re meeting up with a friend in Tokyo some relaxing Suntory times at 9:00 p.m. on the Thursday of the 27th week of 2020. What is that date?

The answer comes from this code:

// 9:00 p.m. Tokyo time on the Thursday of the 27th week of 2020
// -------------------------------------------------------------
var relaxingSuntoryTimesDateComponents = DateComponents(
  timeZone: TimeZone(identifier: "Asia/Tokyo")!,
  year: 2020,
  hour: 21,
  weekday: 5,
  weekOfYear: 27
)

let relaxingSuntoryTimesDate = userCalendar.date(from: relaxingSuntoryTimesDateComponents)!
print("Thursday on the 27th week of 2020 at 9:00 p.m. Tokyo time is \(relaxingSuntoryTimesDate.description(with: Locale(identifier: "en-US"))).")

On my computer, the output is:

Thursday on the 27th week of 2020 at 9:00 p.m. Tokyo time is Thursday, July 2, 2020 at 8:00:00 AM Eastern Daylight Time.

Here’s a simple question: What’s the 234th day of 2020?

Add the following to the playground, then run it:

// 234th day of 2020
// -----------------
let day234DateComponents = DateComponents(
  year: 2020,         // We want a date in 2020:
  day: 234            // the 234th day.
)

let day234Date = userCalendar.date(from: day234DateComponents)!
print("The 234th day of 2020 is \(day234Date.description(with: Locale(identifier: "en-US"))).")

On my computer, the output is:

The 234th day of 2020 is Friday, August 21, 2020 at 12:00:00 AM Eastern Daylight Time.

The “Ten Thousand Hour Rule”, which states that it takes 10,000 hours of directed practice to become an expert at something, was popularized by Malcolm Gladwell in his novel Blink. There’s been a lot of debate about the truth of the rule, and we’re going to side-step it to ask a related question: If I set out to get 10,000 hours of non-stop practice starting on midnight of January 1, 2020, when would I be done?

Add the following to the playground, then run it:

// 10000th hour of 2020
// -----------------
let hour10kDateComponents = DateComponents(
  year: 2020,         // We want a date in 2020:
  hour: 10000         // the 10000th hour.
)

let hour10kDate = userCalendar.date(from: hour10kDateComponents)!
print("Your 10,000 hours would complete on \(hour10kDate.description(with: Locale(identifier: "en-US"))).")

On my computer, the output is:

Your 10,000 hours would complete on Saturday, February 20, 2021 at 4:00:00 PM Eastern Standard Time.

In other words, 10,000 hours is longer than a year.

Let’s look at the case of overflow. What happens if you try to create a Date using components that would define the nonsense date September 50th, 2020?

Add the following to the playground, then run it:

// September 50, 2020
// ------------------
var sept50DateComponents = DateComponents(
  year: 2020,
  month: 9,
  day: 50)
let sept50Date = userCalendar.date(from: sept50DateComponents)!
print("September 50, 2020 is actually \(sept50Date.description(with: Locale(identifier: "en-US"))).")

On my computer, the output is:

September 50, 2020 is actually Tuesday, October 20, 2020 at 12:00:00 AM Eastern Daylight Time.

Swift treats these date components as “the start of September, plus 50 days” — September’s 30 days, plus an additional 20 days into October.

Let’s extract DateComponents from a Date, part 1

Now that we’ve created some Dates using DateComponents, let’s do the reverse and extract DateComponents from given Dates. We’ll continue with our playground and use a Date we’ve already created

Let’s extract the year, month, and day from firstLandPhoneCallDate, which corresponds to the date of Alexander Graham Bell’s historic phone call, March 10, 1876:

// We want to extract the year, month, and day from firstLandLineCallDate
let alexanderGrahamBellDateComponents = userCalendar.dateComponents([.year, .month, .day],
                                                                    from: firstLandLineCallDate)
print("The first land line phone call happened \(-firstLandLineCallDate.timeIntervalSinceNow) seconds ago.")
print("Year: \(alexanderGrahamBellDateComponents.year!)")
print("Month: \(alexanderGrahamBellDateComponents.month!)")
print("Day: \(alexanderGrahamBellDateComponents.day!)")

When I ran it on my computer, the output was:

The first land line phone call happened 4550860374.044979 seconds ago.
Year: 1876
Month: 3
Day: 10

Let’s extract DateComponents from a Date, part 2

This time, let’s extract the DateComponents from another Date we’d previously defined: The date and time of the “Stevenote” where the original iPhone was first announced:

It happened 190,058,400 seconds after the reference date. For most of us, this is a meaningless figure, so we’ll extract the following DateComponents from this Date:

• Year
• Month
• Day
• Hour
• Minute
• What day of the week it fell on
• What week of the year it fell on

Here’s the code:

// The original iPad Stevenote (10 a.m. Pacific time,
// January 27, 2010)
// ----------------------------------------------------
// We want to extract ALL the DateComponents for this date
// in local time for the event (which took place in San Francisco).

let iPadStevenoteDateComponents = pacificCalendar.dateComponents([.calendar,
                                                                  .day,
                                                                  .era,
                                                                  .hour,
                                                                  .minute,
                                                                  .month,
                                                                  .nanosecond,
                                                                  .quarter,
                                                                  .second,
                                                                  .timeZone,
                                                                  .weekday,
                                                                  .weekdayOrdinal,
                                                                  .weekOfMonth,
                                                                  .weekOfYear,
                                                                  .year,
                                                                  .yearForWeekOfYear],
                                                                 from: iPadStevenoteDate)
print("The original iPad Stevenote happened \(-iPadStevenoteDate.timeIntervalSinceNow) seconds ago.")
print("Calendar: \(iPadStevenoteDateComponents.calendar!.identifier)")
print("Day: \(iPadStevenoteDateComponents.day!)")
print("Era: \(iPadStevenoteDateComponents.era!)")
print("Hour: \(iPadStevenoteDateComponents.hour!)")
print("Minute: \(iPadStevenoteDateComponents.minute!)")
print("Month: \(iPadStevenoteDateComponents.month!)")
print("Nanosecond: \(iPadStevenoteDateComponents.nanosecond!)")
print("Quarter: \(iPadStevenoteDateComponents.quarter!)")
print("Second: \(iPadStevenoteDateComponents.second!)")
print("Time zone: \(iPadStevenoteDateComponents.timeZone!)")
print("Weekday: \(iPadStevenoteDateComponents.weekday!)")
print("Weekday ordinal: \(iPadStevenoteDateComponents.weekdayOrdinal!)")
print("Week of month: \(iPadStevenoteDateComponents.weekOfMonth!)")
print("Week of year: \(iPadStevenoteDateComponents.weekOfYear!)")
print("Year: \(iPadStevenoteDateComponents.year!)")
print("Year for week of year: \(iPadStevenoteDateComponents.yearForWeekOfYear!)")

Let’s extract DateComponents from a Date, part 3

Let’s try it again with another key iOS date — the Stevenote where the original iPad was announced:

This time, if you were to ask Swift when this Stevenote took place, it would reply “286,308,000 seconds after the reference date”. Let’s get all the DateComponents for this date:

// The original iPad Stevenote (10 a.m. Pacific time,
// January 27, 2010)
// ----------------------------------------------------
// We want to extract ALL the DateComponents for this date
// in local time for the event (which took place in San Francisco).

let iPadStevenoteDateComponents = pacificCalendar.dateComponents([.calendar,
                                                                  .day,
                                                                  .era,
                                                                  .hour,
                                                                  .minute,
                                                                  .month,
                                                                  .nanosecond,
                                                                  .quarter,
                                                                  .second,
                                                                  .timeZone,
                                                                  .weekday,
                                                                  .weekdayOrdinal,
                                                                  .weekOfMonth,
                                                                  .weekOfYear,
                                                                  .year,
                                                                  .yearForWeekOfYear],
                                                                from: iPadStevenoteDate)
print("The original iPad Stevenote happened \(-iPadStevenoteDate.timeIntervalSinceNow) seconds ago.")
print("Calendar: \(iPadStevenoteDateComponents.calendar!.identifier)")
print("Day: \(iPadStevenoteDateComponents.day!)")
print("Era: \(iPadStevenoteDateComponents.era!)")
print("Hour: \(iPadStevenoteDateComponents.hour!)")
print("Minute: \(iPadStevenoteDateComponents.minute!)")
print("Month: \(iPadStevenoteDateComponents.month!)")
print("Nanosecond: \(iPadStevenoteDateComponents.nanosecond!)")
print("Quarter: \(iPadStevenoteDateComponents.quarter!)")
print("Second: \(iPadStevenoteDateComponents.second!)")
print("Time zone: \(iPadStevenoteDateComponents.timeZone!)")
print("Weekday: \(iPadStevenoteDateComponents.weekday!)")
print("Weekday ordinal: \(iPadStevenoteDateComponents.weekdayOrdinal!)")
print("Week of month: \(iPadStevenoteDateComponents.weekOfMonth!)")
print("Week of year: \(iPadStevenoteDateComponents.weekOfYear!)")
print("Year: \(iPadStevenoteDateComponents.year!)")
print("Year for week of year: \(iPadStevenoteDateComponents.yearForWeekOfYear!)")

When I ran it on my computer, the output was:

The original iPad Stevenote happened 325902655.723246 seconds ago.
Calendar: gregorian
Day: 27
Era: 1
Hour: 10
Minute: 0
Month: 1
Nanosecond: 0
Quarter: 0
Second: 0
Time zone: America/Los_Angeles (fixed)
Weekday: 4
Weekday ordinal: 4
Week of month: 5
Week of year: 5
Year: 2010
Year for week of year: 2010

Let’s take a look at each DateComponents property and what it represents:

Wrapping it all up

Here’s the complete code for the playground containing all the code we just worked with while learning about dates and times in Swift 5:

import UIKit

// To create a Date representing the current date and time,
// simply initialize a new Date.
let now = Date()  // Contains the date and time that this object
                  // was instantiated.

// How many seconds have passed between the Date we just created
// and the reference date of January 1, 2001, 00:00:00 UTC?
print("It’s been \(now.timeIntervalSinceReferenceDate) seconds since the start of the Third Millennium.")


// Use Date’s description property for debugging
print(now.description)                                      // YYYY-MM-DD HH:MM:SS +HHMM
print(now.description(with: Locale(identifier: "en-US")))   // US English
print(now.description(with: Locale(identifier: "en-GB")))   // UK English*
print(now.description(with: Locale(identifier: "es")))      // Spanish
print(now.description(with: Locale(identifier: "zh-Hans"))) // Simplified Chinese

// * Yes, I know that “gb” means “Great Britain” and that it’s not the same thing
// as the UK. I didn’t come up with these locale names!


// Date’s other initializers expect arguments of type TimeInterval,
// which is a typealias for Double.

// To create a Date a specified number of seconds before or after
// the current date and time, use the "timeIntervalSinceNow" initializer.
let fiveMinutesAgo = Date(timeIntervalSinceNow: -5 * 60)
let fiveMinutesFromNow = Date(timeIntervalSinceNow: 5 * 60)

// Martin Cooper made the first cellular phone call on April 3, 1973.
// We don't know the exact time the call was made, but it happened
// sometime during business hours in New York City, in the U.S. Eastern
// Time Zone (UTC-5).
//
// Let’s suppose that he made the call at 12:00 p.m.. That would mean that
// he made the call 875,602,800 seconds BEFORE the reference date and time.
let firstCellularCallDate = Date(timeIntervalSinceReferenceDate: -875_602_800)

// The "Stevenote" where the iPhone was introduced started on January 9, 2007,
// 10 a.m. Pacific time (UTC-7), 190,058,400 seconds AFTER the reference date and time.
let iPhoneStevenoteDate = Date(timeIntervalSinceReferenceDate: 190_058_400)

// Unix time (a.k.a. POSIX time or Epoch Time) is the way time is represented
// by Unix, Unix-like, and other operating systems. It defines time as a
// number of seconds after the Unix Epoch, January 1, 1970, 00:00:00 UTC.
// To create a Date relative to the Unix Epoch, use the
// "timeIntervalSince1970" initializer.
let oneYear = TimeInterval(60 * 60 * 24 * 365)
let newYears1971 = Date(timeIntervalSince1970: oneYear)
let newYears1969 = Date(timeIntervalSince1970: -oneYear)

// To create a Date relative to another Date, use the
// "timeInterval:Since:" initializer.
//
// The "Stevenote" where the iPad was introduced started on January 27, 2010,
// 10 a.m. Pacific time (UTC-7), 96,249,600 seconds after the start of the
// iPhone Stevenote three years earlier.
let secondsBetweeniPhoneAndiPadStevenote = TimeInterval(96_249_600)
let iPadStevenoteDate = Date(timeInterval: secondsBetweeniPhoneAndiPadStevenote,
                             since: iPhoneStevenoteDate)



// To translate between Dates and DateComponents, you need a Calendar.
// The user's Calendar is probably the one you’ll use most often,
// as it incorporates the user's locale and time zone settings.
let userCalendar = Calendar.current


// March 10, 1876: The day Alexander Graham Bell
// made the first phone call in Boston (UTC-5)
// ---------------------------------------------
// DateComponents' full initializer method is very thorough, but very long.
let firstLandLineCallDateComponents = DateComponents(
  calendar: nil,
  timeZone: TimeZone(secondsFromGMT: -18000),
  era: nil,
  year: 1876,
  month: 3,
  day: 10,
  hour: 12,
  minute: 00,
  second: 00,
  nanosecond: nil,
  weekday: nil,
  weekdayOrdinal: nil,
  quarter: nil,
  weekOfMonth: nil,
  weekOfYear: nil,
  yearForWeekOfYear: nil)

let firstLandLineCallDate = userCalendar.date(from: firstLandLineCallDateComponents)!
print("The first land line phone call happened on \(firstLandLineCallDate.description(with: Locale(identifier: "en-US"))).")
print("That’s \(firstLandLineCallDate.timeIntervalSinceReferenceDate) seconds since the start of the Third Millennium.")


// December 9, 1968, 3:45 p.m. Pacific Time:
// Douglas Englebart gives “The Mother of All Demos”
// -------------------------------------------------
// This time, we’ll use only the DateComponents initializer parameters we need.
let motherOfAllDemosDateComponents = DateComponents(
  timeZone: TimeZone(identifier: "America/Los_Angeles"),
  year: 1968,
  month: 12,
  day: 9,
  hour: 15,
  minute: 45
)

let motherOfAllDemosDate = userCalendar.date(from: motherOfAllDemosDateComponents)!
print("The Mother of All Demos happened on \(motherOfAllDemosDate.description(with: Locale(identifier: "en-US"))).")
print("That’s \(motherOfAllDemosDate.timeIntervalSince1970) seconds since the start of the Unix Epoch.")


// April 3, 1973: Martin Cooper makes the first
// cellular phone call
// --------------------------------------------
var firstCellCallDateComponents = DateComponents()
firstCellCallDateComponents.year = 1973
firstCellCallDateComponents.month = 4
firstCellCallDateComponents.day = 3
firstCellCallDateComponents.timeZone = TimeZone(abbreviation: "EST")

let firstCellCallDate = userCalendar.date(from: firstCellCallDateComponents)!
print("Martin Cooper made the first cellular call on \(firstCellCallDate.description(with: Locale(identifier: "en-US"))).")
print("That’s \(firstCellCallDate.timeIntervalSince(motherOfAllDemosDate)) seconds since the Mother of All Demos.")



// The first Friday in June, 2020:
// National Donut Day
// -------------------------------
let donutDay2020DateComponents = DateComponents(
  year: 2020,         // We want a date in 2020,
  month: 6,           // in June.
  weekday: 6,         // We want a Friday;
  weekdayOrdinal: 1   // the first one.
)

let donutDay2020Date = userCalendar.date(from: donutDay2020DateComponents)!
print("Donut Day 2020 happens on \(donutDay2020Date.description(with: Locale(identifier: "en-US"))).")


// Mystery Friday 2020
// -------------------------------
let mysteryFridayDateComponents = DateComponents(
  year: 2020,         // We want a date in 2020:
  weekday: 6,         // A Friday;
  weekdayOrdinal: 1   // the first one.
)

let mysteryFridayDate = userCalendar.date(from: mysteryFridayDateComponents)!
print("Mystery Friday happens on \(mysteryFridayDate.description(with: Locale(identifier: "en-US"))).")


// 9:00 p.m. Tokyo time on the Thursday of the 27th week of 2020
// -------------------------------------------------------------
var relaxingSuntoryTimesDateComponents = DateComponents(
  timeZone: TimeZone(identifier: "Asia/Tokyo")!,
  year: 2020,
  hour: 21,
  weekday: 5,
  weekOfYear: 27
)

let relaxingSuntoryTimesDate = userCalendar.date(from: relaxingSuntoryTimesDateComponents)!
print("Thursday on the 27th week of 2020 at 9:00 p.m. Tokyo time is \(relaxingSuntoryTimesDate.description(with: Locale(identifier: "en-US"))).")


// 234th day of 2020
// -----------------
let day234DateComponents = DateComponents(
  year: 2020,         // We want a date in 2020:
  day: 234            // the 234th day.
)

let day234Date = userCalendar.date(from: day234DateComponents)!
print("The 234th day of 2020 is \(day234Date.description(with: Locale(identifier: "en-US"))).")


// 10000th hour of 2020
// -----------------
let hour10kDateComponents = DateComponents(
  year: 2020,         // We want a date in 2020:
  hour: 10000         // the 10000th hour.
)

let hour10kDate = userCalendar.date(from: hour10kDateComponents)!
print("Your 10,000 hours would complete on \(hour10kDate.description(with: Locale(identifier: "en-US"))).")


// September 50, 2020
// ------------------
var sept50DateComponents = DateComponents(
  year: 2020,
  month: 9,
  day: 50)
let sept50Date = userCalendar.date(from: sept50DateComponents)!
print("September 50, 2020 is actually \(sept50Date.description(with: Locale(identifier: "en-US"))).")


// Date of the first land line phone call (March 10, 1876)
// -------------------------------------------------------
// We want to extract the year, month, and day
let alexanderGrahamBellDateComponents = userCalendar.dateComponents([.year, .month, .day],
                                                                    from: firstLandLineCallDate)
print("The first land line phone call happened \(-firstLandLineCallDate.timeIntervalSinceNow) seconds ago.")
print("Year: \(alexanderGrahamBellDateComponents.year!)")
print("Month: \(alexanderGrahamBellDateComponents.month!)")
print("Day: \(alexanderGrahamBellDateComponents.day!)")


// The original iPhone Stevenote (10 a.m. Pacific time,
// January 9, 2007)
// ----------------------------------------------------
// We want to extract the year, month, day, hour, and minute from this date,
// in local time for the event (which took place in San Francisco).
// We also want to know what day of the week and week of the year
// this date fell on.

// Create a calendar set to Pacific standard time (UTC-8)
var pacificCalendar = Calendar(identifier: .gregorian)
pacificCalendar.timeZone = TimeZone(abbreviation: "PST")!

let iPhoneStevenoteDateComponents = pacificCalendar.dateComponents([.year,
                                                                 .month,
                                                                 .day,
                                                                 .hour,
                                                                 .minute,
                                                                 .weekday,
                                                                 .weekOfYear],
                                                                from: iPhoneStevenoteDate)
print("The original iPhone Stevenote happened \(-iPhoneStevenoteDate.timeIntervalSinceNow) seconds ago.")
print("Year: \(iPhoneStevenoteDateComponents.year!)")
print("Month: \(iPhoneStevenoteDateComponents.month!)")
print("Day: \(iPhoneStevenoteDateComponents.day!)")
print("Hour: \(iPhoneStevenoteDateComponents.hour!)")
print("Minute: \(iPhoneStevenoteDateComponents.minute!)")
print("Weekday: \(iPhoneStevenoteDateComponents.weekday!)")
print("Week of year: \(iPhoneStevenoteDateComponents.weekOfYear!)")


// The original iPad Stevenote (10 a.m. Pacific time,
// January 27, 2010)
// ----------------------------------------------------
// We want to extract ALL the DateComponents for this date
// in local time for the event (which took place in San Francisco).

let iPadStevenoteDateComponents = pacificCalendar.dateComponents([.calendar,
                                                                  .day,
                                                                  .era,
                                                                  .hour,
                                                                  .minute,
                                                                  .month,
                                                                  .nanosecond,
                                                                  .quarter,
                                                                  .second,
                                                                  .timeZone,
                                                                  .weekday,
                                                                  .weekdayOrdinal,
                                                                  .weekOfMonth,
                                                                  .weekOfYear,
                                                                  .year,
                                                                  .yearForWeekOfYear],
                                                                 from: iPadStevenoteDate)
print("The original iPad Stevenote happened \(-iPadStevenoteDate.timeIntervalSinceNow) seconds ago.")
print("Calendar: \(iPadStevenoteDateComponents.calendar!.identifier)")
print("Day: \(iPadStevenoteDateComponents.day!)")
print("Era: \(iPadStevenoteDateComponents.era!)")
print("Hour: \(iPadStevenoteDateComponents.hour!)")
print("Minute: \(iPadStevenoteDateComponents.minute!)")
print("Month: \(iPadStevenoteDateComponents.month!)")
print("Nanosecond: \(iPadStevenoteDateComponents.nanosecond!)")
print("Quarter: \(iPadStevenoteDateComponents.quarter!)")
print("Second: \(iPadStevenoteDateComponents.second!)")
print("Time zone: \(iPadStevenoteDateComponents.timeZone!)")
print("Weekday: \(iPadStevenoteDateComponents.weekday!)")
print("Weekday ordinal: \(iPadStevenoteDateComponents.weekdayOrdinal!)")
print("Week of month: \(iPadStevenoteDateComponents.weekOfMonth!)")
print("Week of year: \(iPadStevenoteDateComponents.weekOfYear!)")
print("Year: \(iPadStevenoteDateComponents.year!)")
print("Year for week of year: \(iPadStevenoteDateComponents.yearForWeekOfYear!)")

You can download the playground here (14KB, zipped Xcode playground file).

In the next installment in the How to work with dates and times in Swift 5 series, we’ll look at converting Dates to Strings, and vice versa.

The Dates and times in Swift 5 series

Here are the articles in this series:

• Part 1: Creating and deconstructing dates with the Date, Calendar, and DateComponents structs
• Part 2: Formatting and parsing dates and times with DateFormatter
• Part 3: Date arithmetic
• Part 4: Adding Swift syntactic magic