UCalendar C API is used for converting between a UDate object and a set of integer fields such as UCAL_YEAR, UCAL_MONTH, UCAL_DAY, UCAL_HOUR, and so on. (A UDate object represents a specific instant in time with millisecond precision. See {@link UDate} for information about the UDate .)

Types of UCalendar interpret a UDate according to the rules of a specific calendar system. The U_CAPI provides the enum UCalendarType with UCAL_TRADITIONAL and UCAL_GREGORIAN.

Like other locale-sensitive C API, calendar API provides a function, ucal_open(), which returns a pointer to UCalendar whose time fields have been initialized with the current date and time. We need to specify the type of calendar to be opened and the timezoneId.

UCalendar *caldef;
UChar *tzId;
UErrorCode status;
tzId=(UChar*)malloc(sizeof(UChar) * (strlen("PST") +1) );
u_uastrcpy(tzId, "PST");
caldef=ucal_open(tzID, u_strlen(tzID), NULL, UCAL_TRADITIONAL, &status);

A UCalendar object can produce all the time field values needed to implement the date-time formatting for a particular language and calendar style (for example, Japanese-Gregorian, Japanese-Traditional).

When computing a UDate from time fields, two special circumstances may arise: there may be insufficient information to compute the UDate (such as only year and month but no day in the month), or there may be inconsistent information (such as "Tuesday, July 15, 1996" -- July 15, 1996 is actually a Monday).

Insufficient information. The calendar will use default information to specify the missing fields. This may vary by calendar; for the Gregorian calendar, the default for a field is the same as that of the start of the epoch: i.e., UCAL_YEAR = 1970, UCAL_MONTH = JANUARY, UCAL_DATE = 1, etc.

Inconsistent information. If fields conflict, the calendar will give preference to fields set more recently. For example, when determining the day, the calendar will look for one of the following combinations of fields. The most recent combination, as determined by the most recently set single field, will be used.

UCAL_MONTH + UCAL_DAY_OF_MONTH
UCAL_MONTH + UCAL_WEEK_OF_MONTH + UCAL_DAY_OF_WEEK
UCAL_MONTH + UCAL_DAY_OF_WEEK_IN_MONTH + UCAL_DAY_OF_WEEK
UCAL_DAY_OF_YEAR
UCAL_DAY_OF_WEEK + UCAL_WEEK_OF_YEAR

For the time of day:

UCAL_HOUR_OF_DAY
UCAL_AM_PM + UCAL_HOUR

Note: for some non-Gregorian calendars, different fields may be necessary for complete disambiguation. For example, a full specification of the historial Arabic astronomical calendar requires year, month, day-of-month and day-of-week in some cases.

Note: There are certain possible ambiguities in interpretation of certain singular times, which are resolved in the following ways:

1. 24:00:00 "belongs" to the following day. That is, 23:59 on Dec 31, 1969 < 24:00 on Jan 1, 1970 < 24:01:00 on Jan 1, 1970
2. Although historically not precise, midnight also belongs to "am", and noon belongs to "pm", so on the same day, 12:00 am (midnight) < 12:01 am, and 12:00 pm (noon) < 12:01 pm

The date or time format strings are not part of the definition of a calendar, as those must be modifiable or overridable by the user at runtime. Use {@link UDateFormat} to format dates.

Calendar provides an API for field "rolling", where fields can be incremented or decremented, but wrap around. For example, rolling the month up in the date December 12, 1996 results in January 12, 1996.

Calendar also provides a date arithmetic function for adding the specified (signed) amount of time to a particular time field. For example, subtracting 5 days from the date September 12, 1996 results in September 7, 1996.