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.

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.

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

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

  • Initializes a newly-allocated NSCalendar object for the calendar specified by a given identifier.

    Declaration

    Swift

    init?(calendarIdentifier ident: String)

    Objective-C

    - (id nullable)initWithCalendarIdentifier:(NSString * nonnull)string

    Parameters

    string

    The identifier for the new calendar. For valid identifiers, see NSLocale.

    Return Value

    The initialized calendar, or nil if the identifier is unknown (if, for example, it is either an unrecognized string or the calendar is not supported by the current version of the operating system).

    Availability

    Available in iOS 2.0 and later.

  • Sets the index of the first weekday for the receiver.

    Declaration

    Swift

    var firstWeekday: Int

    Objective-C

    @property NSUInteger firstWeekday

    Parameters

    weekday

    The first weekday for the receiver.

    Availability

    Available in iOS 2.0 and later.

  • Sets the locale for the receiver.

    Declaration

    Swift

    @NSCopying var locale: NSLocale?

    Objective-C

    @property(copy) NSLocale *locale

    Parameters

    locale

    The locale for the receiver.

    Availability

    Available in iOS 2.0 and later.

    See Also

    – locale

  • Sets the minimum number of days in the first week of the receiver.

    Declaration

    Swift

    var minimumDaysInFirstWeek: Int

    Objective-C

    @property NSUInteger minimumDaysInFirstWeek

    Parameters

    mdw

    The minimum number of days in the first week of the receiver.

    Availability

    Available in iOS 2.0 and later.

  • Sets the time zone for the receiver.

    Declaration

    Swift

    @NSCopying var timeZone: NSTimeZone

    Objective-C

    @property(copy) NSTimeZone *timeZone

    Parameters

    tz

    The time zone for the receiver.

    Availability

    Available in iOS 2.0 and later.

    See Also

    – timeZone

  • 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—a bitwise OR of NSCalendarUnit constants.

    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):

    Objective-C

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

    Swift

    1. let flags: NSCalendarUnit = .DayCalendarUnit | .MonthCalendarUnit | .YearCalendarUnit
    2. let date = NSDate()
    3. let components = gregorian.components(flags, 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)opts

    Parameters

    unitFlags

    Specifies the components for the returned NSDateComponents object—a bitwise OR of NSCalendarUnit constants.

    startingDate

    The start date for the calculation.

    resultDate

    The end date for the calculation.

    opts

    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 opts. 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):

    Objective-C

    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];

    Swift

    1. let startDate = ...
    2. let endDate = ...
    3. let flags: NSCalendarUnit = .MonthCalendarUnit | .DayCalendarUnit
    4. let components = gregorian.components(flags, fromDate: startDate, toDate: endDate, options: nil)
    5. let months = components.month
    6. let days = components.day

    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 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 “NSDateComponents wrapping behavior” for possible values. Pass 0 to specify no options.

    If you specify no options (you pass 0), 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):

    Objective-C

    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];

    Swift

    1. let currentDate = NSDate()
    2. let components = NSDateComponents()
    3. components.month = 2
    4. components.day = 3
    5. let date = gregorian.dateByAddingComponents(components, toDate: currentDate, options: nil)

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

    Objective-C

    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];

    Swift

    1. let components = NSDateComponents()
    2. components.year = 1965
    3. components.month = 1
    4. components.day = 6
    5. components.hour = 14
    6. components.minute = 10
    7. components.second = 0
    8. let date = gregorian.dateFromComponents(components)

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

    Availability

    Available in iOS 2.0 and later.

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

    • NSEraCalendarUnit

      NSEraCalendarUnit

      Specifies the era unit.

      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.

      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.

      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.

      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.

      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.

      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.

      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.

      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.

      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.

      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.

      Available in iOS 4.0 and later.

      Deprecated in iOS 8.0.

    • NSWeekOfMonthCalendarUnit

      NSWeekOfMonthCalendarUnit

      Specifies the original week of a month calendar unit.

      Available in iOS 5.0 and later.

      Deprecated in iOS 8.0.

    • NSWeekOfYearCalendarUnit

      NSWeekOfYearCalendarUnit

      Specifies the original week of the year calendar unit.

      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.

      Available in iOS 5.0 and later.

      Deprecated in iOS 8.0.

    • NSCalendarCalendarUnit

      NSCalendarCalendarUnit

      Specifies the calendar of the calendar.

      Available in iOS 4.0 and later.

      Deprecated in iOS 8.0.

    • NSTimeZoneCalendarUnit

      NSTimeZoneCalendarUnit

      Specifies the time zone of the calendar as an NSTimeZone.

      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.

  • The wrapping option specifies wrapping behavior for calculations involving NSDateComponents objects.

    Declaration

    Swift

    var NSWrapCalendarComponents: Int { get }

    Objective-C

    enum { NSWrapCalendarComponents = kCFCalendarComponentsWrap, };

    Constants

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

      Available in iOS 2.0 and later.

      Deprecated in iOS 8.0.