Class

NSDate​Components

NSDate​Components encapsulates the components of a date in an extendable, object-oriented manner. It is 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. It can also be used to specify a duration of time, for example, 5 hours and 16 minutes. An NSDate​Components object is not required to define all the component fields. When a new instance of NSDate​Components is created the date components are set to NSDate​Component​Undefined.

Overview

An instance of NSDate​Components 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, 2004, its weekday is NSDate​Component​Undefined, 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​Components:​ and then use components:​from​Date:​ to retrieve the weekday—as illustrated in the following example.

let dateComponents = NSDateComponents()
dateComponents.day = 4
dateComponents.month = 5
dateComponents.year = 2006
 
if let gregorianCalendar = NSCalendar(calendarIdentifier: NSCalendarIdentifierGregorian),
    let date = gregorianCalendar.dateFromComponents(dateComponents) {
    let weekday = gregorianCalendar.component(.Weekday, fromDate: date)
    print(weekday) // 5, which corresponds to Thursday in the Gregorian Calendar
}

For more details, see Calendars, Date Components, and Calendar Units in Date and Time Programming Guide.

Symbols

Getting the Date Value

var date:​ Date?

The date of the receiver.

var calendar:​ Calendar?

The calendar used to interpret the components of the receiver.

var time​Zone:​ Time​Zone?

The time zone used to interpret the components of the receiver.

Validating the Date Value

var is​Valid​Date:​ Bool

Whether the properties set on the receiver corresponds to a date that exists for the calendar property value. If the time​Zone property is set on the receiver, the time zone property value is used. If the calendar property is not set on the receiver, nil is returned.

func is​Valid​Date(in:​ Calendar)

Whether the properties set on the receiver corresponds to a date that exists for the calendar property value. If the time​Zone property is set on the receiver, the time zone property value is used.

Accessing the Date Components

var era:​ Int

The number of era units for the receiver.

var year:​ Int

The number of year units for the receiver.

var month:​ Int

The number of month units for the receiver.

var day:​ Int

The number of day units for the receiver.

var hour:​ Int

The number of hour units for the receiver.

var minute:​ Int

The number of minute units for the receiver.

var second:​ Int

The number of second units for the receiver.

var nanosecond:​ Int

The number of nanosecond units for the receiver.

var weekday:​ Int

The number of the weekday unit for the receiver.

var weekday​Ordinal:​ Int

The ordinal number of weekday units for the receiver.

var quarter:​ Int

The number of quarters for the receiver.

var week​Of​Month:​ Int

The week number of the month for the receiver.

var week​Of​Year:​ Int

The ISO 8601 week date of the year for the receiver.

var year​For​Week​Of​Year:​ Int

The ISO 8601 week-numbering year of the receiver.

var is​Leap​Month:​ Bool

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

func week()Deprecated
func value(for​Component:​ NSCalendar.Unit)

Returns the value for a given NSCalendar​Unit value.

func set​Value(Int, for​Component:​ NSCalendar.Unit)

Sets a given value for a given NSCalendar​Unit value.

Constants

Undefined Components

The NSDate​Component​Undefined constant is used to denote that the value of a date component is undefined. For example, when an NSDate​Components object is created as the result of calculating the distance in time between two dates represented by a particular calendar, the value for the NSCalendar​Unit​Week​Of​Year component would be set to NSDate​Component​Undefined.