Logo Search packages:      
Sourcecode: icu version File versions

Defines | Typedefs | Enumerations | Functions

ucal.h File Reference

C API: Calendar. More...

#include "unicode/utypes.h"
#include "unicode/uenum.h"
#include "unicode/uloc.h"
#include "unicode/localpointer.h"
Include dependency graph for ucal.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Defines

#define UCAL_UNKNOWN_ZONE_ID   "Etc/Unknown"

Typedefs

typedef void * UCalendar
typedef enum UCalendarAMPMs UCalendarAMPMs
typedef enum UCalendarAttribute UCalendarAttribute
typedef enum UCalendarDateFields UCalendarDateFields
typedef enum UCalendarDaysOfWeek UCalendarDaysOfWeek
typedef enum
UCalendarDisplayNameType 
UCalendarDisplayNameType
typedef enum UCalendarLimitType UCalendarLimitType
typedef enum UCalendarMonths UCalendarMonths
typedef enum UCalendarType UCalendarType
typedef enum UCalendarWeekdayType UCalendarWeekdayType
typedef enum USystemTimeZoneType USystemTimeZoneType

Enumerations

enum  UCalendarAMPMs { UCAL_AM, UCAL_PM }
enum  UCalendarAttribute { UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK, UCAL_MINIMAL_DAYS_IN_FIRST_WEEK }
enum  UCalendarDateFields {
  UCAL_ERA, UCAL_YEAR, UCAL_MONTH, UCAL_WEEK_OF_YEAR,
  UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
  UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY,
  UCAL_MINUTE, UCAL_SECOND, UCAL_MILLISECOND, UCAL_ZONE_OFFSET,
  UCAL_DST_OFFSET, UCAL_YEAR_WOY, UCAL_DOW_LOCAL, UCAL_EXTENDED_YEAR,
  UCAL_JULIAN_DAY, UCAL_MILLISECONDS_IN_DAY, UCAL_IS_LEAP_MONTH, UCAL_FIELD_COUNT,
  UCAL_DAY_OF_MONTH = UCAL_DATE
}
enum  UCalendarDaysOfWeek {
  UCAL_SUNDAY = 1, UCAL_MONDAY, UCAL_TUESDAY, UCAL_WEDNESDAY,
  UCAL_THURSDAY, UCAL_FRIDAY, UCAL_SATURDAY
}
enum  UCalendarDisplayNameType { UCAL_STANDARD, UCAL_SHORT_STANDARD, UCAL_DST, UCAL_SHORT_DST }
enum  UCalendarLimitType {
  UCAL_MINIMUM, UCAL_MAXIMUM, UCAL_GREATEST_MINIMUM, UCAL_LEAST_MAXIMUM,
  UCAL_ACTUAL_MINIMUM, UCAL_ACTUAL_MAXIMUM
}
enum  UCalendarMonths {
  UCAL_JANUARY, UCAL_FEBRUARY, UCAL_MARCH, UCAL_APRIL,
  UCAL_MAY, UCAL_JUNE, UCAL_JULY, UCAL_AUGUST,
  UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBER, UCAL_DECEMBER,
  UCAL_UNDECIMBER
}
enum  UCalendarType { UCAL_TRADITIONAL, UCAL_DEFAULT = UCAL_TRADITIONAL, UCAL_GREGORIAN }
enum  UCalendarWeekdayType { UCAL_WEEKDAY, UCAL_WEEKEND, UCAL_WEEKEND_ONSET, UCAL_WEEKEND_CEASE }
enum  USystemTimeZoneType { UCAL_ZONE_TYPE_ANY, UCAL_ZONE_TYPE_CANONICAL, UCAL_ZONE_TYPE_CANONICAL_LOCATION }

Functions

U_STABLE void U_EXPORT2 ucal_add (UCalendar *cal, UCalendarDateFields field, int32_t amount, UErrorCode *status)
U_STABLE void U_EXPORT2 ucal_clear (UCalendar *calendar)
U_STABLE void U_EXPORT2 ucal_clearField (UCalendar *cal, UCalendarDateFields field)
U_STABLE UCalendar *U_EXPORT2 ucal_clone (const UCalendar *cal, UErrorCode *status)
U_STABLE void U_EXPORT2 ucal_close (UCalendar *cal)
U_STABLE int32_t U_EXPORT2 ucal_countAvailable (void)
U_STABLE UBool U_EXPORT2 ucal_equivalentTo (const UCalendar *cal1, const UCalendar *cal2)
U_STABLE int32_t U_EXPORT2 ucal_get (const UCalendar *cal, UCalendarDateFields field, UErrorCode *status)
U_STABLE int32_t U_EXPORT2 ucal_getAttribute (const UCalendar *cal, UCalendarAttribute attr)
U_STABLE const char *U_EXPORT2 ucal_getAvailable (int32_t localeIndex)
U_STABLE int32_t U_EXPORT2 ucal_getCanonicalTimeZoneID (const UChar *id, int32_t len, UChar *result, int32_t resultCapacity, UBool *isSystemID, UErrorCode *status)
U_STABLE UCalendarWeekdayType
U_EXPORT2 
ucal_getDayOfWeekType (const UCalendar *cal, UCalendarDaysOfWeek dayOfWeek, UErrorCode *status)
U_STABLE int32_t U_EXPORT2 ucal_getDefaultTimeZone (UChar *result, int32_t resultCapacity, UErrorCode *ec)
U_STABLE int32_t U_EXPORT2 ucal_getDSTSavings (const UChar *zoneID, UErrorCode *ec)
U_DRAFT int32_t U_EXPORT2 ucal_getFieldDifference (UCalendar *cal, UDate target, UCalendarDateFields field, UErrorCode *status)
U_STABLE UDate U_EXPORT2 ucal_getGregorianChange (const UCalendar *cal, UErrorCode *pErrorCode)
U_STABLE UEnumeration *U_EXPORT2 ucal_getKeywordValuesForLocale (const char *key, const char *locale, UBool commonlyUsed, UErrorCode *status)
U_STABLE int32_t U_EXPORT2 ucal_getLimit (const UCalendar *cal, UCalendarDateFields field, UCalendarLimitType type, UErrorCode *status)
U_STABLE const char *U_EXPORT2 ucal_getLocaleByType (const UCalendar *cal, ULocDataLocaleType type, UErrorCode *status)
U_STABLE UDate U_EXPORT2 ucal_getMillis (const UCalendar *cal, UErrorCode *status)
U_STABLE UDate U_EXPORT2 ucal_getNow (void)
U_STABLE int32_t U_EXPORT2 ucal_getTimeZoneDisplayName (const UCalendar *cal, UCalendarDisplayNameType type, const char *locale, UChar *result, int32_t resultLength, UErrorCode *status)
U_STABLE const char *U_EXPORT2 ucal_getType (const UCalendar *cal, UErrorCode *status)
U_STABLE const char *U_EXPORT2 ucal_getTZDataVersion (UErrorCode *status)
U_STABLE int32_t U_EXPORT2 ucal_getWeekendTransition (const UCalendar *cal, UCalendarDaysOfWeek dayOfWeek, UErrorCode *status)
U_STABLE UBool U_EXPORT2 ucal_inDaylightTime (const UCalendar *cal, UErrorCode *status)
U_STABLE UBool U_EXPORT2 ucal_isSet (const UCalendar *cal, UCalendarDateFields field)
U_STABLE UBool U_EXPORT2 ucal_isWeekend (const UCalendar *cal, UDate date, UErrorCode *status)
U_STABLE UCalendar *U_EXPORT2 ucal_open (const UChar *zoneID, int32_t len, const char *locale, UCalendarType type, UErrorCode *status)
U_STABLE UEnumeration *U_EXPORT2 ucal_openCountryTimeZones (const char *country, UErrorCode *ec)
U_DRAFT UEnumeration *U_EXPORT2 ucal_openTimeZoneIDEnumeration (USystemTimeZoneType zoneType, const char *region, const int32_t *rawOffset, UErrorCode *ec)
U_STABLE UEnumeration *U_EXPORT2 ucal_openTimeZones (UErrorCode *ec)
U_STABLE void U_EXPORT2 ucal_roll (UCalendar *cal, UCalendarDateFields field, int32_t amount, UErrorCode *status)
U_STABLE void U_EXPORT2 ucal_set (UCalendar *cal, UCalendarDateFields field, int32_t value)
U_STABLE void U_EXPORT2 ucal_setAttribute (UCalendar *cal, UCalendarAttribute attr, int32_t newValue)
U_STABLE void U_EXPORT2 ucal_setDate (UCalendar *cal, int32_t year, int32_t month, int32_t date, UErrorCode *status)
U_STABLE void U_EXPORT2 ucal_setDateTime (UCalendar *cal, int32_t year, int32_t month, int32_t date, int32_t hour, int32_t minute, int32_t second, UErrorCode *status)
U_STABLE void U_EXPORT2 ucal_setDefaultTimeZone (const UChar *zoneID, UErrorCode *ec)
U_STABLE void U_EXPORT2 ucal_setGregorianChange (UCalendar *cal, UDate date, UErrorCode *pErrorCode)
U_STABLE void U_EXPORT2 ucal_setMillis (UCalendar *cal, UDate dateTime, UErrorCode *status)
U_STABLE void U_EXPORT2 ucal_setTimeZone (UCalendar *cal, const UChar *zoneID, int32_t len, UErrorCode *status)

Detailed Description

C API: Calendar.

Calendar C API

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 UDate for information about the UDate .)

Types of UCalendar interpret a UDate according to the rules of a specific calendar system. The U_STABLE 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.

 
 

For the time of day:

 
 

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

ICU 2.0

Definition in file ucal.h.


Generated by  Doxygen 1.6.0   Back to index