CFCalendar Reference

Overview

The CFCalendar opaque type represents a calendar system. The associated API provides information about a calendar and supports calendrical computations such as determining the range of a given calendrical unit and adding units to a given absolute time.

CFAbsoluteTime is the operational lingua franca of CFCalendar—to do calendar arithmetic, you start and end with an absolute time; to convert between a decomposed date in one calendar and another calendar, you first convert to an absolute time. CFAbsoluteTime provides the absolute scale and epoch for dates and times, which can then be rendered into a particular calendar, for calendrical computations or user display.

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” or have a “correspondence with,” values for that unit in another calendar.

Several CFCalendar functions (CFCalendarComposeAbsoluteTime, CFCalendarDecomposeAbsoluteTime, CFCalendarAddComponents, and CFCalendarGetComponentDifference) take a description string that describes the calendrical components provided in a varargs parameter area. You can provide as many components as you need (or choose to), in whatever order you choose. 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). The characters of the description string specify the units and order of the parameters which follow. The characters are adopted from the corresponding format characters used by CFDateFormatter when possible, as shown in Table 1.

Information related to formatting dates and times and name-related calendar information is managed by CFDateFormatter.

CFCalendar is subject to some limitations. There is no leap second handling—the existence of leap seconds is ignored as in the other CoreFoundation API. In general, historical accuracy of calendars is not guaranteed. There is currently no API for defining your own calendars.

CFCalendar is “toll-free bridged” with its Cocoa Foundation counterpart, NSCalendar. This means that the Core Foundation type is interchangeable in function or method calls with the bridged Foundation object. Therefore, in a method where you see an NSCalendar * parameter, you can pass in a CFCalendarRef, and in a function where you see a CFCalendarRef parameter, you can pass in an NSCalendar instance. See “Toll-Free Bridged Types” for more information on toll-free bridging.

Functions by Task

Creating a Calendar

• CFCalendarCopyCurrent
• CFCalendarCreateWithIdentifier

Calendrical Calculations

• CFCalendarAddComponents
• CFCalendarComposeAbsoluteTime
• CFCalendarDecomposeAbsoluteTime
• CFCalendarGetComponentDifference

Getting Ranges of Units

• CFCalendarGetRangeOfUnit
• CFCalendarGetOrdinalityOfUnit
• CFCalendarGetTimeRangeOfUnit
• CFCalendarGetMaximumRangeOfUnit
• CFCalendarGetMinimumRangeOfUnit

Getting and Setting the Time Zone

• CFCalendarCopyTimeZone
• CFCalendarSetTimeZone

Getting the Identifier

• CFCalendarGetIdentifier

Getting and Setting the Locale

• CFCalendarCopyLocale
• CFCalendarSetLocale

Getting and Setting Day Information

• CFCalendarGetFirstWeekday
• CFCalendarSetFirstWeekday
• CFCalendarGetMinimumDaysInFirstWeek
• CFCalendarSetMinimumDaysInFirstWeek

Getting the Type ID

• CFCalendarGetTypeID

Functions

CFCalendarAddComponents

Computes the absolute time when specified components are added to a given absolute time.

Boolean CFCalendarAddComponents (
   CFCalendarRef calendar,
   CFAbsoluteTime *at,
   CFOptionFlags options,
   const unsigned char *componentDesc,
   ...
);

CFCalendarAddComponents(gregorian, &at, 0, "Md",  2, 3);

CFCalendarComposeAbsoluteTime

Computes the absolute time from components in a description string.

Boolean CFCalendarComposeAbsoluteTime (
   CFCalendarRef calendar,
   CFAbsoluteTime *at,
   const unsigned char *componentDesc,
   ...
);

CFCalendarComposeAbsoluteTime(gregorian, &at, "yMdHms",  1965, 1, 6, 14, 10, 00);

CFCalendarCopyCurrent

Returns a copy of the logical calendar for the current user.

CFCalendarRef CFCalendarCopyCurrent (
   void
);

CFCalendarCopyLocale

Returns a locale object for a specified calendar.

CFLocaleRef CFCalendarCopyLocale (
   CFCalendarRef calendar
);

CFCalendarCopyTimeZone

Returns a time zone object for a specified calendar.

CFTimeZoneRef CFCalendarCopyTimeZone (
   CFCalendarRef calendar
);

CFCalendarCreateWithIdentifier

Returns a calendar object for the calendar identified by a calendar identifier.

CFCalendarRef CFCalendarCreateWithIdentifier (
   CFAllocatorRef allocator,
   CFStringRef identifier
);

CFCalendarDecomposeAbsoluteTime

Computes the components which are indicated by the componentDesc description string for the given absolute time.

Boolean CFCalendarDecomposeAbsoluteTime (
   CFCalendarRef calendar,
   CFAbsoluteTime at,
   const unsigned char *componentDesc,
   ...
);

CFCalendarDecomposeAbsoluteTime(gregorian, CFAbsoluteTimeGetCurrent(), "yMd",  &year, &month, &day);

CFCalendarGetComponentDifference

Computes the difference between the two absolute times, in terms of specified calendrical components.

Boolean CFCalendarGetComponentDifference (
   CFCalendarRef calendar,
   CFAbsoluteTime startingAT,
   CFAbsoluteTime resultAT,
   CFOptionFlags options,
   const unsigned char *componentDesc,
   ...
);

CFCalendarGetComponentDifference(gregorian, at1, at2, 0, "d",  &days);

CFCalendarGetFirstWeekday

Returns the index of first weekday for a specified calendar.

CFIndex CFCalendarGetFirstWeekday (
   CFCalendarRef calendar
);

CFCalendarGetIdentifier

Returns the given calendar’s identifier.

CFStringRef CFCalendarGetIdentifier (
   CFCalendarRef calendar
);

CFCalendarGetMaximumRangeOfUnit

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

CFRange CFCalendarGetMaximumRangeOfUnit (
   CFCalendarRef calendar,
   CFCalendarUnit unit
);

CFCalendarGetMinimumDaysInFirstWeek

Returns the minimum number of days in the first week of a specified calendar.

CFIndex CFCalendarGetMinimumDaysInFirstWeek (
   CFCalendarRef calendar
);

CFCalendarGetMinimumRangeOfUnit

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

CFRange CFCalendarGetMinimumRangeOfUnit (
   CFCalendarRef calendar,
   CFCalendarUnit unit
);

CFCalendarGetOrdinalityOfUnit

Returns the ordinal number of a calendrical unit within a larger unit at a specified absolute time.

CFIndex CFCalendarGetOrdinalityOfUnit (
   CFCalendarRef calendar,
   CFCalendarUnit smallerUnit,
   CFCalendarUnit biggerUnit,
   CFAbsoluteTime at
);

CFCalendarGetRangeOfUnit

Returns the range of values that one unit can take on within a larger unit during which a specific absolute time occurs.

CFRange CFCalendarGetRangeOfUnit (
   CFCalendarRef calendar,
   CFCalendarUnit smallerUnit,
   CFCalendarUnit biggerUnit,
   CFAbsoluteTime at
);

CFCalendarGetTimeRangeOfUnit

Returns by reference the start time and duration of a given calendar unit that contains a given absolute time.

Boolean CFCalendarGetTimeRangeOfUnit (
   CFCalendarRef calendar,
   CFCalendarUnit unit,
   CFAbsoluteTime at,
   CFAbsoluteTime *startp,
   CFTimeInterval *tip
);

CFCalendarGetTypeID

Returns the type identifier for the CFCalendar opaque type.

CFTypeID CFCalendarGetTypeID (
   void
);

CFCalendarSetFirstWeekday

Sets the first weekday for a calendar.

void CFCalendarSetFirstWeekday (
   CFCalendarRef calendar,
   CFIndex wkdy
);

CFCalendarSetLocale

Sets the locale for a calendar.

void CFCalendarSetLocale (
   CFCalendarRef calendar,
   CFLocaleRef locale
);

CFCalendarSetMinimumDaysInFirstWeek

Sets the minimum number of days in the first week of a specified calendar.

void CFCalendarSetMinimumDaysInFirstWeek (
   CFCalendarRef calendar,
   CFIndex mwd
);

CFCalendarSetTimeZone

Sets the time zone for a calendar.

void CFCalendarSetTimeZone (
   CFCalendarRef calendar,
   CFTimeZoneRef tz
);

Data Types

CFCalendarRef

A reference to a CFCalendar object.

typedef const struct __CFCalendar *CFCalendarRef;

Constants

CFCalendarUnit

CFCalendarUnit constants are used to specify calendrical units, such as day or month, in various calendar calculations.

typedef enum {
   kCFCalendarUnitEra = (1 << 1),
   kCFCalendarUnitYear = (1 << 2),
   kCFCalendarUnitMonth = (1 << 3),
   kCFCalendarUnitDay = (1 << 4),
   kCFCalendarUnitHour = (1 << 5),
   kCFCalendarUnitMinute = (1 << 6),
   kCFCalendarUnitSecond = (1 << 7),
   kCFCalendarUnitWeek = (1 << 8),
   kCFCalendarUnitWeekday = (1 << 9),
   kCFCalendarUnitWeekdayOrdinal = (1 << 10),
   kCFCalendarUnitQuarter = (1UL << 11),
   kCFCalendarUnitWeekOfMonth = (1UL << 12),
   kCFCalendarUnitWeekOfYear = (1UL << 13),
   kCFCalendarUnitYearForWeekOfYear = (1UL << 14),
} CFCalendarUnit;

Constants

kCFCalendarUnitEra

Specifies the era unit.

Available in OS X v10.4 and later.

Declared in CFCalendar.h.

kCFCalendarUnitYear

Specifies the year unit.

Available in OS X v10.4 and later.

Declared in CFCalendar.h.

kCFCalendarUnitMonth

Specifies the month unit.

Available in OS X v10.4 and later.

Declared in CFCalendar.h.

kCFCalendarUnitDay

Specifies the day unit.

Available in OS X v10.4 and later.

Declared in CFCalendar.h.

kCFCalendarUnitHour

Specifies the hour unit.

Available in OS X v10.4 and later.

Declared in CFCalendar.h.

kCFCalendarUnitMinute

Specifies the minute unit.

Available in OS X v10.4 and later.

Declared in CFCalendar.h.

kCFCalendarUnitSecond

Specifies the second unit.

Available in OS X v10.4 and later.

Declared in CFCalendar.h.

kCFCalendarUnitWeek

Specifies the week unit.

Available in OS X v10.4 and later.

Declared in CFCalendar.h.

kCFCalendarUnitWeekday

Specifies the weekday unit.

The weekday units are the numbers 1-N (where for the Gregorian calendar N=7 and 1 is Sunday).

Available in OS X v10.4 and later.

Declared in CFCalendar.h.

kCFCalendarUnitWeekdayOrdinal

Specifies the ordinal weekday unit.

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 OS X v10.4 and later.

Declared in CFCalendar.h.

kCFCalendarUnitQuarter

Specifies the quarter-year unit.

Available in OS X v10.6 and later.

Declared in CFCalendar.h.

kCFCalendarUnitWeekOfMonth

Specifies the original week of a month calendar unit.

Available in OS X v10.7 and later.

Declared in CFCalendar.h.

kCFCalendarUnitWeekOfYear

Specifies the original week of the year calendar unit.

Available in OS X v10.7 and later.

Declared in CFCalendar.h.

kCFCalendarUnitYearForWeekOfYear

Specifies the relative year for a week within a year calendar unit.

Available in OS X v10.7 and later.

Declared in CFCalendar.h.

Component Wrapping Options

The wrapping option specifies overflow behavior for calendar components in calendrical calculations—see CFCalendarAddComponents and CFCalendarGetComponentDifference.

enum {
   kCFCalendarComponentsWrap = (1 << 0)
}

Constants

kCFCalendarComponentsWrap

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

Available in OS X v10.4 and later.

Declared in CFCalendar.h.