Class

NSCalendar

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

Overview

NSCalendar is “toll-free bridged” with its Core Foundation counterpart, CFCalendar. 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 (gregorian), but there remain exceptions to this trend. For example:

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

  • India also uses the Indian national calendar (indian).

  • Israel also uses the Hebrew calendar (hebrew).

  • China and other regions also use the Chinese calendar (chinese), primarily to calculate astronomical date and Chinese traditional holidays.

  • Japan also uses the Japanese calendar (japanese), primarily to add year names.

Independent of any particular locale, certain calendars are used primarily to calculate dates for religious observances. Among these are the Buddhist (buddhist), Coptic (coptic), Hebrew (hebrew), and Islamic (islamic) 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 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, date(from:​), date(by​Adding:​to:​options:​), take as a parameter an NSDate​Components 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(_:​from:​) and components(_:​from:​to:​options:​)) take a bit mask parameter that specifies which components to calculate when returning an NSDate​Components object. The bit mask is composed of NSCalendar​Unit 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.

Nested Types

NSCalendar.Identifier

The type of a calendar identifier. See Calendar Identifiers for defined values.

NSCalendar.Options

The options for arithmetic operations involving calendars.

NSCalendar.Unit

Specify calendrical units such as day and month.

Symbols

System Locale Information

class var current:​ Calendar

Returns the logical calendar for the current user.

class var autoupdating​Current:​ Calendar

Returns the current logical calendar for the current user.

Creating and Initializing Calendars

init?(identifier:​ NSCalendar.Identifier)

Creates and returns a new NSCalendar object specified by a given identifier.

init?(calendar​Identifier:​ NSCalendar.Identifier)

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

Getting Information About a Calendar

var calendar​Identifier:​ NSCalendar.Identifier

A string representing a calendar identity.

var first​Weekday:​ Int

The index of the first weekday of the receiver.

var locale:​ Locale?

The locale of the receiver.

func maximum​Range(of:​ NSCalendar.Unit)

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

var minimum​Days​In​First​Week:​ Int

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

func minimum​Range(of:​ NSCalendar.Unit)

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

func ordinality(of:​ NSCalendar.Unit, in:​ NSCalendar.Unit, for:​ Date)

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

func range(of:​ NSCalendar.Unit, in:​ NSCalendar.Unit, for:​ Date)

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.

func range(of​Weekend​Start:​ Autoreleasing​Unsafe​Mutable​Pointer<NSDate?>?, interval:​ Unsafe​Mutable​Pointer<Time​Interval>?, containing:​ Date)

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.

var time​Zone:​ Time​Zone

The time zone for the receiver.

Calendrical Calculations

func date(by​Adding:​ Date​Components, to:​ Date, options:​ NSCalendar.Options = [])

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

func date(by​Adding:​ NSCalendar.Unit, value:​ Int, to:​ Date, options:​ NSCalendar.Options = [])

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

func date(from:​ Date​Components)

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

func enumerate​Dates(starting​After:​ Date, matching:​ Date​Components, options:​ NSCalendar.Options = [], using:​ (Date?, Bool, Unsafe​Mutable​Pointer<Obj​CBool>) -> Void)

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.

func date(by​Setting​Unit:​ NSCalendar.Unit, value:​ Int, of:​ Date, options:​ NSCalendar.Options = [])

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.

func date(Date, matches​Components:​ Date​Components)

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

func next​Date(after:​ Date, matching:​ Date​Components, options:​ NSCalendar.Options = [])

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

func next​Date(after:​ Date, matching​Hour:​ Int, minute:​ Int, second:​ Int, options:​ NSCalendar.Options = [])

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

func next​Date(after:​ Date, matching:​ NSCalendar.Unit, value:​ Int, options:​ NSCalendar.Options = [])

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

func start​Of​Day(for:​ Date)

Returns the first moment date of a given date

Comparing Dates

func compare(Date, to:​ Date, to​Unit​Granularity:​ NSCalendar.Unit)

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

func is​Date(Date, equal​To:​ Date, to​Unit​Granularity:​ NSCalendar.Unit)

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

func is​Date(Date, in​Same​Day​As:​ Date)

Returns whether two dates are in the same day.

func is​Date​In​Today(Date)

Returns whether the given date is in “today.”

func is​Date​In​Tomorrow(Date)

Returns whether the given date is in “tomorrow.”

func is​Date​In​Weekend(Date)

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

func is​Date​In​Yesterday(Date)

Returns whether the given date is in “yesterday.”

Extracting Components

func component(NSCalendar.Unit, from:​ Date)

Returns the specified date component from a given date.

func components(NSCalendar.Unit, from:​ Date)

Returns a NSDate​Components object containing a given date decomposed into specified components.

func components(NSCalendar.Unit, from:​ Date, to:​ Date, options:​ NSCalendar.Options = [])

Returns, as an NSDate​Components object using specified components, the difference between two supplied dates.

func components(NSCalendar.Unit, from:​ Date​Components, to:​ Date​Components, options:​ NSCalendar.Options = [])

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

func components(in:​ Time​Zone, from:​ Date)

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

AM and PM Symbols

var am​Symbol:​ String

The AM symbol for the receiver.

var pm​Symbol:​ String

The PM symbol for the receiver.

Weekday Symbols

var weekday​Symbols:​ [String]

An array of weekday symbols for the receiver.

var short​Weekday​Symbols:​ [String]

An array of short weekday symbols for the receiver.

var very​Short​Weekday​Symbols:​ [String]

An array of very short weekday symbols for the receiver.

var standalone​Weekday​Symbols:​ [String]

An array of standalone weekday symbols for the receiver.

var short​Standalone​Weekday​Symbols:​ [String]

An array of short standalone weekday symbols for the receiver.

var very​Short​Standalone​Weekday​Symbols:​ [String]

An array of very short standalone weekday symbols for the receiver.

Month Symbols

var month​Symbols:​ [String]

An array of month symbols for the receiver.

var short​Month​Symbols:​ [String]

An array of short month symbols for the receiver.

var very​Short​Month​Symbols:​ [String]

An array of very short month symbols for the receiver.

var standalone​Month​Symbols:​ [String]

An array of standalone month symbols for the receiver.

var short​Standalone​Month​Symbols:​ [String]

An array of short standalone month symbols for the receiver.

var very​Short​Standalone​Month​Symbols:​ [String]

An array of very short month symbols for the receiver.

Quarter Symbols

var quarter​Symbols:​ [String]

An array of quarter symbols for the receiver.

var short​Quarter​Symbols:​ [String]

An array of short quarter symbols for the receiver.

var standalone​Quarter​Symbols:​ [String]

An array of standalone quarter symbols for the receiver.

var short​Standalone​Quarter​Symbols:​ [String]

An array of short standalone quarter symbols for the receiver.

Era Symbols

var era​Symbols:​ [String]

An array of era symbols for the receiver.

var long​Era​Symbols:​ [String]

An array of long era symbols for the receiver

Constants

NSCalendar.Identifier

The type of a calendar identifier. See Calendar Identifiers for defined values.

Calendar Identifiers

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

Notifications

Notifications are posted through [NSNotification​Center default​Center] when the system day changes.

NSCalendar.Unit

Specify calendrical units such as day and month.

NSCalendar.Options

The options for arithmetic operations involving calendars.