<!--
{
  "availability" : [
    "iOS: 2.0.0 -",
    "iPadOS: 2.0.0 -",
    "macCatalyst: 13.0.0 -",
    "macOS: 10.0.0 -",
    "tvOS: 9.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 2.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "Foundation",
  "identifier" : "/documentation/Foundation/NSCalendar",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Foundation"
    ],
    "preciseIdentifier" : "c:objc(cs)NSCalendar"
  },
  "title" : "NSCalendar"
}
-->

# NSCalendar

A definition of the relationships between calendar units and absolute points in time, providing features for calculation and comparison of dates.

```
class NSCalendar
```

## Overview

In Swift, this object bridges to [`Calendar`](/documentation/Foundation/Calendar); use [`NSCalendar`](/documentation/Foundation/NSCalendar) when you need reference semantics or other Foundation-specific behavior.

[`NSCalendar`](/documentation/Foundation/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.

[`NSCalendar`](/documentation/Foundation/NSCalendar) is *toll-free bridged* with its Core Foundation counterpart, <doc://com.apple.documentation/documentation/CoreFoundation/CFCalendar>. See [Toll-Free Bridging](https://developer.apple.com/library/archive/documentation/General/Conceptual/CocoaEncyclopedia/Toll-FreeBridgin/Toll-FreeBridgin.html#//apple_ref/doc/uid/TP40010810-CH2) for more information on toll-free bridging.

> Important:
> The Swift overlay to the Foundation framework provides the ``doc://com.apple.foundation/documentation/Foundation/Calendar`` structure, which bridges to the ``doc://com.apple.foundation/documentation/Foundation/NSCalendar`` class. For more information about value types, see <doc://com.apple.documentation/documentation/Swift/working-with-foundation-types>.

### Locales and Calendars

Most locales use the most widely used civil calendar, called the *Gregorian calendar* ([`gregorian`](/documentation/Foundation/NSCalendar/Identifier/gregorian)), but there remain exceptions to this trend. For example:

- In Saudi Arabia, some locales use primarily the Islamic Umm al-Qura calendar ([`islamicUmmAlQura`](/documentation/Foundation/NSCalendar/Identifier/islamicUmmAlQura)).
- In Ethiopia, some locales use primarily the Ethiopian calendar ([`ethiopicAmeteMihret`](/documentation/Foundation/NSCalendar/Identifier/ethiopicAmeteMihret) or [`ethiopicAmeteAlem`](/documentation/Foundation/NSCalendar/Identifier/ethiopicAmeteAlem)).
- In Iran and Afghanistan, some locales use primarily the Persian calendar ([`persian`](/documentation/Foundation/NSCalendar/Identifier/persian)).
- In Thailand, some locales use primarily the Buddhist calendar ([`buddhist`](/documentation/Foundation/NSCalendar/Identifier/buddhist)).

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

- India also uses the Indian national calendar ([`indian`](/documentation/Foundation/NSCalendar/Identifier/indian)).
- Israel also uses the Hebrew calendar ([`hebrew`](/documentation/Foundation/NSCalendar/Identifier/hebrew)).
- China mainland and other regions also use the Chinese calendar ([`chinese`](/documentation/Foundation/NSCalendar/Identifier/chinese)), primarily to calculate astronomical date and Chinese traditional holidays.
- Japan also uses the Japanese calendar ([`japanese`](/documentation/Foundation/NSCalendar/Identifier/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`](/documentation/Foundation/NSCalendar/Identifier/buddhist)), Coptic ([`coptic`](/documentation/Foundation/NSCalendar/Identifier/coptic)), Hebrew ([`hebrew`](/documentation/Foundation/NSCalendar/Identifier/hebrew)), and Islamic ([`islamic`](/documentation/Foundation/NSCalendar/Identifier/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 regions continued to use the Julian calendar, with Turkey being the last country or region to adopt the Gregorian calendar, in 1926. As a result of the staggered adoption, the transition period for regions 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`](/documentation/Foundation/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`](/documentation/Foundation/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`](/documentation/Foundation/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`](/documentation/Foundation/NSCalendar) methods that return a date object, [`date(from:)`](/documentation/Foundation/NSCalendar/date(from:)), [`date(byAdding:to:options:)`](/documentation/Foundation/NSCalendar/date(byAdding:to:options:)), take as a parameter an [`NSDateComponents`](/documentation/Foundation/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(_:from:)`](/documentation/Foundation/NSCalendar/components(_:from:)) and [`components(_:from:to:options:)`](/documentation/Foundation/NSCalendar/components(_:from:to:options:)-84y5w)) take a bit mask parameter that specifies which components to calculate when returning an [`NSDateComponents`](/documentation/Foundation/NSDateComponents) object. The bit mask is composed of [`NSCalendar.Unit`](/documentation/Foundation/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.

## Topics

### Creating and Initializing Calendars

[`+  calendarWithIdentifier:`](/documentation/Foundation/NSCalendar/init(identifier:))

Creates a new calendar specified by a given identifier.

[`-  initWithCalendarIdentifier:`](/documentation/Foundation/NSCalendar/init(calendarIdentifier:))

Initializes a calendar according to a given identifier.

[`Identifier`](/documentation/Foundation/NSCalendar/Identifier)

The supported calendar types.

### Getting the User’s Calendar

[`currentCalendar`](/documentation/Foundation/NSCalendar/current)

The user’s current calendar.

[`autoupdatingCurrentCalendar`](/documentation/Foundation/NSCalendar/autoupdatingCurrent)

A calendar that tracks changes to user’s preferred calendar.

### Extracting Components

[`-  date:matchesComponents:`](/documentation/Foundation/NSCalendar/date(_:matchesComponents:))

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

[`-  component:fromDate:`](/documentation/Foundation/NSCalendar/component(_:from:))

Returns the specified date component from a given date.

[`-  components:fromDate:`](/documentation/Foundation/NSCalendar/components(_:from:))

Returns the date components representing a given date.

[`-  components:fromDate:toDate:options:`](/documentation/Foundation/NSCalendar/components(_:from:to:options:)-84y5w)

Returns the difference between two supplied dates as date components.

[`-  components:fromDateComponents:toDateComponents:options:`](/documentation/Foundation/NSCalendar/components(_:from:to:options:)-49lo8)

Returns the difference between start and end dates given as date components.

[`-  componentsInTimeZone:fromDate:`](/documentation/Foundation/NSCalendar/components(in:from:))

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

[`-  getEra:year:month:day:fromDate:`](/documentation/Foundation/NSCalendar/getEra(_:year:month:day:from:))

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

[`-  getEra:yearForWeekOfYear:weekOfYear:weekday:fromDate:`](/documentation/Foundation/NSCalendar/getEra(_:yearForWeekOfYear:weekOfYear:weekday:from:))

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

[`-  getHour:minute:second:nanosecond:fromDate:`](/documentation/Foundation/NSCalendar/getHour(_:minute:second:nanosecond:from:))

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

### Getting Calendar Information

[`calendarIdentifier`](/documentation/Foundation/NSCalendar/calendarIdentifier)

An identifier for the calendar.

[`firstWeekday`](/documentation/Foundation/NSCalendar/firstWeekday)

The index of the first weekday of the receiver.

[`locale`](/documentation/Foundation/NSCalendar/locale)

The locale of the receiver.

[`timeZone`](/documentation/Foundation/NSCalendar/timeZone)

The time zone for the calendar.

[`-  maximumRangeOfUnit:`](/documentation/Foundation/NSCalendar/maximumRange(of:))

Returns the maximum range limits of the values that a given unit can take on.

[`-  minimumRangeOfUnit:`](/documentation/Foundation/NSCalendar/minimumRange(of:))

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

[`minimumDaysInFirstWeek`](/documentation/Foundation/NSCalendar/minimumDaysInFirstWeek)

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

[`-  ordinalityOfUnit:inUnit:forDate:`](/documentation/Foundation/NSCalendar/ordinality(of:in:for:))

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

[`-  rangeOfUnit:inUnit:forDate:`](/documentation/Foundation/NSCalendar/range(of:in:for:))

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.

[`-  rangeOfUnit:startDate:interval:forDate:`](/documentation/Foundation/NSCalendar/range(of:start:interval:for:))

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

[`-  rangeOfWeekendStartDate:interval:containingDate:`](/documentation/Foundation/NSCalendar/range(ofWeekendStart:interval:containing:))

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.

[`Unit`](/documentation/Foundation/NSCalendar/Unit)

Calendrical units such as year, month, day and hour.

### Scanning Dates

[`-  startOfDayForDate:`](/documentation/Foundation/NSCalendar/startOfDay(for:))

Returns the first moment of a given date as a date instance.

[`-  enumerateDatesStartingAfterDate:matchingComponents:options:usingBlock:`](/documentation/Foundation/NSCalendar/enumerateDates(startingAfter:matching:options:using:))

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.

[`-  nextDateAfterDate:matchingComponents:options:`](/documentation/Foundation/NSCalendar/nextDate(after:matching:options:))

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

[`-  nextDateAfterDate:matchingHour:minute:second:options:`](/documentation/Foundation/NSCalendar/nextDate(after:matchingHour:minute:second:options:))

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

[`-  nextDateAfterDate:matchingUnit:value:options:`](/documentation/Foundation/NSCalendar/nextDate(after:matching:value:options:))

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

[`Options`](/documentation/Foundation/NSCalendar/Options)

The options for arithmetic operations involving calendars.

[NSWrapCalendarComponents](/documentation/Foundation/NSWrapCalendarComponents-api)

A legacy constant used to control overflow in date calculations.

### Calculating Dates

[`-  dateFromComponents:`](/documentation/Foundation/NSCalendar/date(from:))

Returns a date representing the absolute time calculated from given components.

[`-  dateByAddingComponents:toDate:options:`](/documentation/Foundation/NSCalendar/date(byAdding:to:options:))

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

[`-  dateByAddingUnit:value:toDate:options:`](/documentation/Foundation/NSCalendar/date(byAdding:value:to:options:))

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

[`-  dateBySettingHour:minute:second:ofDate:options:`](/documentation/Foundation/NSCalendar/date(bySettingHour:minute:second:of:options:))

Creates a new date calculated with the given time.

[`-  dateBySettingUnit:value:ofDate:options:`](/documentation/Foundation/NSCalendar/date(bySettingUnit:value:of:options:))

Returns a new date 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.

[`-  dateWithEra:year:month:day:hour:minute:second:nanosecond:`](/documentation/Foundation/NSCalendar/date(era:year:month:day:hour:minute:second:nanosecond:))

Returns a date created with the given components.

[`-  dateWithEra:yearForWeekOfYear:weekOfYear:weekday:hour:minute:second:nanosecond:`](/documentation/Foundation/NSCalendar/date(era:yearForWeekOfYear:weekOfYear:weekday:hour:minute:second:nanosecond:))

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

[`-  nextWeekendStartDate:interval:options:afterDate:`](/documentation/Foundation/NSCalendar/nextWeekendStart(_:interval:options:after:))

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

### Comparing Dates

[`-  compareDate:toDate:toUnitGranularity:`](/documentation/Foundation/NSCalendar/compare(_:to:toUnitGranularity:))

Indicates the ordering of two given dates based on their components down to a given unit granularity.

[`-  isDate:equalToDate:toUnitGranularity:`](/documentation/Foundation/NSCalendar/isDate(_:equalTo:toUnitGranularity:))

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

[`-  isDate:inSameDayAsDate:`](/documentation/Foundation/NSCalendar/isDate(_:inSameDayAs:))

Indicates whether two dates are in the same day.

[`-  isDateInToday:`](/documentation/Foundation/NSCalendar/isDateInToday(_:))

Indicates whether the given date is in “today.”

[`-  isDateInTomorrow:`](/documentation/Foundation/NSCalendar/isDateInTomorrow(_:))

Indicates whether the given date is in “tomorrow.”

[`-  isDateInWeekend:`](/documentation/Foundation/NSCalendar/isDateInWeekend(_:))

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

[`-  isDateInYesterday:`](/documentation/Foundation/NSCalendar/isDateInYesterday(_:))

Indicates whether the given date is in “yesterday.”

### Getting AM and PM Symbols

[`AMSymbol`](/documentation/Foundation/NSCalendar/amSymbol)

The symbol used to represent “AM” for this calendar.

[`PMSymbol`](/documentation/Foundation/NSCalendar/pmSymbol)

The symbol used to represent “PM” for this calendar.

### Getting Weekday Symbols

[`weekdaySymbols`](/documentation/Foundation/NSCalendar/weekdaySymbols)

A list of weekdays in this calendar.

[`shortWeekdaySymbols`](/documentation/Foundation/NSCalendar/shortWeekdaySymbols)

A list of shorter-named weekdays in this calendar.

[`veryShortWeekdaySymbols`](/documentation/Foundation/NSCalendar/veryShortWeekdaySymbols)

A list of very-shortly-named weekdays in this calendar.

[`standaloneWeekdaySymbols`](/documentation/Foundation/NSCalendar/standaloneWeekdaySymbols)

A list of standalone weekday symbols for this calendar.

[`shortStandaloneWeekdaySymbols`](/documentation/Foundation/NSCalendar/shortStandaloneWeekdaySymbols)

A list of short standalone weekday symbols for this calendar.

[`veryShortStandaloneWeekdaySymbols`](/documentation/Foundation/NSCalendar/veryShortStandaloneWeekdaySymbols)

A list of very short standalone weekday symbols for this calendar.

### Getting Month Symbols

[`monthSymbols`](/documentation/Foundation/NSCalendar/monthSymbols)

A list of month symbols for this calendar.

[`shortMonthSymbols`](/documentation/Foundation/NSCalendar/shortMonthSymbols)

A list of short month symbols for this calendar.

[`veryShortMonthSymbols`](/documentation/Foundation/NSCalendar/veryShortMonthSymbols)

A list of very short month symbols for this calendar.

[`standaloneMonthSymbols`](/documentation/Foundation/NSCalendar/standaloneMonthSymbols)

A list of standalone month symbols for this calendar.

[`shortStandaloneMonthSymbols`](/documentation/Foundation/NSCalendar/shortStandaloneMonthSymbols)

A list of short standalone month symbols for this calendar.

[`veryShortStandaloneMonthSymbols`](/documentation/Foundation/NSCalendar/veryShortStandaloneMonthSymbols)

A list of very short month symbols for this calendar.

### Getting Quarter Symbols

[`quarterSymbols`](/documentation/Foundation/NSCalendar/quarterSymbols)

A list of quarter symbols for this calendar.

[`shortQuarterSymbols`](/documentation/Foundation/NSCalendar/shortQuarterSymbols)

A list of short quarter symbols for this calendar.

[`standaloneQuarterSymbols`](/documentation/Foundation/NSCalendar/standaloneQuarterSymbols)

A list of standalone quarter symbols for this calendar.

[`shortStandaloneQuarterSymbols`](/documentation/Foundation/NSCalendar/shortStandaloneQuarterSymbols)

A list of short standalone quarter symbols for this calendar.

### Getting Era Symbols

[`eraSymbols`](/documentation/Foundation/NSCalendar/eraSymbols)

A list of era symbols for this calendar.

[`longEraSymbols`](/documentation/Foundation/NSCalendar/longEraSymbols)

A list of long era symbols for this calendar.

### Recognizing Notifications

[`NSCalendarDayChangedNotification`](/documentation/Foundation/NSNotification/Name-swift.struct/NSCalendarDayChanged)

A notification that is posted whenever the calendar day of the system changes, as determined by the system calendar, locale, and time zone.

## Relationships

### Conforms To

[`NSCoding`](/documentation/Foundation/NSCoding)

[`Escapable`](/documentation/Swift/Escapable)

[`Equatable`](/documentation/Swift/Equatable)

[`Hashable`](/documentation/Swift/Hashable)

[`NSObjectProtocol`](/documentation/ObjectiveC/NSObjectProtocol)

[`CVarArg`](/documentation/Swift/CVarArg)

[`CustomDebugStringConvertible`](/documentation/Swift/CustomDebugStringConvertible)

[`CustomStringConvertible`](/documentation/Swift/CustomStringConvertible)

[`NSSecureCoding`](/documentation/Foundation/NSSecureCoding)

[`NSCopying`](/documentation/Foundation/NSCopying)

[`Copyable`](/documentation/Swift/Copyable)

### Inherits From

[`NSObject-swift.class`](/documentation/ObjectiveC/NSObject-swift.class)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)