About Dates and Times

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.

Relevant Chapters: Dates

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.

Relevant Chapters: Calendars, Date Components, and Calendar Units

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.

Relevant Chapters: Performing Calendar Calculations

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.

Relevant Chapters: Using Time Zones

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.

Relevant Chapters: Historical Dates

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.

See Also

If you display dates and times to users or create dates from user input, read:

Data Formatting Guide , which explains how to create and format user-readable strings from date objects, and how to create date objects from formatted strings.

Next

Copyright © 2002, 2013 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2013-04-23