Christian Beer

Christian Beer

Hands on Tutorial to NSDateComponents

Calculating dates is quite a hard thing to do. You need to keep in mind that adding or subtracting days (or months, hours, …) to a date can lead to changing months or even years: Getting the date of “two days before the first of January” leads to substract a year and a month from the current date, the result is the 29th of December a year before. You even need to keep leap years in mind.

But there are tools in Cocoa that takes all the heavy stuff off of calculating dates: the NSDate, NSCalendar and NSDateComponents classes. There are (at minimum) two things you can do using NSDateComponents: get components of a date and calculate new dates by changing components.

Getting Date Components

Getting date components of a given NSDate is very easy using NSDateComponents:

-(int)month:(NSDate*)date { NSDateComponents *comps = [[NSCalendar currentCalendar] components:NSMonthCalendarUnit fromDate:date]; return comps.month; }

To access components of a given NSDate we are using NSCalendar to get a group of components of it. Here we are interested in the month. So at first we are asking NSCalendar for the NSMonthCalendarUnit of our given date.

After that we can access the specified units from the NSDateComponent. What’s important to know is that accessing units we didn’t specify on components:fromDate won’t give the correct values but more or less random values.

You can also use NSDateComponents to get a date that only contains the values for given components. For example you can get a NSDate that contains the beginning of the day without hours, minutes, seconds, etc.:

NSDate *date = [NSDate date]; NSDateComponents *comps = [[NSCalendar currentCalendar] components:(NSYearCalendarUnit | NSMonthCalendarUnit | NSDayCalendarUnit) fromDate:date]; NSDate *beginningOfDay = [[NSCalendar currentCalendar] dateFromComponents:comps];

Calculating New Dates

To calculate new dates from a given date, you can configure a NSDateComponents instance as an offset to a date:

-(NSDate *)previousMonth:(NSDate*)date { NSDateComponents *comps = [[NSDateComponents alloc] init]; [comps setMonth:-1]; NSCalendar *cal = [NSCalendar currentCalendar]; NSDate *date = [cal dateByAddingComponents:comps toDate:date options:0]; [comps release]; return date; }

At first we instantiate a NSDateComponent and configure it with the offsets we want to add to the NSDate. In this example we want to calculate the date a month before today so we set the month to -1.

After that we create a new NSDate by adding the components to the given date.


NSDateComponents provides some really great functionality for creating dates with only requested components and to calculate dates as offsets from a given date. The class ensures that the calculated date is valid.

For my projects I created a NSDate category that provides some convenient methods to get date components and calculated dates.