Class

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

@interface NSDateComponents : NSObject

Overview

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.

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 dateFromComponents: and then use components:fromDate: to retrieve the weekday—as illustrated in the following example.

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 in Date and Time Programming Guide.

Topics

Setting a Calendar and Time Zone

calendar

The calendar used to interpret the date components.

timeZone

The time zone used to interpret the date components.

Validating a Date

validDate

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

- isValidDateInCalendar:

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

date

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

Undefined Components

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

Accessing Years and Months

era

The number of eras.

year

The number of years.

yearForWeekOfYear

The ISO 8601 week-numbering year.

quarter

The number of quarters.

month

The number of months.

leapMonth

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

Accessing Weeks and Days

weekday

The number of the weekdays.

weekdayOrdinal

The ordinal number of weekdays.

weekOfMonth

The week number of the months.

weekOfYear

The ISO 8601 week date of the year.

day

The number of days.

- week

Returns the number of weeks.

Deprecated
- setWeek:

Sets the number of weeks.

Deprecated

Accessing Hours and Seconds

hour

The number of hour units for the receiver.

minute

The number of minute units for the receiver.

second

The number of second units for the receiver.

nanosecond

The number of nanosecond units for the receiver.

Accessing Components as Calendrical Units

- valueForComponent:

Returns the value for a given calendar unit.

- setValue:forComponent:

Sets a value for a given calendar unit.

NSCalendarUnit

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

Relationships

Inherits From

See Also

Calendrical Calculations

NSCalendar

An object that defines the relationships between calendar units (such as eras, years, and weekdays) and absolute points in time, providing features for calculation and comparison of dates.

NSTimeZone

Information about standard time conventions associated with a specific geopolitical region.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software