Next Page > Hide TOC

NSDateComponents Class Reference

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

Tasks

Getting Information About an NSDateComponents Object

• – era
• – year
• – month
• – day
• – hour
• – minute
• – second
• – week
• – weekday
• – weekdayOrdinal

Setting Information for an NSDateComponents Object

• – setEra:
• – setYear:
• – setMonth:
• – setDay:
• – setHour:
• – setMinute:
• – setSecond:
• – setWeek:
• – setWeekday:
• – setWeekdayOrdinal:

Instance Methods

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

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setDay:

Related Sample Code

• Birthdays

Declared In

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

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setEra:

Declared In

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

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setHour:

Declared In

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

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setMinute:

Declared In

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

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setMonth:

Declared In

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

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setSecond:

Declared In

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

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – day

Related Sample Code

• Reminders

Declared In

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

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – era

Declared In

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

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – hour

Related Sample Code

• Reminders

Declared In

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

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – minute

Related Sample Code

• Reminders

Declared In

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

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – month

Related Sample Code

• Reminders

Declared In

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

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – second

Related Sample Code

• Reminders

Declared In

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

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – week

Declared In

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

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – weekday

Declared In

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

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – weekdayOrdinal

Declared In

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

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – year

Related Sample Code

• Reminders

Declared In

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

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setWeek:

Declared In

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

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setWeekday:

Related Sample Code

• Birthdays

Declared In

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

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setWeekdayOrdinal:

Declared In

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

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setYear:

Declared In

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 Mac OS X v10.4 and later.

Declared in NSCalendar.h.

Declared In

Next Page > Hide TOC