iOS Developer Library — Prerelease

Developer

Foundation Framework Reference NSCalendar Class Reference

Options
Deployment Target:

On This Page
Language:

NSCalendar

Calendars encapsulate information about systems of reckoning time in which the beginning, length, and divisions of a year are defined. They provide information about the calendar and support for calendrical computations such as determining the range of a given calendrical unit and adding units to a given absolute time.

NSCalendar is “toll-free bridged” with its Core Foundation counterpart, CFCalendarRef. See Toll-Free Bridging for more information on toll-free bridging.

Locales and Calendars

Most locales use the most widely used civil calendar, called the Gregorian calendar (NSCalendarIdentifierGregorian), but there remain exceptions to this trend. For example:

Other locales use another calendar alongside the Gregorian calendar. For example:

Independent of any particular locale, certain calendars are used primarily to calculate dates for religious observances. Among these are the Buddhist (NSCalendarIdentifierBuddhist), Coptic (NSCalendarIdentifierCoptic), Hebrew (NSCalendarIdentifierHebrew), and Islamic (NSCalendarIdentifierIslamic) calendars.

How NSCalendar Models the Gregorian Calendar

The Gregorian calendar was first introduced in 1582, as a replacement for the Julian Calendar. According to the Julian calendar, a leap day is added to February for any year with a number divisible by 4, which results in an annual disparity of 11 minutes, or 1 day every 128 years. The Gregorian calendar revised the rules for leap day calculation, by skipping the leap day for any year with a number divisible by 100, unless that year number is also divisible by 400, resulting in an annual disparity of only 26 seconds, or 1 day every 3323 years.

To transition from the Julian calendar to the Gregorian calendar, 10 days were dropped from the Gregorian calendar (October 5–14).

After the Gregorian calendar was introduced, many countries continued to use the Julian calendar, with Turkey being the last country to adopt the Gregorian calendar, in 1926. As a result of the staggered adoption, the transition period for countries at the time of adoption have different start dates and and a different number of skipped days to account for the additional disparity from leap day calculations.

NSCalendar models the behavior of a proleptic Gregorian calendar (as defined by ISO 8601:2004), which extends the Gregorian calendar backward in time from the date of its introduction. This behavior should be taken into account when working with dates created before the transition period of the affected locales.

Calendar Arithmetic

To do calendar arithmetic, you use NSDate objects in conjunction with a calendar. For example, to convert between a decomposed date in one calendar and another calendar, you must first convert the decomposed elements into a date using the first calendar, then decompose it using the second. NSDate provides the absolute scale and epoch (reference point) for dates and times, which can then be rendered into a particular calendar, for calendrical computations or user display.

Two NSCalendar methods that return a date object, dateFromComponents:, dateByAddingComponents:toDate:options:, take as a parameter an NSDateComponents object that describes the calendrical components required for the computation. You can provide as many components as you need (or choose to). When there is incomplete information to compute an absolute time, default values similar to 0 and 1 are usually chosen by a calendar, but this is a calendar-specific choice. If you provide inconsistent information, calendar-specific disambiguation is performed (which may involve ignoring one or more of the parameters). Related methods (components:fromDate: and components:fromDate:toDate:options:) take a bit mask parameter that specifies which components to calculate when returning an NSDateComponents object. The bit mask is composed of NSCalendarUnit constants (see Constants).

In a calendar, day, week, weekday, month, and year numbers are generally 1-based, but there may be calendar-specific exceptions. Ordinal numbers, where they occur, are 1-based. Some calendars represented by this API may have to map their basic unit concepts into year/month/week/day/… nomenclature. For example, a calendar composed of 4 quarters in a year instead of 12 months uses the month unit to represent quarters. The particular values of the unit are defined by each calendar, and are not necessarily consistent with values for that unit in another calendar.

  • Returns the logical calendar for the current user.

    Declaration

    Swift

    class func currentCalendar() -> NSCalendar

    Objective-C

    + (NSCalendar * _Nonnull)currentCalendar

    Return Value

    The logical calendar for the current user.

    Discussion

    The returned calendar is formed from the settings for the current user’s chosen system locale overlaid with any custom settings the user has specified in System Preferences. Settings you get from this calendar do not change as System Preferences are changed, so that your operations are consistent (contrast with autoupdatingCurrentCalendar).

    Availability

    Available in iOS 2.0 and later.

  • Returns the current logical calendar for the current user.

    Declaration

    Swift

    class func autoupdatingCurrentCalendar() -> NSCalendar

    Objective-C

    + (NSCalendar * _Nonnull)autoupdatingCurrentCalendar

    Return Value

    The current logical calendar for the current user.

    Discussion

    Settings you get from this calendar do change as the user’s settings change (contrast with currentCalendar).

    Note that if you cache values based on the calendar or related information those caches will of course not be automatically updated by the updating of the calendar object.

    Availability

    Available in iOS 2.0 and later.

  • A string representing a calendar identity. (read-only)

    Declaration

    Swift

    var calendarIdentifier: String { get }

    Objective-C

    @property(readonly, copy, nonnull) NSString *calendarIdentifier

    Availability

    Available in iOS 2.0 and later.

  • The index of the first weekday of the receiver.

    Declaration

    Swift

    var firstWeekday: Int

    Objective-C

    @property NSUInteger firstWeekday

    Availability

    Available in iOS 2.0 and later.

  • The locale of the receiver.

    Declaration

    Swift

    @NSCopying var locale: NSLocale?

    Objective-C

    @property(copy, nullable) NSLocale *locale

    Availability

    Available in iOS 2.0 and later.

  • The maximum range limits of the values that a given unit can take on in the receive

    Declaration

    Swift

    func maximumRangeOfUnit(_ unit: NSCalendarUnit) -> NSRange

    Objective-C

    - (NSRange)maximumRangeOfUnit:(NSCalendarUnit)unit

    Parameters

    unit

    The unit for which the maximum range is returned.

    Return Value

    The maximum range limits of the values that the unit specified by unit can take on in the receiver.

    Discussion

    As an example, in the Gregorian calendar the maximum range of values for the Day unit is 1-31.

    Availability

    Available in iOS 2.0 and later.

  • The minimum number of days, an integer value, in the first week of the receiver.

    Declaration

    Swift

    var minimumDaysInFirstWeek: Int

    Objective-C

    @property NSUInteger minimumDaysInFirstWeek

    Availability

    Available in iOS 2.0 and later.

  • Returns the minimum range limits of the values that a given unit can take on in the receiver.

    Declaration

    Swift

    func minimumRangeOfUnit(_ unit: NSCalendarUnit) -> NSRange

    Objective-C

    - (NSRange)minimumRangeOfUnit:(NSCalendarUnit)unit

    Parameters

    unit

    The unit for which the maximum range is returned.

    Return Value

    The minimum range limits of the values that the unit specified by unit can take on in the receiver.

    Discussion

    As an example, in the Gregorian calendar the minimum range of values for the Day unit is 1-28.

    Availability

    Available in iOS 2.0 and later.

  • Returns, for a given absolute time, the ordinal number of a smaller calendar unit (such as a day) within a specified larger calendar unit (such as a week).

    Declaration

    Swift

    func ordinalityOfUnit(_ smaller: NSCalendarUnit, inUnit larger: NSCalendarUnit, forDate date: NSDate) -> Int

    Objective-C

    - (NSUInteger)ordinalityOfUnit:(NSCalendarUnit)smaller inUnit:(NSCalendarUnit)larger forDate:(NSDate * _Nonnull)date

    Parameters

    smaller

    The smaller calendar unit

    larger

    The larger calendar unit

    date

    The absolute time for which the calculation is performed

    Return Value

    The ordinal number of smaller within larger at the time specified by date. Returns NSNotFound if larger is not logically bigger than smaller in the calendar, or the given combination of units does not make sense (or is a computation which is undefined).

    Discussion

    The ordinality is in most cases not the same as the decomposed value of the unit. Typically return values are 1 and greater. For example, the time 00:45 is in the first hour of the day, and for units Hour and Day respectively, the result would be 1. An exception is the week-in-month calculation, which returns 0 for days before the first week in the month containing the date.

    Note that some computations can take a relatively long time.

    Availability

    Available in iOS 2.0 and later.

  • Returns the range of absolute time values that a smaller calendar unit (such as a day) can take on in a larger calendar unit (such as a month) that includes a specified absolute time.

    Declaration

    Swift

    func rangeOfUnit(_ smaller: NSCalendarUnit, inUnit larger: NSCalendarUnit, forDate date: NSDate) -> NSRange

    Objective-C

    - (NSRange)rangeOfUnit:(NSCalendarUnit)smaller inUnit:(NSCalendarUnit)larger forDate:(NSDate * _Nonnull)date

    Parameters

    smaller

    The smaller calendar unit.

    larger

    The larger calendar unit.

    date

    The absolute time for which the calculation is performed.

    Return Value

    The range of absolute time values smaller can take on in larger at the time specified by date. Returns {NSNotFound, NSNotFound} if larger is not logically bigger than smaller in the calendar, or the given combination of units does not make sense (or is a computation which is undefined).

    Discussion

    You can use this method to calculate, for example, the range the Day unit can take on in the Month in which date lies.

    Availability

    Available in iOS 2.0 and later.

  • Returns by reference the starting time and duration of a given calendar unit that contains a given date.

    Declaration

    Swift

    func rangeOfUnit(_ unit: NSCalendarUnit, startDate datep: AutoreleasingUnsafeMutablePointer<NSDate?>, interval tip: UnsafeMutablePointer<NSTimeInterval>, forDate date: NSDate) -> Bool

    Objective-C

    - (BOOL)rangeOfUnit:(NSCalendarUnit)unit startDate:(NSDate * _Nullable * _Nullable)datep interval:(NSTimeInterval * _Nullable)tip forDate:(NSDate * _Nonnull)date

    Parameters

    unit

    A calendar unit (see Calendar Units for possible values).

    datep

    Upon return, contains the starting time of the calendar unit unit that contains the date date

    tip

    Upon return, contains the duration of the calendar unit unit that contains the date date

    date

    A date.

    Return Value

    YEStrue if the starting time and duration of a unit could be calculated, otherwise NOfalse.

    Availability

    Available in iOS 2.0 and later.

  • Returns whether a given date falls within a weekend period, and if so, returns by reference the start date and time interval of the weekend range.

    Declaration

    Swift

    func rangeOfWeekendStartDate(_ datep: AutoreleasingUnsafeMutablePointer<NSDate?>, interval tip: UnsafeMutablePointer<NSTimeInterval>, containingDate date: NSDate) -> Bool

    Objective-C

    - (BOOL)rangeOfWeekendStartDate:(out NSDate * _Nullable * _Nullable)datep interval:(out NSTimeInterval * _Nullable)tip containingDate:(NSDate * _Nonnull)date

    Parameters

    datep

    Upon return, contains the starting date of the next weekend period.

    tip

    Upon return, contains the time interval of the next weekend period.

    date

    The date to use to perform the calculation.

    Return Value

    YEStrue if the given date falls within a weekend period, otherwise NOfalse.

    Special Considerations

    Note that a particular calendar day may not necessarily fall entirely within a weekend period, as weekends can start in the middle of a day in some calendars and locales.

    Availability

    Available in iOS 8.0 and later.

  • The time zone for the receiver.

    Declaration

    Swift

    @NSCopying var timeZone: NSTimeZone

    Objective-C

    @property(copy, nonnull) NSTimeZone *timeZone

    Availability

    Available in iOS 2.0 and later.

  • Returns a new NSDate object representing the absolute time calculated by adding given components to a given date.

    Declaration

    Swift

    func dateByAddingComponents(_ comps: NSDateComponents, toDate date: NSDate, options opts: NSCalendarOptions) -> NSDate?

    Objective-C

    - (NSDate * _Nullable)dateByAddingComponents:(NSDateComponents * _Nonnull)comps toDate:(NSDate * _Nonnull)date options:(NSCalendarOptions)opts

    Parameters

    comps

    The components to add to date.

    date

    The date to which comps are added.

    opts

    Options for the calculation. See “Calendar Options” for possible values. Pass 0 to specify no options.

    If you specify no options, overflow in a unit carries into the higher units (as in typical addition).

    Return Value

    A new NSDate object representing the absolute time calculated by adding to date the calendrical components specified by comps using the options specified by opts. Returns nil if date falls outside the defined range of the receiver or if the computation cannot be performed.

    Discussion

    Some operations can be ambiguous, and the behavior of the computation is calendar-specific, but generally components are added in the order specified.

    The following example shows how to add 2 months and 3 days to the current date and time using an existing calendar (gregorian):

    1. NSDate *currentDate = [NSDate date];
    2. NSDateComponents *comps = [[NSDateComponents alloc] init];
    3. [comps setMonth:2];
    4. [comps setDay:3];
    5. NSDate *date = [gregorian dateByAddingComponents:comps toDate:currentDate options:0];
    6. [comps release];

    Note that some computations can take a relatively long time.

    Availability

    Available in iOS 2.0 and later.

  • Returns a new NSDate object representing the absolute time calculated by adding the value of a given component to a given date.

    Declaration

    Swift

    func dateByAddingUnit(_ unit: NSCalendarUnit, value value: Int, toDate date: NSDate, options options: NSCalendarOptions) -> NSDate?

    Objective-C

    - (NSDate * _Nullable)dateByAddingUnit:(NSCalendarUnit)unit value:(NSInteger)value toDate:(NSDate * _Nonnull)date options:(NSCalendarOptions)options

    Parameters

    unit

    The unit to use for the calculation. For possible values, see “Calendar Units”.

    value

    The value for the given unit.

    date

    The date to use to perform the calculation.

    options

    Options for the calculation. See “Calendar Options” for possible values. If you specify a “wrap” option (NSWrapCalendarComponents), the specified components are incremented and wrap around to zero/one on overflow, but do not cause higher units to be incremented. When the wrap option is false, overflow in a unit carries into the higher units, as in typical addition.

    Return Value

    A new NSDate object representing the absolute time calculated by adding to date the value of the given calendrical unit using the options specified by options. Returns nil if date falls outside the defined range of the receiver or if the computation cannot be performed.

    Availability

    Available in iOS 8.0 and later.

  • Returns a new NSDate object representing the absolute time calculated from given components.

    Declaration

    Swift

    func dateFromComponents(_ comps: NSDateComponents) -> NSDate?

    Objective-C

    - (NSDate * _Nullable)dateFromComponents:(NSDateComponents * _Nonnull)comps

    Parameters

    comps

    The components from which to calculate the returned date.

    Return Value

    A new NSDate object representing the absolute time calculated from comps. Returns nil if the receiver cannot convert the components given in comps into an absolute time. The method also returns nil and for out-of-range values.

    Discussion

    When there are insufficient components provided to completely specify an absolute time, a calendar uses default values of its choice. When there is inconsistent information, a calendar may ignore some of the components parameters or the method may return nil. Unnecessary components are ignored (for example, Day takes precedence over Weekday and Weekday ordinals).

    The following example shows how to use this method to create a date object to represent 14:10:00 on 6 January 1965, for a given calendar (gregorian).

    1. NSDateComponents *comps = [[NSDateComponents alloc] init];
    2. [comps setYear:1965];
    3. [comps setMonth:1];
    4. [comps setDay:6];
    5. [comps setHour:14];
    6. [comps setMinute:10];
    7. [comps setSecond:0];
    8. NSDate *date = [gregorian dateFromComponents:comps];
    9. [comps release];

    Note that some computations can take a relatively long time to perform.

    Availability

    Available in iOS 2.0 and later.

  • Computes the dates that match (or most closely match) a given set of components, and calls the block once for each of them, until the enumeration is stopped.

    Declaration

    Swift

    func enumerateDatesStartingAfterDate(_ start: NSDate, matchingComponents comps: NSDateComponents, options opts: NSCalendarOptions, usingBlock block: (NSDate?, Bool, UnsafeMutablePointer<ObjCBool>) -> Void)

    Objective-C

    - (void)enumerateDatesStartingAfterDate:(NSDate * _Nonnull)start matchingComponents:(NSDateComponents * _Nonnull)comps options:(NSCalendarOptions)opts usingBlock:(void (^ _Nonnull)(NSDate * _Nullable date, BOOL exactMatch, BOOL * _Nonnull stop))block

    Parameters

    start

    The date for which to perform the calculation.

    comps

    The date components to match. If no components are specified, the enumeration will not be executed. If the nanoseconds component is set to a nonzero value, the resulting dates will have floating point seconds values that most closely match the specified nanoseconds value. Otherwise, the resulting dates will have an integer seconds value.

    opts

    Options for the enumeration. For possible values, see “Calendar Options”. For usage, see Discussion below.

    block

    The block to apply to each enumerated date. The block takes three arguments:

    date

    The enumerated date.

    idx

    Whether date exactly matches the specified date components.

    stop

    A reference to a Boolean value. The block can set the value to YEStrue to stop further processing of the array. The stop argument is an out-only argument. You should only ever set this Boolean to YEStrue within the Block.

    Discussion

    Executes a given block with dates that most closely match a given set of components after a given date, until the enumeration is stopped.

    Strict Matching

    If you specify a strict matching option (NSCalendarMatchStrictly), this method searches as far as necessary looking for a match, up to a an implementation-defined limit. If an exact match is not possible, nil is passed to the date argument of the block, and the enumeration is stopped. Otherwise, this method searches as far as the next instance of the next highest calendar unit in the given NSDateComponents object.

    Non-Strict Matching

    If you do not specify a strict matching option, you must specify one of the following options, or else an illegal argument exception will be thrown:

    NSCalendarMatchPreviousTimePreservingSmallerUnits

    If specified, and there is no matching time before the end of the next instance of the next highest unit specified in the given NSDateComponents object, this method uses the previous existing value of the missing unit and preserves the lower units' values. For example, if the time "2:37AM" does not exist for a particular day, such as when advancing by an hour at the beginning of Daylight Savings Time, the date at the time "1:37AM" would be used instead, if that time exists.

    NSCalendarMatchNextTimePreservingSmallerUnits

    If specified, and there is no matching time before the end of the next instance of the next highest unit specified in the given NSDateComponents object, this method uses the next existing value of the missing unit and preserves the lower units' values. For example, if the time "2:37AM" does not exist for a particular day, such as when advancing by an hour at the beginning of Daylight Savings Time, the date at the time "3:37AM" would be used instead, if that time exists.

    NSCalendarMatchNextTime

    If specified, and there is no matching time before the end of the next instance of the next highest unit specified in the given NSDateComponents object, this method uses the next existing value of the missing unit and does not preserve the lower units' values. For example, if the time "2:37AM" does not exist for a particular day, such as when advancing by an hour at the beginning of Daylight Savings Time, the date at the time "3:00AM" would be used instead, if that time exists.

    Matching First or Last Occurrence

    If you specify a "match first" option (NSCalendarMatchFirst) and there are two or more matching times (that is, all components are the same) before the end of the next instance of the next highest unit specified in the given NSDateComponents object, this method uses the first occurrence.

    If you specify a "match last" option (NSCalendarMatchLast) and there are two or more matching times (that is, all components are the same) before the end of the next instance of the next highest unit specified in the given NSDateComponents object, this method uses the last occurrence.

    If neither "match first" or "match last" options are specified or both options are specified, this method behaves as if NSCalendarMatchFirst was specified.

    There is no option to return middle occurrences of more than two occurrences of a matching time, if such exist.

    Backwards Search

    If you specify a backward search option (NSCalendarSearchBackwards), this method will search for previous matches before the given date. This method will return the same results as if the search were made in the forward direction from the distant past, but with the results in reverse order starting with the match most recent to the given date. That is, when searching backwards for a particular hour with no specified minute or second value, the resulting time is not "59" minutes and "59" seconds for the matching hour. When enumerating dates that repeat a time, such as when the clock turns back to 1:00AM from 2:00AM when Daylight Savings Time ends, the "first" time is determined as if the search were performed in the forwards direction.

    Availability

    Available in iOS 8.0 and later.

  • Creates a new NSDate instance calculated with the given time.

    Declaration

    Swift

    func dateBySettingHour(_ h: Int, minute m: Int, second s: Int, ofDate date: NSDate, options opts: NSCalendarOptions) -> NSDate?

    Objective-C

    - (NSDate * _Nullable)dateBySettingHour:(NSInteger)h minute:(NSInteger)m second:(NSInteger)s ofDate:(NSDate * _Nonnull)date options:(NSCalendarOptions)opts

    Parameters

    h

    The hour value.

    m

    The minute value.

    s

    The second value.

    date

    The date to use to perform the calculation.

    opts

    Options for the calculation. For possible values, see “Calendar Options”.

    Return Value

    A new NSDate instance representing the date calculated by setting the given hour, minute, and second, to a given time. If no such time exists for the specified components, the next available date is returned, which may be on a different calendar day.

    Discussion

    You can use this method to calculate a date at a different time of a particular calendar day.

    Availability

    Available in iOS 8.0 and later.

  • Returns a new NSDate object representing the date calculated by setting a specific component of a given date to a given value, while trying to keep lower components the same.

    Declaration

    Swift

    func dateBySettingUnit(_ unit: NSCalendarUnit, value v: Int, ofDate date: NSDate, options opts: NSCalendarOptions) -> NSDate?

    Objective-C

    - (NSDate * _Nullable)dateBySettingUnit:(NSCalendarUnit)unit value:(NSInteger)v ofDate:(NSDate * _Nonnull)date options:(NSCalendarOptions)opts

    Parameters

    unit

    The unit to set with the given value. For possible values, see “Calendar Units”.

    v

    The value to set for the given calendar unit.

    date

    The date to use to perform the calculation.

    opts

    Options for the calculation. For possible values, see “Calendar Options”.

    Return Value

    A new NSDate instance representing the date calculated by setting a specific component of a given date to a given value. If the unit already has that value, this may result in a date which is the same as the given date. If no such time exists for the specified components, the next available date is returned, which may be on a different calendar day.

    Discussion

    Changing a component's value often requires higher or coupled components to change as well. For example, setting the weekday to "Thursday" will require the day component to change its value, and possibly the month and year as well. You can use the nextDateAfterDate:matchingUnit:value:options: method to specify more precise behavior for determining the next or previous date for a given date component.

    Availability

    Available in iOS 8.0 and later.

  • Returns a new NSDate object created with the given components.

    Declaration

    Swift

    func dateWithEra(_ eraValue: Int, year yearValue: Int, month monthValue: Int, day dayValue: Int, hour hourValue: Int, minute minuteValue: Int, second secondValue: Int, nanosecond nanosecondValue: Int) -> NSDate?

    Objective-C

    - (NSDate * _Nullable)dateWithEra:(NSInteger)eraValue year:(NSInteger)yearValue month:(NSInteger)monthValue day:(NSInteger)dayValue hour:(NSInteger)hourValue minute:(NSInteger)minuteValue second:(NSInteger)secondValue nanosecond:(NSInteger)nanosecondValue

    Parameters

    eraValue

    The value to set for the era.

    yearValue

    The value to set for the year.

    monthValue

    The value to set for the month.

    dayValue

    The value to set for the day.

    hourValue

    The value to set for the hour.

    minuteValue

    The value to set for the minute.

    secondValue

    The value to set for the second.

    nanosecondValue

    The value to set for the nanosecond.

    Return Value

    A new NSDate instance created with the given components, or nil if the components do not correspond to a valid date.

    Availability

    Available in iOS 8.0 and later.

  • Returns a new NSDate object created with the given components base on a week-of-year value.

    Declaration

    Swift

    func dateWithEra(_ eraValue: Int, yearForWeekOfYear yearValue: Int, weekOfYear weekValue: Int, weekday weekdayValue: Int, hour hourValue: Int, minute minuteValue: Int, second secondValue: Int, nanosecond nanosecondValue: Int) -> NSDate?

    Objective-C

    - (NSDate * _Nullable)dateWithEra:(NSInteger)eraValue yearForWeekOfYear:(NSInteger)yearValue weekOfYear:(NSInteger)weekValue weekday:(NSInteger)weekdayValue hour:(NSInteger)hourValue minute:(NSInteger)minuteValue second:(NSInteger)secondValue nanosecond:(NSInteger)nanosecondValue

    Parameters

    eraValue

    The value for the era component.

    yearValue

    The value for the year component.

    weekValue

    The value for the week-of-year component.

    weekdayValue

    The value to use as the weekday.

    hourValue

    The value for the hour component.

    minuteValue

    The value for the minute component.

    secondValue

    The value for the second component.

    nanosecondValue

    The value for the nanosecond component.

    Return Value

    A new NSDate instance created with the given components based on a week-of-year calculation, or nil if the components do not correspond to a valid date.

    Availability

    Available in iOS 8.0 and later.

  • Returns whether a given date matches all of the given date components.

    Declaration

    Swift

    func date(_ date: NSDate, matchesComponents components: NSDateComponents) -> Bool

    Objective-C

    - (BOOL)date:(NSDate * _Nonnull)date matchesComponents:(NSDateComponents * _Nonnull)comps

    Parameters

    date

    The date for which to perform the calculation.

    comps

    The date components to match.

    Return Value

    YEStrue if the given date matches the given components, otherwise NOfalse.

    Discussion

    This method is useful for determining whether dates calculated by methods like nextDateAfterDate:matchingUnit:value:options: or enumerateDatesStartingAfterDate:matchingComponents:options:usingBlock: are exact, or required an adjustment due to a nonexistent time.

    Availability

    Available in iOS 8.0 and later.

  • Returns the next date after a given date matching the given components.

    Declaration

    Swift

    func nextDateAfterDate(_ date: NSDate, matchingComponents comps: NSDateComponents, options options: NSCalendarOptions) -> NSDate?

    Objective-C

    - (NSDate * _Nullable)nextDateAfterDate:(NSDate * _Nonnull)date matchingComponents:(NSDateComponents * _Nonnull)comps options:(NSCalendarOptions)options

    Parameters

    date

    The date for which to perform the calculation.

    comps

    The date components to match.

    options

    Options for the calculation. For possible values, see “Calendar Options”.

    Return Value

    A new NSDate object.

    Discussion

    To compute a sequence of dates, use the enumerateDatesStartingAfterDate:matchingComponents:options:usingBlock: method instead of calling this method in a loop with the previous loop iteration's result.

    Availability

    Available in iOS 8.0 and later.

  • Returns the next date after a given date that matches the given hour, minute, and second, component values.

    Declaration

    Swift

    func nextDateAfterDate(_ date: NSDate, matchingHour hourValue: Int, minute minuteValue: Int, second secondValue: Int, options options: NSCalendarOptions) -> NSDate?

    Objective-C

    - (NSDate * _Nullable)nextDateAfterDate:(NSDate * _Nonnull)date matchingHour:(NSInteger)hourValue minute:(NSInteger)minuteValue second:(NSInteger)secondValue options:(NSCalendarOptions)options

    Parameters

    date

    The date for which to perform the calculation.

    hourValue

    The value for the hour component.

    minuteValue

    The value for the minute component.

    secondValue

    The value for the second component.

    options

    Options for the calculation. For possible values, see “Calendar Options”.

    Return Value

    A new NSDate object.

    Availability

    Available in iOS 8.0 and later.

  • Returns the next date after a given date matching the given calendar unit value.

    Declaration

    Swift

    func nextDateAfterDate(_ date: NSDate, matchingUnit unit: NSCalendarUnit, value value: Int, options options: NSCalendarOptions) -> NSDate?

    Objective-C

    - (NSDate * _Nullable)nextDateAfterDate:(NSDate * _Nonnull)date matchingUnit:(NSCalendarUnit)unit value:(NSInteger)value options:(NSCalendarOptions)options

    Parameters

    date

    The date for which to perform the calculation.

    unit

    The component to use. For possible values, see “Calendar Units”.

    value

    The value for the given component.

    options

    Options for the calculation. For possible values, see “Calendar Options”.

    Return Value

    A new NSDate object.

    Availability

    Available in iOS 8.0 and later.

  • Returns by reference the starting date and time interval range of the next weekend period after a given date.

    Declaration

    Swift

    func nextWeekendStartDate(_ datep: AutoreleasingUnsafeMutablePointer<NSDate?>, interval tip: UnsafeMutablePointer<NSTimeInterval>, options options: NSCalendarOptions, afterDate date: NSDate) -> Bool

    Objective-C

    - (BOOL)nextWeekendStartDate:(out NSDate * _Nullable * _Nullable)datep interval:(out NSTimeInterval * _Nullable)tip options:(NSCalendarOptions)options afterDate:(NSDate * _Nonnull)date

    Parameters

    datep

    Upon return, contains the starting date of the next weekend period.

    tip

    Upon return, contains the time interval of the next weekend period.

    options

    Options for the calculation. If you specify a backward search option (NSCalendarSearchBackwards), the starting date and time interval range of the preceding weekend period will be returned by reference instead.

    date

    The date for which to perform the calculation.

    Return Value

    NOfalse if the calendar and locale do not have the concept of a weekend, otherwise YEStrue.

    Special Considerations

    Note that a particular calendar day may not necessarily fall entirely within a weekend period, as weekends can start in the middle of a day in some calendars and locales.

    Availability

    Available in iOS 8.0 and later.

  • Returns the first moment date of a given date

    Declaration

    Swift

    func startOfDayForDate(_ date: NSDate) -> NSDate

    Objective-C

    - (NSDate * _Nonnull)startOfDayForDate:(NSDate * _Nonnull)date

    Parameters

    date

    The date for which to perform the calculation.

    Return Value

    An NSDate instance representing the first moment date of the given date.

    Discussion

    For example, passing [NSDate date] for the date parameter would give you the start of “today.”

    Special Considerations

    If there were two midnights, this method returns the first. If there was none, it returns the first moment that did exist.

    Availability

    Available in iOS 8.0 and later.

  • Returns an NSComparisonResult value that indicates the ordering of two given dates based on their components down to a given unit granularity.

    Declaration

    Swift

    func compareDate(_ date1: NSDate, toDate date2: NSDate, toUnitGranularity unit: NSCalendarUnit) -> NSComparisonResult

    Objective-C

    - (NSComparisonResult)compareDate:(NSDate * _Nonnull)date1 toDate:(NSDate * _Nonnull)date2 toUnitGranularity:(NSCalendarUnit)unit

    Parameters

    date1

    The first date to compare.

    date2

    The second date to compare.

    unit

    The smallest unit that must, along with all larger units, be equal for the given dates to be considered the same. For possible values, see “Calendar Units”.

    Return Value

    NSOrderedSame if the dates are the same down to the given granularity, otherwise NSOrderedAscending or NSOrderedDescending.

    Availability

    Available in iOS 8.0 and later.

  • Returns whether two dates are equal to a given unit of granularity.

    Declaration

    Swift

    func isDate(_ date1: NSDate, equalToDate date2: NSDate, toUnitGranularity unit: NSCalendarUnit) -> Bool

    Objective-C

    - (BOOL)isDate:(NSDate * _Nonnull)date1 equalToDate:(NSDate * _Nonnull)date2 toUnitGranularity:(NSCalendarUnit)unit

    Parameters

    date1

    The first date to compare.

    date2

    The second date to compare.

    unit

    The smallest unit that must, along with all larger units, be equal in the given dates. For possible values, see “Calendar Units”.

    Return Value

    YEStrue if both dates have equal date component for all units greater than or equal to the given unit, otherwise NOfalse.

    Availability

    Available in iOS 8.0 and later.

  • Returns whether two dates are in the same day.

    Declaration

    Swift

    func isDate(_ date1: NSDate, inSameDayAsDate date2: NSDate) -> Bool

    Objective-C

    - (BOOL)isDate:(NSDate * _Nonnull)date1 inSameDayAsDate:(NSDate * _Nonnull)date2

    Parameters

    date1

    The first date to compare.

    date2

    The second date to compare.

    Return Value

    YEStrue if both dates are within the same day, otherwise NOfalse.

    Availability

    Available in iOS 8.0 and later.

  • Returns whether the given date is in “today.”

    Declaration

    Swift

    func isDateInToday(_ date: NSDate) -> Bool

    Objective-C

    - (BOOL)isDateInToday:(NSDate * _Nonnull)date

    Parameters

    date

    The date for which to perform the calculation.

    Return Value

    YEStrue if the given date is in “today,” otherwise NOfalse.

    Availability

    Available in iOS 8.0 and later.

  • Returns whether the given date is in “tomorrow.”

    Declaration

    Swift

    func isDateInTomorrow(_ date: NSDate) -> Bool

    Objective-C

    - (BOOL)isDateInTomorrow:(NSDate * _Nonnull)date

    Parameters

    date

    The date for which to perform the calculation.

    Return Value

    YEStrue if the given date is in “tomorrow,” otherwise NOfalse.

    Availability

    Available in iOS 8.0 and later.

  • Returns whether a given date falls within a weekend period, as defined by the calendar and the calendar's locale.

    Declaration

    Swift

    func isDateInWeekend(_ date: NSDate) -> Bool

    Objective-C

    - (BOOL)isDateInWeekend:(NSDate * _Nonnull)date

    Parameters

    date

    The date for which to perform the calculation.

    Return Value

    YEStrue if the given date is within a weekend period, otherwise NOfalse.

    Discussion

    If the date does fall within a weekend, you can use the rangeOfWeekendStartDate:interval:containingDate: method to determine the start date of that weekend period. Otherwise, you can use the nextWeekendStartDate:interval:options:afterDate: method to determine the start date of the next or previous weekend.

    Availability

    Available in iOS 8.0 and later.

  • Returns whether the given date is in “yesterday.”

    Declaration

    Swift

    func isDateInYesterday(_ date: NSDate) -> Bool

    Objective-C

    - (BOOL)isDateInYesterday:(NSDate * _Nonnull)date

    Parameters

    date

    The date for which to perform the calculation.

    Return Value

    YEStrue if the given date is in “yesterday,” otherwise NOfalse.

    Availability

    Available in iOS 8.0 and later.

  • Returns the specified date component from a given date.

    Declaration

    Swift

    func component(_ unit: NSCalendarUnit, fromDate date: NSDate) -> Int

    Objective-C

    - (NSInteger)component:(NSCalendarUnit)unit fromDate:(NSDate * _Nonnull)date

    Parameters

    unit

    The component to return. For possible values, see “Calendar Units”.

    date

    The date for which to perform the calculation.

    Return Value

    An NSInteger value for the requested component.

    Availability

    Available in iOS 8.0 and later.

  • Returns a NSDateComponents object containing a given date decomposed into specified components.

    Declaration

    Swift

    func components(_ unitFlags: NSCalendarUnit, fromDate date: NSDate) -> NSDateComponents

    Objective-C

    - (NSDateComponents * _Nonnull)components:(NSCalendarUnit)unitFlags fromDate:(NSDate * _Nonnull)date

    Parameters

    unitFlags

    The components into which to decompose date.

    date

    The date for which to perform the calculation.

    Return Value

    An NSDateComponents object containing date decomposed into the components specified by unitFlags. Returns nil if date falls outside of the defined range of the receiver or if the computation cannot be performed

    Discussion

    The Weekday ordinality, when requested, refers to the next larger (than Week) of the requested units. Some computations can take a relatively long time.

    The following example shows how to use this method to determine the current year, month, and day, using an existing calendar (gregorian):

    1. unsigned unitFlags = NSYearCalendarUnit | NSMonthCalendarUnit | NSDayCalendarUnit;
    2. NSDate *date = [NSDate date];
    3. NSDateComponents *comps = [gregorian components:unitFlags fromDate:date];

    Availability

    Available in iOS 2.0 and later.

  • Returns, as an NSDateComponents object using specified components, the difference between two supplied dates.

    Declaration

    Swift

    func components(_ unitFlags: NSCalendarUnit, fromDate startingDate: NSDate, toDate resultDate: NSDate, options opts: NSCalendarOptions) -> NSDateComponents

    Objective-C

    - (NSDateComponents * _Nonnull)components:(NSCalendarUnit)unitFlags fromDate:(NSDate * _Nonnull)startingDate toDate:(NSDate * _Nonnull)resultDate options:(NSCalendarOptions)options

    Parameters

    unitFlags

    Specifies the components for the returned NSDateComponents object.

    startingDate

    The start date for the calculation.

    resultDate

    The end date for the calculation.

    options

    Options for the calculation.

    If you specify a “wrap” option (NSWrapCalendarComponents), the specified components are incremented and wrap around to zero/one on overflow, but do not cause higher units to be incremented. When the wrap option is false, overflow in a unit carries into the higher units, as in typical addition.

    Return Value

    An NSDateComponents object whose components are specified by unitFlags and calculated from the difference between the resultDate and startDate using the options specified by options. Returns nil if either date falls outside the defined range of the receiver or if the computation cannot be performed.

    Discussion

    The result is lossy if there is not a small enough unit requested to hold the full precision of the difference. Some operations can be ambiguous, and the behavior of the computation is calendar-specific, but generally larger components will be computed before smaller components; for example, in the Gregorian calendar a result might be 1 month and 5 days instead of, for example, 0 months and 35 days. The resulting component values may be negative if resultDate is before startDate.

    The following example shows how to get the approximate number of months and days between two dates using an existing calendar (gregorian):

    1. NSDate *startDate = ...;
    2. NSDate *endDate = ...;
    3. unsigned int unitFlags = NSMonthCalendarUnit | NSDayCalendarUnit;
    4. NSDateComponents *comps = [gregorian components:unitFlags fromDate:startDate toDate:endDate options:0];
    5. int months = [comps month];
    6. int days = [comps day];

    Note that some computations can take a relatively long time.

    Availability

    Available in iOS 2.0 and later.

  • Returns an NSDateComponents object representing the difference between start and end NSDate objects constructed from given NSDateComponents objects.

    Declaration

    Swift

    func components(_ unitFlags: NSCalendarUnit, fromDateComponents startingDateComp: NSDateComponents, toDateComponents resultDateComp: NSDateComponents, options options: NSCalendarOptions) -> NSDateComponents

    Objective-C

    - (NSDateComponents * _Nonnull)components:(NSCalendarUnit)unitFlags fromDateComponents:(NSDateComponents * _Nonnull)startingDateComp toDateComponents:(NSDateComponents * _Nonnull)resultDateComp options:(NSCalendarOptions)options

    Parameters

    unitFlags

    Specifies the components for the returned NSDateComponents object.

    startingDateComp

    The start date for the calculation as an NSDateComponents object.

    resultDateComp

    The end date for the calculation as an NSDateComponents object.

    options

    Options for the calculation. No options are currently defined, so you should pass 0 for this parameter.

    Return Value

    An NSDateComponents object whose components are specified by unitFlags and calculated from the difference between the startingDateComp and resultDateComp using the options specified by options. Returns nil if either date falls outside the defined range of the receiver or if the computation cannot be performed.

    Discussion

    If an NSDateComponents object does not specify a value for a calendar unit required to determine an absolute date, the base value of that unit is assumed. For example, given an NSDateComponents object with only a year and a month specified, the resulting NSDate object would be constructed using a day value of 1 and hour, minute, second and nanosecond values of 0. Passing an NSDateComponents argument with an unspecified era or year value is not advised.

    If an NSDateComponents object's timeZone property is set, the time zone property value will be used in the calculation. If an NSDateComponents object's calendar property is set, the calendar property value will be used instead of the receiving calendar. If both an NSDateComponents object's timeZone and calendar properties are set, the time zone property value overrides the time zone of the calendar property value.

    Availability

    Available in iOS 8.0 and later.

  • Returns all the date components of a date, as if in a given time zone (instead of the receiving calendar’s time zone).

    Declaration

    Swift

    func componentsInTimeZone(_ timezone: NSTimeZone, fromDate date: NSDate) -> NSDateComponents

    Objective-C

    - (NSDateComponents * _Nonnull)componentsInTimeZone:(NSTimeZone * _Nonnull)timezone fromDate:(NSDate * _Nonnull)date

    Parameters

    timezone

    The time zone to use when returning the components. This value overrides the time zone of the receiving NSCalendar.

    date

    The date for which to perform the calculation.

    Return Value

    An NSDateComponents object containing all the components from the given date, calculated using the given time zone.

    Special Considerations

    If you want "date information in a given time zone" for the purpose to displaying it, you should use NSDateFormatter to format the date.

    Availability

    Available in iOS 8.0 and later.

  • Returns by reference the era, year, week of year, and weekday component values for a given date.

    Declaration

    Swift

    func getEra(_ eraValuePointer: UnsafeMutablePointer<Int>, year yearValuePointer: UnsafeMutablePointer<Int>, month monthValuePointer: UnsafeMutablePointer<Int>, day dayValuePointer: UnsafeMutablePointer<Int>, fromDate date: NSDate)

    Objective-C

    - (void)getEra:(out NSInteger * _Nullable)eraValuePointer year:(out NSInteger * _Nullable)yearValuePointer month:(out NSInteger * _Nullable)monthValuePointer day:(out NSInteger * _Nullable)dayValuePointer fromDate:(NSDate * _Nonnull)date

    Parameters

    eraValuePointer

    Upon return, contains the era of the given date.

    yearValuePointer

    Upon return, contains the year of the given date.

    monthValuePointer

    Upon return, contains the month of the given date.

    dayValuePointer

    Upon return, contains the day of the given date.

    date

    The date for which to perform the calculation.

    Discussion

    Pass NULL to ignore any individual component parameter.

    This is a convenience method for getting the time components of a given date using components:fromDate:

    Availability

    Available in iOS 8.0 and later.

  • Returns by reference the era, year, week of year, and weekday component values for a given date.

    Declaration

    Swift

    func getEra(_ eraValuePointer: UnsafeMutablePointer<Int>, yearForWeekOfYear yearValuePointer: UnsafeMutablePointer<Int>, weekOfYear weekValuePointer: UnsafeMutablePointer<Int>, weekday weekdayValuePointer: UnsafeMutablePointer<Int>, fromDate date: NSDate)

    Objective-C

    - (void)getEra:(out NSInteger * _Nullable)eraValuePointer yearForWeekOfYear:(out NSInteger * _Nullable)yearValuePointer weekOfYear:(out NSInteger * _Nullable)weekValuePointer weekday:(out NSInteger * _Nullable)weekdayValuePointer fromDate:(NSDate * _Nonnull)date

    Parameters

    eraValuePointer

    Upon return, contains the era of the given date.

    yearValuePointer

    Upon return, contains the year of the given date.

    weekValuePointer

    Upon return, contains the week of the given date.

    weekdayValuePointer

    Upon return, contains the weekday of the given date.

    date

    The date for which to perform the calculation.

    Discussion

    Pass NULL to ignore any individual component parameter.

    This is a convenience method for getting the time components of a given date using components:fromDate:

    Availability

    Available in iOS 8.0 and later.

  • Returns by reference the hour, minute, second, and nanosecond component values for a given date.

    Declaration

    Swift

    func getHour(_ hourValuePointer: UnsafeMutablePointer<Int>, minute minuteValuePointer: UnsafeMutablePointer<Int>, second secondValuePointer: UnsafeMutablePointer<Int>, nanosecond nanosecondValuePointer: UnsafeMutablePointer<Int>, fromDate date: NSDate)

    Objective-C

    - (void)getHour:(out NSInteger * _Nullable)hourValuePointer minute:(out NSInteger * _Nullable)minuteValuePointer second:(out NSInteger * _Nullable)secondValuePointer nanosecond:(out NSInteger * _Nullable)nanosecondValuePointer fromDate:(NSDate * _Nonnull)date

    Parameters

    hourValuePointer

    Upon return, contains the hour of the given date.

    minuteValuePointer

    Upon return, contains the minute of the given date.

    secondValuePointer

    Upon return, contains the second of the given date.

    nanosecondValuePointer

    Upon return, contains the nanosecond of the given date.

    date

    The date for which to perform the calculation.

    Discussion

    Pass NULL to ignore any individual component parameter.

    This is a convenience method for getting the time components of a given date using components:fromDate:

    Availability

    Available in iOS 8.0 and later.

  • The AM symbol for the receiver. (read-only)

    Declaration

    Swift

    var AMSymbol: String { get }

    Objective-C

    @property(readonly, copy, nonnull) NSString *AMSymbol

    Availability

    Available in iOS 5.0 and later.

  • The PM symbol for the receiver. (read-only)

    Declaration

    Swift

    var PMSymbol: String { get }

    Objective-C

    @property(readonly, copy, nonnull) NSString *PMSymbol

    Availability

    Available in iOS 5.0 and later.

  • An array of weekday symbols for the receiver. (read-only)

    Declaration

    Swift

    var weekdaySymbols: [String] { get }

    Objective-C

    @property(readonly, copy, nonnull) NSArray <NSString *> *weekdaySymbols

    Availability

    Available in iOS 5.0 and later.

  • An array of short weekday symbols for the receiver. (read-only)

    Declaration

    Swift

    var shortWeekdaySymbols: [String] { get }

    Objective-C

    @property(readonly, copy, nonnull) NSArray <NSString *> *shortWeekdaySymbols

    Availability

    Available in iOS 5.0 and later.

  • An array of very short weekday symbols for the receiver. (read-only)

    Declaration

    Swift

    var veryShortWeekdaySymbols: [String] { get }

    Objective-C

    @property(readonly, copy, nonnull) NSArray <NSString *> *veryShortWeekdaySymbols

    Availability

    Available in iOS 5.0 and later.

  • An array of standalone weekday symbols for the receiver. (read-only)

    Declaration

    Swift

    var standaloneWeekdaySymbols: [String] { get }

    Objective-C

    @property(readonly, copy, nonnull) NSArray <NSString *> *standaloneWeekdaySymbols

    Availability

    Available in iOS 5.0 and later.

  • An array of short standalone weekday symbols for the receiver. (read-only)

    Declaration

    Swift

    var shortStandaloneWeekdaySymbols: [String] { get }

    Objective-C

    @property(readonly, copy, nonnull) NSArray <NSString *> *shortStandaloneWeekdaySymbols

    Availability

    Available in iOS 5.0 and later.

  • An array of very short standalone weekday symbols for the receiver. (read-only)

    Declaration

    Swift

    var veryShortStandaloneWeekdaySymbols: [String] { get }

    Objective-C

    @property(readonly, copy, nonnull) NSArray <NSString *> *veryShortStandaloneWeekdaySymbols

    Availability

    Available in iOS 5.0 and later.

  • An array of month symbols for the receiver. (read-only)

    Declaration

    Swift

    var monthSymbols: [String] { get }

    Objective-C

    @property(readonly, copy, nonnull) NSArray <NSString *> *monthSymbols

    Availability

    Available in iOS 5.0 and later.

  • An array of short month symbols for the receiver. (read-only)

    Declaration

    Swift

    var shortMonthSymbols: [String] { get }

    Objective-C

    @property(readonly, copy, nonnull) NSArray <NSString *> *shortMonthSymbols

    Availability

    Available in iOS 5.0 and later.

  • An array of very short month symbols for the receiver. (read-only)

    Declaration

    Swift

    var veryShortMonthSymbols: [String] { get }

    Objective-C

    @property(readonly, copy, nonnull) NSArray <NSString *> *veryShortMonthSymbols

    Availability

    Available in iOS 5.0 and later.

  • An array of standalone month symbols for the receiver. (read-only)

    Declaration

    Swift

    var standaloneMonthSymbols: [String] { get }

    Objective-C

    @property(readonly, copy, nonnull) NSArray <NSString *> *standaloneMonthSymbols

    Availability

    Available in iOS 5.0 and later.

  • An array of short standalone month symbols for the receiver. (read-only)

    Declaration

    Swift

    var shortStandaloneMonthSymbols: [String] { get }

    Objective-C

    @property(readonly, copy, nonnull) NSArray <NSString *> *shortStandaloneMonthSymbols

    Availability

    Available in iOS 5.0 and later.

  • An array of very short month symbols for the receiver. (read-only)

    Declaration

    Swift

    var veryShortStandaloneMonthSymbols: [String] { get }

    Objective-C

    @property(readonly, copy, nonnull) NSArray <NSString *> *veryShortStandaloneMonthSymbols

    Availability

    Available in iOS 5.0 and later.

  • An array of quarter symbols for the receiver. (read-only)

    Declaration

    Swift

    var quarterSymbols: [String] { get }

    Objective-C

    @property(readonly, copy, nonnull) NSArray <NSString *> *quarterSymbols

    Availability

    Available in iOS 5.0 and later.

  • An array of short quarter symbols for the receiver. (read-only)

    Declaration

    Swift

    var shortQuarterSymbols: [String] { get }

    Objective-C

    @property(readonly, copy, nonnull) NSArray <NSString *> *shortQuarterSymbols

    Availability

    Available in iOS 5.0 and later.

  • An array of standalone quarter symbols for the receiver. (read-only)

    Declaration

    Swift

    var standaloneQuarterSymbols: [String] { get }

    Objective-C

    @property(readonly, copy, nonnull) NSArray <NSString *> *standaloneQuarterSymbols

    Availability

    Available in iOS 5.0 and later.

  • An array of short standalone quarter symbols for the receiver. (read-only)

    Declaration

    Swift

    var shortStandaloneQuarterSymbols: [String] { get }

    Objective-C

    @property(readonly, copy, nonnull) NSArray <NSString *> *shortStandaloneQuarterSymbols

    Availability

    Available in iOS 5.0 and later.

  • An array of era symbols for the receiver. (read-only)

    Declaration

    Swift

    var eraSymbols: [String] { get }

    Objective-C

    @property(readonly, copy, nonnull) NSArray <NSString *> *eraSymbols

    Availability

    Available in iOS 5.0 and later.

  • An array of long era symbols for the receiver (read-only)

    Declaration

    Swift

    var longEraSymbols: [String] { get }

    Objective-C

    @property(readonly, copy, nonnull) NSArray <NSString *> *longEraSymbols

    Availability

    Available in iOS 5.0 and later.

Data Types

  • The options for arithmetic operations involving calendars.

    Declaration

    Swift

    struct NSCalendarUnit : OptionSetType { init(rawValue rawValue: UInt) static var Era: NSCalendarUnit { get } static var Year: NSCalendarUnit { get } static var Month: NSCalendarUnit { get } static var Day: NSCalendarUnit { get } static var Hour: NSCalendarUnit { get } static var Minute: NSCalendarUnit { get } static var Second: NSCalendarUnit { get } static var Weekday: NSCalendarUnit { get } static var WeekdayOrdinal: NSCalendarUnit { get } static var Quarter: NSCalendarUnit { get } static var WeekOfMonth: NSCalendarUnit { get } static var WeekOfYear: NSCalendarUnit { get } static var YearForWeekOfYear: NSCalendarUnit { get } static var Nanosecond: NSCalendarUnit { get } static var Calendar: NSCalendarUnit { get } static var TimeZone: NSCalendarUnit { get } static var NSEraCalendarUnit: NSCalendarUnit { get } static var NSYearCalendarUnit: NSCalendarUnit { get } static var NSMonthCalendarUnit: NSCalendarUnit { get } static var NSDayCalendarUnit: NSCalendarUnit { get } static var NSHourCalendarUnit: NSCalendarUnit { get } static var NSMinuteCalendarUnit: NSCalendarUnit { get } static var NSSecondCalendarUnit: NSCalendarUnit { get } static var NSWeekCalendarUnit: NSCalendarUnit { get } static var NSWeekdayCalendarUnit: NSCalendarUnit { get } static var NSWeekdayOrdinalCalendarUnit: NSCalendarUnit { get } static var NSQuarterCalendarUnit: NSCalendarUnit { get } static var NSWeekOfMonthCalendarUnit: NSCalendarUnit { get } static var NSWeekOfYearCalendarUnit: NSCalendarUnit { get } static var NSYearForWeekOfYearCalendarUnit: NSCalendarUnit { get } static var NSCalendarCalendarUnit: NSCalendarUnit { get } static var NSTimeZoneCalendarUnit: NSCalendarUnit { get } }

    Objective-C

    enum { NSCalendarWrapComponents = (1UL << 0), NSCalendarMatchStrictly = (1ULL << 1), NSCalendarSearchBackwards = (1ULL << 2), NSCalendarMatchPreviousTimePreservingSmallerUnits = (1ULL << 8), NSCalendarMatchNextTimePreservingSmallerUnits = (1ULL << 9), NSCalendarMatchNextTime = (1ULL << 10), NSCalendarMatchFirst = (1ULL << 12), NSCalendarMatchLast = (1ULL << 13) }; typedef NSUInteger NSCalendarUnit; enum { NSWrapCalendarComponents = NSCalendarWrapComponents, };

    Constants

    • WrapComponents

      NSCalendarWrapComponents

      Specifies that the operation should use arithmetic for calendar addition.

      Available in iOS 7.0 and later.

    • MatchStrictly

      NSCalendarMatchStrictly

      Specifies that the operation should travel as far forward or backward as necessary looking for a match.

      Available in iOS 7.0 and later.

    • SearchBackwards

      NSCalendarSearchBackwards

      Specifies that the operation should travel backwards to find the previous match before the given date.

      Available in iOS 7.0 and later.

    • MatchPreviousTimePreservingSmallerUnits

      NSCalendarMatchPreviousTimePreservingSmallerUnits

      Specifies that, if no matching time before the end of the next instance of the next higher unit to the highest specified unit is found, the operation should return the previous value of the highest unit that exists.

      Available in iOS 7.0 and later.

    • MatchNextTimePreservingSmallerUnits

      NSCalendarMatchNextTimePreservingSmallerUnits

      Specifies that, if no matching time before the end of the next instance of the next higher unit to the highest specified unit is found, the operation should return the next value of the highest unit that exists.

      Available in iOS 7.0 and later.

    • MatchNextTime

      NSCalendarMatchNextTime

      Specifies that, if no matching time before the end of the next instance of the next higher unit to the highest specified unit is found, the operation should return the next existing time value.

      Available in iOS 7.0 and later.

    • MatchFirst

      NSCalendarMatchFirst

      Specifies that, if there are two or more matching times, the operation should return the first occurrence.

      Available in iOS 7.0 and later.

    • MatchLast

      NSCalendarMatchLast

      Specifies that, if there are two or more matching times, the operation should return the last occurrence.

      Available in iOS 7.0 and later.

    • NSWrapCalendarComponents

      NSWrapCalendarComponents

      Specifies that the components specified for an NSDateComponents object should be incremented and wrap around to zero/one on overflow, but should not cause higher units to be incremented.

      Use NSCalendarWrapComponents instead.

      Available in iOS 2.0 and later.

      Deprecated in iOS 8.0.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.

  • Specify the identifier of the calendar, such as Gregorian, which is the common calendar in Europe, the Western Hemisphere, and elsewhere.

    Declaration

    Swift

    let NSCalendarIdentifierGregorian: String let NSCalendarIdentifierBuddhist: String let NSCalendarIdentifierChinese: String let NSCalendarIdentifierCoptic: String let NSCalendarIdentifierEthiopicAmeteMihret: String let NSCalendarIdentifierEthiopicAmeteAlem: String let NSCalendarIdentifierHebrew: String let NSCalendarIdentifierISO8601: String let NSCalendarIdentifierIndian: String let NSCalendarIdentifierIslamic: String let NSCalendarIdentifierIslamicCivil: String let NSCalendarIdentifierJapanese: String let NSCalendarIdentifierPersian: String let NSCalendarIdentifierRepublicOfChina: String let NSCalendarIdentifierIslamicTabular: String let NSCalendarIdentifierIslamicUmmAlQura: String

    Objective-C

    NSString * const NSCalendarIdentifierGregorian NSString * const NSCalendarIdentifierBuddhist NSString * const NSCalendarIdentifierChinese NSString * const NSCalendarIdentifierCoptic NSString * const NSCalendarIdentifierEthiopicAmeteMihret NSString * const NSCalendarIdentifierEthiopicAmeteAlem NSString * const NSCalendarIdentifierHebrew NSString * const NSCalendarIdentifierISO8601 NSString * const NSCalendarIdentifierIndian NSString * const NSCalendarIdentifierIslamic NSString * const NSCalendarIdentifierIslamicCivil NSString * const NSCalendarIdentifierJapanese NSString * const NSCalendarIdentifierPersian NSString * const NSCalendarIdentifierRepublicOfChina NSString * const NSCalendarIdentifierIslamicTabular NSString * const NSCalendarIdentifierIslamicUmmAlQura

    Constants

    • NSCalendarIdentifierGregorian

      NSCalendarIdentifierGregorian

      Identifier for the Gregorian calendar.

      Available in iOS 4.0 and later.

    • NSCalendarIdentifierBuddhist

      NSCalendarIdentifierBuddhist

      Identifier for the Buddhist calendar.

      Available in iOS 4.0 and later.

    • NSCalendarIdentifierChinese

      NSCalendarIdentifierChinese

      Identifier for the Chinese calendar.

      Available in iOS 4.0 and later.

    • NSCalendarIdentifierCoptic

      NSCalendarIdentifierCoptic

      Identifier for the Coptic calendar.

      Available in iOS 4.0 and later.

    • NSCalendarIdentifierEthiopicAmeteMihret

      NSCalendarIdentifierEthiopicAmeteMihret

      Identifier for the Ethiopic (Amete Mihret) calendar.

      Available in iOS 4.0 and later.

    • NSCalendarIdentifierEthiopicAmeteAlem

      NSCalendarIdentifierEthiopicAmeteAlem

      Identifier for the Ethiopic (Amete Alem) calendar.

      Available in iOS 4.0 and later.

    • NSCalendarIdentifierHebrew

      NSCalendarIdentifierHebrew

      Identifier for the Hebrew calendar.

      Available in iOS 4.0 and later.

    • NSCalendarIdentifierISO8601

      NSCalendarIdentifierISO8601

      Identifier for the ISO8601 calendar.

      Available in iOS 4.0 and later.

    • NSCalendarIdentifierIndian

      NSCalendarIdentifierIndian

      Identifier for the Indian calendar.

      Available in iOS 4.0 and later.

    • NSCalendarIdentifierIslamic

      NSCalendarIdentifierIslamic

      Identifier for the Islamic calendar.

      Available in iOS 4.0 and later.

    • NSCalendarIdentifierIslamicCivil

      NSCalendarIdentifierIslamicCivil

      Identifier for the Islamic civil calendar.

      Available in iOS 4.0 and later.

    • NSCalendarIdentifierJapanese

      NSCalendarIdentifierJapanese

      Identifier for the Japanese calendar.

      Available in iOS 4.0 and later.

    • NSCalendarIdentifierPersian

      NSCalendarIdentifierPersian

      Identifier for the Persian calendar.

      Available in iOS 4.0 and later.

    • NSCalendarIdentifierRepublicOfChina

      NSCalendarIdentifierRepublicOfChina

      Identifier for the Republic of Chain (Taiwan) calendar.

      Available in iOS 4.0 and later.

    • NSCalendarIdentifierIslamicTabular

      NSCalendarIdentifierIslamicTabular

      Identifier for a tabular Islamic calendar.

      Available in iOS 8.0 and later.

    • NSCalendarIdentifierIslamicUmmAlQura

      NSCalendarIdentifierIslamicUmmAlQura

      Identifier for the Islamic Umm al-Qura calendar.

      Available in iOS 8.0 and later.

  • Notifications are posted through [NSNotificationCenter defaultCenter] when the system day changes.

    Declaration

    Swift

    let NSCalendarDayChangedNotification: String

    Objective-C

    (NSString *) const NSCalendarDayChangedNotification

    Constants

    • NSCalendarDayChangedNotification

      NSCalendarDayChangedNotification

      Posted whenever the calendar day of the system changes, as determined by the system calendar, locale, and time zone. This notification does not provide an object.

      If the the device is asleep when the day changes, this notification will be posted on wakeup. Only one notification will be posted on wakeup if the device has been asleep for multiple days.

      There are no guarantees about the timeliness of when this notification will be received by observers. As such, you should not rely on this notification being posted or received at any precise time.

      Available in iOS 8.0 and later.

  • NSDateComponents is not responsible for answering questions about a date beyond the information it has been initialized with; for example, if you initialize one with May 6, 2004, and then ask for the weekday, you'll get Undefined, not Thurs. A NSDateComponents is meaningless in itself, because you need to know what calendar it is interpreted against, and you need to know whether the values are absolute values of the units,or quantities of the units. When you create a new one of these, all values begin Undefined.

    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 iOS 7.0 and later.

    • NSUndefinedDateComponent

      NSUndefinedDateComponent

      Specifies a date component without a value.

      Use NSDateComponentUndefined instead.

      Available in iOS 2.0 and later.

      Deprecated in iOS 8.0.

  • Specify calendrical units such as day and month.

    Declaration

    Swift

    struct NSCalendarUnit : OptionSetType { init(rawValue rawValue: UInt) static var Era: NSCalendarUnit { get } static var Year: NSCalendarUnit { get } static var Month: NSCalendarUnit { get } static var Day: NSCalendarUnit { get } static var Hour: NSCalendarUnit { get } static var Minute: NSCalendarUnit { get } static var Second: NSCalendarUnit { get } static var Weekday: NSCalendarUnit { get } static var WeekdayOrdinal: NSCalendarUnit { get } static var Quarter: NSCalendarUnit { get } static var WeekOfMonth: NSCalendarUnit { get } static var WeekOfYear: NSCalendarUnit { get } static var YearForWeekOfYear: NSCalendarUnit { get } static var Nanosecond: NSCalendarUnit { get } static var Calendar: NSCalendarUnit { get } static var TimeZone: NSCalendarUnit { get } static var NSEraCalendarUnit: NSCalendarUnit { get } static var NSYearCalendarUnit: NSCalendarUnit { get } static var NSMonthCalendarUnit: NSCalendarUnit { get } static var NSDayCalendarUnit: NSCalendarUnit { get } static var NSHourCalendarUnit: NSCalendarUnit { get } static var NSMinuteCalendarUnit: NSCalendarUnit { get } static var NSSecondCalendarUnit: NSCalendarUnit { get } static var NSWeekCalendarUnit: NSCalendarUnit { get } static var NSWeekdayCalendarUnit: NSCalendarUnit { get } static var NSWeekdayOrdinalCalendarUnit: NSCalendarUnit { get } static var NSQuarterCalendarUnit: NSCalendarUnit { get } static var NSWeekOfMonthCalendarUnit: NSCalendarUnit { get } static var NSWeekOfYearCalendarUnit: NSCalendarUnit { get } static var NSYearForWeekOfYearCalendarUnit: NSCalendarUnit { get } static var NSCalendarCalendarUnit: NSCalendarUnit { get } static var NSTimeZoneCalendarUnit: NSCalendarUnit { get } }

    Objective-C

    enum { NSCalendarUnitEra = kCFCalendarUnitEra, NSCalendarUnitYear = kCFCalendarUnitYear, NSCalendarUnitMonth = kCFCalendarUnitMonth, NSCalendarUnitDay = kCFCalendarUnitDay, NSCalendarUnitHour = kCFCalendarUnitHour, NSCalendarUnitMinute = kCFCalendarUnitMinute, NSCalendarUnitSecond = kCFCalendarUnitSecond, NSCalendarUnitWeekday = kCFCalendarUnitWeekday, NSCalendarUnitWeekdayOrdinal = kCFCalendarUnitWeekdayOrdinal, NSCalendarUnitQuarter = kCFCalendarUnitQuarter, NSCalendarUnitWeekOfMonth = kCFCalendarUnitWeekOfMonth, NSCalendarUnitWeekOfYear = kCFCalendarUnitWeekOfYear, NSCalendarUnitYearForWeekOfYear = kCFCalendarUnitYearForWeekOfYear, NSCalendarUnitNanosecond = (1 << 15), NSCalendarUnitCalendar = (1 << 20), NSCalendarUnitTimeZone = (1 << 21), NSEraCalendarUnit = kCFCalendarUnitEra, NSYearCalendarUnit = kCFCalendarUnitYear, NSMonthCalendarUnit = kCFCalendarUnitMonth, NSDayCalendarUnit = kCFCalendarUnitDay, NSHourCalendarUnit = kCFCalendarUnitHour, NSMinuteCalendarUnit = kCFCalendarUnitMinute, NSSecondCalendarUnit = kCFCalendarUnitSecond, NSWeekCalendarUnit = kCFCalendarUnitWeek, NSWeekdayCalendarUnit = kCFCalendarUnitWeekday, NSWeekdayOrdinalCalendarUnit = kCFCalendarUnitWeekdayOrdinal, NSQuarterCalendarUnit = kCFCalendarUnitQuarter, NSWeekOfMonthCalendarUnit = kCFCalendarUnitWeekOfMonth, NSWeekOfYearCalendarUnit = kCFCalendarUnitWeekOfYear, NSYearForWeekOfYearCalendarUnit = kCFCalendarUnitYearForWeekOfYear NSCalendarCalendarUnit = (1 << 20), NSTimeZoneCalendarUnit = (1 << 21), }; typedef NSUInteger NSCalendarUnit;

    Constants

    • Era

      NSCalendarUnitEra

      Specifies the era unit.

      The corresponding value is an NSInteger. Equal to kCFCalendarUnitEra.

      Available in iOS 7.0 and later.

    • Year

      NSCalendarUnitYear

      Specifies the year unit.

      The corresponding value is an NSInteger. Equal to kCFCalendarUnitYear.

      Available in iOS 7.0 and later.

    • Month

      NSCalendarUnitMonth

      Specifies the month unit.

      The corresponding value is an NSInteger. Equal to kCFCalendarUnitMonth.

      Available in iOS 7.0 and later.

    • Day

      NSCalendarUnitDay

      Specifies the day unit.

      The corresponding value is an NSInteger. Equal to kCFCalendarUnitDay.

      Available in iOS 7.0 and later.

    • Hour

      NSCalendarUnitHour

      Specifies the hour unit.

      The corresponding value is an NSInteger. Equal to kCFCalendarUnitHour.

      Available in iOS 7.0 and later.

    • Minute

      NSCalendarUnitMinute

      Specifies the minute unit.

      The corresponding value is an NSInteger. Equal to kCFCalendarUnitMinute.

      Available in iOS 7.0 and later.

    • Second

      NSCalendarUnitSecond

      Specifies the second unit.

      The corresponding value is a double. Equal to kCFCalendarUnitSecond.

      Available in iOS 7.0 and later.

    • Weekday

      NSCalendarUnitWeekday

      Specifies the weekday unit.

      The corresponding value is an kCFCalendarUnitSecond. Equal to kCFCalendarUnitWeekday. The weekday units are the numbers 1 through N (where for the Gregorian calendar N=7 and 1 is Sunday).

      Available in iOS 7.0 and later.

    • WeekdayOrdinal

      NSCalendarUnitWeekdayOrdinal

      Specifies the ordinal weekday unit.

      The corresponding value is an kCFCalendarUnitSecond. Equal to kCFCalendarUnitWeekdayOrdinal. The weekday ordinal unit describes ordinal position within the month unit of the corresponding weekday unit. For example, in the Gregorian calendar a weekday ordinal unit of 2 for a weekday unit 3 indicates "the second Tuesday in the month".

      Available in iOS 7.0 and later.

    • Quarter

      NSCalendarUnitQuarter

      Specifies the quarter of the calendar as an kCFCalendarUnitSecond.

      Available in iOS 4.0 and later.

    • WeekOfMonth

      NSCalendarUnitWeekOfMonth

      Specifies the original week of a month calendar unit.

      Available in iOS 5.0 and later.

    • WeekOfYear

      NSCalendarUnitWeekOfYear

      Specifies the original week of the year calendar unit.

      Available in iOS 5.0 and later.

    • YearForWeekOfYear

      NSCalendarUnitYearForWeekOfYear

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

      Available in iOS 5.0 and later.

    • Nanosecond

      NSCalendarUnitNanosecond

      Specifies the nanosecond unit.

      Available in iOS 5.0 and later.

    • Calendar

      NSCalendarUnitCalendar

      Specifies the calendar of the calendar.

      Available in iOS 4.0 and later.

    • TimeZone

      NSCalendarUnitTimeZone

      Specifies the time zone of the calendar as an NSTimeZone.

      Available in iOS 4.0 and later.

    • NSEraCalendarUnit

      NSEraCalendarUnit

      Specifies the era unit.

      Use NSCalendarUnitEra instead.

      The corresponding value is an NSInteger. Equal to kCFCalendarUnitEra.

      Available in iOS 2.0 and later.

      Deprecated in iOS 8.0.

    • NSYearCalendarUnit

      NSYearCalendarUnit

      Specifies the year unit.

      Use NSCalendarUnitYear instead.

      The corresponding value is an NSInteger. Equal to kCFCalendarUnitYear.

      Available in iOS 2.0 and later.

      Deprecated in iOS 8.0.

    • NSMonthCalendarUnit

      NSMonthCalendarUnit

      Specifies the month unit.

      Use NSCalendarUnitMonth instead.

      The corresponding value is an NSInteger. Equal to kCFCalendarUnitMonth.

      Available in iOS 2.0 and later.

      Deprecated in iOS 8.0.

    • NSDayCalendarUnit

      NSDayCalendarUnit

      Specifies the day unit.

      Use NSCalendarUnitDay instead.

      The corresponding value is an NSInteger. Equal to kCFCalendarUnitDay.

      Available in iOS 2.0 and later.

      Deprecated in iOS 8.0.

    • NSHourCalendarUnit

      NSHourCalendarUnit

      Specifies the hour unit.

      Use NSCalendarUnitHour instead.

      The corresponding value is an NSInteger. Equal to kCFCalendarUnitHour.

      Available in iOS 2.0 and later.

      Deprecated in iOS 8.0.

    • NSMinuteCalendarUnit

      NSMinuteCalendarUnit

      Specifies the minute unit.

      Use NSCalendarUnitMinute instead.

      The corresponding value is an NSInteger. Equal to kCFCalendarUnitMinute.

      Available in iOS 2.0 and later.

      Deprecated in iOS 8.0.

    • NSSecondCalendarUnit

      NSSecondCalendarUnit

      Specifies the second unit.

      Use NSCalendarUnitSecond instead.

      The corresponding value is a double. Equal to kCFCalendarUnitSecond.

      Available in iOS 2.0 and later.

      Deprecated in iOS 8.0.

    • NSWeekCalendarUnit

      NSWeekCalendarUnit

      Specifies the week unit.

      Use NSCalendarUnitWeekOfMonth or NSCalendarUnitWeekOfYear instead.

      The corresponding value is an kCFCalendarUnitSecond. Equal to kCFCalendarUnitWeek.

      Available in iOS 2.0 and later.

      Deprecated in iOS 8.0.

    • NSWeekdayCalendarUnit

      NSWeekdayCalendarUnit

      Specifies the weekday unit.

      Use NSCalendarUnitWeekday instead.

      The corresponding value is an kCFCalendarUnitSecond. Equal to kCFCalendarUnitWeekday. The weekday units are the numbers 1 through N (where for the Gregorian calendar N=7 and 1 is Sunday).

      Available in iOS 2.0 and later.

      Deprecated in iOS 8.0.

    • NSWeekdayOrdinalCalendarUnit

      NSWeekdayOrdinalCalendarUnit

      Specifies the ordinal weekday unit.

      Use NSCalendarUnitWeekdayOrdinal instead.

      The corresponding value is an kCFCalendarUnitSecond. Equal to kCFCalendarUnitWeekdayOrdinal. The weekday ordinal unit describes ordinal position within the month unit of the corresponding weekday unit. For example, in the Gregorian calendar a weekday ordinal unit of 2 for a weekday unit 3 indicates "the second Tuesday in the month".

      Available in iOS 2.0 and later.

      Deprecated in iOS 8.0.

    • NSQuarterCalendarUnit

      NSQuarterCalendarUnit

      Specifies the quarter of the calendar as an kCFCalendarUnitSecond. In OS X v10.6 and earlier this was defined as equal to kCFCalendarUnitQuarter. In OS X v10.7 and later it is defined as (1 << 20).

      Use NSCalendarUnitQuarter instead.

      Available in iOS 4.0 and later.

      Deprecated in iOS 8.0.

    • NSWeekOfMonthCalendarUnit

      NSWeekOfMonthCalendarUnit

      Specifies the original week of a month calendar unit.

      Use NSCalendarUnitWeekOfMonth instead.

      Available in iOS 5.0 and later.

      Deprecated in iOS 8.0.

    • NSWeekOfYearCalendarUnit

      NSWeekOfYearCalendarUnit

      Specifies the original week of the year calendar unit.

      Use NSCalendarUnitWeekOfYear instead.

      Available in iOS 5.0 and later.

      Deprecated in iOS 8.0.

    • NSYearForWeekOfYearCalendarUnit

      NSYearForWeekOfYearCalendarUnit

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

      Use NSCalendarUnitYearForWeekOfYear instead.

      Available in iOS 5.0 and later.

      Deprecated in iOS 8.0.

    • NSCalendarCalendarUnit

      NSCalendarCalendarUnit

      Specifies the calendar of the calendar.

      Use NSCalendarUnitCalendar instead.

      Available in iOS 4.0 and later.

      Deprecated in iOS 8.0.

    • NSTimeZoneCalendarUnit

      NSTimeZoneCalendarUnit

      Specifies the time zone of the calendar as an NSTimeZone.

      Use NSCalendarUnitTimeZone instead.

      Available in iOS 4.0 and later.

      Deprecated in iOS 8.0.

    Discussion

    Calendar units may be used as a bit mask to specify a combination of units. Values in this enum are equal to the corresponding constants in the CFCalendarUnit enum.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in iOS 2.0 and later.