About Dates and Times

Date and time objects allow you to store references to particular instances in time. You can use date and time objects to perform calculations and comparisons that account for the corner cases of date and time calculations.

At a Glance

There are three main classes used for working with dates and times.

NSDate allows you to represent an absolute point in time.
NSCalendar allows you to represent a particular calendar, such as a Gregorian or Hebrew calendar. It provides the interface for most date-based calculations and allows you to convert between NSDate objects and NSDateComponents objects.
NSDateComponents allows you to represent the components of a particular date, such as hour, minute, day, year, and so on.

In addition to these classes, NSTimeZone allows you to represent a geopolitical region’s time zone information. It eases the task of working across different time zones and performing calculations that may be affected by daylight savings time transitions.

Creating and Using Date Objects to Represent Absolute Points in Time

Date objects represent dates and times in Cocoa. Date objects allow you to store absolute points in time which are meaningful across locales, calendars and timezones.

Working with Calendars and Date Components

Date components allow you to break a date down into the various parts that comprise it, such as day, month, year, hour, and so on. Calendars represent a particular form of reckoning time, such as the Gregorian calendar or the Chinese calendar. Calendar objects allow you to convert between date objects and date component objects, as well as from one calendar to another.

Performing Date and Time Calculations

Calendars and date components allow you to perform calculations such as the number of days or hours between two dates or finding the Sunday in the current week. You can also add components to a date or check when a date falls.

Working with Different Time Zones

Time zone objects allow you to present absolute times as local—that is, wall clock—time. In addition to time offsets, they also keep track of daylight saving time differences. Proper use of time zone objects can avoid issues such as miscalculation of elapsed time due to daylight saving time transitions or the user moving to a different time zone.

Special Considerations for Historical Dates

Dates in the past have a number of edge cases that do not exist for contemporary dates. These include issues such as dates that do not exist in a particular calendar—such as the lack of the year 0 in the Gregorian calendar— or calendar transitions—such as the Julian to Gregorian transition in the Middle Ages. There are also eras with seemingly backward time flow—such as BCE dates in the Gregorian calendar.

How to Use this Document

If your application keeps track of dates and times, read from Dates to Using Time Zones. The NSDate, NSCalendar, NSDateComponents, and NSTimeZone classes described in these chapters work together to store, compare, and manipulate dates and times.

If your application deals with dates in the past—particularly prior to the early 1900s, also read Historical Dates to learn about some of the issues that can arise when dealing with dates in the past.

Date and Time Programming Guide