Class

NSDateComponents

NSDateComponents 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 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.

Overview

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, 2004, 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 dateFromComponents: and then use components:fromDate: 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 timeZone: TimeZone?

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

Validating the Date Value

var isValidDate: Bool

Whether the properties set on the receiver corresponds to a date that exists for the calendar property value. If the timeZone 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 isValidDate(in: Calendar)

Whether the properties set on the receiver corresponds to a date that exists for the calendar property value. If the timeZone 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 weekdayOrdinal: Int

The ordinal number of weekday units for the receiver.

var quarter: Int

The number of quarters for the receiver.

var weekOfMonth: Int

The week number of the month for the receiver.

var weekOfYear: Int

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

var yearForWeekOfYear: Int

The ISO 8601 week-numbering year of the receiver.

var isLeapMonth: Bool

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

func week()Deprecated
func value(forComponent: NSCalendar.Unit)

Returns the value for a given NSCalendarUnit value.

func setValue(Int, forComponent: NSCalendar.Unit)

Sets a given value for a given NSCalendarUnit value.

Constants

Undefined Components

The NSDateComponentUndefined constant is used to denote that the value of a date component is undefined. For example, when an NSDateComponents object is created as the result of calculating the distance in time between two dates represented by a particular calendar, the value for the NSCalendarUnitWeekOfYear component would be set to NSDateComponentUndefined.

Relationships

Inherits From