---
title: NSDateComponents
framework: foundation
role: symbol
role_heading: Class
path: foundation/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.

## Declaration

```swift
class NSDateComponents
```

## Overview

Overview In Swift, this object bridges to DateComponents; use NSDateComponents when you need reference semantics or other Foundation-specific behavior. 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 object is not required to define all the component fields. When a new instance of NSDateComponents is created, the date components are set to NSDateComponentUndefined. important: An 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 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, not Thursday. To get the correct day of the week, you must create a suitable instance of NSCalendar, create an NSDate object using date(from:) and then use components(_:from:) to retrieve the weekday—as illustrated in the following example. For more details, see Calendars, Date Components, and Calendar Units in Date and Time Programming Guide. important: The Swift overlay to the Foundation framework provides the DateComponents structure, which bridges to the NSDateComponents class. For more information about value types, see Working with Foundation Types.

## Topics

### Setting a Calendar and Time Zone

- [calendar](foundation/nsdatecomponents/calendar.md)
- [timeZone](foundation/nsdatecomponents/timezone.md)

### Validating a Date

- [isValidDate](foundation/nsdatecomponents/isvaliddate.md)
- [isValidDate(in:)](foundation/nsdatecomponents/isvaliddate(in:).md)
- [date](foundation/nsdatecomponents/date.md)
- [Undefined Components](foundation/1430344-undefined-components.md)

### Accessing Years and Months

- [era](foundation/nsdatecomponents/era.md)
- [year](foundation/nsdatecomponents/year.md)
- [yearForWeekOfYear](foundation/nsdatecomponents/yearforweekofyear.md)
- [quarter](foundation/nsdatecomponents/quarter.md)
- [month](foundation/nsdatecomponents/month.md)
- [isLeapMonth](foundation/nsdatecomponents/isleapmonth.md)

### Accessing Weeks and Days

- [weekday](foundation/nsdatecomponents/weekday.md)
- [weekdayOrdinal](foundation/nsdatecomponents/weekdayordinal.md)
- [weekOfMonth](foundation/nsdatecomponents/weekofmonth.md)
- [weekOfYear](foundation/nsdatecomponents/weekofyear.md)
- [day](foundation/nsdatecomponents/day.md)
- [week()](foundation/nsdatecomponents/week().md)
- [setWeek(_:)](foundation/nsdatecomponents/setweek(_:).md)

### Accessing Hours and Seconds

- [hour](foundation/nsdatecomponents/hour.md)
- [minute](foundation/nsdatecomponents/minute.md)
- [second](foundation/nsdatecomponents/second.md)
- [nanosecond](foundation/nsdatecomponents/nanosecond.md)

### Accessing Components as Calendrical Units

- [value(forComponent:)](foundation/nsdatecomponents/value(forcomponent:).md)
- [setValue(_:forComponent:)](foundation/nsdatecomponents/setvalue(_:forcomponent:).md)
- [NSCalendar.Unit](foundation/nscalendar/unit.md)

### Initializers

- [init(coder:)](foundation/nsdatecomponents/init(coder:).md)

### Instance Properties

- [dayOfYear](foundation/nsdatecomponents/dayofyear.md)
- [isRepeatedDay](foundation/nsdatecomponents/isrepeatedday.md)

## Relationships

### Inherits From

- [NSObject](objectivec/nsobject-swift.class.md)

### Conforms To

- [CVarArg](swift/cvararg.md)
- [Copyable](swift/copyable.md)
- [CustomDebugStringConvertible](swift/customdebugstringconvertible.md)
- [CustomStringConvertible](swift/customstringconvertible.md)
- [Equatable](swift/equatable.md)
- [Escapable](swift/escapable.md)
- [Hashable](swift/hashable.md)
- [NSCoding](foundation/nscoding.md)
- [NSCopying](foundation/nscopying.md)
- [NSObjectProtocol](objectivec/nsobjectprotocol.md)
- [NSSecureCoding](foundation/nssecurecoding.md)