You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1623 lines
57 KiB
1623 lines
57 KiB
// © 2016 and later: Unicode, Inc. and others.
|
|
// License & terms of use: http://www.unicode.org/copyright.html
|
|
/*
|
|
*******************************************************************************
|
|
* Copyright (C) 1996-2015, International Business Machines Corporation and
|
|
* others. All Rights Reserved.
|
|
*******************************************************************************
|
|
*/
|
|
|
|
#ifndef UCAL_H
|
|
#define UCAL_H
|
|
|
|
#include "unicode/utypes.h"
|
|
#include "unicode/uenum.h"
|
|
#include "unicode/uloc.h"
|
|
|
|
#if U_SHOW_CPLUSPLUS_API
|
|
#include "unicode/localpointer.h"
|
|
#endif // U_SHOW_CPLUSPLUS_API
|
|
|
|
#if !UCONFIG_NO_FORMATTING
|
|
|
|
/**
|
|
* \file
|
|
* \brief C API: Calendar
|
|
*
|
|
* <h2>Calendar C API</h2>
|
|
*
|
|
* UCalendar C API is used for converting between a <code>UDate</code> object
|
|
* and a set of integer fields such as <code>UCAL_YEAR</code>, <code>UCAL_MONTH</code>,
|
|
* <code>UCAL_DAY</code>, <code>UCAL_HOUR</code>, and so on.
|
|
* (A <code>UDate</code> object represents a specific instant in
|
|
* time with millisecond precision. See UDate
|
|
* for information about the <code>UDate</code> .)
|
|
*
|
|
* <p>
|
|
* Types of <code>UCalendar</code> interpret a <code>UDate</code>
|
|
* according to the rules of a specific calendar system. The C API
|
|
* provides the enum UCalendarType with UCAL_TRADITIONAL and
|
|
* UCAL_GREGORIAN.
|
|
* <p>
|
|
* Like other locale-sensitive C API, calendar API provides a
|
|
* function, <code>ucal_open()</code>, which returns a pointer to
|
|
* <code>UCalendar</code> 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.
|
|
* \htmlonly<blockquote>\endhtmlonly
|
|
* <pre>
|
|
* \code
|
|
* 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);
|
|
* \endcode
|
|
* </pre>
|
|
* \htmlonly</blockquote>\endhtmlonly
|
|
*
|
|
* <p>
|
|
* A <code>UCalendar</code> 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).
|
|
*
|
|
* <p>
|
|
* When computing a <code>UDate</code> from time fields, two special circumstances
|
|
* may arise: there may be insufficient information to compute the
|
|
* <code>UDate</code> (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).
|
|
*
|
|
* <p>
|
|
* <strong>Insufficient information.</strong> 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.
|
|
*
|
|
* <p>
|
|
* <strong>Inconsistent information.</strong> 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.
|
|
*
|
|
* \htmlonly<blockquote>\endhtmlonly
|
|
* <pre>
|
|
* \code
|
|
* 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
|
|
* \endcode
|
|
* </pre>
|
|
* \htmlonly</blockquote>\endhtmlonly
|
|
*
|
|
* For the time of day:
|
|
*
|
|
* \htmlonly<blockquote>\endhtmlonly
|
|
* <pre>
|
|
* \code
|
|
* UCAL_HOUR_OF_DAY
|
|
* UCAL_AM_PM + UCAL_HOUR
|
|
* \endcode
|
|
* </pre>
|
|
* \htmlonly</blockquote>\endhtmlonly
|
|
*
|
|
* <p>
|
|
* <strong>Note:</strong> for some non-Gregorian calendars, different
|
|
* fields may be necessary for complete disambiguation. For example, a full
|
|
* specification of the historical Arabic astronomical calendar requires year,
|
|
* month, day-of-month <em>and</em> day-of-week in some cases.
|
|
*
|
|
* <p>
|
|
* <strong>Note:</strong> There are certain possible ambiguities in
|
|
* interpretation of certain singular times, which are resolved in the
|
|
* following ways:
|
|
* <ol>
|
|
* <li> 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
|
|
*
|
|
* <li> 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
|
|
* </ol>
|
|
*
|
|
* <p>
|
|
* 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 icu::DateFormat}
|
|
* to format dates.
|
|
*
|
|
* <p>
|
|
* <code>Calendar</code> 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 <code>December 12, <b>1996</b></code> results in
|
|
* <code>January 12, <b>1996</b></code>.
|
|
*
|
|
* <p>
|
|
* <code>Calendar</code> 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 <code>September 12, 1996</code>
|
|
* results in <code>September 7, 1996</code>.
|
|
*
|
|
* <p>
|
|
* The Japanese calendar uses a combination of era name and year number.
|
|
* When an emperor of Japan abdicates and a new emperor ascends the throne,
|
|
* a new era is declared and year number is reset to 1. Even if the date of
|
|
* abdication is scheduled ahead of time, the new era name might not be
|
|
* announced until just before the date. In such case, ICU4C may include
|
|
* a start date of future era without actual era name, but not enabled
|
|
* by default. ICU4C users who want to test the behavior of the future era
|
|
* can enable the tentative era by:
|
|
* <ul>
|
|
* <li>Environment variable <code>ICU_ENABLE_TENTATIVE_ERA=true</code>.</li>
|
|
* </ul>
|
|
*
|
|
* @stable ICU 2.0
|
|
*/
|
|
|
|
/**
|
|
* The time zone ID reserved for unknown time zone.
|
|
* It behaves like the GMT/UTC time zone but has the special ID "Etc/Unknown".
|
|
* @stable ICU 4.8
|
|
*/
|
|
#define UCAL_UNKNOWN_ZONE_ID "Etc/Unknown"
|
|
|
|
/** A calendar.
|
|
* For usage in C programs.
|
|
* @stable ICU 2.0
|
|
*/
|
|
typedef void* UCalendar;
|
|
|
|
/** Possible types of UCalendars
|
|
* @stable ICU 2.0
|
|
*/
|
|
enum UCalendarType {
|
|
/**
|
|
* Despite the name, UCAL_TRADITIONAL designates the locale's default calendar,
|
|
* which may be the Gregorian calendar or some other calendar.
|
|
* @stable ICU 2.0
|
|
*/
|
|
UCAL_TRADITIONAL,
|
|
/**
|
|
* A better name for UCAL_TRADITIONAL.
|
|
* @stable ICU 4.2
|
|
*/
|
|
UCAL_DEFAULT = UCAL_TRADITIONAL,
|
|
/**
|
|
* Unambiguously designates the Gregorian calendar for the locale.
|
|
* @stable ICU 2.0
|
|
*/
|
|
UCAL_GREGORIAN
|
|
};
|
|
|
|
/** @stable ICU 2.0 */
|
|
typedef enum UCalendarType UCalendarType;
|
|
|
|
/** Possible fields in a UCalendar
|
|
* @stable ICU 2.0
|
|
*/
|
|
enum UCalendarDateFields {
|
|
/**
|
|
* Field number indicating the era, e.g., AD or BC in the Gregorian (Julian) calendar.
|
|
* This is a calendar-specific value.
|
|
* @stable ICU 2.6
|
|
*/
|
|
UCAL_ERA,
|
|
|
|
/**
|
|
* Field number indicating the year. This is a calendar-specific value.
|
|
* @stable ICU 2.6
|
|
*/
|
|
UCAL_YEAR,
|
|
|
|
/**
|
|
* Field number indicating the month. This is a calendar-specific value.
|
|
* The first month of the year is
|
|
* <code>JANUARY</code>; the last depends on the number of months in a year.
|
|
* @see #UCAL_JANUARY
|
|
* @see #UCAL_FEBRUARY
|
|
* @see #UCAL_MARCH
|
|
* @see #UCAL_APRIL
|
|
* @see #UCAL_MAY
|
|
* @see #UCAL_JUNE
|
|
* @see #UCAL_JULY
|
|
* @see #UCAL_AUGUST
|
|
* @see #UCAL_SEPTEMBER
|
|
* @see #UCAL_OCTOBER
|
|
* @see #UCAL_NOVEMBER
|
|
* @see #UCAL_DECEMBER
|
|
* @see #UCAL_UNDECIMBER
|
|
* @stable ICU 2.6
|
|
*/
|
|
UCAL_MONTH,
|
|
|
|
/**
|
|
* Field number indicating the
|
|
* week number within the current year. The first week of the year, as
|
|
* defined by <code>UCAL_FIRST_DAY_OF_WEEK</code> and <code>UCAL_MINIMAL_DAYS_IN_FIRST_WEEK</code>
|
|
* attributes, has value 1. Subclasses define
|
|
* the value of <code>UCAL_WEEK_OF_YEAR</code> for days before the first week of
|
|
* the year.
|
|
* @see ucal_getAttribute
|
|
* @see ucal_setAttribute
|
|
* @stable ICU 2.6
|
|
*/
|
|
UCAL_WEEK_OF_YEAR,
|
|
|
|
/**
|
|
* Field number indicating the
|
|
* week number within the current month. The first week of the month, as
|
|
* defined by <code>UCAL_FIRST_DAY_OF_WEEK</code> and <code>UCAL_MINIMAL_DAYS_IN_FIRST_WEEK</code>
|
|
* attributes, has value 1. Subclasses define
|
|
* the value of <code>WEEK_OF_MONTH</code> for days before the first week of
|
|
* the month.
|
|
* @see ucal_getAttribute
|
|
* @see ucal_setAttribute
|
|
* @see #UCAL_FIRST_DAY_OF_WEEK
|
|
* @see #UCAL_MINIMAL_DAYS_IN_FIRST_WEEK
|
|
* @stable ICU 2.6
|
|
*/
|
|
UCAL_WEEK_OF_MONTH,
|
|
|
|
/**
|
|
* Field number indicating the
|
|
* day of the month. This is a synonym for <code>DAY_OF_MONTH</code>.
|
|
* The first day of the month has value 1.
|
|
* @see #UCAL_DAY_OF_MONTH
|
|
* @stable ICU 2.6
|
|
*/
|
|
UCAL_DATE,
|
|
|
|
/**
|
|
* Field number indicating the day
|
|
* number within the current year. The first day of the year has value 1.
|
|
* @stable ICU 2.6
|
|
*/
|
|
UCAL_DAY_OF_YEAR,
|
|
|
|
/**
|
|
* Field number indicating the day
|
|
* of the week. This field takes values <code>SUNDAY</code>,
|
|
* <code>MONDAY</code>, <code>TUESDAY</code>, <code>WEDNESDAY</code>,
|
|
* <code>THURSDAY</code>, <code>FRIDAY</code>, and <code>SATURDAY</code>.
|
|
* @see #UCAL_SUNDAY
|
|
* @see #UCAL_MONDAY
|
|
* @see #UCAL_TUESDAY
|
|
* @see #UCAL_WEDNESDAY
|
|
* @see #UCAL_THURSDAY
|
|
* @see #UCAL_FRIDAY
|
|
* @see #UCAL_SATURDAY
|
|
* @stable ICU 2.6
|
|
*/
|
|
UCAL_DAY_OF_WEEK,
|
|
|
|
/**
|
|
* Field number indicating the
|
|
* ordinal number of the day of the week within the current month. Together
|
|
* with the <code>DAY_OF_WEEK</code> field, this uniquely specifies a day
|
|
* within a month. Unlike <code>WEEK_OF_MONTH</code> and
|
|
* <code>WEEK_OF_YEAR</code>, this field's value does <em>not</em> depend on
|
|
* <code>getFirstDayOfWeek()</code> or
|
|
* <code>getMinimalDaysInFirstWeek()</code>. <code>DAY_OF_MONTH 1</code>
|
|
* through <code>7</code> always correspond to <code>DAY_OF_WEEK_IN_MONTH
|
|
* 1</code>; <code>8</code> through <code>15</code> correspond to
|
|
* <code>DAY_OF_WEEK_IN_MONTH 2</code>, and so on.
|
|
* <code>DAY_OF_WEEK_IN_MONTH 0</code> indicates the week before
|
|
* <code>DAY_OF_WEEK_IN_MONTH 1</code>. Negative values count back from the
|
|
* end of the month, so the last Sunday of a month is specified as
|
|
* <code>DAY_OF_WEEK = SUNDAY, DAY_OF_WEEK_IN_MONTH = -1</code>. 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, <code>DAY_OF_WEEK_IN_MONTH -1</code> will overlap
|
|
* <code>DAY_OF_WEEK_IN_MONTH 5</code> and the end of <code>4</code>.
|
|
* @see #UCAL_DAY_OF_WEEK
|
|
* @see #UCAL_WEEK_OF_MONTH
|
|
* @stable ICU 2.6
|
|
*/
|
|
UCAL_DAY_OF_WEEK_IN_MONTH,
|
|
|
|
/**
|
|
* Field number indicating
|
|
* whether the <code>HOUR</code> is before or after noon.
|
|
* E.g., at 10:04:15.250 PM the <code>AM_PM</code> is <code>PM</code>.
|
|
* @see #UCAL_AM
|
|
* @see #UCAL_PM
|
|
* @see #UCAL_HOUR
|
|
* @stable ICU 2.6
|
|
*/
|
|
UCAL_AM_PM,
|
|
|
|
/**
|
|
* Field number indicating the
|
|
* hour of the morning or afternoon. <code>HOUR</code> is used for the 12-hour
|
|
* clock.
|
|
* E.g., at 10:04:15.250 PM the <code>HOUR</code> is 10.
|
|
* @see #UCAL_AM_PM
|
|
* @see #UCAL_HOUR_OF_DAY
|
|
* @stable ICU 2.6
|
|
*/
|
|
UCAL_HOUR,
|
|
|
|
/**
|
|
* Field number indicating the
|
|
* hour of the day. <code>HOUR_OF_DAY</code> is used for the 24-hour clock.
|
|
* E.g., at 10:04:15.250 PM the <code>HOUR_OF_DAY</code> is 22.
|
|
* @see #UCAL_HOUR
|
|
* @stable ICU 2.6
|
|
*/
|
|
UCAL_HOUR_OF_DAY,
|
|
|
|
/**
|
|
* Field number indicating the
|
|
* minute within the hour.
|
|
* E.g., at 10:04:15.250 PM the <code>UCAL_MINUTE</code> is 4.
|
|
* @stable ICU 2.6
|
|
*/
|
|
UCAL_MINUTE,
|
|
|
|
/**
|
|
* Field number indicating the
|
|
* second within the minute.
|
|
* E.g., at 10:04:15.250 PM the <code>UCAL_SECOND</code> is 15.
|
|
* @stable ICU 2.6
|
|
*/
|
|
UCAL_SECOND,
|
|
|
|
/**
|
|
* Field number indicating the
|
|
* millisecond within the second.
|
|
* E.g., at 10:04:15.250 PM the <code>UCAL_MILLISECOND</code> is 250.
|
|
* @stable ICU 2.6
|
|
*/
|
|
UCAL_MILLISECOND,
|
|
|
|
/**
|
|
* Field number indicating the
|
|
* raw offset from GMT in milliseconds.
|
|
* @stable ICU 2.6
|
|
*/
|
|
UCAL_ZONE_OFFSET,
|
|
|
|
/**
|
|
* Field number indicating the
|
|
* daylight savings offset in milliseconds.
|
|
* @stable ICU 2.6
|
|
*/
|
|
UCAL_DST_OFFSET,
|
|
|
|
/**
|
|
* Field number
|
|
* indicating the extended year corresponding to the
|
|
* <code>UCAL_WEEK_OF_YEAR</code> field. This may be one greater or less
|
|
* than the value of <code>UCAL_EXTENDED_YEAR</code>.
|
|
* @stable ICU 2.6
|
|
*/
|
|
UCAL_YEAR_WOY,
|
|
|
|
/**
|
|
* Field number
|
|
* indicating the localized day of week. This will be a value from 1
|
|
* to 7 inclusive, with 1 being the localized first day of the week.
|
|
* @stable ICU 2.6
|
|
*/
|
|
UCAL_DOW_LOCAL,
|
|
|
|
/**
|
|
* 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.
|
|
* @stable ICU 2.8
|
|
*/
|
|
UCAL_EXTENDED_YEAR,
|
|
|
|
/**
|
|
* 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.
|
|
* @stable ICU 2.8
|
|
*/
|
|
UCAL_JULIAN_DAY,
|
|
|
|
/**
|
|
* Ranges from 0 to 23:59:59.999 (regardless of DST). This field behaves <em>exactly</em>
|
|
* like a composite of all time-related fields, not including the zone fields. As such,
|
|
* it also reflects discontinuities of 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.
|
|
* @stable ICU 2.8
|
|
*/
|
|
UCAL_MILLISECONDS_IN_DAY,
|
|
|
|
/**
|
|
* Whether or not the current month is a leap month (0 or 1). See the Chinese calendar for
|
|
* an example of this.
|
|
*/
|
|
UCAL_IS_LEAP_MONTH,
|
|
|
|
/* Do not conditionalize the following with #ifndef U_HIDE_DEPRECATED_API,
|
|
* it is needed for layout of Calendar, DateFormat, and other objects */
|
|
#ifndef U_FORCE_HIDE_DEPRECATED_API
|
|
/**
|
|
* One more than the highest normal UCalendarDateFields value.
|
|
* @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
|
|
*/
|
|
UCAL_FIELD_COUNT,
|
|
#endif // U_FORCE_HIDE_DEPRECATED_API
|
|
|
|
/**
|
|
* Field number indicating the
|
|
* day of the month. This is a synonym for <code>UCAL_DATE</code>.
|
|
* The first day of the month has value 1.
|
|
* @see #UCAL_DATE
|
|
* Synonym for UCAL_DATE
|
|
* @stable ICU 2.8
|
|
**/
|
|
UCAL_DAY_OF_MONTH=UCAL_DATE
|
|
};
|
|
|
|
/** @stable ICU 2.0 */
|
|
typedef enum UCalendarDateFields UCalendarDateFields;
|
|
/**
|
|
* Useful constant 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., UCAL_SUNDAY.
|
|
*/
|
|
/** Possible days of the week in a UCalendar
|
|
* @stable ICU 2.0
|
|
*/
|
|
enum UCalendarDaysOfWeek {
|
|
/** Sunday */
|
|
UCAL_SUNDAY = 1,
|
|
/** Monday */
|
|
UCAL_MONDAY,
|
|
/** Tuesday */
|
|
UCAL_TUESDAY,
|
|
/** Wednesday */
|
|
UCAL_WEDNESDAY,
|
|
/** Thursday */
|
|
UCAL_THURSDAY,
|
|
/** Friday */
|
|
UCAL_FRIDAY,
|
|
/** Saturday */
|
|
UCAL_SATURDAY
|
|
};
|
|
|
|
/** @stable ICU 2.0 */
|
|
typedef enum UCalendarDaysOfWeek UCalendarDaysOfWeek;
|
|
|
|
/** Possible months in a UCalendar. Note: Calendar month is 0-based.
|
|
* @stable ICU 2.0
|
|
*/
|
|
enum UCalendarMonths {
|
|
/** January */
|
|
UCAL_JANUARY,
|
|
/** February */
|
|
UCAL_FEBRUARY,
|
|
/** March */
|
|
UCAL_MARCH,
|
|
/** April */
|
|
UCAL_APRIL,
|
|
/** May */
|
|
UCAL_MAY,
|
|
/** June */
|
|
UCAL_JUNE,
|
|
/** July */
|
|
UCAL_JULY,
|
|
/** August */
|
|
UCAL_AUGUST,
|
|
/** September */
|
|
UCAL_SEPTEMBER,
|
|
/** October */
|
|
UCAL_OCTOBER,
|
|
/** November */
|
|
UCAL_NOVEMBER,
|
|
/** December */
|
|
UCAL_DECEMBER,
|
|
/** Value of the <code>UCAL_MONTH</code> field indicating the
|
|
* thirteenth month of the year. Although the Gregorian calendar
|
|
* does not use this value, lunar calendars do.
|
|
*/
|
|
UCAL_UNDECIMBER
|
|
};
|
|
|
|
/** @stable ICU 2.0 */
|
|
typedef enum UCalendarMonths UCalendarMonths;
|
|
|
|
/** Possible AM/PM values in a UCalendar
|
|
* @stable ICU 2.0
|
|
*/
|
|
enum UCalendarAMPMs {
|
|
/** AM */
|
|
UCAL_AM,
|
|
/** PM */
|
|
UCAL_PM
|
|
};
|
|
|
|
/** @stable ICU 2.0 */
|
|
typedef enum UCalendarAMPMs UCalendarAMPMs;
|
|
|
|
/**
|
|
* System time zone type constants used by filtering zones
|
|
* in ucal_openTimeZoneIDEnumeration.
|
|
* @see ucal_openTimeZoneIDEnumeration
|
|
* @stable ICU 4.8
|
|
*/
|
|
enum USystemTimeZoneType {
|
|
/**
|
|
* Any system zones.
|
|
* @stable ICU 4.8
|
|
*/
|
|
UCAL_ZONE_TYPE_ANY,
|
|
/**
|
|
* Canonical system zones.
|
|
* @stable ICU 4.8
|
|
*/
|
|
UCAL_ZONE_TYPE_CANONICAL,
|
|
/**
|
|
* Canonical system zones associated with actual locations.
|
|
* @stable ICU 4.8
|
|
*/
|
|
UCAL_ZONE_TYPE_CANONICAL_LOCATION
|
|
};
|
|
|
|
/** @stable ICU 4.8 */
|
|
typedef enum USystemTimeZoneType USystemTimeZoneType;
|
|
|
|
/**
|
|
* Create an enumeration over system time zone IDs with the given
|
|
* filter conditions.
|
|
* @param zoneType The system time zone type.
|
|
* @param region The ISO 3166 two-letter country code or UN M.49
|
|
* three-digit area code. When NULL, no filtering
|
|
* done by region.
|
|
* @param rawOffset An offset from GMT in milliseconds, ignoring the
|
|
* effect of daylight savings time, if any. When NULL,
|
|
* no filtering done by zone offset.
|
|
* @param ec A pointer to an UErrorCode to receive any errors
|
|
* @return an enumeration object that the caller must dispose of
|
|
* using enum_close(), or NULL upon failure. In case of failure,
|
|
* *ec will indicate the error.
|
|
* @stable ICU 4.8
|
|
*/
|
|
U_CAPI UEnumeration* U_EXPORT2
|
|
ucal_openTimeZoneIDEnumeration(USystemTimeZoneType zoneType, const char* region,
|
|
const int32_t* rawOffset, UErrorCode* ec);
|
|
|
|
/**
|
|
* Create an enumeration over all time zones.
|
|
*
|
|
* @param ec input/output error code
|
|
*
|
|
* @return an enumeration object that the caller must dispose of using
|
|
* uenum_close(), or NULL upon failure. In case of failure *ec will
|
|
* indicate the error.
|
|
*
|
|
* @stable ICU 2.6
|
|
*/
|
|
U_CAPI UEnumeration* U_EXPORT2
|
|
ucal_openTimeZones(UErrorCode* ec);
|
|
|
|
/**
|
|
* Create 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.
|
|
*
|
|
* @param country the ISO 3166 two-letter country code, or NULL to
|
|
* retrieve zones not affiliated with any country
|
|
*
|
|
* @param ec input/output error code
|
|
*
|
|
* @return an enumeration object that the caller must dispose of using
|
|
* uenum_close(), or NULL upon failure. In case of failure *ec will
|
|
* indicate the error.
|
|
*
|
|
* @stable ICU 2.6
|
|
*/
|
|
U_CAPI UEnumeration* U_EXPORT2
|
|
ucal_openCountryTimeZones(const char* country, UErrorCode* ec);
|
|
|
|
/**
|
|
* Return the default time zone. The default is determined initially
|
|
* by querying the host operating system. If the host system detection
|
|
* routines fail, or if they specify a TimeZone or TimeZone offset
|
|
* which is not recognized, then the special TimeZone "Etc/Unknown"
|
|
* is returned.
|
|
*
|
|
* The default may be changed with `ucal_setDefaultTimeZone()` or with
|
|
* the C++ TimeZone API, `TimeZone::adoptDefault(TimeZone*)`.
|
|
*
|
|
* @param result A buffer to receive the result, or NULL
|
|
*
|
|
* @param resultCapacity The capacity of the result buffer
|
|
*
|
|
* @param ec input/output error code
|
|
*
|
|
* @return The result string length, not including the terminating
|
|
* null
|
|
*
|
|
* @see #UCAL_UNKNOWN_ZONE_ID
|
|
*
|
|
* @stable ICU 2.6
|
|
*/
|
|
U_CAPI int32_t U_EXPORT2
|
|
ucal_getDefaultTimeZone(UChar* result, int32_t resultCapacity, UErrorCode* ec);
|
|
|
|
/**
|
|
* Set the default time zone.
|
|
*
|
|
* @param zoneID null-terminated time zone ID
|
|
*
|
|
* @param ec input/output error code
|
|
*
|
|
* @stable ICU 2.6
|
|
*/
|
|
U_CAPI void U_EXPORT2
|
|
ucal_setDefaultTimeZone(const UChar* zoneID, UErrorCode* ec);
|
|
|
|
/**
|
|
* Return the current host time zone. The host time zone is detected from
|
|
* the current host system configuration by querying the host operating
|
|
* system. If the host system detection routines fail, or if they specify
|
|
* a TimeZone or TimeZone offset which is not recognized, then the special
|
|
* TimeZone "Etc/Unknown" is returned.
|
|
*
|
|
* Note that host time zone and the ICU default time zone can be different.
|
|
*
|
|
* The ICU default time zone does not change once initialized unless modified
|
|
* by calling `ucal_setDefaultTimeZone()` or with the C++ TimeZone API,
|
|
* `TimeZone::adoptDefault(TimeZone*)`.
|
|
*
|
|
* If the host operating system configuration has changed since ICU has
|
|
* initialized then the returned value can be different than the ICU default
|
|
* time zone, even if the default has not changed.
|
|
*
|
|
* <p>This function is not thread safe.</p>
|
|
*
|
|
* @param result A buffer to receive the result, or NULL
|
|
* @param resultCapacity The capacity of the result buffer
|
|
* @param ec input/output error code
|
|
* @return The result string length, not including the terminating
|
|
* null
|
|
*
|
|
* @see #UCAL_UNKNOWN_ZONE_ID
|
|
*
|
|
* @stable ICU 65
|
|
*/
|
|
U_CAPI int32_t U_EXPORT2
|
|
ucal_getHostTimeZone(UChar *result, int32_t resultCapacity, UErrorCode *ec);
|
|
|
|
/**
|
|
* Return the amount of time in milliseconds that the clock is
|
|
* advanced during daylight savings time for the given time zone, or
|
|
* zero if the time zone does not observe daylight savings time.
|
|
*
|
|
* @param zoneID null-terminated time zone ID
|
|
*
|
|
* @param ec input/output error code
|
|
*
|
|
* @return the number of milliseconds the time is advanced with
|
|
* respect to standard time when the daylight savings rules are in
|
|
* effect. This is always a non-negative number, most commonly either
|
|
* 3,600,000 (one hour) or zero.
|
|
*
|
|
* @stable ICU 2.6
|
|
*/
|
|
U_CAPI int32_t U_EXPORT2
|
|
ucal_getDSTSavings(const UChar* zoneID, UErrorCode* ec);
|
|
|
|
/**
|
|
* Get the current date and time.
|
|
* The value returned is represented as milliseconds from the epoch.
|
|
* @return The current date and time.
|
|
* @stable ICU 2.0
|
|
*/
|
|
U_CAPI UDate U_EXPORT2
|
|
ucal_getNow(void);
|
|
|
|
/**
|
|
* Open a UCalendar.
|
|
* A UCalendar may be used to convert a millisecond value to a year,
|
|
* month, and day.
|
|
* <p>
|
|
* Note: When unknown TimeZone ID is specified or if the TimeZone ID specified is "Etc/Unknown",
|
|
* the UCalendar returned by the function is initialized with GMT zone with TimeZone ID
|
|
* <code>UCAL_UNKNOWN_ZONE_ID</code> ("Etc/Unknown") without any errors/warnings. If you want
|
|
* to check if a TimeZone ID is valid prior to this function, use <code>ucal_getCanonicalTimeZoneID</code>.
|
|
*
|
|
* @param zoneID The desired TimeZone ID. If 0, use the default time zone.
|
|
* @param len The length of zoneID, or -1 if null-terminated.
|
|
* @param locale The desired locale
|
|
* @param type The type of UCalendar to open. This can be UCAL_GREGORIAN to open the Gregorian
|
|
* calendar for the locale, or UCAL_DEFAULT to open the default calendar for the locale (the
|
|
* default calendar may also be Gregorian). To open a specific non-Gregorian calendar for the
|
|
* locale, use uloc_setKeywordValue to set the value of the calendar keyword for the locale
|
|
* and then pass the locale to ucal_open with UCAL_DEFAULT as the type.
|
|
* @param status A pointer to an UErrorCode to receive any errors
|
|
* @return A pointer to a UCalendar, or 0 if an error occurred.
|
|
* @see #UCAL_UNKNOWN_ZONE_ID
|
|
* @stable ICU 2.0
|
|
*/
|
|
U_CAPI UCalendar* U_EXPORT2
|
|
ucal_open(const UChar* zoneID,
|
|
int32_t len,
|
|
const char* locale,
|
|
UCalendarType type,
|
|
UErrorCode* status);
|
|
|
|
/**
|
|
* Close a UCalendar.
|
|
* Once closed, a UCalendar may no longer be used.
|
|
* @param cal The UCalendar to close.
|
|
* @stable ICU 2.0
|
|
*/
|
|
U_CAPI void U_EXPORT2
|
|
ucal_close(UCalendar *cal);
|
|
|
|
#if U_SHOW_CPLUSPLUS_API
|
|
|
|
U_NAMESPACE_BEGIN
|
|
|
|
/**
|
|
* \class LocalUCalendarPointer
|
|
* "Smart pointer" class, closes a UCalendar via ucal_close().
|
|
* For most methods see the LocalPointerBase base class.
|
|
*
|
|
* @see LocalPointerBase
|
|
* @see LocalPointer
|
|
* @stable ICU 4.4
|
|
*/
|
|
U_DEFINE_LOCAL_OPEN_POINTER(LocalUCalendarPointer, UCalendar, ucal_close);
|
|
|
|
U_NAMESPACE_END
|
|
|
|
#endif
|
|
|
|
/**
|
|
* Open a copy of a UCalendar.
|
|
* This function performs a deep copy.
|
|
* @param cal The calendar to copy
|
|
* @param status A pointer to an UErrorCode to receive any errors.
|
|
* @return A pointer to a UCalendar identical to cal.
|
|
* @stable ICU 4.0
|
|
*/
|
|
U_CAPI UCalendar* U_EXPORT2
|
|
ucal_clone(const UCalendar* cal,
|
|
UErrorCode* status);
|
|
|
|
/**
|
|
* Set the TimeZone used by a UCalendar.
|
|
* A UCalendar uses a timezone for converting from Greenwich time to local time.
|
|
* @param cal The UCalendar to set.
|
|
* @param zoneID The desired TimeZone ID. If 0, use the default time zone.
|
|
* @param len The length of zoneID, or -1 if null-terminated.
|
|
* @param status A pointer to an UErrorCode to receive any errors.
|
|
* @stable ICU 2.0
|
|
*/
|
|
U_CAPI void U_EXPORT2
|
|
ucal_setTimeZone(UCalendar* cal,
|
|
const UChar* zoneID,
|
|
int32_t len,
|
|
UErrorCode* status);
|
|
|
|
/**
|
|
* Get the ID of the UCalendar's time zone.
|
|
*
|
|
* @param cal The UCalendar to query.
|
|
* @param result Receives the UCalendar's time zone ID.
|
|
* @param resultLength The maximum size of result.
|
|
* @param status Receives the status.
|
|
* @return The total buffer size needed; if greater than resultLength, the output was truncated.
|
|
* @stable ICU 51
|
|
*/
|
|
U_CAPI int32_t U_EXPORT2
|
|
ucal_getTimeZoneID(const UCalendar *cal,
|
|
UChar *result,
|
|
int32_t resultLength,
|
|
UErrorCode *status);
|
|
|
|
/**
|
|
* Possible formats for a UCalendar's display name
|
|
* @stable ICU 2.0
|
|
*/
|
|
enum UCalendarDisplayNameType {
|
|
/** Standard display name */
|
|
UCAL_STANDARD,
|
|
/** Short standard display name */
|
|
UCAL_SHORT_STANDARD,
|
|
/** Daylight savings display name */
|
|
UCAL_DST,
|
|
/** Short daylight savings display name */
|
|
UCAL_SHORT_DST
|
|
};
|
|
|
|
/** @stable ICU 2.0 */
|
|
typedef enum UCalendarDisplayNameType UCalendarDisplayNameType;
|
|
|
|
/**
|
|
* Get the display name for a UCalendar's TimeZone.
|
|
* A display name is suitable for presentation to a user.
|
|
* @param cal The UCalendar to query.
|
|
* @param type The desired display name format; one of UCAL_STANDARD, UCAL_SHORT_STANDARD,
|
|
* UCAL_DST, UCAL_SHORT_DST
|
|
* @param locale The desired locale for the display name.
|
|
* @param result A pointer to a buffer to receive the formatted number.
|
|
* @param resultLength The maximum size of result.
|
|
* @param status A pointer to an UErrorCode to receive any errors
|
|
* @return The total buffer size needed; if greater than resultLength, the output was truncated.
|
|
* @stable ICU 2.0
|
|
*/
|
|
U_CAPI int32_t U_EXPORT2
|
|
ucal_getTimeZoneDisplayName(const UCalendar* cal,
|
|
UCalendarDisplayNameType type,
|
|
const char* locale,
|
|
UChar* result,
|
|
int32_t resultLength,
|
|
UErrorCode* status);
|
|
|
|
/**
|
|
* Determine if a UCalendar is currently in daylight savings time.
|
|
* Daylight savings time is not used in all parts of the world.
|
|
* @param cal The UCalendar to query.
|
|
* @param status A pointer to an UErrorCode to receive any errors
|
|
* @return true if cal is currently in daylight savings time, false otherwise
|
|
* @stable ICU 2.0
|
|
*/
|
|
U_CAPI UBool U_EXPORT2
|
|
ucal_inDaylightTime(const UCalendar* cal,
|
|
UErrorCode* status );
|
|
|
|
/**
|
|
* Sets the GregorianCalendar 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 UCalendar is not
|
|
* an instance of a Gregorian calendar, then a U_UNSUPPORTED_ERROR
|
|
* error code is set.
|
|
*
|
|
* @param cal The calendar object.
|
|
* @param date The given Gregorian cutover date.
|
|
* @param pErrorCode Pointer to a standard ICU error code. Its input value must
|
|
* pass the U_SUCCESS() test, or else the function returns
|
|
* immediately. Check for U_FAILURE() on output or use with
|
|
* function chaining. (See User Guide for details.)
|
|
*
|
|
* @see GregorianCalendar::setGregorianChange
|
|
* @see ucal_getGregorianChange
|
|
* @stable ICU 3.6
|
|
*/
|
|
U_CAPI void U_EXPORT2
|
|
ucal_setGregorianChange(UCalendar *cal, UDate date, UErrorCode *pErrorCode);
|
|
|
|
/**
|
|
* 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 UCalendar is not
|
|
* an instance of a Gregorian calendar, then a U_UNSUPPORTED_ERROR
|
|
* error code is set.
|
|
*
|
|
* @param cal The calendar object.
|
|
* @param pErrorCode Pointer to a standard ICU error code. Its input value must
|
|
* pass the U_SUCCESS() test, or else the function returns
|
|
* immediately. Check for U_FAILURE() on output or use with
|
|
* function chaining. (See User Guide for details.)
|
|
* @return The Gregorian cutover time for this calendar.
|
|
*
|
|
* @see GregorianCalendar::getGregorianChange
|
|
* @see ucal_setGregorianChange
|
|
* @stable ICU 3.6
|
|
*/
|
|
U_CAPI UDate U_EXPORT2
|
|
ucal_getGregorianChange(const UCalendar *cal, UErrorCode *pErrorCode);
|
|
|
|
/**
|
|
* Types of UCalendar attributes
|
|
* @stable ICU 2.0
|
|
*/
|
|
enum UCalendarAttribute {
|
|
/**
|
|
* Lenient parsing
|
|
* @stable ICU 2.0
|
|
*/
|
|
UCAL_LENIENT,
|
|
/**
|
|
* First day of week
|
|
* @stable ICU 2.0
|
|
*/
|
|
UCAL_FIRST_DAY_OF_WEEK,
|
|
/**
|
|
* Minimum number of days in first week
|
|
* @stable ICU 2.0
|
|
*/
|
|
UCAL_MINIMAL_DAYS_IN_FIRST_WEEK,
|
|
/**
|
|
* The behavior for handling wall time repeating multiple times
|
|
* at negative time zone offset transitions
|
|
* @stable ICU 49
|
|
*/
|
|
UCAL_REPEATED_WALL_TIME,
|
|
/**
|
|
* The behavior for handling skipped wall time at positive time
|
|
* zone offset transitions.
|
|
* @stable ICU 49
|
|
*/
|
|
UCAL_SKIPPED_WALL_TIME
|
|
};
|
|
|
|
/** @stable ICU 2.0 */
|
|
typedef enum UCalendarAttribute UCalendarAttribute;
|
|
|
|
/**
|
|
* Options for handling ambiguous wall time at time zone
|
|
* offset transitions.
|
|
* @stable ICU 49
|
|
*/
|
|
enum UCalendarWallTimeOption {
|
|
/**
|
|
* An ambiguous wall time to be interpreted as the latest.
|
|
* This option is valid for UCAL_REPEATED_WALL_TIME and
|
|
* UCAL_SKIPPED_WALL_TIME.
|
|
* @stable ICU 49
|
|
*/
|
|
UCAL_WALLTIME_LAST,
|
|
/**
|
|
* An ambiguous wall time to be interpreted as the earliest.
|
|
* This option is valid for UCAL_REPEATED_WALL_TIME and
|
|
* UCAL_SKIPPED_WALL_TIME.
|
|
* @stable ICU 49
|
|
*/
|
|
UCAL_WALLTIME_FIRST,
|
|
/**
|
|
* An ambiguous wall time to be interpreted as the next valid
|
|
* wall time. This option is valid for UCAL_SKIPPED_WALL_TIME.
|
|
* @stable ICU 49
|
|
*/
|
|
UCAL_WALLTIME_NEXT_VALID
|
|
};
|
|
/** @stable ICU 49 */
|
|
typedef enum UCalendarWallTimeOption UCalendarWallTimeOption;
|
|
|
|
/**
|
|
* Get a numeric attribute associated with a UCalendar.
|
|
* Numeric attributes include the first day of the week, or the minimal numbers
|
|
* of days in the first week of the month.
|
|
* @param cal The UCalendar to query.
|
|
* @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK,
|
|
* UCAL_MINIMAL_DAYS_IN_FIRST_WEEK, UCAL_REPEATED_WALL_TIME or UCAL_SKIPPED_WALL_TIME
|
|
* @return The value of attr.
|
|
* @see ucal_setAttribute
|
|
* @stable ICU 2.0
|
|
*/
|
|
U_CAPI int32_t U_EXPORT2
|
|
ucal_getAttribute(const UCalendar* cal,
|
|
UCalendarAttribute attr);
|
|
|
|
/**
|
|
* Set a numeric attribute associated with a UCalendar.
|
|
* Numeric attributes include the first day of the week, or the minimal numbers
|
|
* of days in the first week of the month.
|
|
* @param cal The UCalendar to set.
|
|
* @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK,
|
|
* UCAL_MINIMAL_DAYS_IN_FIRST_WEEK, UCAL_REPEATED_WALL_TIME or UCAL_SKIPPED_WALL_TIME
|
|
* @param newValue The new value of attr.
|
|
* @see ucal_getAttribute
|
|
* @stable ICU 2.0
|
|
*/
|
|
U_CAPI void U_EXPORT2
|
|
ucal_setAttribute(UCalendar* cal,
|
|
UCalendarAttribute attr,
|
|
int32_t newValue);
|
|
|
|
/**
|
|
* Get a locale for which calendars are available.
|
|
* A UCalendar in a locale returned by this function will contain the correct
|
|
* day and month names for the locale.
|
|
* @param localeIndex The index of the desired locale.
|
|
* @return A locale for which calendars are available, or 0 if none.
|
|
* @see ucal_countAvailable
|
|
* @stable ICU 2.0
|
|
*/
|
|
U_CAPI const char* U_EXPORT2
|
|
ucal_getAvailable(int32_t localeIndex);
|
|
|
|
/**
|
|
* Determine how many locales have calendars available.
|
|
* This function is most useful as determining the loop ending condition for
|
|
* calls to \ref ucal_getAvailable.
|
|
* @return The number of locales for which calendars are available.
|
|
* @see ucal_getAvailable
|
|
* @stable ICU 2.0
|
|
*/
|
|
U_CAPI int32_t U_EXPORT2
|
|
ucal_countAvailable(void);
|
|
|
|
/**
|
|
* Get a UCalendar's current time in millis.
|
|
* The time is represented as milliseconds from the epoch.
|
|
* @param cal The UCalendar to query.
|
|
* @param status A pointer to an UErrorCode to receive any errors
|
|
* @return The calendar's current time in millis.
|
|
* @see ucal_setMillis
|
|
* @see ucal_setDate
|
|
* @see ucal_setDateTime
|
|
* @stable ICU 2.0
|
|
*/
|
|
U_CAPI UDate U_EXPORT2
|
|
ucal_getMillis(const UCalendar* cal,
|
|
UErrorCode* status);
|
|
|
|
/**
|
|
* Set a UCalendar's current time in millis.
|
|
* The time is represented as milliseconds from the epoch.
|
|
* @param cal The UCalendar to set.
|
|
* @param dateTime The desired date and time.
|
|
* @param status A pointer to an UErrorCode to receive any errors
|
|
* @see ucal_getMillis
|
|
* @see ucal_setDate
|
|
* @see ucal_setDateTime
|
|
* @stable ICU 2.0
|
|
*/
|
|
U_CAPI void U_EXPORT2
|
|
ucal_setMillis(UCalendar* cal,
|
|
UDate dateTime,
|
|
UErrorCode* status );
|
|
|
|
/**
|
|
* Set a UCalendar's current date.
|
|
* The date is represented as a series of 32-bit integers.
|
|
* @param cal The UCalendar to set.
|
|
* @param year The desired year.
|
|
* @param month The desired month; one of 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
|
|
* @param date The desired day of the month.
|
|
* @param status A pointer to an UErrorCode to receive any errors
|
|
* @see ucal_getMillis
|
|
* @see ucal_setMillis
|
|
* @see ucal_setDateTime
|
|
* @stable ICU 2.0
|
|
*/
|
|
U_CAPI void U_EXPORT2
|
|
ucal_setDate(UCalendar* cal,
|
|
int32_t year,
|
|
int32_t month,
|
|
int32_t date,
|
|
UErrorCode* status);
|
|
|
|
/**
|
|
* Set a UCalendar's current date.
|
|
* The date is represented as a series of 32-bit integers.
|
|
* @param cal The UCalendar to set.
|
|
* @param year The desired year.
|
|
* @param month The desired month; one of 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
|
|
* @param date The desired day of the month.
|
|
* @param hour The desired hour of day.
|
|
* @param minute The desired minute.
|
|
* @param second The desirec second.
|
|
* @param status A pointer to an UErrorCode to receive any errors
|
|
* @see ucal_getMillis
|
|
* @see ucal_setMillis
|
|
* @see ucal_setDate
|
|
* @stable ICU 2.0
|
|
*/
|
|
U_CAPI 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);
|
|
|
|
/**
|
|
* Returns true if two UCalendars are equivalent. Equivalent
|
|
* UCalendars will behave identically, but they may be set to
|
|
* different times.
|
|
* @param cal1 The first of the UCalendars to compare.
|
|
* @param cal2 The second of the UCalendars to compare.
|
|
* @return true if cal1 and cal2 are equivalent, false otherwise.
|
|
* @stable ICU 2.0
|
|
*/
|
|
U_CAPI UBool U_EXPORT2
|
|
ucal_equivalentTo(const UCalendar* cal1,
|
|
const UCalendar* cal2);
|
|
|
|
/**
|
|
* Add a specified signed amount to a particular field in a UCalendar.
|
|
* This can modify more significant fields in the calendar.
|
|
* Adding a positive value always means moving forward in time, so for the Gregorian calendar,
|
|
* starting with 100 BC and adding +1 to year results in 99 BC (even though this actually reduces
|
|
* the numeric value of the field itself).
|
|
* @param cal The UCalendar to which to add.
|
|
* @param field The field to which to add the signed value; one of 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.
|
|
* @param amount The signed amount to add to 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.
|
|
* @param status A pointer to an UErrorCode to receive any errors
|
|
* @see ucal_roll
|
|
* @stable ICU 2.0
|
|
*/
|
|
U_CAPI void U_EXPORT2
|
|
ucal_add(UCalendar* cal,
|
|
UCalendarDateFields field,
|
|
int32_t amount,
|
|
UErrorCode* status);
|
|
|
|
/**
|
|
* Add a specified signed amount to a particular field in a UCalendar.
|
|
* 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).
|
|
* @param cal The UCalendar to which to add.
|
|
* @param field The field to which to add the signed value; one of 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.
|
|
* @param amount The signed amount to add to 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.
|
|
* @param status A pointer to an UErrorCode to receive any errors
|
|
* @see ucal_add
|
|
* @stable ICU 2.0
|
|
*/
|
|
U_CAPI void U_EXPORT2
|
|
ucal_roll(UCalendar* cal,
|
|
UCalendarDateFields field,
|
|
int32_t amount,
|
|
UErrorCode* status);
|
|
|
|
/**
|
|
* Get the current value of a field from a UCalendar.
|
|
* All fields are represented as 32-bit integers.
|
|
* @param cal The UCalendar to query.
|
|
* @param field The desired field; one of 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.
|
|
* @param status A pointer to an UErrorCode to receive any errors
|
|
* @return The value of the desired field.
|
|
* @see ucal_set
|
|
* @see ucal_isSet
|
|
* @see ucal_clearField
|
|
* @see ucal_clear
|
|
* @stable ICU 2.0
|
|
*/
|
|
U_CAPI int32_t U_EXPORT2
|
|
ucal_get(const UCalendar* cal,
|
|
UCalendarDateFields field,
|
|
UErrorCode* status );
|
|
|
|
/**
|
|
* Set the value of a field in a UCalendar.
|
|
* All fields are represented as 32-bit integers.
|
|
* @param cal The UCalendar to set.
|
|
* @param field The field to set; one of 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.
|
|
* @param value The desired value of field.
|
|
* @see ucal_get
|
|
* @see ucal_isSet
|
|
* @see ucal_clearField
|
|
* @see ucal_clear
|
|
* @stable ICU 2.0
|
|
*/
|
|
U_CAPI void U_EXPORT2
|
|
ucal_set(UCalendar* cal,
|
|
UCalendarDateFields field,
|
|
int32_t value);
|
|
|
|
/**
|
|
* Determine if a field in a UCalendar is set.
|
|
* All fields are represented as 32-bit integers.
|
|
* @param cal The UCalendar to query.
|
|
* @param field The desired field; one of 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.
|
|
* @return true if field is set, false otherwise.
|
|
* @see ucal_get
|
|
* @see ucal_set
|
|
* @see ucal_clearField
|
|
* @see ucal_clear
|
|
* @stable ICU 2.0
|
|
*/
|
|
U_CAPI UBool U_EXPORT2
|
|
ucal_isSet(const UCalendar* cal,
|
|
UCalendarDateFields field);
|
|
|
|
/**
|
|
* Clear a field in a UCalendar.
|
|
* All fields are represented as 32-bit integers.
|
|
* @param cal The UCalendar containing the field to clear.
|
|
* @param field The field to clear; one of 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.
|
|
* @see ucal_get
|
|
* @see ucal_set
|
|
* @see ucal_isSet
|
|
* @see ucal_clear
|
|
* @stable ICU 2.0
|
|
*/
|
|
U_CAPI void U_EXPORT2
|
|
ucal_clearField(UCalendar* cal,
|
|
UCalendarDateFields field);
|
|
|
|
/**
|
|
* Clear all fields in a UCalendar.
|
|
* All fields are represented as 32-bit integers.
|
|
* @param calendar The UCalendar to clear.
|
|
* @see ucal_get
|
|
* @see ucal_set
|
|
* @see ucal_isSet
|
|
* @see ucal_clearField
|
|
* @stable ICU 2.0
|
|
*/
|
|
U_CAPI void U_EXPORT2
|
|
ucal_clear(UCalendar* calendar);
|
|
|
|
/**
|
|
* Possible limit values for a UCalendar
|
|
* @stable ICU 2.0
|
|
*/
|
|
enum UCalendarLimitType {
|
|
/** Minimum value */
|
|
UCAL_MINIMUM,
|
|
/** Maximum value */
|
|
UCAL_MAXIMUM,
|
|
/** Greatest minimum value */
|
|
UCAL_GREATEST_MINIMUM,
|
|
/** Leaest maximum value */
|
|
UCAL_LEAST_MAXIMUM,
|
|
/** Actual minimum value */
|
|
UCAL_ACTUAL_MINIMUM,
|
|
/** Actual maximum value */
|
|
UCAL_ACTUAL_MAXIMUM
|
|
};
|
|
|
|
/** @stable ICU 2.0 */
|
|
typedef enum UCalendarLimitType UCalendarLimitType;
|
|
|
|
/**
|
|
* Determine a limit for a field in a UCalendar.
|
|
* A limit is a maximum or minimum value for a field.
|
|
* @param cal The UCalendar to query.
|
|
* @param field The desired field; one of 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.
|
|
* @param type The desired critical point; one of UCAL_MINIMUM, UCAL_MAXIMUM, UCAL_GREATEST_MINIMUM,
|
|
* UCAL_LEAST_MAXIMUM, UCAL_ACTUAL_MINIMUM, UCAL_ACTUAL_MAXIMUM
|
|
* @param status A pointer to an UErrorCode to receive any errors.
|
|
* @return The requested value.
|
|
* @stable ICU 2.0
|
|
*/
|
|
U_CAPI int32_t U_EXPORT2
|
|
ucal_getLimit(const UCalendar* cal,
|
|
UCalendarDateFields field,
|
|
UCalendarLimitType type,
|
|
UErrorCode* status);
|
|
|
|
/** Get the locale for this calendar object. You can choose between valid and actual locale.
|
|
* @param cal The calendar object
|
|
* @param type type of the locale we're looking for (valid or actual)
|
|
* @param status error code for the operation
|
|
* @return the locale name
|
|
* @stable ICU 2.8
|
|
*/
|
|
U_CAPI const char * U_EXPORT2
|
|
ucal_getLocaleByType(const UCalendar *cal, ULocDataLocaleType type, UErrorCode* status);
|
|
|
|
/**
|
|
* Returns the timezone data version currently used by ICU.
|
|
* @param status error code for the operation
|
|
* @return the version string, such as "2007f"
|
|
* @stable ICU 3.8
|
|
*/
|
|
U_CAPI const char * U_EXPORT2
|
|
ucal_getTZDataVersion(UErrorCode* status);
|
|
|
|
/**
|
|
* Returns the canonical system timezone ID or the normalized
|
|
* custom time zone ID for the given time zone ID.
|
|
* @param id The input timezone ID to be canonicalized.
|
|
* @param len The length of id, or -1 if null-terminated.
|
|
* @param result The buffer receives the canonical system timezone ID
|
|
* or the custom timezone ID in normalized format.
|
|
* @param resultCapacity The capacity of the result buffer.
|
|
* @param isSystemID Receives if the given ID is a known system
|
|
* timezone ID.
|
|
* @param status Receives the status. When the given timezone ID
|
|
* is neither a known system time zone ID nor a
|
|
* valid custom timezone ID, U_ILLEGAL_ARGUMENT_ERROR
|
|
* is set.
|
|
* @return The result string length, not including the terminating
|
|
* null.
|
|
* @stable ICU 4.0
|
|
*/
|
|
U_CAPI int32_t U_EXPORT2
|
|
ucal_getCanonicalTimeZoneID(const UChar* id, int32_t len,
|
|
UChar* result, int32_t resultCapacity, UBool *isSystemID, UErrorCode* status);
|
|
/**
|
|
* Get the resource keyword value string designating the calendar type for the UCalendar.
|
|
* @param cal The UCalendar to query.
|
|
* @param status The error code for the operation.
|
|
* @return The resource keyword value string.
|
|
* @stable ICU 4.2
|
|
*/
|
|
U_CAPI const char * U_EXPORT2
|
|
ucal_getType(const UCalendar *cal, UErrorCode* status);
|
|
|
|
/**
|
|
* 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.
|
|
* @param key one of the keys supported by this service. For now, only
|
|
* "calendar" is supported.
|
|
* @param locale the locale
|
|
* @param commonlyUsed 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.
|
|
* @param status error status
|
|
* @return a string enumeration over keyword values for the given key and the locale.
|
|
* @stable ICU 4.2
|
|
*/
|
|
U_CAPI UEnumeration* U_EXPORT2
|
|
ucal_getKeywordValuesForLocale(const char* key,
|
|
const char* locale,
|
|
UBool commonlyUsed,
|
|
UErrorCode* status);
|
|
|
|
|
|
/** Weekday types, as returned by ucal_getDayOfWeekType().
|
|
* @stable ICU 4.4
|
|
*/
|
|
enum UCalendarWeekdayType {
|
|
/**
|
|
* Designates a full weekday (no part of the day is included in the weekend).
|
|
* @stable ICU 4.4
|
|
*/
|
|
UCAL_WEEKDAY,
|
|
/**
|
|
* Designates a full weekend day (the entire day is included in the weekend).
|
|
* @stable ICU 4.4
|
|
*/
|
|
UCAL_WEEKEND,
|
|
/**
|
|
* Designates a day that starts as a weekday and transitions to the weekend.
|
|
* Call ucal_getWeekendTransition() to get the time of transition.
|
|
* @stable ICU 4.4
|
|
*/
|
|
UCAL_WEEKEND_ONSET,
|
|
/**
|
|
* Designates a day that starts as the weekend and transitions to a weekday.
|
|
* Call ucal_getWeekendTransition() to get the time of transition.
|
|
* @stable ICU 4.4
|
|
*/
|
|
UCAL_WEEKEND_CEASE
|
|
};
|
|
|
|
/** @stable ICU 4.4 */
|
|
typedef enum UCalendarWeekdayType UCalendarWeekdayType;
|
|
|
|
/**
|
|
* 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 UCalendar (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 UCAL_WEEKDAY or UCAL_WEEKEND. If a transition occurs at a time
|
|
* other than midnight, then the day of the transition will have
|
|
* the type UCAL_WEEKEND_ONSET or UCAL_WEEKEND_CEASE. In this case, the
|
|
* function ucal_getWeekendTransition() will return the point of
|
|
* transition.
|
|
* @param cal The UCalendar to query.
|
|
* @param dayOfWeek The day of the week whose type is desired (UCAL_SUNDAY..UCAL_SATURDAY).
|
|
* @param status The error code for the operation.
|
|
* @return The UCalendarWeekdayType for the day of the week.
|
|
* @stable ICU 4.4
|
|
*/
|
|
U_CAPI UCalendarWeekdayType U_EXPORT2
|
|
ucal_getDayOfWeekType(const UCalendar *cal, UCalendarDaysOfWeek dayOfWeek, UErrorCode* status);
|
|
|
|
/**
|
|
* Returns the time during the day at which the weekend begins or ends in
|
|
* this calendar system. If ucal_getDayOfWeekType() returns UCAL_WEEKEND_ONSET
|
|
* for the specified dayOfWeek, return the time at which the weekend begins.
|
|
* If ucal_getDayOfWeekType() returns UCAL_WEEKEND_CEASE for the specified dayOfWeek,
|
|
* return the time at which the weekend ends. If ucal_getDayOfWeekType() returns
|
|
* some other UCalendarWeekdayType for the specified dayOfWeek, is it an error condition
|
|
* (U_ILLEGAL_ARGUMENT_ERROR).
|
|
* @param cal The UCalendar to query.
|
|
* @param dayOfWeek The day of the week for which the weekend transition time is
|
|
* desired (UCAL_SUNDAY..UCAL_SATURDAY).
|
|
* @param status The error code for the operation.
|
|
* @return The milliseconds after midnight at which the weekend begins or ends.
|
|
* @stable ICU 4.4
|
|
*/
|
|
U_CAPI int32_t U_EXPORT2
|
|
ucal_getWeekendTransition(const UCalendar *cal, UCalendarDaysOfWeek dayOfWeek, UErrorCode *status);
|
|
|
|
/**
|
|
* Returns true if the given UDate is in the weekend in
|
|
* this calendar system.
|
|
* @param cal The UCalendar to query.
|
|
* @param date The UDate in question.
|
|
* @param status The error code for the operation.
|
|
* @return true if the given UDate is in the weekend in
|
|
* this calendar system, false otherwise.
|
|
* @stable ICU 4.4
|
|
*/
|
|
U_CAPI UBool U_EXPORT2
|
|
ucal_isWeekend(const UCalendar *cal, UDate date, UErrorCode *status);
|
|
|
|
/**
|
|
* Return 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 UCAL_MONTH
|
|
* and ucal_getFieldDifference 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 ucal_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.
|
|
*
|
|
* @param cal The UCalendar to compare and update.
|
|
* @param target The target date to compare to the current calendar setting.
|
|
* @param field The field to compare; one of 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.
|
|
* @param status A pointer to an UErrorCode to receive any errors
|
|
* @return The date difference for the specified field.
|
|
* @stable ICU 4.8
|
|
*/
|
|
U_CAPI int32_t U_EXPORT2
|
|
ucal_getFieldDifference(UCalendar* cal,
|
|
UDate target,
|
|
UCalendarDateFields field,
|
|
UErrorCode* status);
|
|
|
|
/**
|
|
* Time zone transition types for ucal_getTimeZoneTransitionDate
|
|
* @stable ICU 50
|
|
*/
|
|
enum UTimeZoneTransitionType {
|
|
/**
|
|
* Get the next transition after the current date,
|
|
* i.e. excludes the current date
|
|
* @stable ICU 50
|
|
*/
|
|
UCAL_TZ_TRANSITION_NEXT,
|
|
/**
|
|
* Get the next transition on or after the current date,
|
|
* i.e. may include the current date
|
|
* @stable ICU 50
|
|
*/
|
|
UCAL_TZ_TRANSITION_NEXT_INCLUSIVE,
|
|
/**
|
|
* Get the previous transition before the current date,
|
|
* i.e. excludes the current date
|
|
* @stable ICU 50
|
|
*/
|
|
UCAL_TZ_TRANSITION_PREVIOUS,
|
|
/**
|
|
* Get the previous transition on or before the current date,
|
|
* i.e. may include the current date
|
|
* @stable ICU 50
|
|
*/
|
|
UCAL_TZ_TRANSITION_PREVIOUS_INCLUSIVE
|
|
};
|
|
|
|
typedef enum UTimeZoneTransitionType UTimeZoneTransitionType; /**< @stable ICU 50 */
|
|
|
|
/**
|
|
* Get the 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.
|
|
* @param cal The UCalendar to query.
|
|
* @param type The type of transition desired.
|
|
* @param transition A pointer to a UDate to be set to the transition time.
|
|
* If the function returns false, the value set is unspecified.
|
|
* @param status A pointer to a UErrorCode to receive any errors.
|
|
* @return true if a valid transition time is set in *transition, false
|
|
* otherwise.
|
|
* @stable ICU 50
|
|
*/
|
|
U_CAPI UBool U_EXPORT2
|
|
ucal_getTimeZoneTransitionDate(const UCalendar* cal, UTimeZoneTransitionType type,
|
|
UDate* transition, UErrorCode* status);
|
|
|
|
/**
|
|
* Converts a system time zone ID to an equivalent Windows time zone ID. For example,
|
|
* Windows time zone ID "Pacific Standard Time" is returned for input "America/Los_Angeles".
|
|
*
|
|
* <p>There are system time zones that cannot be mapped to Windows zones. When the input
|
|
* system time zone ID is unknown or unmappable to a Windows time zone, then this
|
|
* function returns 0 as the result length, but the operation itself remains successful
|
|
* (no error status set on return).
|
|
*
|
|
* <p>This implementation utilizes <a href="http://unicode.org/cldr/charts/supplemental/zone_tzid.html">
|
|
* Zone-Tzid mapping data</a>. The mapping data is updated time to time. To get the latest changes,
|
|
* please read the ICU user guide section <a href="https://unicode-org.github.io/icu/userguide/datetime/timezone#updating-the-time-zone-data">
|
|
* Updating the Time Zone Data</a>.
|
|
*
|
|
* @param id A system time zone ID.
|
|
* @param len The length of <code>id</code>, or -1 if null-terminated.
|
|
* @param winid A buffer to receive a Windows time zone ID.
|
|
* @param winidCapacity The capacity of the result buffer <code>winid</code>.
|
|
* @param status Receives the status.
|
|
* @return The result string length, not including the terminating null.
|
|
* @see ucal_getTimeZoneIDForWindowsID
|
|
*
|
|
* @stable ICU 52
|
|
*/
|
|
U_CAPI int32_t U_EXPORT2
|
|
ucal_getWindowsTimeZoneID(const UChar* id, int32_t len,
|
|
UChar* winid, int32_t winidCapacity, UErrorCode* status);
|
|
|
|
/**
|
|
* Converts a Windows time zone ID to an equivalent system time zone ID
|
|
* for a region. For example, system time zone ID "America/Los_Angeles" is returned
|
|
* for input Windows ID "Pacific Standard Time" and region "US" (or <code>null</code>),
|
|
* "America/Vancouver" is returned for the same Windows ID "Pacific Standard Time" and
|
|
* region "CA".
|
|
*
|
|
* <p>Not all Windows time zones can be mapped to system time zones. When the input
|
|
* Windows time zone ID is unknown or unmappable to a system time zone, then this
|
|
* function returns 0 as the result length, but the operation itself remains successful
|
|
* (no error status set on return).
|
|
*
|
|
* <p>This implementation utilizes <a href="http://unicode.org/cldr/charts/supplemental/zone_tzid.html">
|
|
* Zone-Tzid mapping data</a>. The mapping data is updated time to time. To get the latest changes,
|
|
* please read the ICU user guide section <a href="https://unicode-org.github.io/icu/userguide/datetime/timezone#updating-the-time-zone-data">
|
|
* Updating the Time Zone Data</a>.
|
|
*
|
|
* @param winid A Windows time zone ID.
|
|
* @param len The length of <code>winid</code>, or -1 if null-terminated.
|
|
* @param region A null-terminated region code, or <code>NULL</code> if no regional preference.
|
|
* @param id A buffer to receive a system time zone ID.
|
|
* @param idCapacity The capacity of the result buffer <code>id</code>.
|
|
* @param status Receives the status.
|
|
* @return The result string length, not including the terminating null.
|
|
* @see ucal_getWindowsTimeZoneID
|
|
*
|
|
* @stable ICU 52
|
|
*/
|
|
U_CAPI int32_t U_EXPORT2
|
|
ucal_getTimeZoneIDForWindowsID(const UChar* winid, int32_t len, const char* region,
|
|
UChar* id, int32_t idCapacity, UErrorCode* status);
|
|
|
|
#endif /* #if !UCONFIG_NO_FORMATTING */
|
|
|
|
#endif
|