# Date​Components

There are as many mnemonic devices for making sense of time as the day is long. “Spring ahead, Fall back”. That knuckle trick for remembering the lengths of months. Musical theater aficionados can tell you in quick measure the length of a year in minutes. Mathematicians, though, have the best ones of all: Did you know that the fifth hyperfactorial (5⁵ × 4⁴ × 3³ × 2² × 1¹) is equal to 86400000, or exactly 1 (civil) day in milliseconds? Or that ten factorial (10! = 10 × 9 × 8… = 3628800) seconds is equal to 6 weeks?

Amazing, right? But I want you to forget all of those, at least for the purposes of programming.

As we discussed in our article about `Date`, et al., the only unit of time with a constant duration is the second (and its subdivisions). When you want to express the duration of, 1 day, don’t write `60 * 60 * 24`. Instead, write `DateComponents(day: 1)`.

“What is `DateComponents`”, you ask? It’s a relatively recent addition to Foundation for representing a date or duration of time, and it’s the subject of this article.

`DateComponents` is a useful, but ambiguous type.

Taken in one context, date components can be used to represent a specific calendar date. But in another context, the same object might instead be used as a duration of time. For example, a date components object with `year` set to `2018`, `month` set to `10`, and `day` set to `10` could represent a period of 2018 years, 10 months, and 10 days or the tenth day of the tenth month in the year 2018:

``````import Foundation

let calendar = Calendar.current
let dateComponents = DateComponents(calendar: calendar,
year: 2018,
month: 10,
day: 10)

// DateComponents as a date specifier
let date = calendar.date(from: dateComponents)! // 2018-10-10

// DateComponents as a duration of time
calendar.date(byAdding: dateComponents, to: date) // 4037-08-20
``````

Let’s explore both of these contexts individually, starting with date components as a representation of a calendar date:

## Date Components as a Representation of a Calendar Date

### Extracting Components from a Date

`DateComponents` objects can be created for a particular date using the `Calendar` method `components(_:from:)`:

``````let date = Date() // 2018-10-10T10:00:00+00:00
let calendar = Calendar.current
calendar.dateComponents([.year, .month, .day], from: date)
// (year: 2018, month: 0, day: 10)
``````

Each property in `DateComponents` has a corresponding entry in the `Calendar.Component` enumeration.

For reference, here’s what the `dateComponents(_:from:)` method produces when you specify all of the available calendar units:

``````import Foundation

let date = Date() // 2018-10-10T10:00:00+00:00
let calendar = Calendar.current
let dateComponents = calendar.dateComponents(
[.calendar, .timeZone,
.era, .quarter,
.year, .month, .day,
.hour, .minute, .second, .nanosecond,
.weekday, .weekdayOrdinal,
.weekOfMonth, .weekOfYear, .yearForWeekOfYear],
from: date)
``````
Component Value
`calendar` gregorian
`timeZone` America/Los_Angeles
`era` 1
`quarter` 0
`year` 2018
`month` 10
`day` 10
`hour` 10
`minute` 0
`second` 0
`nanosecond` 0
`weekday` 4
`weekdayOrdinal` 2
`weekOfMonth` 2
`weekOfYear` 41
`yearForWeekOfYear` 2018
`isLeapMonth` false

One of the advantages of learning Foundation APIs is that you gain a deeper understanding of the domains that it models. Unless you’re a horologist or ISO 8601 enthusiast, there are probably a few of these components that you’re less familiar with, so let’s take a look at some of the more obscure ones:

### Era and Year

The Gregorian calendar has two eras: BC and AD (alternatively, C.E. and B.C.E). Their respective integer date component values are `0` and `1`. No matter what the era is, the `year` component is always a positive number.

### Quarter

In academia and business, calendar years are often divided up into quarter (Q1, Q2, Q3, Q4).

### Weekday, Weekday Ordinal, and Week of Month

Weekdays are given integer values starting with 1 for Sunday and ending with 7 for Saturday.

But the first weekday varies across different locales. The first weekday in the calendar depends on your current locale. The United States, China, and other countries begin their weeks on Sunday. Most countries in Europe, as well as India, Australia, and elsewhere typically designate Monday as their first weekday. Certain locales in the Middle East and North Africa use Saturday as the start of their week.

The locale also affects the values returned for the `weekdayOrdinal` and `weekOfMonth` components. In the `en-US` locale, the date components returned for October 7th, 2018 would have `weekdayOrdinal` equal to 1 (meaning “the first Sunday of the month”) and a `weekOfMonth` value of 2 (meaning “the second week of the month”).

### Week of Year and Year for Week of Year

These two are probably the most confusing of all the date components. Part of that has to do with the ridiculous API name `yearForWeekOfYear`, but it mostly comes down to the lack of general awareness for ISO week dates.

The `weekOfYear` component returns the ISO week number for the date in question. For example, October 10th, 2018 occurs on the 41st ISO week.

The `yearForWeekOfYear` component is helpful for weeks that span two calendar years. For example, New Years Eve this year — December 31st, 2018 — falls on a Monday. Because occurs in the first week of 2019, its `weekOfYear` value is `1`, its `yearForWeekOfYear` value is `2019`, and its `year` value is `2018`

### Creating a Date from Date Components

In addition to extracting components from a date, we can go the opposite direction to create a date from components using the `Calendar` method `date(from:)`.

Use it the next time you need to initialize a static date as a more performant and reliable way than parsing a timestamp with a date formatter.

``````var date: Date?

let timestamp = "2018-10-03"
let formatter = ISO8601DateFormatter()
formatter.formatOptions =
[.withFullDate, .withDashSeparatorInDate]
date = formatter.date(from: timestamp)

// Good
let calendar = Calendar.current
let dateComponents =
DateComponents(calendar: calendar,
year: 2018, month: 10, day: 3)
date = calendar.date(from: dateComponents)
``````

When date components are used to represent a date, there’s still some ambiguity. Date components can be (and often are) under-specified, such that the values of components like `era` or `hour` are inferred from additional context. When you use the `date(from:)` method, what you’re really doing is telling `Calendar` to search for the next date that satisfies the criteria you specified.

Sometimes this isn’t possible, like if date components have contradictory values (such as `weekOfYear = 1` and `weekOfMonth = 3`), or a value in excess of what a calendar allows (such as an `hour = 127`). In these cases, `date(from:)` returns `nil`.

### Getting the Range of a Calendar Unit

A common task when working with dates is to get the start of day, week, month, or year. Although it’s possible to do this with `DateComponents` creating a new date with a subset of date component values, a better way would be to use the `Calendar` method `dateInterval(of:for:)`:

``````let date = Date() // 2018-10-10T10:00:00+00:00
let calendar = Calendar.current

var beginningOfMonth: Date?

// OK
let dateComponents =
calendar.dateComponents([.year, .month], from: date)
beginningOfMonth = calendar.date(from: dateComponents)

// Better
beginningOfMonth =
calendar.dateInterval(of: .month, for: date)?.start
``````

## Calculating the Distance Between Two Dates

Picking up from the previous example — you can use the `Calendar` method `dateComponents(_:from:to:)` to calculate the time between two dates in terms of your desired units.

How long is the month of October in hours?

``````let date = Date() // 2018-10-10T10:00:00+00:00
let calendar = Calendar.current

let monthInterval =
calendar.dateInterval(of: .month, for: date)!

calendar.dateComponents([.hour],
from: monthInterval.start,
to: monthInterval.end)
.hour // 744
``````

Another frequent programming task is to calculate a date from an offset like “tomorrow” or “next week”.

If you’re adding a single calendar component value, you can use the `Calendar` method `date(byAdding:value:to:)`:

``````let date = Date() // 2018-10-10T10:00:00+00:00
let calendar = Calendar.current

var tomorrow: Date?

tomorrow = date.addingTimeInterval(60 * 60 * 24)

// Good
value: 1,
to: date)
``````

For more than one calendar component value, use the `date(byAdding:to:)` method instead, passing a `DateComponents` object.

``````let date = Date()
let calendar = Calendar.current

calendar.date(byAdding: .year, value: 1, to: date)

// Adding a year and a day
let dateComponents = DateComponents(year: 1, day: 1)
``````

If you really want to be pedantic when time traveling, though, the method you’re looking for is `nextDate(after:matching:matchingPolicy:repeatedTimePolicy:direction:)`. For example, if you wanted to find the date corresponding to the next time with the same time components (hour, minute, second, nanosecond) and wanted to be specific about how to handle phenomena like 2:59AM occurring twice on November 4th, 2018, here’s how you might do that:

``````let dateComponents =
calendar.dateComponents([.hour,
.minute,
.second,
.nanosecond],
from: date)

tomorrow = calendar.nextDate(after: date,
matching: dateComponents,
matchingPolicy: .nextTime,
repeatedTimePolicy: .first,
direction: .forward)
``````

So there you have it! Now you know how to do calendar arithmetic correctly using `Calendar` and `DateComponents`.

Are you multiplying seconds? Don’t! /
Instead, use `(NS)DateComponents`*

* `NS` prefix added to make the meter work. Thanks, Swift 3.

NSMutableHipster

Questions? Corrections? Issues and pull requests are always welcome.

This article uses Swift version 4.2 and was last reviewed on October 10, 2018. Find status information for all articles on the status page.

Written by
Mattt

Mattt (@mattt) is a writer and developer in Portland, Oregon.

Next Article

# CFString​Transform

NSString is the crown jewel of Foundation. But as powerful as it is, one would be remiss not to mention its toll-free bridged cousin, CFMutableString—or more specifically, CFStringTransform.