Mac Developer Library

Developer

Foundation Framework Reference NSDateComponents Class Reference

Options
Deployment Target:

On This Page
Language:

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.

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

  1. NSDateComponents *comps = [[NSDateComponents alloc] init];
  2. [comps setDay:6];
  3. [comps setMonth:5];
  4. [comps setYear:2004];
  5. NSCalendar *gregorian = [[NSCalendar alloc]
  6. initWithCalendarIdentifier:NSGregorianCalendar];
  7. NSDate *date = [gregorian dateFromComponents:comps];
  8. [comps release];
  9. NSDateComponents *weekdayComponents =
  10. [gregorian components:NSWeekdayCalendarUnit fromDate:date];
  11. int weekday = [weekdayComponents weekday];

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

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

    Declaration

    Swift

    var validDate: Bool { get }

    Objective-C

    @property(getter=isValidDate, readonly) BOOL validDate

    Discussion

    This property is a convenience API for the isValidDateInCalendar: method.

    Availability

    Available in OS X v10.9 and later.

    See Also

    date

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

    Declaration

    Swift

    func isValidDateInCalendar(_ calendar: NSCalendar) -> Bool

    Objective-C

    - (BOOL)isValidDateInCalendar:(NSCalendar *)calendar

    Parameters

    calendar

    The calendar for which to use in the calculation.

    Return Value

    YEStrue if the date corresponding to the receiver's values is valid and exists in the given calendar, otherwise NOfalse.

    Discussion

    This property should not be used for NSDateComponents objects that represent relative quantities of calendar components. To find the the next or previous date that matches a particular set of date components, use the NSCalendar instance method nextDateAfterDate:matchingUnit:value:options: instead.

    Availability

    Available in OS X v10.9 and later.

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

    Declaration

    Swift

    var NSDateComponentUndefined: Int { get } var NSUndefinedDateComponent: Int { get }

    Objective-C

    enum { NSDateComponentUndefined = NSIntegerMax, NSUndefinedDateComponent NS_CALENDAR_ENUM_DEPRECATED = NSDateComponentUndefined };

    Constants

    • NSDateComponentUndefined

      NSDateComponentUndefined

      Specifies a date component without a value. Undefined fields can be set to NSDateComponentUndefined.

      Available in OS X v10.9 and later.

    • NSUndefinedDateComponent

      NSUndefinedDateComponent

      Specifies a date component without a value.

      Use NSDateComponentUndefined instead.

      Available in OS X v10.4 and later.

      Deprecated in OS X v10.10.