Click the diagram to see it at full size.
In the previous article in this series, we looked at three key structs for date and time programming in Swift:
Date represents a single point in time, using a format that can easily be translated into just about any calendar and time-reckoning system: a number of seconds relative to the start of the Third Millennium (January 1, 2001, 00:00:00 UTC).
DateComponents specifies time units like year, month, day, hour, minute, and more to represent either a point in time or a duration of time.
Calendar provides a context for Dates, and converts Dates to DateComponents and DateComponents to Dates.
These structs all deal with the internal representation of dates and times. In this article, we’ll look at the DateFormatter class, which allows us to deal with their external representation — by converting Dates into Strings, and properly-formatted Strings into Dates.
Let’s convert a Date into a String, part 1: Just the date
Start a new playground and enter the following code, which gives us a Date that we can format — the day when Alexander Graham Bell made the very first phone call:
Now let’s try turning this date into a string with a DateFormatter:
You may be surprised that the result is an empty String. This can be fixed by specifying a dateStyle:
Let’s try the other dateStyles:
Why would there be a dateStyle called .none? I’ll explain in a little bit.
Let’s convert a Date into a String, part 2: A date and a time
Let’s work with an event for which we know both the date and time: the “Stevenote” where the iPad was introduced, which started on January 27, 2010, at 10:00 a.m. Pacific Time (UTC-8). We’ll define this as a Date by adding the following code:
Now that we have a date and time, let’s format it using the dateStyle and timeStyle properties:
Now that we’re working with a date and time, let’s see what the .none style is for:
Remember that in Swift, the Date struct represents a single point in time, which has both a date and a time. The .none style for DateFormatter‘s dateStyle and timeStyle properties allows us to create a String representation of a Date that shows only its date or time part.
Let’s convert a Date into a String, part 3: Custom date/time formats
Before we begin working with custom date/time formats, I should point out that if you need to display a Date as a String to the user, it’s best if you use Swift’s built-in dateStyle and timeStyle values. They display dates and times properly, according to the user’s settings, which include country and language. You’d be surprised how date formats differ from culture to culture, and it’s better to let Swift do the formatting work.
However, there are times when you need to format dates and times in a specific way that doesn’t match the styles provided by DateFormatter‘s dateStyle and timeStyle properties, such as when dealing with certain APIs. That’s where DateFormatter‘s dateFormat property comes in handy:
You can use the date format specifiers listed in Appendix F of the Unicode Technical Standard #35 to define the formatting String for the dateFormat property. Here are some examples:
Let’s convert a String into a Date
DateFormatter works the other way — just as it can convert Dates to Strings, it can also convert Strings to Dates. By setting its dateFormat to the format of the String it should expect, you can use its date(from:) method to convert a String into a Date:
Let’s change the dateFormat string and try it again:
Wrapping it all up
Here’s a playground containing all the code we just worked with:
In the next installment, we’ll look at date calculations.