<!--
{
  "availability" : [
    "iOS: 2.0.0 -",
    "iPadOS: 2.0.0 -",
    "macCatalyst: 13.0.0 -",
    "macOS: 10.0.0 -",
    "tvOS: 9.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 2.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Foundation",
  "identifier" : "/documentation/Foundation/NSCalendar/components(_:from:to:options:)-84y5w",
  "metadataVersion" : "0.1.0",
  "role" : "Instance Method",
  "symbol" : {
    "kind" : "Instance Method",
    "modules" : [
      "Foundation"
    ],
    "preciseIdentifier" : "c:objc(cs)NSCalendar(im)components:fromDate:toDate:options:"
  },
  "title" : "components(_:from:to:options:)"
}
-->

# components(_:from:to:options:)

Returns the difference between two supplied dates as date components.

```
func components(_ unitFlags: NSCalendar.Unit, from startingDate: Date, to resultDate: Date, options opts: NSCalendar.Options = []) -> DateComponents
```

## Parameters

`unitFlags`

Specifies the components for the returned `NSDateComponents` object.

`startingDate`

The start date for the calculation.

`resultDate`

The end date for the calculation.

`opts`

Options for the calculation.  For possible values, see [`NSCalendar.Options`](/documentation/Foundation/NSCalendar/Options).

    If you specify a “wrap” option ([`wrapComponents`](/documentation/Foundation/NSCalendar/Options/wrapComponents)    ), 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.

## Discussion

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`):

```objc
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

[`date(from:)`](/documentation/Foundation/NSCalendar/date(from:))

Returns a date representing the absolute time calculated from given components.

[`date(byAdding:to:options:)`](/documentation/Foundation/NSCalendar/date(byAdding:to:options:))

Returns a date representing the absolute time calculated by adding given components to a given date.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)