NSDateComponents Class Reference

Inherits from
NSObject
Conforms to
NSCopying
NSSecureCoding
NSObject (NSObject)
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.4 and later.
Companion guide
Date and Time Programming Guide
Declared in
NSCalendar.h
Related sample code

Overview

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

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 6, 2004, its weekday is NSUndefinedDateComponent, 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 *comps = [[NSDateComponents alloc] init];
[comps setDay:6];
[comps setMonth:5];
[comps setYear:2004];
NSCalendar *gregorian = [[NSCalendar alloc]
    initWithCalendarIdentifier:NSGregorianCalendar];
NSDate *date = [gregorian dateFromComponents:comps];
[comps release];
NSDateComponents *weekdayComponents =
    [gregorian components:NSWeekdayCalendarUnit fromDate:date];
int weekday = [weekdayComponents weekday];

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

Tasks

Getting Information About an NSDateComponents Object

Setting Information for an NSDateComponents Object

Instance Methods

calendar

Returns the calendar of the receiver.

- (NSCalendar *)calendar
Return Value

The calendar.

Discussion

This value is interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSCalendar.h

date

Returns the date of the receiver.

- (NSDate *)date
Return Value

The date.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSCalendar.h

day

Returns the number of day units for the receiver.

- (NSInteger)day
Return Value

The number of day units for the receiver.

Discussion

This value is interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSCalendar.h

era

Returns the number of era units for the receiver.

- (NSInteger)era
Return Value

The number of era units for the receiver.

Discussion

This value is interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSCalendar.h

hour

Returns the number of hour units for the receiver.

- (NSInteger)hour
Return Value

The number of hour units for the receiver.

Discussion

This value is interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSCalendar.h

isLeapMonth

Returns whether the month is a leap month.

- (BOOL)isLeapMonth
Return Value

YES if the month is a leap month, NO otherwise.

Availability
  • Available in OS X v10.8 and later.
See Also
Declared In
NSCalendar.h

minute

Returns the number of minute units for the receiver.

- (NSInteger)minute
Return Value

The number of minute units for the receiver.

Discussion

This value is interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSCalendar.h

month

Returns the number of month units for the receiver.

- (NSInteger)month
Return Value

The number of month units for the receiver.

Discussion

This value is interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSCalendar.h

quarter

Returns the number of quarters in the calendar.

- (NSInteger)quarter
Return Value

The number of quarters units for the receiver.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSCalendar.h

second

Returns the number of second units for the receiver.

- (NSInteger)second
Return Value

The number of second units for the receiver.

Discussion

This value is interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSCalendar.h

setCalendar:

Sets the receiver’s calendar.

- (void)setCalendar:(NSCalendar *)cal
Parameters
cal

The calendar.

Discussion

This value is interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSCalendar.h

setDay:

Sets the number of day units for the receiver.

- (void)setDay:(NSInteger)v
Parameters
v

The number of day units for the receiver.

Discussion

This value will be interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSCalendar.h

setEra:

Sets the number of era units for the receiver.

- (void)setEra:(NSInteger)v
Parameters
v

The number of era units for the receiver.

Discussion

This value will be interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSCalendar.h

setHour:

Sets the number of hour units for the receiver.

- (void)setHour:(NSInteger)v
Parameters
v

The number of hour units for the receiver.

Discussion

This value will be interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSCalendar.h

setLeapMonth:

Sets the month as a leap month.

- (void)setLeapMonth:(BOOL)lm
Parameters
lm

YES if the month is a leap month, NO otherwise.

Availability
  • Available in OS X v10.8 and later.
See Also
Declared In
NSCalendar.h

setMinute:

Sets the number of minute units for the receiver.

- (void)setMinute:(NSInteger)v
Parameters
v

The number of minute units for the receiver.

Discussion

This value will be interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSCalendar.h

setMonth:

Sets the number of month units for the receiver.

- (void)setMonth:(NSInteger)v
Parameters
v

The number of month units for the receiver.

Discussion

This value will be interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSCalendar.h

setQuarter:

Sets the number of quarters in the calendar.

- (void)setQuarter:(NSInteger)v
Parameters
v

The number of quarters units for the receiver.

Discussion

This value is interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSCalendar.h

setSecond:

Sets the number of second units for the receiver.

- (void)setSecond:(NSInteger)v
Parameters
v

The number of second units for the receiver.

Discussion

This value will be interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSCalendar.h

setTimeZone:

Sets the receiver’s time zone.

- (void)setTimeZone:(NSTimeZone *)tz
Parameters
tz

The time zone.

Discussion

This value is interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSCalendar.h

setWeek:

Sets the number of week units for the receiver.

- (void)setWeek:(NSInteger)v
Parameters
v

The number of week units for the receiver.

Discussion

This value will be interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSCalendar.h

setWeekday:

Sets the number of weekday units for the receiver.

- (void)setWeekday:(NSInteger)v
Parameters
v

The number of weekday units for the receiver.

Discussion

Weekday units are the numbers 1 through n, where n is the number of days in the week. For example, in the Gregorian calendar, n is 7 and Sunday is represented by 1.

This value will be interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSCalendar.h

setWeekdayOrdinal:

Sets the ordinal number of weekday units for the receiver.

- (void)setWeekdayOrdinal:(NSInteger)v
Parameters
v

The ordinal number of weekday units for the receiver.

Discussion

Weekday ordinal units represent the position of the weekday within the next larger calendar unit, such as the month. For example, 2 is the weekday ordinal unit for the second Friday of the month.

This value will be interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSCalendar.h

setWeekOfMonth:

Sets the week of the month.

- (void)setWeekOfMonth:(NSInteger)week
Parameters
week

The week number of the month.

Discussion

This value is interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSCalendar.h

setWeekOfYear:

Sets the week of the year.

- (void)setWeekOfYear:(NSInteger)week
Parameters
week

The week number of the year.

Discussion

This value is interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSCalendar.h

setYear:

Sets the number of year units for the receiver.

- (void)setYear:(NSInteger)v
Parameters
v

The number of year units for the receiver.

Discussion

This value will be interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSCalendar.h

setYearForWeekOfYear:

Sets the year for the week of the year.

- (void)setYearForWeekOfYear:(NSInteger)year
Parameters
year

The year when the calendar is being interpreted as a week-based calendar.

Discussion

This value is interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSCalendar.h

timeZone

Returns the receiver’s time zone.

- (NSTimeZone *)timeZone
Return Value

The time zone.

Discussion

This value is interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSCalendar.h

week

Returns the number of week units for the receiver.

- (NSInteger)week
Return Value

The number of week units for the receiver.

Discussion

This value is interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSCalendar.h

weekday

Returns the number of weekday units for the receiver.

- (NSInteger)weekday
Return Value

The number of weekday units for the receiver.

Discussion

Weekday units are the numbers 1 through n, where n is the number of days in the week. For example, in the Gregorian calendar, n is 7 and Sunday is represented by 1.

This value is interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSCalendar.h

weekdayOrdinal

Returns the ordinal number of weekday units for the receiver.

- (NSInteger)weekdayOrdinal
Return Value

The ordinal number of weekday units for the receiver.

Discussion

Weekday ordinal units represent the position of the weekday within the next larger calendar unit, such as the month. For example, 2 is the weekday ordinal unit for the second Friday of the month.

This value is interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSCalendar.h

weekOfMonth

Returns the week of the month.

- (NSInteger)weekOfMonth
Return Value

The week number of the month.

Discussion

This value is interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSCalendar.h

weekOfYear

Returns the week of the year.

- (NSInteger)weekOfYear
Return Value

The week number of the year.

Discussion

This value is interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSCalendar.h

year

Returns the number of year units for the receiver.

- (NSInteger)year
Return Value

The number of year units for the receiver.

Discussion

This value is interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSCalendar.h

yearForWeekOfYear

Returns the year for the week of the year.

- (NSInteger)yearForWeekOfYear
Return Value

The year number for the week of the year.

Discussion

This value is interpreted in the context of the calendar with which it is used—see “Calendars, Date Components, and Calendar Units” in Date and Time Programming Guide.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSCalendar.h

Constants

NSDateComponents undefined component identifier

This constant specifies that an NSDateComponents component is undefined.

enum {
   NSUndefinedDateComponent = 0x7fffffff
};
Constants
NSUndefinedDateComponent

Specifies that the component is undefined.

Available in OS X v10.4 and later.

Declared in NSCalendar.h.

Declared In
NSCalendar.h


© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-07-17)

Did this document help you? Yes It's good, but... Not helpful...