<!--
{
  "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/NSDateComponents",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Foundation"
    ],
    "preciseIdentifier" : "c:objc(cs)NSDateComponents"
  },
  "title" : "NSDateComponents"
}
-->

# NSDateComponents

An object that specifies a date or time in terms of units (such as year, month, day, hour, and minute) to be evaluated in a calendar system and time zone.

```
class NSDateComponents
```

## Overview

In Swift, this object bridges to [`DateComponents`](/documentation/Foundation/DateComponents); use [`NSDateComponents`](/documentation/Foundation/NSDateComponents) when you need reference semantics or other Foundation-specific behavior.

[`NSDateComponents`](/documentation/Foundation/NSDateComponents) encapsulates the components of a date in an extendable, object-oriented manner. It’s used to specify a date by providing the temporal components that make up a date and time: hour, minutes, seconds, day, month, year, and so on. You can also use it to specify a duration of time, for example, 5 hours and 16 minutes. An [`NSDateComponents`](/documentation/Foundation/NSDateComponents) object is not required to define all the component fields. When a new instance of [`NSDateComponents`](/documentation/Foundation/NSDateComponents) is created, the date components are set to [`NSDateComponentUndefined`](/documentation/Foundation/NSDateComponentUndefined).

> Important:
> An ``doc://com.apple.foundation/documentation/Foundation/NSDateComponents`` object is meaningless in itself; you need to know what calendar it is interpreted against, and you need to know whether the values are absolute values of the units, or quantities of the units.

An instance of [`NSDateComponents`](/documentation/Foundation/NSDateComponents) is not responsible for answering questions about a date beyond the information with which it was initialized. For example, if you initialize one with May 4, 2017, its weekday is [`NSDateComponentUndefined`](/documentation/Foundation/NSDateComponentUndefined), not Thursday. To get the correct day of the week, you must create a suitable instance of [`NSCalendar`](/documentation/Foundation/NSCalendar), create an [`NSDate`](/documentation/Foundation/NSDate) object using [`date(from:)`](/documentation/Foundation/NSCalendar/date(from:)) and then use [`components(_:from:)`](/documentation/Foundation/NSCalendar/components(_:from:)) to retrieve the weekday—as illustrated in the following example.

```objc
NSDateComponents *dateComponents = [[NSDateComponents alloc] init];
dateComponents.day = 4;
dateComponents.month = 5;
dateComponents.year = 2017;
 
NSCalendar *gregorianCalendar = [[NSCalendar alloc] initWithCalendarIdentifier:NSCalendarIdentifierGregorian];
NSDate *date = [gregorianCalendar dateFromComponents:dateComponents];
 
NSInteger weekday = [gregorianCalendar component:NSCalendarUnitWeekday fromDate:date];
NSLog(@"%d", weekday); // 5, which corresponds to Thursday in the Gregorian Calendar
```

For more details, see [Calendars, Date Components, and Calendar Units](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/DatesAndTimes/Articles/dtCalendars.html#//apple_ref/doc/uid/TP40003470) in [Date and Time Programming Guide](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/DatesAndTimes/DatesAndTimes.html#//apple_ref/doc/uid/10000039i).

> Important:
> The Swift overlay to the Foundation framework provides the ``doc://com.apple.foundation/documentation/Foundation/DateComponents`` structure, which bridges to the ``doc://com.apple.foundation/documentation/Foundation/NSDateComponents`` class. For more information about value types, see <doc://com.apple.documentation/documentation/Swift/working-with-foundation-types>.

## Topics

### Setting a Calendar and Time Zone

[`calendar`](/documentation/Foundation/NSDateComponents/calendar)

The calendar used to interpret the date components.

[`timeZone`](/documentation/Foundation/NSDateComponents/timeZone)

The time zone used to interpret the date components.

### Validating a Date

[`validDate`](/documentation/Foundation/NSDateComponents/isValidDate)

A Boolean value that indicates whether the current combination of properties represents a date which exists in the current calendar.

[`-  isValidDateInCalendar:`](/documentation/Foundation/NSDateComponents/isValidDate(in:))

Returns a Boolean value that indicates whether the current combination of properties represents a date which exists in the specified calendar.

[`date`](/documentation/Foundation/NSDateComponents/date)

The date calculated from the current components using the stored calendar.

[Undefined Components](/documentation/Foundation/1430344-undefined-components)

Constants that denote that the value of a date component is undefined.

  <doc:1430344-undefined_components>

### Accessing Years and Months

[`era`](/documentation/Foundation/NSDateComponents/era)

The number of eras.

[`year`](/documentation/Foundation/NSDateComponents/year)

The number of years.

[`yearForWeekOfYear`](/documentation/Foundation/NSDateComponents/yearForWeekOfYear)

The ISO 8601 week-numbering year.

[`quarter`](/documentation/Foundation/NSDateComponents/quarter)

The number of quarters.

[`month`](/documentation/Foundation/NSDateComponents/month)

The number of months.

[`leapMonth`](/documentation/Foundation/NSDateComponents/isLeapMonth)

A Boolean value that indicates whether the month is a leap month.

### Accessing Weeks and Days

[`weekday`](/documentation/Foundation/NSDateComponents/weekday)

The number of the weekdays.

[`weekdayOrdinal`](/documentation/Foundation/NSDateComponents/weekdayOrdinal)

The ordinal number of weekdays.

[`weekOfMonth`](/documentation/Foundation/NSDateComponents/weekOfMonth)

The week number of the months.

[`weekOfYear`](/documentation/Foundation/NSDateComponents/weekOfYear)

The ISO 8601 week date of the year.

[`day`](/documentation/Foundation/NSDateComponents/day)

The number of days.

[`-  week`](/documentation/Foundation/NSDateComponents/week())

Returns the number of weeks.

[`-  setWeek:`](/documentation/Foundation/NSDateComponents/setWeek(_:))

Sets the number of weeks.

### Accessing Hours and Seconds

[`hour`](/documentation/Foundation/NSDateComponents/hour)

The number of hour units for the receiver.

[`minute`](/documentation/Foundation/NSDateComponents/minute)

The number of minute units for the receiver.

[`second`](/documentation/Foundation/NSDateComponents/second)

The number of second units for the receiver.

[`nanosecond`](/documentation/Foundation/NSDateComponents/nanosecond)

The number of nanosecond units for the receiver.

### Accessing Components as Calendrical Units

[`-  valueForComponent:`](/documentation/Foundation/NSDateComponents/value(forComponent:))

Returns the value for a given calendar unit.

[`-  setValue:forComponent:`](/documentation/Foundation/NSDateComponents/setValue(_:forComponent:))

Sets a value for a given calendar unit.

[`Unit`](/documentation/Foundation/NSCalendar/Unit)

Calendrical units such as year, month, day and hour.

## Relationships

### Conforms To

[`CustomDebugStringConvertible`](/documentation/Swift/CustomDebugStringConvertible)

[`NSCopying`](/documentation/Foundation/NSCopying)

[`NSObjectProtocol`](/documentation/ObjectiveC/NSObjectProtocol)

[`NSCoding`](/documentation/Foundation/NSCoding)

[`Escapable`](/documentation/Swift/Escapable)

[`CVarArg`](/documentation/Swift/CVarArg)

[`Equatable`](/documentation/Swift/Equatable)

[`Hashable`](/documentation/Swift/Hashable)

[`Copyable`](/documentation/Swift/Copyable)

[`CustomStringConvertible`](/documentation/Swift/CustomStringConvertible)

[`NSSecureCoding`](/documentation/Foundation/NSSecureCoding)

### Inherits From

[`NSObject-swift.class`](/documentation/ObjectiveC/NSObject-swift.class)

---

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)