The Ucalendar is used for converting between an udate module and a set of integer fields such as I18N_UCALENDAR_YEAR, I18N_UCALENDAR_MONTH, I18N_UCALENDAR_DATE, I18N_UCALENDAR_HOUR, and so on.

Required Header

#include <utils_i18n.h>

Overview

The Ucalendar is used for converting between an udate module and a set of integer fields such as I18N_UCALENDAR_YEAR, I18N_UCALENDAR_MONTH, I18N_UCALENDAR_DATE, I18N_UCALENDAR_HOUR, and so on. (An udate module represents a specific instant in time with millisecond precision. See udate for information about the udate.)

Sample Code 1

Converts the given date and time to the corresponding UTC time(number of seconds that have elapsed since January 1, 1970), considering the given time zone

 #define ms2sec(ms) (long long int)(ms)/1000.0

  // get time in sec from input date and time
  long long int _time_convert_itol(char *tzid, int y, int mon, int d, int h, int min, int s)
 {
     long long int lli;
     i18n_ucalendar_h ucal;
     i18n_udate date;
     int ret = I18N_ERROR_NONE;
     int year, month, day, hour, minute, second;
     int len;

     i18n_uchar *_tzid = NULL;

     if (tzid == NULL) {
         tzid = "Etc/GMT";
     }
     _tzid = (i18n_uchar*)calloc(strlen(tzid) + 1, sizeof(i18n_uchar));
     if (_tzid == NULL) {
         return -1;
     }
     // converts 'tzid' to unicode string
     i18n_ustring_copy_ua(_tzid, tzid);

     // gets length of '_tzid'
     len = i18n_ustring_get_length(_tzid);
     // creates i18n_ucalendar_h
     ret = i18n_ucalendar_create(_tzid, len, "en_US", I18N_UCALENDAR_TRADITIONAL, &ucal);
     if (ret) {
         dlog_print(DLOG_INFO, LOG_TAG, "i18n_ucalendar_create failed.\n");
         return -1;
     }

     // sets i18n_ucalendar_h's date
     i18n_ucalendar_set_date_time(ucal, y, mon-1, d, h, min, s);

     // gets the current value of a field from i18n_ucalendar_h
     i18n_ucalendar_get(ucal, I18N_UCALENDAR_YEAR, &year);
     i18n_ucalendar_get(ucal, I18N_UCALENDAR_MONTH, &month);
     i18n_ucalendar_get(ucal, I18N_UCALENDAR_DATE, &day);
     i18n_ucalendar_get(ucal, I18N_UCALENDAR_HOUR, &hour);
     i18n_ucalendar_get(ucal, I18N_UCALENDAR_MINUTE, &minute);
     i18n_ucalendar_get(ucal, I18N_UCALENDAR_SECOND, &second);
     dlog_print(DLOG_INFO, LOG_TAG, "Date from ucal, year:%d month:%d day:%d hour:%d minute:%d second:%d.\n",year, month, day, hour, minute, second);

     // gets i18n_ucalendar's current time and converts it from milliseconds to seconds
     i18n_ucalendar_get_milliseconds(ucal, &date);
     lli = ms2sec(date);
     // destroys i18n_ucalendar_h
     i18n_ucalendar_destroy(ucal);
     if (_tzid) {
         free(_tzid);
     }

     return lli;
 }

Sample Code 2

Describes an example that uses _time_convert_itol from 'Sample Code 2'

       // converts the given time to UTC time(number of seconds that have elapsed since January 1, 1970)
     long long int time = _time_convert_itol("Etc/GMT", 2014, 5, 28, 15, 14, 0);
     dlog_print(DLOG_INFO, LOG_TAG, "Time Zone: %s\t, %d/%d/%d/%d/%d/%d\n", "Etc/GMT", 2014, 5, 28, 15, 14, 0);
     dlog_print(DLOG_INFO, LOG_TAG, "_time_convert_itol test : %lld\n", time);

Functions
int	i18n_ucalendar_set_default_timezone (const i18n_uchar *zone_id)
	Sets the default time zone.
int	i18n_ucalendar_get_now (i18n_udate *date)
	Gets the current date and time.
int	i18n_ucalendar_create (const i18n_uchar zone_id, int32_t len, const char locale, i18n_ucalendar_type_e type, i18n_ucalendar_h *calendar)
	Creates an i18n_ucalendar_h. An i18n_ucalendar_h may be used to convert a millisecond value to a year, month, and day.
int	i18n_ucalendar_destroy (i18n_ucalendar_h calendar)
	Destroys an i18n_ucalendar_h.
int	i18n_ucalendar_clone (const i18n_ucalendar_h cal, i18n_ucalendar_h *identical_to_cal)
	Creates a copy of a i18n_ucalendar_h. This function performs a deep copy.
int	i18n_ucalendar_get_timezone_displayname (const i18n_ucalendar_h calendar, i18n_ucalendar_displayname_type_e type, const char locale, i18n_uchar result, int32_t result_len, int32_t *buf_size_needed)
	Gets the display name for a calendar's TimeZone.
int	i18n_ucalendar_is_in_daylight_time (const i18n_ucalendar_h calendar, i18n_ubool *is_in)
	Determines if an i18n_ucalendar_h is currently in daylight savings time.
int	i18n_ucalendar_set (i18n_ucalendar_h cal, i18n_ucalendar_date_fields_e field, int32_t val)
	Sets the value of a field in a i18n_ucalendar_h.
int	i18n_ucalendar_set_attribute (i18n_ucalendar_h calendar, i18n_ucalendar_attribute_e attr, int32_t val)
	Sets a numeric attribute associated with an i18n_ucalendar_h.
int	i18n_ucalendar_get_attribute (i18n_ucalendar_h calendar, i18n_ucalendar_attribute_e attr, int32_t *val)
	Gets a numeric attribute associated with an i18n_ucalendar.
int	i18n_ucalendar_get_milliseconds (const i18n_ucalendar_h calendar, i18n_udate *date)
	Gets a calendar's current time in milliseconds.
int	i18n_ucalendar_set_milliseconds (i18n_ucalendar_h calendar, i18n_udate milliseconds)
	Sets a calendar's current time in milliseconds.
int	i18n_ucalendar_set_date_time (i18n_ucalendar_h calendar, int32_t year, int32_t month, int32_t date, int32_t hour, int32_t min, int32_t sec)
	Sets a calendar's current date.
int	i18n_ucalendar_is_equivalent_to (const i18n_ucalendar_h calendar1, const i18n_ucalendar_h calendar2, i18n_ubool *equiv)
	Returns `true` if two i18n_ucalendar_h calendars are equivalent.
int	i18n_ucalendar_add (i18n_ucalendar_h calendar, i18n_ucalendar_date_fields_e field, int32_t amount)
	Adds a specified signed amount to a particular field in a i18n_ucalendar_h.
int	i18n_ucalendar_get (const i18n_ucalendar_h calendar, i18n_ucalendar_date_fields_e field, int32_t *val)
	Gets the current value of a field from an i18n_ucalendar_h.
int32_t	i18n_ucalendar_get_field_difference (i18n_ucalendar_h calendar, i18n_udate target, i18n_ucalendar_date_fields_e field, i18n_error_code_e *status)
	Returns the difference between the target time and the time this calendar object is currently set to.
int	i18n_ucalendar_timezone_id_enumeration_create (i18n_system_timezone_type_e zone_type, const char region, const int32_t raw_offset, i18n_uenumeration_h *enumeration)
	Creates an enumeration over system time zone IDs with the given filter conditions.
int	i18n_ucalendar_timezones_create (i18n_uenumeration_h *enumeration)
	Creates an enumeration over all time zones.
int	i18n_ucalendar_country_timezones_create (const char country, i18n_uenumeration_h enumeration)
	Creates an enumeration over all time zones associated with the given country.
int32_t	i18n_ucalendar_get_default_timezone (i18n_uchar *result, int32_t result_capacity)
	Returns the default time zone (i.e., the one returned by the i18n_timezone_create_default() function).
int	i18n_ucalendar_set_timezone (i18n_ucalendar_h calendar, const i18n_uchar *zone_id, int32_t length)
	Sets the TimeZone used by a i18n_ucalendar_h.
int32_t	i18n_ucalendar_get_timezone_id (const i18n_ucalendar_h calendar, i18n_uchar *result, int32_t result_length)
	Gets the ID of the calendar's time zone.
int	i18n_ucalendar_set_gregorian_change (i18n_ucalendar_h calendar, i18n_udate date)
	Sets the Gregorian Calendar change date.
int	i18n_ucalendar_get_gregorian_change (const i18n_ucalendar_h calendar, i18n_udate *date)
	Gets the Gregorian Calendar change date.
const char *	i18n_ucalendar_get_available (int32_t locale_index)
	Gets a locale for which calendars are available.
int32_t	i18n_ucalendar_count_available (void)
	Determines how many locales have calendars available.
int	i18n_ucalendar_set_date (i18n_ucalendar_h calendar, int32_t year, int32_t month, int32_t date)
	Sets a calendar's current date.
int	i18n_ucalendar_roll (i18n_ucalendar_h calendar, i18n_ucalendar_date_fields_e field, int32_t amount)
	Adds a specified signed amount to a particular field in a i18n_ucalendar_h.
i18n_ubool	i18n_ucalendar_is_set (const i18n_ucalendar_h calendar, i18n_ucalendar_date_fields_e field)
	Determines if a field in a i18n_ucalendar_h is set.
int	i18n_ucalendar_clear_field (i18n_ucalendar_h calendar, i18n_ucalendar_date_fields_e field)
	Clears a field in a i18n_ucalendar_h.
int	i18n_ucalendar_clear (i18n_ucalendar_h calendar)
	Clears all fields in a i18n_ucalendar_h.
int32_t	i18n_ucalendar_get_limit (const i18n_ucalendar_h calendar, i18n_ucalendar_date_fields_e field, i18n_ucalendar_limit_type_e type)
	Determines a limit for a field in an i18n_ucalendar_h.
const char *	i18n_ucalendar_get_locale_by_type (const i18n_ucalendar_h calendar, i18n_ulocale_data_locale_type_e type)
	Gets the locale for this `calendar` object.
const char *	i18n_ucalendar_get_tz_data_version (void)
	Returns the timezone data version currently used by ICU.
int32_t	i18n_ucalendar_get_canonical_timezone_id (const i18n_uchar id, int32_t length, i18n_uchar result, int32_t result_capacity, i18n_ubool *is_system_id)
	Returns the canonical system timezone ID or the normalized custom time zone ID for the given time zone ID.
const char *	i18n_ucalendar_get_type (const i18n_ucalendar_h calendar)
	Gets the resource keyword value string designating the calendar type for the i18n_ucalendar_h.
int	i18n_ucalendar_get_keyword_values_for_locale (const char key, const char locale, i18n_ubool commonly_used, i18n_uenumeration_h *enumeration)
	Given a key and a locale, returns an array of string values in a preferred order that would make a difference.
int	i18n_ucalendar_get_day_of_week_type (const i18n_ucalendar_h calendar, i18n_ucalendar_days_of_week_e day_of_week, i18n_ucalendar_weekday_type_e *weekday)
	Returns whether the given day of the week is a weekday, a weekend day, or a day that transitions from one to the other, for the locale and calendar system associated with this `i18n_ucalendar_h` (the locale's region is often the most determinant factor).
int32_t	i18n_ucalendar_get_weekend_transition (const i18n_ucalendar_h calendar, i18n_ucalendar_days_of_week_e day_of_week)
	Returns the time during the day at which the weekend begins or ends in this calendar system.
i18n_ubool	i18n_ucalendar_is_weekend (i18n_ucalendar_h calendar, i18n_udate date)
	Returns `true` if the given i18n_udate is in the weekend in this calendar system.
i18n_ubool	i18n_ucalendar_get_timezone_transition_date (const i18n_ucalendar_h calendar, i18n_utimezone_transition_type_e type, i18n_udate *transition)
	Get the i18n_udate for the next/previous time zone transition relative to the calendar's current date, in the time zone to which the calendar is currently set.
Typedefs
typedef void *	i18n_ucalendar_h
	i18n_ucalendar_h.
Defines
#define	I18N_UCALENDAR_UNKNOWN_ZONE_ID "Etc/Unknown"
	The time zone ID reserved for unknown time zone.

Define Documentation

#define I18N_UCALENDAR_UNKNOWN_ZONE_ID "Etc/Unknown"

The time zone ID reserved for unknown time zone.

Since :: 2.3.1

Typedef Documentation

typedef void* i18n_ucalendar_h

i18n_ucalendar_h.

Since :: 2.3

Enumeration Type Documentation

enum i18n_system_timezone_type_e

System time zone type constants.

Since :: 2.3

Enumerator:

I18N_UCALENDAR_ZONE_TYPE_ANY	Any system zones.
I18N_UCALENDAR_ZONE_TYPE_CANONICAL	Canonical system zones.
I18N_UCALENDAR_ZONE_TYPE_CANONICAL_LOCATION	Canonical system zones associated with actual locations.

enum i18n_ucalendar_attribute_e

Enumeration for types of i18n_ucalendar_h attributes.

Since :: 2.3

Enumerator:

I18N_UCALENDAR_LENIENT	Lenient parsing
I18N_UCALENDAR_FIRST_DAY_OF_WEEK	First day of the week
I18N_UCALENDAR_MINIMAL_DAYS_IN_FIRST_WEEK	Minimum number of days in the first week

enum i18n_ucalendar_date_fields_e

Enumeration for possible fields in an i18n_ucalendar_h.

Since :: 2.3

Enumerator:

I18N_UCALENDAR_ERA	Field number indicating the era, e.g., AD or BC in the Gregorian (Julian) calendar
I18N_UCALENDAR_YEAR	Field number indicating the year
I18N_UCALENDAR_MONTH	Field number indicating the month. This is a calendar-specific value. The first month of the year is JANUARY; the last depends on the number of months in a year
I18N_UCALENDAR_WEEK_OF_YEAR	Field number indicating the week number within the current year. The first week of the year, as defined by the I18N_UCALENDAR_FIRST_DAY_OF_WEEK and I18N_UCALENDAR_MINIMAL_DAYS_IN_FIRST_WEEK attributes, has value 1. Subclasses define the value of I18N_UCALENDAR_WEEK_OF_YEAR for days before the first week of the year
I18N_UCALENDAR_WEEK_OF_MONTH	Field number indicating the week number within the current month. The first week of the month, as defined by the I18N_UCALENDAR_FIRST_DAY_OF_WEEK and I18N_UCALENDAR_MINIMAL_DAYS_IN_FIRST_WEEK attributes, has value 1. Subclasses define the value of WEEK_OF_MONTH for days before the first week of the month
I18N_UCALENDAR_DATE	Field number indicating the day of the month. This is a synonym for DAY_OF_MONTH. The first day of the month has value 1
I18N_UCALENDAR_DAY_OF_YEAR	Field number indicating the day number within the current year. The first day of the year has value 1.
I18N_UCALENDAR_DAY_OF_WEEK	Field number indicating the day of the week. This field takes values "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", and "Saturday"
I18N_UCALENDAR_DAY_OF_WEEK_IN_MONTH	Field number indicating the ordinal number of the day of the week within the current month. Together with the "day of week" field, this uniquely specifies a day within a month. "day of month" 1 through 7 always correspond to "day of week in month" 1; 8 through 15 correspond to "day of week in month" 2, and so on. "day of week in month" 0 indicates the week before "day of week in month" 1. Negative values count back from the end of the month, so the last Sunday of a month is specified as "day of week" = "Sunday", "day of week in month" = -1. Because negative values count backward they will usually be aligned differently within the month than positive values. For example, if a month has 31 days, "day of week in month" -1 will overlap "day of week in month" 5 and the end of 4
I18N_UCALENDAR_AM_PM	Field number indicating whether the "hour" is before or after noon. E.g., at 10:04:15.250 PM the AM_PM is PM
I18N_UCALENDAR_HOUR	Field number indicating the hour of the morning or afternoon. "hour" is used for the 12-hour clock. E.g., at 10:04:15.250 PM the "Hour" is 10
I18N_UCALENDAR_HOUR_OF_DAY	Field number indicating the hour of the day. "Hour of day" is used for the 24-hour clock. E.g., at 10:04:15.250 PM the "Hour of day" is 22
I18N_UCALENDAR_MINUTE	Field number indicating the minute within the hour. E.g., at 10:04:15.250 PM the I18N_UCALENDAR_MINUTE is 4
I18N_UCALENDAR_SECOND	Field number indicating the second within the minute. E.g., at 10:04:15.250 PM the I18N_UCALENDAR_SECOND is 15
I18N_UCALENDAR_MILLISECOND	Field number indicating the millisecond within the second. E.g., at 10:04:15.250 PM the I18N_UCALENDAR_MILLISECOND is 250
I18N_UCALENDAR_ZONE_OFFSET	Field number indicating the raw offset from GMT in milliseconds
I18N_UCALENDAR_DST_OFFSET	Field number indicating the daylight savings offset in milliseconds
I18N_UCALENDAR_YEAR_WOY	Field number indicating the extended year corresponding to the I18N_UCALENDAR_WEEK_OF_YEAR field. This may be one greater or less than the value of I18N_UCALENDAR_EXTENDED_YEAR
I18N_UCALENDAR_DOW_LOCAL	Field number indicating the localized day of the week. This will be a value from 1 to 7 inclusive, with 1 being the localized first day of the week
I18N_UCALENDAR_EXTENDED_YEAR	Year of this calendar system, encompassing all supra-year fields. For example, in Gregorian/Julian calendars, positive Extended Year values indicate years AD, 1 BC = 0 extended, 2 BC = -1 extended, and so on
I18N_UCALENDAR_JULIAN_DAY	Field number indicating the modified Julian day number. This is different from the conventional Julian day number in two regards. First, it demarcates days at local zone midnight, rather than noon GMT. Second, it is a local number; that is, it depends on the local time zone. It can be thought of as a single number that encompasses all the date-related fields
I18N_UCALENDAR_MILLISECONDS_IN_DAY	Ranges from 0 to 23:59:59.999 (regardless of DST). This field behaves exactly like a composite of all time-related fields, not including the zone fields. As such, it also reflects discontinuities in those fields on DST transition days. On a day of DST onset, it will jump forward. On a day of DST cessation, it will jump backward. This reflects the fact that it must be combined with the DST offset field to obtain a unique local time value
I18N_UCALENDAR_IS_LEAP_MONTH	Whether or not the current month is a leap month (0 or 1)
I18N_UCALENDAR_FIELD_COUNT	Number of enumerators
I18N_UCALENDAR_DAY_OF_MONTH	Field number indicating the day of the month. This is a synonym for I18N_UCALENDAR_DATE. The first day of the month has value 1

enum i18n_ucalendar_days_of_week_e

Useful constants for days of week.

Note: Calendar day-of-week is 1-based. Clients who create locale resources for the field of first-day-of-week should be aware of this. For instance, in US locale, first-day-of-week is set to 1, i.e., I18N_UCALENDAR_SUNDAY. Possible days of the week in an i18n_ucalendar_h.

Since :: 2.3.1

Enumerator:

I18N_UCALENDAR_SUNDAY	Sunday
I18N_UCALENDAR_MONDAY	Monday
I18N_UCALENDAR_TUESDAY	Tuesday
I18N_UCALENDAR_WEDNESDAY	Wednesday
I18N_UCALENDAR_THURSDAY	Thursday
I18N_UCALENDAR_FRIDAY	Friday
I18N_UCALENDAR_SATURDAY	Saturday

enum i18n_ucalendar_displayname_type_e

Enumeration for possible formats of an i18n_ucalendar_h's display name.

Since :: 2.3

Enumerator:

I18N_UCALENDAR_STANDARD	Standard display name
I18N_UCALENDAR_SHORT_STANDARD	Short standard display name
I18N_UCALENDAR_DST	Daylight savings display name
I18N_UCALENDAR_SHORT_DST	Short daylight savings display name

enum i18n_ucalendar_limit_type_e

Possible limit values for an i18n_ucalendar_h.

Since :: 2.3.1

Enumerator:

I18N_UCALENDAR_MINIMUM	Minimum value
I18N_UCALENDAR_MAXIMUM	Maximum value
I18N_UCALENDAR_GREATEST_MINIMUM	Greatest minimum value
I18N_UCALENDAR_LEAST_MAXIMUM	Least maximum value
I18N_UCALENDAR_ACTUAL_MINIMUM	Actual minimum value
I18N_UCALENDAR_ACTUAL_MAXIMUM	Actual maximum value

enum i18n_ucalendar_months_e

Enumeration for possible months in an i18n_ucalendar_h.

Since :: 2.3

Enumerator:

I18N_UCALENDAR_JANUARY	January
I18N_UCALENDAR_FEBRUARY	February
I18N_UCALENDAR_MARCH	March
I18N_UCALENDAR_APRIL	April
I18N_UCALENDAR_MAY	May
I18N_UCALENDAR_JUNE	June
I18N_UCALENDAR_JULY	July
I18N_UCALENDAR_AUGUST	August
I18N_UCALENDAR_SEPTEMBER	September
I18N_UCALENDAR_OCTOBER	October
I18N_UCALENDAR_NOVEMBER	November
I18N_UCALENDAR_DECEMBER	December

enum i18n_ucalendar_type_e

Enumeration for possible months in an i18n_ucalendar_h.

Since :: 2.3

Enumerator:

I18N_UCALENDAR_TRADITIONAL	Despite the name, I18N_UCALENDAR_TRADITIONAL designates the locale's default calendar, which may be the Gregorian calendar or some other calendar
I18N_UCALENDAR_DEFAULT	A better name for I18N_UCALENDAR_TRADITIONAL
I18N_UCALENDAR_GREGORIAN	Unambiguously designates the Gregorian calendar for the locale

enum i18n_ucalendar_weekday_type_e

Weekday types, as returned by i18n_ucalendar_get_day_of_week_type().

Since :: 2.3.1

Enumerator:

I18N_UCALENDAR_WEEKDAY	Designates a full weekday (no part of the day is included in the weekend).
I18N_UCALENDAR_WEEKEND	Designates a full weekend day (the entire day is included in the weekend).
I18N_UCALENDAR_WEEKEND_ONSET	Designates a day that starts as a weekday and transitions to the weekend. Call i18n_ucalendar_get_weekend_transition() to get the time of transition.
I18N_UCALENDAR_WEEKEND_CEASE	Designates a day that starts as the weekend and transitions to a weekday. Call i18n_ucalendar_get_weekend_transition() to get the time of transition.

enum i18n_utimezone_transition_type_e

Time zone transition types for i18n_ucalendar_get_timezone_transition_date().

Since :: 2.3.1

See also:: i18n_ucalendar_get_timezone_transition_date()

Enumerator:

I18N_UCALENDAR_TZ_TRANSITION_NEXT	Get the next transition after the current date, i.e. excludes the current date
I18N_UCALENDAR_TZ_TRANSITION_NEXT_INCLUSIVE	Get the next transition on or after the current date, i.e. may include the current date
I18N_UCALENDAR_TZ_TRANSITION_PREVIOUS	Get the previous transition before the current date, i.e. excludes the current date
I18N_UCALENDAR_TZ_TRANSITION_PREVIOUS_INCLUSIVE	Get the previous transition on or before the current date, i.e. may include the current date

Function Documentation

int i18n_ucalendar_add	(	i18n_ucalendar_h	calendar,
		i18n_ucalendar_date_fields_e	field,
		int32_t	amount
	)

Adds a specified signed amount to a particular field in a i18n_ucalendar_h.

This can modify more significant fields in the calendar.

Since :: 2.3

Parameters:

[in]	calendar	The i18n_ucalendar_h to which to add
[in]	field	The field to which to add the signed value One of I18N_UCALENDAR_ERA, I18N_UCALENDAR_YEAR, I18N_UCALENDAR_MONTH, I18N_UCALENDAR_WEEK_OF_YEAR, I18N_UCALENDAR_WEEK_OF_MONTH, I18N_UCALENDAR_DATE, I18N_UCALENDAR_DAY_OF_YEAR, I18N_UCALENDAR_DAY_OF_WEEK, I18N_UCALENDAR_DAY_OF_WEEK_IN_MONTH, I18N_UCALENDAR_AM_PM, I18N_UCALENDAR_HOUR, I18N_UCALENDAR_HOUR_OF_DAY, I18N_UCALENDAR_MINUTE, I18N_UCALENDAR_SECOND, I18N_UCALENDAR_MILLISECOND.
[in]	amount	The signed amount to add to the field If the amount causes the value to exceed to maximum or minimum values for that field, other fields are modified to preserve the magnitude of the change.

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_ucalendar_clear ( i18n_ucalendar_h calendar )

Clears all fields in a i18n_ucalendar_h.

All fields are represented as 32-bit integers.

Since :: 2.3.1

Parameters:

[in] calendar i18n_ucalendar_h to clear.

Returns:: Error code

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

See also:: i18n_ucalendar_is_set(); i18n_ucalendar_clear_field()

int i18n_ucalendar_clear_field	(	i18n_ucalendar_h	calendar,
		i18n_ucalendar_date_fields_e	field
	)

Clears a field in a i18n_ucalendar_h.

All fields are represented as 32-bit integers.

Since :: 2.3.1

Parameters:

[in]	calendar	The i18n_ucalendar_h containing the field to clear.
[in]	field	The field to clear.

Returns:: Error code

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

See also:: i18n_ucalendar_get(); i18n_ucalendar_set(); i18n_ucalendar_is_set(); i18n_ucalendar_clear()

int i18n_ucalendar_clone	(	const i18n_ucalendar_h	cal,
		i18n_ucalendar_h *	identical_to_cal
	)

Creates a copy of a i18n_ucalendar_h. This function performs a deep copy.

Since :: 2.3

Parameters:

[in]	cal	The i18n_ucalendar_h to copy
[out]	identical_to_cal	A pointer to a i18n_ucalendar_h identical to cal.

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int32_t i18n_ucalendar_count_available ( void )

Determines how many locales have calendars available.

This function is most useful as determining the loop ending condition for calls to i18n_ucalendar_get_available().

Remarks:: The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section.

Since :: 2.3.1

Returns:: The number of locales for which calendars are available.

Exceptions:

I18N_ERROR_NONE Successful

See also:: i18n_ucalendar_get_available()

int i18n_ucalendar_country_timezones_create	(	const char *	country,
		i18n_uenumeration_h *	enumeration
	)

Creates an enumeration over all time zones associated with the given country.

Some zones are affiliated with no country (e.g., "UTC"); these may also be retrieved, as a group.

Since :: 2.3.1

Parameters:

[in]	country	The ISO 3166 two-letter country code, or `NULL` to retrieve zones not affiliated with any country
[out]	enumeration	A pointer to the enumeration object that the caller must dispose of using i18n_uenumeration_destroy(), or `NULL` upon failure.

Returns:: Error code. Error codes not listed below are described in i18n_error_code_e

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_ucalendar_create	(	const i18n_uchar *	zone_id,
		int32_t	len,
		const char *	locale,
		i18n_ucalendar_type_e	type,
		i18n_ucalendar_h *	calendar
	)

Creates an i18n_ucalendar_h. An i18n_ucalendar_h may be used to convert a millisecond value to a year, month, and day.

Note: When an unknown TimeZone ID is specified, the i18n_ucalendar_h returned by the function is initialized with GMT ("Etc/GMT") without any errors/warnings.

Since :: 2.3

Remarks:: Must release calendar using i18n_ucalendar_destroy().

Parameters:

[in]	zone_id	The desired TimeZone ID If `0`, use the default time zone.
[in]	len	The length of the zone ID, otherwise `-1` if null-terminated
[in]	locale	The desired locale If `NULL`, the default locale will be used.
[in]	type	The type of I18N_UCALENDAR_DEFAULT to create This can be I18N_UCALENDAR_GREGORIAN to create the Gregorian calendar for the locale, or I18N_UCALENDAR_DEFAULT to create the default calendar for the locale (the default calendar may also be Gregorian).
[out]	calendar	A pointer to an i18n_ucalendar_h, otherwise `0` if an error occurs

Returns:: An i18n_error_code_e error code

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_ucalendar_destroy ( i18n_ucalendar_h calendar )

Destroys an i18n_ucalendar_h.

Once destroyed, an i18n_ucalendar_h may no longer be used.

Since :: 2.3

Parameters:

[in] calendar The i18n_ucalendar_h to destroy

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_ucalendar_get	(	const i18n_ucalendar_h	calendar,
		i18n_ucalendar_date_fields_e	field,
		int32_t *	val
	)

Gets the current value of a field from an i18n_ucalendar_h.

All fields are represented as 32-bit integers.

Since :: 2.3

Parameters:

[in]	calendar	The i18n_ucalendar_h to query
[in]	field	The desired field One of I18N_UCALENDAR_ERA, I18N_UCALENDAR_YEAR, I18N_UCALENDAR_MONTH, I18N_UCALENDAR_WEEK_OF_YEAR, I18N_UCALENDAR_WEEK_OF_MONTH, I18N_UCALENDAR_DATE, I18N_UCALENDAR_DAY_OF_YEAR, I18N_UCALENDAR_DAY_OF_WEEK, I18N_UCALENDAR_DAY_OF_WEEK_IN_MONTH, I18N_UCALENDAR_AM_PM, I18N_UCALENDAR_HOUR, I18N_UCALENDAR_HOUR_OF_DAY, I18N_UCALENDAR_MINUTE, I18N_UCALENDAR_SECOND, I18N_UCALENDAR_MILLISECOND, I18N_UCALENDAR_ZONE_OFFSET, or I18N_UCALENDAR_DST_OFFSET.
[out]	val	The value of the desired field.

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_ucalendar_get_attribute	(	i18n_ucalendar_h	calendar,
		i18n_ucalendar_attribute_e	attr,
		int32_t *	val
	)

Gets a numeric attribute associated with an i18n_ucalendar.

Numeric attributes include the first day of the week, or the minimal numbers of days in the first week of the month.

Since :: 2.3

Parameters:

[in]	calendar	The i18n_ucalendar to query
[in]	attr	The desired attribute One of I18N_UCALENDAR_LENIENT, I18N_UCALENDAR_FIRST_DAY_OF_WEEK, or I18N_UCALENDAR_MINIMAL_DAYS_IN_FIRST_WEEK.
[out]	val	The value of attr

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

const char* i18n_ucalendar_get_available ( int32_t locale_index )

Gets a locale for which calendars are available.

A i18n_ucalendar_h in a locale returned by this function will contain the correct day and month names for the locale.

Remarks:: The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section.

Since :: 2.3.1

Parameters:

[in] locale_index The index of the desired locale.

Returns:: A locale for which calendars are available, or 0 if none.

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid parameter

See also:: i18n_ucalendar_count_available()

int32_t i18n_ucalendar_get_canonical_timezone_id	(	const i18n_uchar *	id,
		int32_t	length,
		i18n_uchar *	result,
		int32_t	result_capacity,
		i18n_ubool *	is_system_id
	)

Returns the canonical system timezone ID or the normalized custom time zone ID for the given time zone ID.

Remarks:: The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.

Since :: 2.3.1

Parameters:

[in]	id	The input timezone ID to be canonicalized.
[in]	length	The length of the `id`, or `-1` if NULL-terminated.
[out]	result	The buffer receives the canonical system timezone ID or the custom timezone ID in normalized format.
[in]	result_capacity	The capacity of the `result` buffer.
[out]	is_system_id	Receives if the given `id` is a known system timezone ID.

Returns:: The result string length, not including the terminating NULL.

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_ucalendar_get_day_of_week_type	(	const i18n_ucalendar_h	calendar,
		i18n_ucalendar_days_of_week_e	day_of_week,
		i18n_ucalendar_weekday_type_e *	weekday
	)

Returns whether the given day of the week is a weekday, a weekend day, or a day that transitions from one to the other, for the locale and calendar system associated with this i18n_ucalendar_h (the locale's region is often the most determinant factor).

If a transition occurs at midnight, then the days before and after the transition will have the type I18N_UCALENDAR_WEEKDAY or I18N_UCALENDAR_WEEKEND. If a transition occurs at a time other than midnight, then the day of the transition will have the type I18N_UCALENDAR_WEEKEND_ONSET or I18N_UCALENDAR_WEEKEND_CEASE. In this case, the function i18n_ucalendar_get_weekend_transition() will return the point of transition.

Since :: 2.3.1

Parameters:

[in]	calendar	The i18n_ucalendar_h to query.
[in]	day_of_week	The day of the week whose type is desired (I18N_UCALENDAR_SUNDAY..I18N_UCALENDAR_SATURDAY).
[out]	weekday	A pointer to the i18n_ucalendar_weekday_type_e for the day of the week.

Returns:: Error code. Error codes not listed below are described in i18n_error_code_e

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int32_t i18n_ucalendar_get_default_timezone	(	i18n_uchar *	result,
		int32_t	result_capacity
	)

Returns the default time zone (i.e., the one returned by the i18n_timezone_create_default() function).

The default time zone is determined initially by querying the host operating system and storing the obtained time zone as default until the application terminates. Therefore, if the time zone is changed after the first call, subsequent calls will not reflect the change, i.e. the returned time zone will be the same as for the first function call.

To query the system for the current timezone, use i18n_timezone_detect_host_timezone() from the Timezone module.

The default time zone may be changed with i18n_ucalendar_set_default_timezone() or with the i18n Timezone API.

Remarks:: The specific error code can be obtained using the get_last_result() method. Error codes are described in i18n_error_code_e description.

Since :: 2.3.1

Parameters:

[out]	result	A buffer to receive the result, or `NULL`
[in]	result_capacity	The capacity of the `result` buffer

Returns:: The result string length, not including the terminating NULL.

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid parameter

int32_t i18n_ucalendar_get_field_difference	(	i18n_ucalendar_h	calendar,
		i18n_udate	target,
		i18n_ucalendar_date_fields_e	field,
		i18n_error_code_e *	status
	)

Returns the difference between the target time and the time this calendar object is currently set to.

If the target time is after the current calendar setting, the the returned value will be positive. The field parameter specifies the units of the return value. For example, if field is I18N_UCALENDAR_MONTH and i18n_ucalendar_get_field_difference returns 3, then the target time is 3 to less than 4 months after the current calendar setting.
As a side effect of this call, this calendar is advanced toward target by the given amount. That is, calling this function has the side effect of calling i18n_ucalendar_add on this calendar with the specified field and an amount equal to the return value from this function.
A typical way of using this function is to call it first with the largest field of interest, then with progressively smaller fields.

Since :: 2.3.1

Parameters:

[in]	calendar	The i18n_ucalendar_h to compare and update.
[in]	target	The target date to compare to the current calendar setting.
[in]	field	One of I18N_UCALENDAR_ERA, I18N_UCALENDAR_YEAR, I18N_UCALENDAR_MONTH, I18N_UCALENDAR_WEEK_OF_YEAR, I18N_UCALENDAR_WEEK_OF_MONTH, I18N_UCALENDAR_DATE, I18N_UCALENDAR_DAY_OF_YEAR, I18N_UCALENDAR_DAY_OF_WEEK, I18N_UCALENDAR_DAY_OF_WEEK_IN_MONTH, I18N_UCALENDAR_AM_PM, I18N_UCALENDAR_HOUR, I18N_UCALENDAR_HOUR_OF_DAY, I18N_UCALENDAR_MINUTE, I18N_UCALENDAR_SECOND, I18N_UCALENDAR_MILLISECOND. Please note that the returned value type is int32_t. In case of I18N_UCALENDAR_MILLISECOND, maximal difference between dates may be equal to the maximal value of the int32_t, which is 2147483647 (about one month difference). If the difference is bigger, then the I18N_ERROR_INVALID_PARAMETER error will be returned.
[out]	status	A pointer to an i18n_error_code_e to receive any errors

Returns:: The date difference for the specified field.

int i18n_ucalendar_get_gregorian_change	(	const i18n_ucalendar_h	calendar,
		i18n_udate *	date
	)

Gets the Gregorian Calendar change date.

This is the point when the switch from Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October 15, 1582. Previous to this time and date will be Julian dates. This function works only for Gregorian calendars. If the i18n_ucalendar_h is not an instance of a Gregorian calendar, then a I18N_ERROR_NOT_SUPPORTED error code is set.

Since :: 2.3.1

Parameters:

[in]	calendar	The calendar object.
[out]	date	A pointer to the Gregorian cutover time for this calendar.

Returns:: Error code. Error codes not listed below are described in i18n_error_code_e

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

See also:: i18n_ucalendar_set_gregorian_change()

int i18n_ucalendar_get_keyword_values_for_locale	(	const char *	key,
		const char *	locale,
		i18n_ubool	commonly_used,
		i18n_uenumeration_h *	enumeration
	)

Given a key and a locale, returns an array of string values in a preferred order that would make a difference.

These are all and only those values where the open (creation) of the service with the locale formed from the input locale plus input keyword and that value has different behavior than creation with the input locale alone.

Since :: 2.3.1

Parameters:

[in]	key	One of the keys supported by this service. For now, only "calendar" is supported.
[in]	locale	The locale
[in]	commonly_used	If set to `true` it will return only commonly used values with the given locale in preferred order. Otherwise, it will return all the available values for the locale.
[out]	enumeration	A pointer to the string enumeration over keyword values for the given key and the locale.

Returns:: Error code. Error codes not listed below are described in i18n_error_code_e

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int32_t i18n_ucalendar_get_limit	(	const i18n_ucalendar_h	calendar,
		i18n_ucalendar_date_fields_e	field,
		i18n_ucalendar_limit_type_e	type
	)

Determines a limit for a field in an i18n_ucalendar_h.

A limit is a maximum or minimum value for a field.

Remarks:: The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.

Since :: 2.3.1

Parameters:

[in]	calendar	The i18n_ucalendar_h to query.
[in]	field	The desired field; one of I18N_UCALENDAR_ERA, I18N_UCALENDAR_YEAR, I18N_UCALENDAR_MONTH, I18N_UCALENDAR_WEEK_OF_YEAR, I18N_UCALENDAR_WEEK_OF_MONTH, I18N_UCALENDAR_DATE, I18N_UCALENDAR_DAY_OF_YEAR, I18N_UCALENDAR_DAY_OF_WEEK, I18N_UCALENDAR_DAY_OF_WEEK_IN_MONTH, I18N_UCALENDAR_AM_PM, I18N_UCALENDAR_HOUR, I18N_UCALENDAR_HOUR_OF_DAY, I18N_UCALENDAR_MINUTE, I18N_UCALENDAR_SECOND, I18N_UCALENDAR_MILLISECOND, I18N_UCALENDAR_ZONE_OFFSET, I18N_UCALENDAR_DST_OFFSET, I18N_UCALENDAR_YEAR_WOY, I18N_UCALENDAR_DOW_LOCAL, I18N_UCALENDAR_EXTENDED_YEAR, I18N_UCALENDAR_JULIAN_DAY, I18N_UCALENDAR_MILLISECONDS_IN_DAY, I18N_UCALENDAR_IS_LEAP_MONTH.
[in]	type	The desired critical point; one of I18N_UCALENDAR_MINIMUM, I18N_UCALENDAR_MAXIMUM, I18N_UCALENDAR_GREATEST_MINIMUM, I18N_UCALENDAR_LEAST_MAXIMUM, I18N_UCALENDAR_ACTUAL_MINIMUM, I18N_UCALENDAR_ACTUAL_MAXIMUM.

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

Returns:: The requested value.

const char* i18n_ucalendar_get_locale_by_type	(	const i18n_ucalendar_h	calendar,
		i18n_ulocale_data_locale_type_e	type
	)

Gets the locale for this calendar object.

You can choose between valid and actual locale.

Remarks:: The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.

Since :: 2.3.1

Parameters:

[in]	calendar	The calendar object
[in]	type	Type of the locale we're looking for (valid or actual)

Returns:: The requested value.

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_ucalendar_get_milliseconds	(	const i18n_ucalendar_h	calendar,
		i18n_udate *	date
	)

Gets a calendar's current time in milliseconds.

The time is represented as milliseconds from the epoch.

Since :: 2.3

Parameters:

[in]	calendar	The i18n_ucalendar_h to query
[out]	date	The calendar's current time in milliseconds

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

See also:: i18n_ucalendar_set_milliseconds(); i18n_ucalendar_set_date_time()

int i18n_ucalendar_get_now ( i18n_udate * date )

Gets the current date and time.

The value returned is represented as milliseconds from the epoch.

Since :: 2.3

Parameters:

[out] date The current date and time

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_ucalendar_get_timezone_displayname	(	const i18n_ucalendar_h	calendar,
		i18n_ucalendar_displayname_type_e	type,
		const char *	locale,
		i18n_uchar *	result,
		int32_t	result_len,
		int32_t *	buf_size_needed
	)

Gets the display name for a calendar's TimeZone.

A display name is suitable for presentation to a user.

Since :: 2.3

Parameters:

[in]	calendar	The i18n_ucalendar_h to query
[in]	type	The desired display name format One of I18N_UCALENDAR_STANDARD, I18N_UCALENDAR_SHORT_STANDARD, I18N_UCALENDAR_DST, or I18N_UCALENDAR_SHORT_DST
[in]	locale	The desired locale for the display name
[out]	result	A pointer to a buffer to receive the formatted number
[in]	result_len	The maximum size of the result
[out]	buf_size_needed	The total buffer size needed If greater than result_len, the output is truncated

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int32_t i18n_ucalendar_get_timezone_id	(	const i18n_ucalendar_h	calendar,
		i18n_uchar *	result,
		int32_t	result_length
	)

Gets the ID of the calendar's time zone.

Remarks:: The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.

Since :: 2.3.1

Parameters:

[in]	calendar	The i18n_ucalendar_h to query.
[out]	result	Receives the calendar's time zone ID.
[in]	result_length	The maximum size of the `result`.

Returns:: The total buffer size needed; if greater than result_length, the output was truncated.

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

i18n_ubool i18n_ucalendar_get_timezone_transition_date	(	const i18n_ucalendar_h	calendar,
		i18n_utimezone_transition_type_e	type,
		i18n_udate *	transition
	)

Get the i18n_udate for the next/previous time zone transition relative to the calendar's current date, in the time zone to which the calendar is currently set.

If there is no known time zone transition of the requested type relative to the calendar's date, the function returns false.

Remarks:: The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.

Since :: 2.3.1

Parameters:

[in]	calendar	The i18n_ucalendar_h to query.
[in]	type	The type of transition desired.
[out]	transition	A pointer to a i18n_udate to be set to the transition time. If the function returns `false`, the value set is unspecified.

Returns:: true if the given i18n_udate is in the weekend in this calendar system, false otherwise.

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

const char* i18n_ucalendar_get_type ( const i18n_ucalendar_h calendar )

Gets the resource keyword value string designating the calendar type for the i18n_ucalendar_h.

Remarks:: The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.

Since :: 2.3.1

Parameters:

[in] calendar The i18n_ucalendar_h to query.

Returns:: The resource keyword value string.

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

const char* i18n_ucalendar_get_tz_data_version ( void )

Returns the timezone data version currently used by ICU.

Remarks:: The specific error code can be obtained using the get_last_result() method. Error codes are described in i18n_error_code_e description.

Since :: 2.3.1

Returns:: The version string, such as "2007f".

Exceptions:

I18N_ERROR_NONE Successful

int32_t i18n_ucalendar_get_weekend_transition	(	const i18n_ucalendar_h	calendar,
		i18n_ucalendar_days_of_week_e	day_of_week
	)

Returns the time during the day at which the weekend begins or ends in this calendar system.

If i18n_ucalendar_get_day_of_week_type() returns I18N_UCALENDAR_WEEKEND_ONSET for the specified day_of_week, return the time at which the weekend begins. If i18n_ucalendar_get_day_of_week_type() returns I18N_UCALENDAR_WEEKEND_CEASE for the specified day_of_week, return the time at which the weekend ends. If i18n_ucalendar_get_day_of_week_type() returns some other i18n_ucalendar_weekday_type_e for the specified day_of_week, it is an error condition (I18N_ERROR_INVALID_PARAMETER).

Remarks:: The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.

Since :: 2.3.1

Parameters:

[in]	calendar	The i18n_ucalendar_h to query.
[in]	day_of_week	The day of the week whose type is desired (I18N_UCALENDAR_SUNDAY..I18N_UCALENDAR_SATURDAY).

Returns:: The milliseconds after midnight at which the weekend begins or ends.

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_ucalendar_is_equivalent_to	(	const i18n_ucalendar_h	calendar1,
		const i18n_ucalendar_h	calendar2,
		i18n_ubool *	equiv
	)

Returns true if two i18n_ucalendar_h calendars are equivalent.

Equivalent i18n_ucalendar_h calendars will behave identically, but they may be set to different times.

Since :: 2.3

Parameters:

[in]	calendar1	The first of the calendars to compare
[in]	calendar2	The second of the calendars to compare
[out]	equiv	If `true` cal1 and cal2 are equivalent, otherwise `false`

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_ucalendar_is_in_daylight_time	(	const i18n_ucalendar_h	calendar,
		i18n_ubool *	is_in
	)

Determines if an i18n_ucalendar_h is currently in daylight savings time.

Daylight savings time is not used in all parts of the world.

Since :: 2.3

Parameters:

[in]	calendar	The i18n_ucalendar_h to query
[out]	is_in	If `true` calendar is currently in daylight savings time, otherwise `false`

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

i18n_ubool i18n_ucalendar_is_set	(	const i18n_ucalendar_h	calendar,
		i18n_ucalendar_date_fields_e	field
	)

Determines if a field in a i18n_ucalendar_h is set.

All fields are represented as 32-bit integers.

Remarks:: The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section.

Since :: 2.3.1

Parameters:

[in]	calendar	The i18n_ucalendar_h to query.
[in]	field	The desired field.

Returns:: true if field is set, false otherwise.

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

See also:: i18n_ucalendar_get(); i18n_ucalendar_set(); i18n_ucalendar_clear_field(); i18n_ucalendar_clear()

i18n_ubool i18n_ucalendar_is_weekend	(	i18n_ucalendar_h	calendar,
		i18n_udate	date
	)

Returns true if the given i18n_udate is in the weekend in this calendar system.

Remarks:: The specific error code can be obtained using the get_last_result() method. Error codes are described in Exceptions section and i18n_error_code_e description.

Since :: 2.3.1

Parameters:

[in]	calendar	The i18n_ucalendar_h to query.
[in]	date	The i18n_udate in question.

Returns:: true if the given i18n_udate is in the weekend in this calendar system, false otherwise.

Exceptions:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_ucalendar_roll	(	i18n_ucalendar_h	calendar,
		i18n_ucalendar_date_fields_e	field,
		int32_t	amount
	)

Adds a specified signed amount to a particular field in a i18n_ucalendar_h.

This will not modify more significant fields in the calendar. Rolling by a positive value always means moving forward in time (unless the limit of the field is reached, in which case it may pin or wrap), so for Gregorian calendar, starting with 100 BC and rolling the year by +1 results in 99 BC. When eras have a definite beginning and end (as in the Chinese calendar, or as in most eras in the Japanese calendar) then rolling the year past either limit of the era will cause the year to wrap around. When eras only have a limit at one end, then attempting to roll the year past that limit will result in pinning the year at that limit. Note that for most calendars in which era 0 years move forward in time (such as Buddhist, Hebrew, or Islamic), it is possible for add or roll to result in negative years for era 0 (that is the only way to represent years before the calendar epoch).

Since :: 2.3.1

Parameters:

[in]	calendar	The i18n_ucalendar_h to which to add.
[in]	field	The field to which to add the signed value; one of I18N_UCALENDAR_ERA, I18N_UCALENDAR_YEAR, I18N_UCALENDAR_MONTH, I18N_UCALENDAR_WEEK_OF_YEAR, I18N_UCALENDAR_WEEK_OF_MONTH, I18N_UCALENDAR_DATE, I18N_UCALENDAR_DAY_OF_YEAR, I18N_UCALENDAR_DAY_OF_WEEK, I18N_UCALENDAR_DAY_OF_WEEK_IN_MONTH, I18N_UCALENDAR_AM_PM, I18N_UCALENDAR_HOUR, I18N_UCALENDAR_HOUR_OF_DAY, I18N_UCALENDAR_MINUTE, I18N_UCALENDAR_SECOND, I18N_UCALENDAR_MILLISECOND.
[in]	amount	The signed amount to add to the `field`. If the amount causes the value to exceed to maximum or minimum values for that field, the field is pinned to a permissible value.

Returns:: Error code. Error codes not listed below are described in i18n_error_code_e

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

Remarks:: I18N_UCALENDAR_ZONE_OFFSET and I18N_UCALENDAR_DST_OFFSET are not supported by this function.

See also:: i18n_ucalendar_add()

int i18n_ucalendar_set	(	i18n_ucalendar_h	cal,
		i18n_ucalendar_date_fields_e	field,
		int32_t	val
	)

Sets the value of a field in a i18n_ucalendar_h.

All fields are represented as 32-bit integers.

Since :: 2.3

Parameters:

[in]	cal	The i18n_ucalendar_h to modify
[in]	field	The field to set One of I18N_UCALENDAR_ERA, I18N_UCALENDAR_YEAR, I18N_UCALENDAR_MONTH, I18N_UCALENDAR_WEEK_OF_YEAR, I18N_UCALENDAR_WEEK_OF_MONTH, I18N_UCALENDAR_DATE, I18N_UCALENDAR_DAY_OF_YEAR, I18N_UCALENDAR_DAY_OF_WEEK, I18N_UCALENDAR_DAY_OF_WEEK_IN_MONTH, I18N_UCALENDAR_AM_PM, I18N_UCALENDAR_HOUR, I18N_UCALENDAR_HOUR_OF_DAY, I18N_UCALENDAR_MINUTE, I18N_UCALENDAR_SECOND, I18N_UCALENDAR_MILLISECOND, I18N_UCALENDAR_ZONE_OFFSET, I18N_UCALENDAR_DST_OFFSET.
[in]	val	The desired value of field.

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_ucalendar_set_attribute	(	i18n_ucalendar_h	calendar,
		i18n_ucalendar_attribute_e	attr,
		int32_t	val
	)

Sets a numeric attribute associated with an i18n_ucalendar_h.

Numeric attributes include the first day of the week, or the minimal number of days in the first week of the month.

Since :: 2.3

Parameters:

[in]	calendar	The i18n_ucalendar_h to modify
[in]	attr	The desired attribute One of I18N_UCALENDAR_LENIENT, I18N_UCALENDAR_FIRST_DAY_OF_WEEK, or I18N_UCALENDAR_MINIMAL_DAYS_IN_FIRST_WEEK.
[in]	val	The new value of attr

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_ucalendar_set_date	(	i18n_ucalendar_h	calendar,
		int32_t	year,
		int32_t	month,
		int32_t	date
	)

Sets a calendar's current date.

The date is represented as a series of 32-bit integers.

Since :: 2.3.1

Parameters:

[in]	calendar	The i18n_ucalendar_h to set.
[in]	year	The desired year.
[in]	month	The desired month; one of I18N_UCALENDAR_JANUARY, I18N_UCALENDAR_FEBRUARY, I18N_UCALENDAR_MARCH, I18N_UCALENDAR_APRIL, I18N_UCALENDAR_MAY, I18N_UCALENDAR_JUNE, I18N_UCALENDAR_JULY, I18N_UCALENDAR_AUGUST, I18N_UCALENDAR_SEPTEMBER, I18N_UCALENDAR_OCTOBER, I18N_UCALENDAR_NOVEMBER, I18N_UCALENDAR_DECEMBER
[in]	date	The desired day of the month.

Returns:: Error code. Error codes not listed below are described in i18n_error_code_e

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

See also:: i18n_ucalendar_add(); i18n_ucalendar_set_milliseconds(); i18n_ucalendar_set_milliseconds(); i18n_ucalendar_set_date_time()

int i18n_ucalendar_set_date_time	(	i18n_ucalendar_h	calendar,
		int32_t	year,
		int32_t	month,
		int32_t	date,
		int32_t	hour,
		int32_t	min,
		int32_t	sec
	)

Sets a calendar's current date.

The date is represented as a series of 32-bit integers.

Since :: 2.3

Parameters:

[in]	calendar	The i18n_ucalendar_h to set
[in]	year	The desired year
[in]	month	The desired month One of I18N_UCALENDAR_JANUARY, I18N_UCALENDAR_FEBRUARY, I18N_UCALENDAR_MARCH, I18N_UCALENDAR_APRIL, I18N_UCALENDAR_MAY, I18N_UCALENDAR_JUNE, I18N_UCALENDAR_JULY, I18N_UCALENDAR_AUGUST, I18N_UCALENDAR_SEPTEMBER, I18N_UCALENDAR_OCTOBER, I18N_UCALENDAR_NOVEMBER, or I18N_UCALENDAR_DECEMBER
[in]	date	The desired day of the month
[in]	hour	The desired hour of the day
[in]	min	The desired minute
[in]	sec	The desired second

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

See also:: i18n_ucalendar_get_milliseconds(); i18n_ucalendar_set_milliseconds()

int i18n_ucalendar_set_default_timezone ( const i18n_uchar * zone_id )

Sets the default time zone.

Since :: 2.3

Parameters:

[in] zone_id null-terminated time zone ID

Returns:: An i18n_error_code_e error code

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_ucalendar_set_gregorian_change	(	i18n_ucalendar_h	calendar,
		i18n_udate	date
	)

Sets the Gregorian Calendar change date.

This is the point when the switch from Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October 15, 1582. Previous to this time and date will be Julian dates. This function works only for Gregorian calendars. If the i18n_ucalendar_h is not an instance of a Gregorian calendar, then a I18N_ERROR_NOT_SUPPORTED error code is set.

Since :: 2.3.1

Parameters:

[in]	calendar	The calendar object.
[in]	date	The given Gregorian cutover date.

Returns:: Error code. Error codes not listed below are described in i18n_error_code_e

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

See also:: i18n_ucalendar_get_gregorian_change()

int i18n_ucalendar_set_milliseconds	(	i18n_ucalendar_h	calendar,
		i18n_udate	milliseconds
	)

Sets a calendar's current time in milliseconds.

The time is represented as milliseconds from the epoch.

Since :: 2.3

Parameters:

[in]	calendar	The i18n_ucalendar_h to set
[in]	milliseconds	The desired date and time

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

See also:: i18n_ucalendar_get_milliseconds(); i18n_ucalendar_set_date_time()

int i18n_ucalendar_set_timezone	(	i18n_ucalendar_h	calendar,
		const i18n_uchar *	zone_id,
		int32_t	length
	)

Sets the TimeZone used by a i18n_ucalendar_h.

A i18n_ucalendar_h uses a timezone for converting from Greenwich time to local time.

Since :: 2.3.1

Parameters:

[in]	calendar	The i18n_ucalendar_h to set.
[in]	zone_id	The desired TimeZone ID. If NULL, use the default time zone.
[in]	length	The length of `zone_id`, or -1 if NULL-terminated.

Returns:: Error code. Error codes not listed below are described in i18n_error_code_e

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_ucalendar_timezone_id_enumeration_create	(	i18n_system_timezone_type_e	zone_type,
		const char *	region,
		const int32_t *	raw_offset,
		i18n_uenumeration_h *	enumeration
	)

Creates an enumeration over system time zone IDs with the given filter conditions.

Since :: 2.3.1

Parameters:

[in]	zone_type	The system time zone type.
[in]	region	The ISO 3166 two-letter country code or UN M.49 three-digit area code. When `NULL`, no filtering done by region.
[in]	raw_offset	An offset from GMT in milliseconds, ignoring the effect of daylight savings time, if any. When `NULL`, no filtering done by zone offset.
[out]	enumeration	A Pointer to the enumeration object that the caller must dispose of using i18n_uenumeration_destroy(), or`NULL` upon failure.

Returns:: Error code. Error codes not listed below are described in i18n_error_code_e

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_ucalendar_timezones_create ( i18n_uenumeration_h * enumeration )

Creates an enumeration over all time zones.

Since :: 2.3.1

Parameters:

[out] enumeration A pointer to the enumeration object that the caller must dispose of using i18n_uenumeration_destroy(), or NULL upon failure.

Returns:: Error code. Error codes not listed below are described in i18n_error_code_e

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

Required Header

Overview

Sample Code 1

Sample Code 2

Functions

Typedefs

Defines

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation