<!--
{
  "availability" : [
    "iOS: 8.0.0 -",
    "iPadOS: 8.0.0 -",
    "macCatalyst: 8.0.0 -",
    "macOS: 10.9.0 -",
    "tvOS: 9.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 2.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Foundation",
  "identifier" : "/documentation/Foundation/DateComponents",
  "metadataVersion" : "0.1.0",
  "role" : "Structure",
  "symbol" : {
    "kind" : "Structure",
    "modules" : [
      "Foundation"
    ],
    "preciseIdentifier" : "s:10Foundation14DateComponentsV"
  },
  "title" : "DateComponents"
}
-->

# DateComponents

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

```
struct DateComponents
```

## Overview

`DateComponents` encapsulates the components of a date in an extendable, structured manner.

It is used to specify a date by providing the temporal components that make up a date and time in a particular calendar: hour, minutes, seconds, day, month, year, and so on. It can also be used to specify a duration of time, for example, 5 hours and 16 minutes. A `DateComponents` is not required to define all the component fields.

When a new instance of `DateComponents` is created, the date components are set to `nil`.

## Topics

### Initializing Date Components

[`init(calendar:timeZone:era:year:month:day:hour:minute:second:nanosecond:weekday:weekdayOrdinal:quarter:weekOfMonth:weekOfYear:yearForWeekOfYear:)`](/documentation/Foundation/DateComponents/init(calendar:timeZone:era:year:month:day:hour:minute:second:nanosecond:weekday:weekdayOrdinal:quarter:weekOfMonth:weekOfYear:yearForWeekOfYear:))

Initializes a date components value, optionally specifying values for its fields.

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

The calendar used to interpret the other values in this structure.

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

A time zone.

### Validating a Date

[`isValidDate`](/documentation/Foundation/DateComponents/isValidDate)

Indicates whether the current combination of properties represents a date which exists in the current calendar.

[`isValidDate(in:)`](/documentation/Foundation/DateComponents/isValidDate(in:))

Indicates whether the current combination of properties represents a date which exists in the specified calendar.

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

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

### Accessing Months and Years

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

An era or count of eras.

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

A year or count of years.

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

The year corresponding to a week-counting week.

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

A quarter or count of quarters.

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

A month or count of months.

[`isLeapMonth`](/documentation/Foundation/DateComponents/isLeapMonth)

Set to true if these components represent a leap month.

### Accessing Weeks and Days

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

A week of the month or a count of weeks of the month.

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

A week of the year or count of the weeks of the year.

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

A weekday or count of weekdays.

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

A weekday ordinal or count of weekday ordinals.

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

A day or count of days.

### Accessing Hours and Seconds

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

An hour or count of hours.

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

A minute or count of minutes.

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

A second or count of seconds.

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

A nanosecond or count of nanoseconds.

### Accessing Calendar Components

[`value(for:)`](/documentation/Foundation/DateComponents/value(for:))

Returns the value of one of the properties, using an enumeration value instead of a property name.

[`setValue(_:for:)`](/documentation/Foundation/DateComponents/setValue(_:for:))

Set the value of one of the properties, using an enumeration value instead of a property name.

[`Calendar.Component`](/documentation/Foundation/Calendar/Component)

An enumeration for the various components of a calendar date.

### Comparing Date Components

### Using Reference Types

[`NSDateComponents`](/documentation/Foundation/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.


---

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)