Instance Method


Returns the difference between two supplied dates as date components.


- (NSDateComponents *)components:(NSCalendarUnit)unitFlags fromDate:(NSDate *)startingDate toDate:(NSDate *)resultDate options:(NSCalendarOptions)opts;



Specifies the components for the returned NSDateComponents object.


The start date for the calculation.


The end date for the calculation.


Options for the calculation. For possible values, see NSCalendarOptions.

If you specify a “wrap” option (NSCalendarWrapComponents), the specified components are incremented and wrap around to zero/one on overflow, but do not cause higher units to be incremented. When the wrap option is not specified, overflow in a unit carries into the higher units, as in typical addition.

Return Value

An NSDateComponents object whose components are specified by unitFlags and calculated from the difference between the resultDate and startDate using the options specified by options. Returns nil if either date falls outside the defined range of the receiver or if the computation cannot be performed.


The result is lossy if there is not a small enough unit requested to hold the full precision of the difference. Some operations can be ambiguous, and the behavior of the computation is calendar-specific, but generally larger components will be computed before smaller components; for example, in the Gregorian calendar a result might be 1 month and 5 days instead of, for example, 0 months and 35 days. The resulting component values may be negative if resultDate is before startDate.

The following example shows how to get the approximate number of months and days between two dates using an existing calendar (gregorian):

NSDate *startDate = ...;
NSDate *endDate = ...;
unsigned int unitFlags = NSMonthCalendarUnit | NSDayCalendarUnit;
NSDateComponents *comps = [gregorian components:unitFlags fromDate:startDate  toDate:endDate  options:0];
int months = [comps month];
int days = [comps day];

Note that some computations can take a relatively long time.

See Also

Extracting Components

- date:matchesComponents:

Returns whether a given date matches all of the given date components.

- component:fromDate:

Returns the specified date component from a given date.

- components:fromDate:

Returns the date components representing a given date.

- components:fromDateComponents:toDateComponents:options:

Returns the difference between start and end dates given as date components.

- componentsInTimeZone:fromDate:

Returns all the date components of a date, as if in a given time zone (instead of the receiving calendar’s time zone).

- getEra:year:month:day:fromDate:

Returns by reference the era, year, week of year, and weekday component values for a given date.

- getEra:yearForWeekOfYear:weekOfYear:weekday:fromDate:

Returns by reference the era, year, week of year, and weekday component values for a given date.

- getHour:minute:second:nanosecond:fromDate:

Returns by reference the hour, minute, second, and nanosecond component values for a given date.