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.
NSDateallows you to represent an absolute point in time.
NSCalendarallows 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
NSDateComponentsallows 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
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.
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.