In Bite #287, we built a small extension to Date to allow us to format relative date strings like "10 minutes ago". We used a bunch of if statements and built our final String. This was a nice way to learn about working with DateComponents, but it turns out 🛎  Foundation actually provides a class to do something similar, and it's much more powerful.

Today we'll continue our look at Foundation's date and time-related functionality with DateComponentsFormatter. Let's dive in.

Much like its cousin DateFormatter (Bite #286), DateComponentsFormatter is all about converting a TimeInterval or DateComponents into a nicely formatted, human-readable String. (Note: It doesn't support parsing Strings yet. Conversions are a one way trip for now).

We'll start with a new formatter:

let formatter = DateComponentsFormatter()

Then we'll configure a few options:

formatter.unitsStyle = .full
formatter.allowedUnits = [.minute, .second]

And finally, we'll ask for a String describing an example TimeInterval:

formatter.string(from: 543.0) // "9 minutes, 3 seconds"

Like many Foundation types, DateComponentsFormatter is a super customizable powerhouse. Let's try a few more options:

formatter.unitsStyle = .abbreviated
formatter.string(from: 123.0)

// "2m 3s"

formatter.unitsStyle = .short
formatter.string(from: 123.0)

// "2 min, 3 sec"

formatter.unitsStyle = .spellOut
formatter.string(from: 123.0)

// "two minutes, three seconds"

formatter.includesApproximationPhrase = true
formatter.includesTimeRemainingPhrase = true
formatter.unitsStyle = .brief
formatter.string(from: 123.0)

// "About 2min 3sec remaining"

Neat. Fun Fact: If you've ever seen a progress bar or "time remaining" bar in iOS or macOS, you've seen a DateComponentsFormatter in action.

We've only been allowing .minutes and .seconds. Let's try allowing some different sets of units:

let formatter = DateComponentsFormatter()

formatter.unitsStyle = .full

formatter.allowedUnits = [.minute, .second]
formatter.string(from: 1234567.0)

// "20,576 minutes, 7 seconds"

formatter.allowedUnits = [.day, .hour, .minute, .second]
formatter.string(from: 1234567.0)

// "14 days, 6 hours, 56 minutes, 7 seconds"

formatter.allowedUnits = [.day, .minute, .second]
formatter.string(from: 1234567.0)

// "14 days, 416 minutes, 7 seconds"

Neat!

These are just the very basics. Look out for some more advanced DateComponentsFormatter fun soon.

In Bite #286, we looked at the basics of using DateFormatters to transform Dates into Strings.

Today we'll explore another common use case of Dates in our apps: "relative" date strings.

Think "2 days ago", "10 minutes ago", "Yesterday", and "Just now". Representing timestamps this way has become common, and it can help our users more quickly understand how old a piece of content is.

Let's add this functionality to our app by extending Date to give it a new computed property to do this.

We'll begin by adding a new File to our Xcode Project. We'll call it Date+Relative.swift. (The Type+SomeExtensionName convention is borrowed from Objective-C.

Then, we'll set up our extension:

extension Date {
  var relativelyFormatted: String {
    // TODO
  }
}

Nice. Next, we'll need a way to calculate how much time is in between now, and self (from the extended Date's point of view). We could do a bunch of ugly math, but we've got a better way!

This is a fantastic use case for Foundation's DateComponents type. It has a function that can calculate the difference between two Dates, and provide it to us in neatly (pre-calculated) components like days, months, hours, seconds, etc.

We'll begin our implementation like so:

let now = Date()

let components = Calendar.current.dateComponents(
  [.year, .month, .weekOfYear, .day, .hour, .minute, .second],
  from: now,
  to: self
)

We ask the current Calendar to please calculate the quantity of each of the components we passed in for the time between the Date we passed in as the from argument to the Date we passed into the to argument.

Beautiful. Now, the returned DateComponents type has a bunch of properties we'll use to build our relatively formatted date `String.

Finally, we'll inspect each date component (starting with most broad at the top) and return a nicely formatted String:

if let years = components.year, years > 0 {
  return "\(years) year\(years == 1 ? "" : "s") ago"
}

if let months = components.month, months > 0 {
  return "\(months) month\(months == 1 ? "" : "s") ago"
}

if let weeks = components.weekOfYear, weeks > 0 {
  return "\(weeks) week\(weeks == 1 ? "" : "s") ago"
}

if let days = components.day, days > 0 {
  guard days > 1 else { return "yesterday" }

  return "\(days) day\(days == 1 ? "" : "s") ago"
}

if let hours = components.hour, hours > 0 {
  return "\(hours) hour\(hours == 1 ? "" : "s") ago"
}

if let minutes = components.minute, minutes > 0 {
  return "\(minutes) minute\(minutes == 1 ? "" : "s") ago"
}

if let seconds = components.second, seconds > 30 {
  return "\(seconds) second\(seconds == 1 ? "" : "s") ago"
}

return "just now"

Doing things manually like this allows us to completely customize and control exactly how this relative date strings appear in our app.

This is fairly straightforward. We get a little fancy for the "days" component, allowing for "yesterday". We could also easily add support for future dates (i.e. "tomorrow") here as well.

All that's left to do is test it out. We can do that easily by constructing some Dates in the past, then printing our new property:

Date(timeIntervalSinceNow: 1).relativelyFormatted
// "just now"

Date(timeIntervalSinceNow: 12).relativelyFormatted
// "just now"

Date(timeIntervalSinceNow: 58).relativelyFormatted
// "58 seconds ago"

Date(timeIntervalSinceNow: 123).relativelyFormatted
// "2 minutes ago"

Date(timeIntervalSinceNow: 1234).relativelyFormatted
// "20 minutes ago"

Date(timeIntervalSinceNow: 12345).relativelyFormatted
// "3 hours ago"

Date(timeIntervalSinceNow: 123456).relativelyFormatted
// "yesterday"

Date(timeIntervalSinceNow: 1234567).relativelyFormatted
// "2 weeks ago"

Date(timeIntervalSinceNow: 12345689).relativelyFormatted
// "2 months ago"

Date(timeIntervalSinceNow: 123456890).relativelyFormatted
// "3 years ago"

Date(timeIntervalSinceNow: 1234568901)
  .relativelyFormatted // "39 years ago"

Date(timeIntervalSinceNow: 12345689012)
  .relativelyFormatted // "391 years ago"

Formatting dates and times is one of those common tasks we all have to do in almost every app. Today we'll take a look at how to use Foundation's solution for this: DateFormatter.

DateFormatters are incredibly powerful. Their core purpose is transforming Dates into Strings and Strings into Dates. They handle things like localization for us under the hood. Let's try one out.

We'll create a new formatter:

let formatter = DateFormatter()

Then we'll need to set a "format" on it. This is a string of characters that represent the date we're going to try to parse or render. Often these appear as one or more repeated series of letters like:

formatter.dateFormat = "MMM yyyy"

To see a rendered date string using this format, we can ask for one like this:

formatter.string(from: Date()) // "Jan 2017"

We can play around with the format for different results:

formatter.dateFormat = "MMMM yy"
formatter.string(from: Date()) // "January 17"

Neat. Let's try going the other way. We'll pass in a string, and ask our DateFormatter to parse it into a Date for us.

formatter.dateFormat = "MMMM yy"
formatter.date(from: "February 28")

// "Feb 1, 2028, 12:00 AM"

Very cool.

A couple of pro tips before we go:

The first is that DateFormatters have historically been heavy-weight objects to create. Performance has definitely improved over the years, but if we can, it's probably a good idea to keep one around instead of creating on the fly each time we need it. (For example we wouldn't want to be creating a new DateFormatter inside a UITableView or UICollectionView "cell for row" style delegate function).

The second is that these format strings are opaque and hard to understand at a glance. To solve this, friend of the show (and creator of the awesome NSScreencasts) Ben Scheirman has created a site called nsdateformatter.com.

There we can not only find easy, glance-able examples and references for all the different date format tokens, but we can also test out formats right there in the browser! Super handy.

We've only scratched the surface of what Foundation is capable of when it comes to Dates. Tune in tomorrow to learn more.