1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/i18n/unicode/ucal.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,1565 @@
1.4 +/*
1.5 + *******************************************************************************
1.6 + * Copyright (C) 1996-2013, International Business Machines Corporation and
1.7 + * others. All Rights Reserved.
1.8 + *******************************************************************************
1.9 + */
1.10 +
1.11 +#ifndef UCAL_H
1.12 +#define UCAL_H
1.13 +
1.14 +#include "unicode/utypes.h"
1.15 +#include "unicode/uenum.h"
1.16 +#include "unicode/uloc.h"
1.17 +#include "unicode/localpointer.h"
1.18 +
1.19 +#if !UCONFIG_NO_FORMATTING
1.20 +
1.21 +/**
1.22 + * \file
1.23 + * \brief C API: Calendar
1.24 + *
1.25 + * <h2>Calendar C API</h2>
1.26 + *
1.27 + * UCalendar C API is used for converting between a <code>UDate</code> object
1.28 + * and a set of integer fields such as <code>UCAL_YEAR</code>, <code>UCAL_MONTH</code>,
1.29 + * <code>UCAL_DAY</code>, <code>UCAL_HOUR</code>, and so on.
1.30 + * (A <code>UDate</code> object represents a specific instant in
1.31 + * time with millisecond precision. See UDate
1.32 + * for information about the <code>UDate</code> .)
1.33 + *
1.34 + * <p>
1.35 + * Types of <code>UCalendar</code> interpret a <code>UDate</code>
1.36 + * according to the rules of a specific calendar system. The U_STABLE
1.37 + * provides the enum UCalendarType with UCAL_TRADITIONAL and
1.38 + * UCAL_GREGORIAN.
1.39 + * <p>
1.40 + * Like other locale-sensitive C API, calendar API provides a
1.41 + * function, <code>ucal_open()</code>, which returns a pointer to
1.42 + * <code>UCalendar</code> whose time fields have been initialized
1.43 + * with the current date and time. We need to specify the type of
1.44 + * calendar to be opened and the timezoneId.
1.45 + * \htmlonly<blockquote>\endhtmlonly
1.46 + * <pre>
1.47 + * \code
1.48 + * UCalendar *caldef;
1.49 + * UChar *tzId;
1.50 + * UErrorCode status;
1.51 + * tzId=(UChar*)malloc(sizeof(UChar) * (strlen("PST") +1) );
1.52 + * u_uastrcpy(tzId, "PST");
1.53 + * caldef=ucal_open(tzID, u_strlen(tzID), NULL, UCAL_TRADITIONAL, &status);
1.54 + * \endcode
1.55 + * </pre>
1.56 + * \htmlonly</blockquote>\endhtmlonly
1.57 + *
1.58 + * <p>
1.59 + * A <code>UCalendar</code> object can produce all the time field values
1.60 + * needed to implement the date-time formatting for a particular language
1.61 + * and calendar style (for example, Japanese-Gregorian, Japanese-Traditional).
1.62 + *
1.63 + * <p>
1.64 + * When computing a <code>UDate</code> from time fields, two special circumstances
1.65 + * may arise: there may be insufficient information to compute the
1.66 + * <code>UDate</code> (such as only year and month but no day in the month),
1.67 + * or there may be inconsistent information (such as "Tuesday, July 15, 1996"
1.68 + * -- July 15, 1996 is actually a Monday).
1.69 + *
1.70 + * <p>
1.71 + * <strong>Insufficient information.</strong> The calendar will use default
1.72 + * information to specify the missing fields. This may vary by calendar; for
1.73 + * the Gregorian calendar, the default for a field is the same as that of the
1.74 + * start of the epoch: i.e., UCAL_YEAR = 1970, UCAL_MONTH = JANUARY, UCAL_DATE = 1, etc.
1.75 + *
1.76 + * <p>
1.77 + * <strong>Inconsistent information.</strong> If fields conflict, the calendar
1.78 + * will give preference to fields set more recently. For example, when
1.79 + * determining the day, the calendar will look for one of the following
1.80 + * combinations of fields. The most recent combination, as determined by the
1.81 + * most recently set single field, will be used.
1.82 + *
1.83 + * \htmlonly<blockquote>\endhtmlonly
1.84 + * <pre>
1.85 + * \code
1.86 + * UCAL_MONTH + UCAL_DAY_OF_MONTH
1.87 + * UCAL_MONTH + UCAL_WEEK_OF_MONTH + UCAL_DAY_OF_WEEK
1.88 + * UCAL_MONTH + UCAL_DAY_OF_WEEK_IN_MONTH + UCAL_DAY_OF_WEEK
1.89 + * UCAL_DAY_OF_YEAR
1.90 + * UCAL_DAY_OF_WEEK + UCAL_WEEK_OF_YEAR
1.91 + * \endcode
1.92 + * </pre>
1.93 + * \htmlonly</blockquote>\endhtmlonly
1.94 + *
1.95 + * For the time of day:
1.96 + *
1.97 + * \htmlonly<blockquote>\endhtmlonly
1.98 + * <pre>
1.99 + * \code
1.100 + * UCAL_HOUR_OF_DAY
1.101 + * UCAL_AM_PM + UCAL_HOUR
1.102 + * \endcode
1.103 + * </pre>
1.104 + * \htmlonly</blockquote>\endhtmlonly
1.105 + *
1.106 + * <p>
1.107 + * <strong>Note:</strong> for some non-Gregorian calendars, different
1.108 + * fields may be necessary for complete disambiguation. For example, a full
1.109 + * specification of the historial Arabic astronomical calendar requires year,
1.110 + * month, day-of-month <em>and</em> day-of-week in some cases.
1.111 + *
1.112 + * <p>
1.113 + * <strong>Note:</strong> There are certain possible ambiguities in
1.114 + * interpretation of certain singular times, which are resolved in the
1.115 + * following ways:
1.116 + * <ol>
1.117 + * <li> 24:00:00 "belongs" to the following day. That is,
1.118 + * 23:59 on Dec 31, 1969 < 24:00 on Jan 1, 1970 < 24:01:00 on Jan 1, 1970
1.119 + *
1.120 + * <li> Although historically not precise, midnight also belongs to "am",
1.121 + * and noon belongs to "pm", so on the same day,
1.122 + * 12:00 am (midnight) < 12:01 am, and 12:00 pm (noon) < 12:01 pm
1.123 + * </ol>
1.124 + *
1.125 + * <p>
1.126 + * The date or time format strings are not part of the definition of a
1.127 + * calendar, as those must be modifiable or overridable by the user at
1.128 + * runtime. Use {@link icu::DateFormat}
1.129 + * to format dates.
1.130 + *
1.131 + * <p>
1.132 + * <code>Calendar</code> provides an API for field "rolling", where fields
1.133 + * can be incremented or decremented, but wrap around. For example, rolling the
1.134 + * month up in the date <code>December 12, <b>1996</b></code> results in
1.135 + * <code>January 12, <b>1996</b></code>.
1.136 + *
1.137 + * <p>
1.138 + * <code>Calendar</code> also provides a date arithmetic function for
1.139 + * adding the specified (signed) amount of time to a particular time field.
1.140 + * For example, subtracting 5 days from the date <code>September 12, 1996</code>
1.141 + * results in <code>September 7, 1996</code>.
1.142 + *
1.143 + * @stable ICU 2.0
1.144 + */
1.145 +
1.146 +/**
1.147 + * The time zone ID reserved for unknown time zone.
1.148 + * @stable ICU 4.8
1.149 + */
1.150 +#define UCAL_UNKNOWN_ZONE_ID "Etc/Unknown"
1.151 +
1.152 +/** A calendar.
1.153 + * For usage in C programs.
1.154 + * @stable ICU 2.0
1.155 + */
1.156 +typedef void* UCalendar;
1.157 +
1.158 +/** Possible types of UCalendars
1.159 + * @stable ICU 2.0
1.160 + */
1.161 +enum UCalendarType {
1.162 + /**
1.163 + * Despite the name, UCAL_TRADITIONAL designates the locale's default calendar,
1.164 + * which may be the Gregorian calendar or some other calendar.
1.165 + * @stable ICU 2.0
1.166 + */
1.167 + UCAL_TRADITIONAL,
1.168 + /**
1.169 + * A better name for UCAL_TRADITIONAL.
1.170 + * @stable ICU 4.2
1.171 + */
1.172 + UCAL_DEFAULT = UCAL_TRADITIONAL,
1.173 + /**
1.174 + * Unambiguously designates the Gregorian calendar for the locale.
1.175 + * @stable ICU 2.0
1.176 + */
1.177 + UCAL_GREGORIAN
1.178 +};
1.179 +
1.180 +/** @stable ICU 2.0 */
1.181 +typedef enum UCalendarType UCalendarType;
1.182 +
1.183 +/** Possible fields in a UCalendar
1.184 + * @stable ICU 2.0
1.185 + */
1.186 +enum UCalendarDateFields {
1.187 + /**
1.188 + * Field number indicating the era, e.g., AD or BC in the Gregorian (Julian) calendar.
1.189 + * This is a calendar-specific value.
1.190 + * @stable ICU 2.6
1.191 + */
1.192 + UCAL_ERA,
1.193 +
1.194 + /**
1.195 + * Field number indicating the year. This is a calendar-specific value.
1.196 + * @stable ICU 2.6
1.197 + */
1.198 + UCAL_YEAR,
1.199 +
1.200 + /**
1.201 + * Field number indicating the month. This is a calendar-specific value.
1.202 + * The first month of the year is
1.203 + * <code>JANUARY</code>; the last depends on the number of months in a year.
1.204 + * @see #UCAL_JANUARY
1.205 + * @see #UCAL_FEBRUARY
1.206 + * @see #UCAL_MARCH
1.207 + * @see #UCAL_APRIL
1.208 + * @see #UCAL_MAY
1.209 + * @see #UCAL_JUNE
1.210 + * @see #UCAL_JULY
1.211 + * @see #UCAL_AUGUST
1.212 + * @see #UCAL_SEPTEMBER
1.213 + * @see #UCAL_OCTOBER
1.214 + * @see #UCAL_NOVEMBER
1.215 + * @see #UCAL_DECEMBER
1.216 + * @see #UCAL_UNDECIMBER
1.217 + * @stable ICU 2.6
1.218 + */
1.219 + UCAL_MONTH,
1.220 +
1.221 + /**
1.222 + * Field number indicating the
1.223 + * week number within the current year. The first week of the year, as
1.224 + * defined by <code>UCAL_FIRST_DAY_OF_WEEK</code> and <code>UCAL_MINIMAL_DAYS_IN_FIRST_WEEK</code>
1.225 + * attributes, has value 1. Subclasses define
1.226 + * the value of <code>UCAL_WEEK_OF_YEAR</code> for days before the first week of
1.227 + * the year.
1.228 + * @see ucal_getAttribute
1.229 + * @see ucal_setAttribute
1.230 + * @stable ICU 2.6
1.231 + */
1.232 + UCAL_WEEK_OF_YEAR,
1.233 +
1.234 + /**
1.235 + * Field number indicating the
1.236 + * week number within the current month. The first week of the month, as
1.237 + * defined by <code>UCAL_FIRST_DAY_OF_WEEK</code> and <code>UCAL_MINIMAL_DAYS_IN_FIRST_WEEK</code>
1.238 + * attributes, has value 1. Subclasses define
1.239 + * the value of <code>WEEK_OF_MONTH</code> for days before the first week of
1.240 + * the month.
1.241 + * @see ucal_getAttribute
1.242 + * @see ucal_setAttribute
1.243 + * @see #UCAL_FIRST_DAY_OF_WEEK
1.244 + * @see #UCAL_MINIMAL_DAYS_IN_FIRST_WEEK
1.245 + * @stable ICU 2.6
1.246 + */
1.247 + UCAL_WEEK_OF_MONTH,
1.248 +
1.249 + /**
1.250 + * Field number indicating the
1.251 + * day of the month. This is a synonym for <code>DAY_OF_MONTH</code>.
1.252 + * The first day of the month has value 1.
1.253 + * @see #UCAL_DAY_OF_MONTH
1.254 + * @stable ICU 2.6
1.255 + */
1.256 + UCAL_DATE,
1.257 +
1.258 + /**
1.259 + * Field number indicating the day
1.260 + * number within the current year. The first day of the year has value 1.
1.261 + * @stable ICU 2.6
1.262 + */
1.263 + UCAL_DAY_OF_YEAR,
1.264 +
1.265 + /**
1.266 + * Field number indicating the day
1.267 + * of the week. This field takes values <code>SUNDAY</code>,
1.268 + * <code>MONDAY</code>, <code>TUESDAY</code>, <code>WEDNESDAY</code>,
1.269 + * <code>THURSDAY</code>, <code>FRIDAY</code>, and <code>SATURDAY</code>.
1.270 + * @see #UCAL_SUNDAY
1.271 + * @see #UCAL_MONDAY
1.272 + * @see #UCAL_TUESDAY
1.273 + * @see #UCAL_WEDNESDAY
1.274 + * @see #UCAL_THURSDAY
1.275 + * @see #UCAL_FRIDAY
1.276 + * @see #UCAL_SATURDAY
1.277 + * @stable ICU 2.6
1.278 + */
1.279 + UCAL_DAY_OF_WEEK,
1.280 +
1.281 + /**
1.282 + * Field number indicating the
1.283 + * ordinal number of the day of the week within the current month. Together
1.284 + * with the <code>DAY_OF_WEEK</code> field, this uniquely specifies a day
1.285 + * within a month. Unlike <code>WEEK_OF_MONTH</code> and
1.286 + * <code>WEEK_OF_YEAR</code>, this field's value does <em>not</em> depend on
1.287 + * <code>getFirstDayOfWeek()</code> or
1.288 + * <code>getMinimalDaysInFirstWeek()</code>. <code>DAY_OF_MONTH 1</code>
1.289 + * through <code>7</code> always correspond to <code>DAY_OF_WEEK_IN_MONTH
1.290 + * 1</code>; <code>8</code> through <code>15</code> correspond to
1.291 + * <code>DAY_OF_WEEK_IN_MONTH 2</code>, and so on.
1.292 + * <code>DAY_OF_WEEK_IN_MONTH 0</code> indicates the week before
1.293 + * <code>DAY_OF_WEEK_IN_MONTH 1</code>. Negative values count back from the
1.294 + * end of the month, so the last Sunday of a month is specified as
1.295 + * <code>DAY_OF_WEEK = SUNDAY, DAY_OF_WEEK_IN_MONTH = -1</code>. Because
1.296 + * negative values count backward they will usually be aligned differently
1.297 + * within the month than positive values. For example, if a month has 31
1.298 + * days, <code>DAY_OF_WEEK_IN_MONTH -1</code> will overlap
1.299 + * <code>DAY_OF_WEEK_IN_MONTH 5</code> and the end of <code>4</code>.
1.300 + * @see #UCAL_DAY_OF_WEEK
1.301 + * @see #UCAL_WEEK_OF_MONTH
1.302 + * @stable ICU 2.6
1.303 + */
1.304 + UCAL_DAY_OF_WEEK_IN_MONTH,
1.305 +
1.306 + /**
1.307 + * Field number indicating
1.308 + * whether the <code>HOUR</code> is before or after noon.
1.309 + * E.g., at 10:04:15.250 PM the <code>AM_PM</code> is <code>PM</code>.
1.310 + * @see #UCAL_AM
1.311 + * @see #UCAL_PM
1.312 + * @see #UCAL_HOUR
1.313 + * @stable ICU 2.6
1.314 + */
1.315 + UCAL_AM_PM,
1.316 +
1.317 + /**
1.318 + * Field number indicating the
1.319 + * hour of the morning or afternoon. <code>HOUR</code> is used for the 12-hour
1.320 + * clock.
1.321 + * E.g., at 10:04:15.250 PM the <code>HOUR</code> is 10.
1.322 + * @see #UCAL_AM_PM
1.323 + * @see #UCAL_HOUR_OF_DAY
1.324 + * @stable ICU 2.6
1.325 + */
1.326 + UCAL_HOUR,
1.327 +
1.328 + /**
1.329 + * Field number indicating the
1.330 + * hour of the day. <code>HOUR_OF_DAY</code> is used for the 24-hour clock.
1.331 + * E.g., at 10:04:15.250 PM the <code>HOUR_OF_DAY</code> is 22.
1.332 + * @see #UCAL_HOUR
1.333 + * @stable ICU 2.6
1.334 + */
1.335 + UCAL_HOUR_OF_DAY,
1.336 +
1.337 + /**
1.338 + * Field number indicating the
1.339 + * minute within the hour.
1.340 + * E.g., at 10:04:15.250 PM the <code>UCAL_MINUTE</code> is 4.
1.341 + * @stable ICU 2.6
1.342 + */
1.343 + UCAL_MINUTE,
1.344 +
1.345 + /**
1.346 + * Field number indicating the
1.347 + * second within the minute.
1.348 + * E.g., at 10:04:15.250 PM the <code>UCAL_SECOND</code> is 15.
1.349 + * @stable ICU 2.6
1.350 + */
1.351 + UCAL_SECOND,
1.352 +
1.353 + /**
1.354 + * Field number indicating the
1.355 + * millisecond within the second.
1.356 + * E.g., at 10:04:15.250 PM the <code>UCAL_MILLISECOND</code> is 250.
1.357 + * @stable ICU 2.6
1.358 + */
1.359 + UCAL_MILLISECOND,
1.360 +
1.361 + /**
1.362 + * Field number indicating the
1.363 + * raw offset from GMT in milliseconds.
1.364 + * @stable ICU 2.6
1.365 + */
1.366 + UCAL_ZONE_OFFSET,
1.367 +
1.368 + /**
1.369 + * Field number indicating the
1.370 + * daylight savings offset in milliseconds.
1.371 + * @stable ICU 2.6
1.372 + */
1.373 + UCAL_DST_OFFSET,
1.374 +
1.375 + /**
1.376 + * Field number
1.377 + * indicating the extended year corresponding to the
1.378 + * <code>UCAL_WEEK_OF_YEAR</code> field. This may be one greater or less
1.379 + * than the value of <code>UCAL_EXTENDED_YEAR</code>.
1.380 + * @stable ICU 2.6
1.381 + */
1.382 + UCAL_YEAR_WOY,
1.383 +
1.384 + /**
1.385 + * Field number
1.386 + * indicating the localized day of week. This will be a value from 1
1.387 + * to 7 inclusive, with 1 being the localized first day of the week.
1.388 + * @stable ICU 2.6
1.389 + */
1.390 + UCAL_DOW_LOCAL,
1.391 +
1.392 + /**
1.393 + * Year of this calendar system, encompassing all supra-year fields. For example,
1.394 + * in Gregorian/Julian calendars, positive Extended Year values indicate years AD,
1.395 + * 1 BC = 0 extended, 2 BC = -1 extended, and so on.
1.396 + * @stable ICU 2.8
1.397 + */
1.398 + UCAL_EXTENDED_YEAR,
1.399 +
1.400 + /**
1.401 + * Field number
1.402 + * indicating the modified Julian day number. This is different from
1.403 + * the conventional Julian day number in two regards. First, it
1.404 + * demarcates days at local zone midnight, rather than noon GMT.
1.405 + * Second, it is a local number; that is, it depends on the local time
1.406 + * zone. It can be thought of as a single number that encompasses all
1.407 + * the date-related fields.
1.408 + * @stable ICU 2.8
1.409 + */
1.410 + UCAL_JULIAN_DAY,
1.411 +
1.412 + /**
1.413 + * Ranges from 0 to 23:59:59.999 (regardless of DST). This field behaves <em>exactly</em>
1.414 + * like a composite of all time-related fields, not including the zone fields. As such,
1.415 + * it also reflects discontinuities of those fields on DST transition days. On a day
1.416 + * of DST onset, it will jump forward. On a day of DST cessation, it will jump
1.417 + * backward. This reflects the fact that it must be combined with the DST_OFFSET field
1.418 + * to obtain a unique local time value.
1.419 + * @stable ICU 2.8
1.420 + */
1.421 + UCAL_MILLISECONDS_IN_DAY,
1.422 +
1.423 + /**
1.424 + * Whether or not the current month is a leap month (0 or 1). See the Chinese calendar for
1.425 + * an example of this.
1.426 + */
1.427 + UCAL_IS_LEAP_MONTH,
1.428 +
1.429 + /**
1.430 + * Field count
1.431 + * @stable ICU 2.6
1.432 + */
1.433 + UCAL_FIELD_COUNT,
1.434 +
1.435 + /**
1.436 + * Field number indicating the
1.437 + * day of the month. This is a synonym for <code>UCAL_DATE</code>.
1.438 + * The first day of the month has value 1.
1.439 + * @see #UCAL_DATE
1.440 + * Synonym for UCAL_DATE
1.441 + * @stable ICU 2.8
1.442 + **/
1.443 + UCAL_DAY_OF_MONTH=UCAL_DATE
1.444 +};
1.445 +
1.446 +/** @stable ICU 2.0 */
1.447 +typedef enum UCalendarDateFields UCalendarDateFields;
1.448 + /**
1.449 + * Useful constant for days of week. Note: Calendar day-of-week is 1-based. Clients
1.450 + * who create locale resources for the field of first-day-of-week should be aware of
1.451 + * this. For instance, in US locale, first-day-of-week is set to 1, i.e., UCAL_SUNDAY.
1.452 + */
1.453 +/** Possible days of the week in a UCalendar
1.454 + * @stable ICU 2.0
1.455 + */
1.456 +enum UCalendarDaysOfWeek {
1.457 + /** Sunday */
1.458 + UCAL_SUNDAY = 1,
1.459 + /** Monday */
1.460 + UCAL_MONDAY,
1.461 + /** Tuesday */
1.462 + UCAL_TUESDAY,
1.463 + /** Wednesday */
1.464 + UCAL_WEDNESDAY,
1.465 + /** Thursday */
1.466 + UCAL_THURSDAY,
1.467 + /** Friday */
1.468 + UCAL_FRIDAY,
1.469 + /** Saturday */
1.470 + UCAL_SATURDAY
1.471 +};
1.472 +
1.473 +/** @stable ICU 2.0 */
1.474 +typedef enum UCalendarDaysOfWeek UCalendarDaysOfWeek;
1.475 +
1.476 +/** Possible months in a UCalendar. Note: Calendar month is 0-based.
1.477 + * @stable ICU 2.0
1.478 + */
1.479 +enum UCalendarMonths {
1.480 + /** January */
1.481 + UCAL_JANUARY,
1.482 + /** February */
1.483 + UCAL_FEBRUARY,
1.484 + /** March */
1.485 + UCAL_MARCH,
1.486 + /** April */
1.487 + UCAL_APRIL,
1.488 + /** May */
1.489 + UCAL_MAY,
1.490 + /** June */
1.491 + UCAL_JUNE,
1.492 + /** July */
1.493 + UCAL_JULY,
1.494 + /** August */
1.495 + UCAL_AUGUST,
1.496 + /** September */
1.497 + UCAL_SEPTEMBER,
1.498 + /** October */
1.499 + UCAL_OCTOBER,
1.500 + /** November */
1.501 + UCAL_NOVEMBER,
1.502 + /** December */
1.503 + UCAL_DECEMBER,
1.504 + /** Value of the <code>UCAL_MONTH</code> field indicating the
1.505 + * thirteenth month of the year. Although the Gregorian calendar
1.506 + * does not use this value, lunar calendars do.
1.507 + */
1.508 + UCAL_UNDECIMBER
1.509 +};
1.510 +
1.511 +/** @stable ICU 2.0 */
1.512 +typedef enum UCalendarMonths UCalendarMonths;
1.513 +
1.514 +/** Possible AM/PM values in a UCalendar
1.515 + * @stable ICU 2.0
1.516 + */
1.517 +enum UCalendarAMPMs {
1.518 + /** AM */
1.519 + UCAL_AM,
1.520 + /** PM */
1.521 + UCAL_PM
1.522 +};
1.523 +
1.524 +/** @stable ICU 2.0 */
1.525 +typedef enum UCalendarAMPMs UCalendarAMPMs;
1.526 +
1.527 +/**
1.528 + * System time zone type constants used by filtering zones
1.529 + * in ucal_openTimeZoneIDEnumeration.
1.530 + * @see ucal_openTimeZoneIDEnumeration
1.531 + * @stable ICU 4.8
1.532 + */
1.533 +enum USystemTimeZoneType {
1.534 + /**
1.535 + * Any system zones.
1.536 + * @stable ICU 4.8
1.537 + */
1.538 + UCAL_ZONE_TYPE_ANY,
1.539 + /**
1.540 + * Canonical system zones.
1.541 + * @stable ICU 4.8
1.542 + */
1.543 + UCAL_ZONE_TYPE_CANONICAL,
1.544 + /**
1.545 + * Canonical system zones associated with actual locations.
1.546 + * @stable ICU 4.8
1.547 + */
1.548 + UCAL_ZONE_TYPE_CANONICAL_LOCATION
1.549 +};
1.550 +
1.551 +/** @stable ICU 4.8 */
1.552 +typedef enum USystemTimeZoneType USystemTimeZoneType;
1.553 +
1.554 +/**
1.555 + * Create an enumeration over system time zone IDs with the given
1.556 + * filter conditions.
1.557 + * @param zoneType The system time zone type.
1.558 + * @param region The ISO 3166 two-letter country code or UN M.49
1.559 + * three-digit area code. When NULL, no filtering
1.560 + * done by region.
1.561 + * @param rawOffset An offset from GMT in milliseconds, ignoring the
1.562 + * effect of daylight savings time, if any. When NULL,
1.563 + * no filtering done by zone offset.
1.564 + * @param ec A pointer to an UErrorCode to receive any errors
1.565 + * @return an enumeration object that the caller must dispose of
1.566 + * using enum_close(), or NULL upon failure. In case of failure,
1.567 + * *ec will indicate the error.
1.568 + * @stable ICU 4.8
1.569 + */
1.570 +U_STABLE UEnumeration* U_EXPORT2
1.571 +ucal_openTimeZoneIDEnumeration(USystemTimeZoneType zoneType, const char* region,
1.572 + const int32_t* rawOffset, UErrorCode* ec);
1.573 +
1.574 +/**
1.575 + * Create an enumeration over all time zones.
1.576 + *
1.577 + * @param ec input/output error code
1.578 + *
1.579 + * @return an enumeration object that the caller must dispose of using
1.580 + * uenum_close(), or NULL upon failure. In case of failure *ec will
1.581 + * indicate the error.
1.582 + *
1.583 + * @stable ICU 2.6
1.584 + */
1.585 +U_STABLE UEnumeration* U_EXPORT2
1.586 +ucal_openTimeZones(UErrorCode* ec);
1.587 +
1.588 +/**
1.589 + * Create an enumeration over all time zones associated with the given
1.590 + * country. Some zones are affiliated with no country (e.g., "UTC");
1.591 + * these may also be retrieved, as a group.
1.592 + *
1.593 + * @param country the ISO 3166 two-letter country code, or NULL to
1.594 + * retrieve zones not affiliated with any country
1.595 + *
1.596 + * @param ec input/output error code
1.597 + *
1.598 + * @return an enumeration object that the caller must dispose of using
1.599 + * uenum_close(), or NULL upon failure. In case of failure *ec will
1.600 + * indicate the error.
1.601 + *
1.602 + * @stable ICU 2.6
1.603 + */
1.604 +U_STABLE UEnumeration* U_EXPORT2
1.605 +ucal_openCountryTimeZones(const char* country, UErrorCode* ec);
1.606 +
1.607 +/**
1.608 + * Return the default time zone. The default is determined initially
1.609 + * by querying the host operating system. It may be changed with
1.610 + * ucal_setDefaultTimeZone() or with the C++ TimeZone API.
1.611 + *
1.612 + * @param result A buffer to receive the result, or NULL
1.613 + *
1.614 + * @param resultCapacity The capacity of the result buffer
1.615 + *
1.616 + * @param ec input/output error code
1.617 + *
1.618 + * @return The result string length, not including the terminating
1.619 + * null
1.620 + *
1.621 + * @stable ICU 2.6
1.622 + */
1.623 +U_STABLE int32_t U_EXPORT2
1.624 +ucal_getDefaultTimeZone(UChar* result, int32_t resultCapacity, UErrorCode* ec);
1.625 +
1.626 +/**
1.627 + * Set the default time zone.
1.628 + *
1.629 + * @param zoneID null-terminated time zone ID
1.630 + *
1.631 + * @param ec input/output error code
1.632 + *
1.633 + * @stable ICU 2.6
1.634 + */
1.635 +U_STABLE void U_EXPORT2
1.636 +ucal_setDefaultTimeZone(const UChar* zoneID, UErrorCode* ec);
1.637 +
1.638 +/**
1.639 + * Return the amount of time in milliseconds that the clock is
1.640 + * advanced during daylight savings time for the given time zone, or
1.641 + * zero if the time zone does not observe daylight savings time.
1.642 + *
1.643 + * @param zoneID null-terminated time zone ID
1.644 + *
1.645 + * @param ec input/output error code
1.646 + *
1.647 + * @return the number of milliseconds the time is advanced with
1.648 + * respect to standard time when the daylight savings rules are in
1.649 + * effect. This is always a non-negative number, most commonly either
1.650 + * 3,600,000 (one hour) or zero.
1.651 + *
1.652 + * @stable ICU 2.6
1.653 + */
1.654 +U_STABLE int32_t U_EXPORT2
1.655 +ucal_getDSTSavings(const UChar* zoneID, UErrorCode* ec);
1.656 +
1.657 +/**
1.658 + * Get the current date and time.
1.659 + * The value returned is represented as milliseconds from the epoch.
1.660 + * @return The current date and time.
1.661 + * @stable ICU 2.0
1.662 + */
1.663 +U_STABLE UDate U_EXPORT2
1.664 +ucal_getNow(void);
1.665 +
1.666 +/**
1.667 + * Open a UCalendar.
1.668 + * A UCalendar may be used to convert a millisecond value to a year,
1.669 + * month, and day.
1.670 + * <p>
1.671 + * Note: When unknown TimeZone ID is specified or if the TimeZone ID specified is "Etc/Unknown",
1.672 + * the UCalendar returned by the function is initialized with GMT zone with TimeZone ID
1.673 + * <code>UCAL_UNKNOWN_ZONE_ID</code> ("Etc/Unknown") without any errors/warnings. If you want
1.674 + * to check if a TimeZone ID is valid prior to this function, use <code>ucal_getCanonicalTimeZoneID</code>.
1.675 + *
1.676 + * @param zoneID The desired TimeZone ID. If 0, use the default time zone.
1.677 + * @param len The length of zoneID, or -1 if null-terminated.
1.678 + * @param locale The desired locale
1.679 + * @param type The type of UCalendar to open. This can be UCAL_GREGORIAN to open the Gregorian
1.680 + * calendar for the locale, or UCAL_DEFAULT to open the default calendar for the locale (the
1.681 + * default calendar may also be Gregorian). To open a specific non-Gregorian calendar for the
1.682 + * locale, use uloc_setKeywordValue to set the value of the calendar keyword for the locale
1.683 + * and then pass the locale to ucal_open with UCAL_DEFAULT as the type.
1.684 + * @param status A pointer to an UErrorCode to receive any errors
1.685 + * @return A pointer to a UCalendar, or 0 if an error occurred.
1.686 + * @see #UCAL_UNKNOWN_ZONE_ID
1.687 + * @stable ICU 2.0
1.688 + */
1.689 +U_STABLE UCalendar* U_EXPORT2
1.690 +ucal_open(const UChar* zoneID,
1.691 + int32_t len,
1.692 + const char* locale,
1.693 + UCalendarType type,
1.694 + UErrorCode* status);
1.695 +
1.696 +/**
1.697 + * Close a UCalendar.
1.698 + * Once closed, a UCalendar may no longer be used.
1.699 + * @param cal The UCalendar to close.
1.700 + * @stable ICU 2.0
1.701 + */
1.702 +U_STABLE void U_EXPORT2
1.703 +ucal_close(UCalendar *cal);
1.704 +
1.705 +#if U_SHOW_CPLUSPLUS_API
1.706 +
1.707 +U_NAMESPACE_BEGIN
1.708 +
1.709 +/**
1.710 + * \class LocalUCalendarPointer
1.711 + * "Smart pointer" class, closes a UCalendar via ucal_close().
1.712 + * For most methods see the LocalPointerBase base class.
1.713 + *
1.714 + * @see LocalPointerBase
1.715 + * @see LocalPointer
1.716 + * @stable ICU 4.4
1.717 + */
1.718 +U_DEFINE_LOCAL_OPEN_POINTER(LocalUCalendarPointer, UCalendar, ucal_close);
1.719 +
1.720 +U_NAMESPACE_END
1.721 +
1.722 +#endif
1.723 +
1.724 +/**
1.725 + * Open a copy of a UCalendar.
1.726 + * This function performs a deep copy.
1.727 + * @param cal The calendar to copy
1.728 + * @param status A pointer to an UErrorCode to receive any errors.
1.729 + * @return A pointer to a UCalendar identical to cal.
1.730 + * @stable ICU 4.0
1.731 + */
1.732 +U_STABLE UCalendar* U_EXPORT2
1.733 +ucal_clone(const UCalendar* cal,
1.734 + UErrorCode* status);
1.735 +
1.736 +/**
1.737 + * Set the TimeZone used by a UCalendar.
1.738 + * A UCalendar uses a timezone for converting from Greenwich time to local time.
1.739 + * @param cal The UCalendar to set.
1.740 + * @param zoneID The desired TimeZone ID. If 0, use the default time zone.
1.741 + * @param len The length of zoneID, or -1 if null-terminated.
1.742 + * @param status A pointer to an UErrorCode to receive any errors.
1.743 + * @stable ICU 2.0
1.744 + */
1.745 +U_STABLE void U_EXPORT2
1.746 +ucal_setTimeZone(UCalendar* cal,
1.747 + const UChar* zoneID,
1.748 + int32_t len,
1.749 + UErrorCode* status);
1.750 +
1.751 +#ifndef U_HIDE_DRAFT_API
1.752 +/**
1.753 + * Get the ID of the UCalendar's time zone.
1.754 + *
1.755 + * @param cal The UCalendar to query.
1.756 + * @param result Receives the UCalendar's time zone ID.
1.757 + * @param resultLength The maximum size of result.
1.758 + * @param status Receives the status.
1.759 + * @return The total buffer size needed; if greater than resultLength, the output was truncated.
1.760 + * @draft ICU 51
1.761 + */
1.762 +U_DRAFT int32_t U_EXPORT2
1.763 +ucal_getTimeZoneID(const UCalendar *cal,
1.764 + UChar *result,
1.765 + int32_t resultLength,
1.766 + UErrorCode *status);
1.767 +#endif /* U_HIDE_DRAFT_API */
1.768 +
1.769 +/**
1.770 + * Possible formats for a UCalendar's display name
1.771 + * @stable ICU 2.0
1.772 + */
1.773 +enum UCalendarDisplayNameType {
1.774 + /** Standard display name */
1.775 + UCAL_STANDARD,
1.776 + /** Short standard display name */
1.777 + UCAL_SHORT_STANDARD,
1.778 + /** Daylight savings display name */
1.779 + UCAL_DST,
1.780 + /** Short daylight savings display name */
1.781 + UCAL_SHORT_DST
1.782 +};
1.783 +
1.784 +/** @stable ICU 2.0 */
1.785 +typedef enum UCalendarDisplayNameType UCalendarDisplayNameType;
1.786 +
1.787 +/**
1.788 + * Get the display name for a UCalendar's TimeZone.
1.789 + * A display name is suitable for presentation to a user.
1.790 + * @param cal The UCalendar to query.
1.791 + * @param type The desired display name format; one of UCAL_STANDARD, UCAL_SHORT_STANDARD,
1.792 + * UCAL_DST, UCAL_SHORT_DST
1.793 + * @param locale The desired locale for the display name.
1.794 + * @param result A pointer to a buffer to receive the formatted number.
1.795 + * @param resultLength The maximum size of result.
1.796 + * @param status A pointer to an UErrorCode to receive any errors
1.797 + * @return The total buffer size needed; if greater than resultLength, the output was truncated.
1.798 + * @stable ICU 2.0
1.799 + */
1.800 +U_STABLE int32_t U_EXPORT2
1.801 +ucal_getTimeZoneDisplayName(const UCalendar* cal,
1.802 + UCalendarDisplayNameType type,
1.803 + const char* locale,
1.804 + UChar* result,
1.805 + int32_t resultLength,
1.806 + UErrorCode* status);
1.807 +
1.808 +/**
1.809 + * Determine if a UCalendar is currently in daylight savings time.
1.810 + * Daylight savings time is not used in all parts of the world.
1.811 + * @param cal The UCalendar to query.
1.812 + * @param status A pointer to an UErrorCode to receive any errors
1.813 + * @return TRUE if cal is currently in daylight savings time, FALSE otherwise
1.814 + * @stable ICU 2.0
1.815 + */
1.816 +U_STABLE UBool U_EXPORT2
1.817 +ucal_inDaylightTime(const UCalendar* cal,
1.818 + UErrorCode* status );
1.819 +
1.820 +/**
1.821 + * Sets the GregorianCalendar change date. This is the point when the switch from
1.822 + * Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October
1.823 + * 15, 1582. Previous to this time and date will be Julian dates.
1.824 + *
1.825 + * This function works only for Gregorian calendars. If the UCalendar is not
1.826 + * an instance of a Gregorian calendar, then a U_UNSUPPORTED_ERROR
1.827 + * error code is set.
1.828 + *
1.829 + * @param cal The calendar object.
1.830 + * @param date The given Gregorian cutover date.
1.831 + * @param pErrorCode Pointer to a standard ICU error code. Its input value must
1.832 + * pass the U_SUCCESS() test, or else the function returns
1.833 + * immediately. Check for U_FAILURE() on output or use with
1.834 + * function chaining. (See User Guide for details.)
1.835 + *
1.836 + * @see GregorianCalendar::setGregorianChange
1.837 + * @see ucal_getGregorianChange
1.838 + * @stable ICU 3.6
1.839 + */
1.840 +U_STABLE void U_EXPORT2
1.841 +ucal_setGregorianChange(UCalendar *cal, UDate date, UErrorCode *pErrorCode);
1.842 +
1.843 +/**
1.844 + * Gets the Gregorian Calendar change date. This is the point when the switch from
1.845 + * Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October
1.846 + * 15, 1582. Previous to this time and date will be Julian dates.
1.847 + *
1.848 + * This function works only for Gregorian calendars. If the UCalendar is not
1.849 + * an instance of a Gregorian calendar, then a U_UNSUPPORTED_ERROR
1.850 + * error code is set.
1.851 + *
1.852 + * @param cal The calendar object.
1.853 + * @param pErrorCode Pointer to a standard ICU error code. Its input value must
1.854 + * pass the U_SUCCESS() test, or else the function returns
1.855 + * immediately. Check for U_FAILURE() on output or use with
1.856 + * function chaining. (See User Guide for details.)
1.857 + * @return The Gregorian cutover time for this calendar.
1.858 + *
1.859 + * @see GregorianCalendar::getGregorianChange
1.860 + * @see ucal_setGregorianChange
1.861 + * @stable ICU 3.6
1.862 + */
1.863 +U_STABLE UDate U_EXPORT2
1.864 +ucal_getGregorianChange(const UCalendar *cal, UErrorCode *pErrorCode);
1.865 +
1.866 +/**
1.867 + * Types of UCalendar attributes
1.868 + * @stable ICU 2.0
1.869 + */
1.870 +enum UCalendarAttribute {
1.871 + /**
1.872 + * Lenient parsing
1.873 + * @stable ICU 2.0
1.874 + */
1.875 + UCAL_LENIENT,
1.876 + /**
1.877 + * First day of week
1.878 + * @stable ICU 2.0
1.879 + */
1.880 + UCAL_FIRST_DAY_OF_WEEK,
1.881 + /**
1.882 + * Minimum number of days in first week
1.883 + * @stable ICU 2.0
1.884 + */
1.885 + UCAL_MINIMAL_DAYS_IN_FIRST_WEEK,
1.886 + /**
1.887 + * The behavior for handling wall time repeating multiple times
1.888 + * at negative time zone offset transitions
1.889 + * @stable ICU 49
1.890 + */
1.891 + UCAL_REPEATED_WALL_TIME,
1.892 + /**
1.893 + * The behavior for handling skipped wall time at positive time
1.894 + * zone offset transitions.
1.895 + * @stable ICU 49
1.896 + */
1.897 + UCAL_SKIPPED_WALL_TIME
1.898 +};
1.899 +
1.900 +/** @stable ICU 2.0 */
1.901 +typedef enum UCalendarAttribute UCalendarAttribute;
1.902 +
1.903 +/**
1.904 + * Options for handling ambiguous wall time at time zone
1.905 + * offset transitions.
1.906 + * @stable ICU 49
1.907 + */
1.908 +enum UCalendarWallTimeOption {
1.909 + /**
1.910 + * An ambiguous wall time to be interpreted as the latest.
1.911 + * This option is valid for UCAL_REPEATED_WALL_TIME and
1.912 + * UCAL_SKIPPED_WALL_TIME.
1.913 + * @stable ICU 49
1.914 + */
1.915 + UCAL_WALLTIME_LAST,
1.916 + /**
1.917 + * An ambiguous wall time to be interpreted as the earliest.
1.918 + * This option is valid for UCAL_REPEATED_WALL_TIME and
1.919 + * UCAL_SKIPPED_WALL_TIME.
1.920 + * @stable ICU 49
1.921 + */
1.922 + UCAL_WALLTIME_FIRST,
1.923 + /**
1.924 + * An ambiguous wall time to be interpreted as the next valid
1.925 + * wall time. This option is valid for UCAL_SKIPPED_WALL_TIME.
1.926 + * @stable ICU 49
1.927 + */
1.928 + UCAL_WALLTIME_NEXT_VALID
1.929 +};
1.930 +/** @stable ICU 49 */
1.931 +typedef enum UCalendarWallTimeOption UCalendarWallTimeOption;
1.932 +
1.933 +/**
1.934 + * Get a numeric attribute associated with a UCalendar.
1.935 + * Numeric attributes include the first day of the week, or the minimal numbers
1.936 + * of days in the first week of the month.
1.937 + * @param cal The UCalendar to query.
1.938 + * @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK,
1.939 + * UCAL_MINIMAL_DAYS_IN_FIRST_WEEK, UCAL_REPEATED_WALL_TIME or UCAL_SKIPPED_WALL_TIME
1.940 + * @return The value of attr.
1.941 + * @see ucal_setAttribute
1.942 + * @stable ICU 2.0
1.943 + */
1.944 +U_STABLE int32_t U_EXPORT2
1.945 +ucal_getAttribute(const UCalendar* cal,
1.946 + UCalendarAttribute attr);
1.947 +
1.948 +/**
1.949 + * Set a numeric attribute associated with a UCalendar.
1.950 + * Numeric attributes include the first day of the week, or the minimal numbers
1.951 + * of days in the first week of the month.
1.952 + * @param cal The UCalendar to set.
1.953 + * @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK,
1.954 + * UCAL_MINIMAL_DAYS_IN_FIRST_WEEK, UCAL_REPEATED_WALL_TIME or UCAL_SKIPPED_WALL_TIME
1.955 + * @param newValue The new value of attr.
1.956 + * @see ucal_getAttribute
1.957 + * @stable ICU 2.0
1.958 + */
1.959 +U_STABLE void U_EXPORT2
1.960 +ucal_setAttribute(UCalendar* cal,
1.961 + UCalendarAttribute attr,
1.962 + int32_t newValue);
1.963 +
1.964 +/**
1.965 + * Get a locale for which calendars are available.
1.966 + * A UCalendar in a locale returned by this function will contain the correct
1.967 + * day and month names for the locale.
1.968 + * @param localeIndex The index of the desired locale.
1.969 + * @return A locale for which calendars are available, or 0 if none.
1.970 + * @see ucal_countAvailable
1.971 + * @stable ICU 2.0
1.972 + */
1.973 +U_STABLE const char* U_EXPORT2
1.974 +ucal_getAvailable(int32_t localeIndex);
1.975 +
1.976 +/**
1.977 + * Determine how many locales have calendars available.
1.978 + * This function is most useful as determining the loop ending condition for
1.979 + * calls to \ref ucal_getAvailable.
1.980 + * @return The number of locales for which calendars are available.
1.981 + * @see ucal_getAvailable
1.982 + * @stable ICU 2.0
1.983 + */
1.984 +U_STABLE int32_t U_EXPORT2
1.985 +ucal_countAvailable(void);
1.986 +
1.987 +/**
1.988 + * Get a UCalendar's current time in millis.
1.989 + * The time is represented as milliseconds from the epoch.
1.990 + * @param cal The UCalendar to query.
1.991 + * @param status A pointer to an UErrorCode to receive any errors
1.992 + * @return The calendar's current time in millis.
1.993 + * @see ucal_setMillis
1.994 + * @see ucal_setDate
1.995 + * @see ucal_setDateTime
1.996 + * @stable ICU 2.0
1.997 + */
1.998 +U_STABLE UDate U_EXPORT2
1.999 +ucal_getMillis(const UCalendar* cal,
1.1000 + UErrorCode* status);
1.1001 +
1.1002 +/**
1.1003 + * Set a UCalendar's current time in millis.
1.1004 + * The time is represented as milliseconds from the epoch.
1.1005 + * @param cal The UCalendar to set.
1.1006 + * @param dateTime The desired date and time.
1.1007 + * @param status A pointer to an UErrorCode to receive any errors
1.1008 + * @see ucal_getMillis
1.1009 + * @see ucal_setDate
1.1010 + * @see ucal_setDateTime
1.1011 + * @stable ICU 2.0
1.1012 + */
1.1013 +U_STABLE void U_EXPORT2
1.1014 +ucal_setMillis(UCalendar* cal,
1.1015 + UDate dateTime,
1.1016 + UErrorCode* status );
1.1017 +
1.1018 +/**
1.1019 + * Set a UCalendar's current date.
1.1020 + * The date is represented as a series of 32-bit integers.
1.1021 + * @param cal The UCalendar to set.
1.1022 + * @param year The desired year.
1.1023 + * @param month The desired month; one of UCAL_JANUARY, UCAL_FEBRUARY, UCAL_MARCH, UCAL_APRIL, UCAL_MAY,
1.1024 + * UCAL_JUNE, UCAL_JULY, UCAL_AUGUST, UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBER, UCAL_DECEMBER, UCAL_UNDECIMBER
1.1025 + * @param date The desired day of the month.
1.1026 + * @param status A pointer to an UErrorCode to receive any errors
1.1027 + * @see ucal_getMillis
1.1028 + * @see ucal_setMillis
1.1029 + * @see ucal_setDateTime
1.1030 + * @stable ICU 2.0
1.1031 + */
1.1032 +U_STABLE void U_EXPORT2
1.1033 +ucal_setDate(UCalendar* cal,
1.1034 + int32_t year,
1.1035 + int32_t month,
1.1036 + int32_t date,
1.1037 + UErrorCode* status);
1.1038 +
1.1039 +/**
1.1040 + * Set a UCalendar's current date.
1.1041 + * The date is represented as a series of 32-bit integers.
1.1042 + * @param cal The UCalendar to set.
1.1043 + * @param year The desired year.
1.1044 + * @param month The desired month; one of UCAL_JANUARY, UCAL_FEBRUARY, UCAL_MARCH, UCAL_APRIL, UCAL_MAY,
1.1045 + * UCAL_JUNE, UCAL_JULY, UCAL_AUGUST, UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBER, UCAL_DECEMBER, UCAL_UNDECIMBER
1.1046 + * @param date The desired day of the month.
1.1047 + * @param hour The desired hour of day.
1.1048 + * @param minute The desired minute.
1.1049 + * @param second The desirec second.
1.1050 + * @param status A pointer to an UErrorCode to receive any errors
1.1051 + * @see ucal_getMillis
1.1052 + * @see ucal_setMillis
1.1053 + * @see ucal_setDate
1.1054 + * @stable ICU 2.0
1.1055 + */
1.1056 +U_STABLE void U_EXPORT2
1.1057 +ucal_setDateTime(UCalendar* cal,
1.1058 + int32_t year,
1.1059 + int32_t month,
1.1060 + int32_t date,
1.1061 + int32_t hour,
1.1062 + int32_t minute,
1.1063 + int32_t second,
1.1064 + UErrorCode* status);
1.1065 +
1.1066 +/**
1.1067 + * Returns TRUE if two UCalendars are equivalent. Equivalent
1.1068 + * UCalendars will behave identically, but they may be set to
1.1069 + * different times.
1.1070 + * @param cal1 The first of the UCalendars to compare.
1.1071 + * @param cal2 The second of the UCalendars to compare.
1.1072 + * @return TRUE if cal1 and cal2 are equivalent, FALSE otherwise.
1.1073 + * @stable ICU 2.0
1.1074 + */
1.1075 +U_STABLE UBool U_EXPORT2
1.1076 +ucal_equivalentTo(const UCalendar* cal1,
1.1077 + const UCalendar* cal2);
1.1078 +
1.1079 +/**
1.1080 + * Add a specified signed amount to a particular field in a UCalendar.
1.1081 + * This can modify more significant fields in the calendar.
1.1082 + * Adding a positive value always means moving forward in time, so for the Gregorian calendar,
1.1083 + * starting with 100 BC and adding +1 to year results in 99 BC (even though this actually reduces
1.1084 + * the numeric value of the field itself).
1.1085 + * @param cal The UCalendar to which to add.
1.1086 + * @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
1.1087 + * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
1.1088 + * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
1.1089 + * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
1.1090 + * @param amount The signed amount to add to field. If the amount causes the value
1.1091 + * to exceed to maximum or minimum values for that field, other fields are modified
1.1092 + * to preserve the magnitude of the change.
1.1093 + * @param status A pointer to an UErrorCode to receive any errors
1.1094 + * @see ucal_roll
1.1095 + * @stable ICU 2.0
1.1096 + */
1.1097 +U_STABLE void U_EXPORT2
1.1098 +ucal_add(UCalendar* cal,
1.1099 + UCalendarDateFields field,
1.1100 + int32_t amount,
1.1101 + UErrorCode* status);
1.1102 +
1.1103 +/**
1.1104 + * Add a specified signed amount to a particular field in a UCalendar.
1.1105 + * This will not modify more significant fields in the calendar.
1.1106 + * Rolling by a positive value always means moving forward in time (unless the limit of the
1.1107 + * field is reached, in which case it may pin or wrap), so for Gregorian calendar,
1.1108 + * starting with 100 BC and rolling the year by +1 results in 99 BC.
1.1109 + * When eras have a definite beginning and end (as in the Chinese calendar, or as in most eras in the
1.1110 + * Japanese calendar) then rolling the year past either limit of the era will cause the year to wrap around.
1.1111 + * When eras only have a limit at one end, then attempting to roll the year past that limit will result in
1.1112 + * pinning the year at that limit. Note that for most calendars in which era 0 years move forward in time
1.1113 + * (such as Buddhist, Hebrew, or Islamic), it is possible for add or roll to result in negative years for
1.1114 + * era 0 (that is the only way to represent years before the calendar epoch).
1.1115 + * @param cal The UCalendar to which to add.
1.1116 + * @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
1.1117 + * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
1.1118 + * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
1.1119 + * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
1.1120 + * @param amount The signed amount to add to field. If the amount causes the value
1.1121 + * to exceed to maximum or minimum values for that field, the field is pinned to a permissible
1.1122 + * value.
1.1123 + * @param status A pointer to an UErrorCode to receive any errors
1.1124 + * @see ucal_add
1.1125 + * @stable ICU 2.0
1.1126 + */
1.1127 +U_STABLE void U_EXPORT2
1.1128 +ucal_roll(UCalendar* cal,
1.1129 + UCalendarDateFields field,
1.1130 + int32_t amount,
1.1131 + UErrorCode* status);
1.1132 +
1.1133 +/**
1.1134 + * Get the current value of a field from a UCalendar.
1.1135 + * All fields are represented as 32-bit integers.
1.1136 + * @param cal The UCalendar to query.
1.1137 + * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
1.1138 + * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
1.1139 + * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
1.1140 + * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
1.1141 + * @param status A pointer to an UErrorCode to receive any errors
1.1142 + * @return The value of the desired field.
1.1143 + * @see ucal_set
1.1144 + * @see ucal_isSet
1.1145 + * @see ucal_clearField
1.1146 + * @see ucal_clear
1.1147 + * @stable ICU 2.0
1.1148 + */
1.1149 +U_STABLE int32_t U_EXPORT2
1.1150 +ucal_get(const UCalendar* cal,
1.1151 + UCalendarDateFields field,
1.1152 + UErrorCode* status );
1.1153 +
1.1154 +/**
1.1155 + * Set the value of a field in a UCalendar.
1.1156 + * All fields are represented as 32-bit integers.
1.1157 + * @param cal The UCalendar to set.
1.1158 + * @param field The field to set; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
1.1159 + * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
1.1160 + * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
1.1161 + * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
1.1162 + * @param value The desired value of field.
1.1163 + * @see ucal_get
1.1164 + * @see ucal_isSet
1.1165 + * @see ucal_clearField
1.1166 + * @see ucal_clear
1.1167 + * @stable ICU 2.0
1.1168 + */
1.1169 +U_STABLE void U_EXPORT2
1.1170 +ucal_set(UCalendar* cal,
1.1171 + UCalendarDateFields field,
1.1172 + int32_t value);
1.1173 +
1.1174 +/**
1.1175 + * Determine if a field in a UCalendar is set.
1.1176 + * All fields are represented as 32-bit integers.
1.1177 + * @param cal The UCalendar to query.
1.1178 + * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
1.1179 + * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
1.1180 + * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
1.1181 + * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
1.1182 + * @return TRUE if field is set, FALSE otherwise.
1.1183 + * @see ucal_get
1.1184 + * @see ucal_set
1.1185 + * @see ucal_clearField
1.1186 + * @see ucal_clear
1.1187 + * @stable ICU 2.0
1.1188 + */
1.1189 +U_STABLE UBool U_EXPORT2
1.1190 +ucal_isSet(const UCalendar* cal,
1.1191 + UCalendarDateFields field);
1.1192 +
1.1193 +/**
1.1194 + * Clear a field in a UCalendar.
1.1195 + * All fields are represented as 32-bit integers.
1.1196 + * @param cal The UCalendar containing the field to clear.
1.1197 + * @param field The field to clear; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
1.1198 + * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
1.1199 + * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
1.1200 + * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
1.1201 + * @see ucal_get
1.1202 + * @see ucal_set
1.1203 + * @see ucal_isSet
1.1204 + * @see ucal_clear
1.1205 + * @stable ICU 2.0
1.1206 + */
1.1207 +U_STABLE void U_EXPORT2
1.1208 +ucal_clearField(UCalendar* cal,
1.1209 + UCalendarDateFields field);
1.1210 +
1.1211 +/**
1.1212 + * Clear all fields in a UCalendar.
1.1213 + * All fields are represented as 32-bit integers.
1.1214 + * @param calendar The UCalendar to clear.
1.1215 + * @see ucal_get
1.1216 + * @see ucal_set
1.1217 + * @see ucal_isSet
1.1218 + * @see ucal_clearField
1.1219 + * @stable ICU 2.0
1.1220 + */
1.1221 +U_STABLE void U_EXPORT2
1.1222 +ucal_clear(UCalendar* calendar);
1.1223 +
1.1224 +/**
1.1225 + * Possible limit values for a UCalendar
1.1226 + * @stable ICU 2.0
1.1227 + */
1.1228 +enum UCalendarLimitType {
1.1229 + /** Minimum value */
1.1230 + UCAL_MINIMUM,
1.1231 + /** Maximum value */
1.1232 + UCAL_MAXIMUM,
1.1233 + /** Greatest minimum value */
1.1234 + UCAL_GREATEST_MINIMUM,
1.1235 + /** Leaest maximum value */
1.1236 + UCAL_LEAST_MAXIMUM,
1.1237 + /** Actual minimum value */
1.1238 + UCAL_ACTUAL_MINIMUM,
1.1239 + /** Actual maximum value */
1.1240 + UCAL_ACTUAL_MAXIMUM
1.1241 +};
1.1242 +
1.1243 +/** @stable ICU 2.0 */
1.1244 +typedef enum UCalendarLimitType UCalendarLimitType;
1.1245 +
1.1246 +/**
1.1247 + * Determine a limit for a field in a UCalendar.
1.1248 + * A limit is a maximum or minimum value for a field.
1.1249 + * @param cal The UCalendar to query.
1.1250 + * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
1.1251 + * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
1.1252 + * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
1.1253 + * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
1.1254 + * @param type The desired critical point; one of UCAL_MINIMUM, UCAL_MAXIMUM, UCAL_GREATEST_MINIMUM,
1.1255 + * UCAL_LEAST_MAXIMUM, UCAL_ACTUAL_MINIMUM, UCAL_ACTUAL_MAXIMUM
1.1256 + * @param status A pointer to an UErrorCode to receive any errors.
1.1257 + * @return The requested value.
1.1258 + * @stable ICU 2.0
1.1259 + */
1.1260 +U_STABLE int32_t U_EXPORT2
1.1261 +ucal_getLimit(const UCalendar* cal,
1.1262 + UCalendarDateFields field,
1.1263 + UCalendarLimitType type,
1.1264 + UErrorCode* status);
1.1265 +
1.1266 +/** Get the locale for this calendar object. You can choose between valid and actual locale.
1.1267 + * @param cal The calendar object
1.1268 + * @param type type of the locale we're looking for (valid or actual)
1.1269 + * @param status error code for the operation
1.1270 + * @return the locale name
1.1271 + * @stable ICU 2.8
1.1272 + */
1.1273 +U_STABLE const char * U_EXPORT2
1.1274 +ucal_getLocaleByType(const UCalendar *cal, ULocDataLocaleType type, UErrorCode* status);
1.1275 +
1.1276 +/**
1.1277 + * Returns the timezone data version currently used by ICU.
1.1278 + * @param status error code for the operation
1.1279 + * @return the version string, such as "2007f"
1.1280 + * @stable ICU 3.8
1.1281 + */
1.1282 +U_STABLE const char * U_EXPORT2
1.1283 +ucal_getTZDataVersion(UErrorCode* status);
1.1284 +
1.1285 +/**
1.1286 + * Returns the canonical system timezone ID or the normalized
1.1287 + * custom time zone ID for the given time zone ID.
1.1288 + * @param id The input timezone ID to be canonicalized.
1.1289 + * @param len The length of id, or -1 if null-terminated.
1.1290 + * @param result The buffer receives the canonical system timezone ID
1.1291 + * or the custom timezone ID in normalized format.
1.1292 + * @param resultCapacity The capacity of the result buffer.
1.1293 + * @param isSystemID Receives if the given ID is a known system
1.1294 + * timezone ID.
1.1295 + * @param status Recevies the status. When the given timezone ID
1.1296 + * is neither a known system time zone ID nor a
1.1297 + * valid custom timezone ID, U_ILLEGAL_ARGUMENT_ERROR
1.1298 + * is set.
1.1299 + * @return The result string length, not including the terminating
1.1300 + * null.
1.1301 + * @stable ICU 4.0
1.1302 + */
1.1303 +U_STABLE int32_t U_EXPORT2
1.1304 +ucal_getCanonicalTimeZoneID(const UChar* id, int32_t len,
1.1305 + UChar* result, int32_t resultCapacity, UBool *isSystemID, UErrorCode* status);
1.1306 +/**
1.1307 + * Get the resource keyword value string designating the calendar type for the UCalendar.
1.1308 + * @param cal The UCalendar to query.
1.1309 + * @param status The error code for the operation.
1.1310 + * @return The resource keyword value string.
1.1311 + * @stable ICU 4.2
1.1312 + */
1.1313 +U_STABLE const char * U_EXPORT2
1.1314 +ucal_getType(const UCalendar *cal, UErrorCode* status);
1.1315 +
1.1316 +/**
1.1317 + * Given a key and a locale, returns an array of string values in a preferred
1.1318 + * order that would make a difference. These are all and only those values where
1.1319 + * the open (creation) of the service with the locale formed from the input locale
1.1320 + * plus input keyword and that value has different behavior than creation with the
1.1321 + * input locale alone.
1.1322 + * @param key one of the keys supported by this service. For now, only
1.1323 + * "calendar" is supported.
1.1324 + * @param locale the locale
1.1325 + * @param commonlyUsed if set to true it will return only commonly used values
1.1326 + * with the given locale in preferred order. Otherwise,
1.1327 + * it will return all the available values for the locale.
1.1328 + * @param status error status
1.1329 + * @return a string enumeration over keyword values for the given key and the locale.
1.1330 + * @stable ICU 4.2
1.1331 + */
1.1332 +U_STABLE UEnumeration* U_EXPORT2
1.1333 +ucal_getKeywordValuesForLocale(const char* key,
1.1334 + const char* locale,
1.1335 + UBool commonlyUsed,
1.1336 + UErrorCode* status);
1.1337 +
1.1338 +
1.1339 +/** Weekday types, as returned by ucal_getDayOfWeekType().
1.1340 + * @stable ICU 4.4
1.1341 + */
1.1342 +enum UCalendarWeekdayType {
1.1343 + /**
1.1344 + * Designates a full weekday (no part of the day is included in the weekend).
1.1345 + * @stable ICU 4.4
1.1346 + */
1.1347 + UCAL_WEEKDAY,
1.1348 + /**
1.1349 + * Designates a full weekend day (the entire day is included in the weekend).
1.1350 + * @stable ICU 4.4
1.1351 + */
1.1352 + UCAL_WEEKEND,
1.1353 + /**
1.1354 + * Designates a day that starts as a weekday and transitions to the weekend.
1.1355 + * Call ucal_getWeekendTransition() to get the time of transition.
1.1356 + * @stable ICU 4.4
1.1357 + */
1.1358 + UCAL_WEEKEND_ONSET,
1.1359 + /**
1.1360 + * Designates a day that starts as the weekend and transitions to a weekday.
1.1361 + * Call ucal_getWeekendTransition() to get the time of transition.
1.1362 + * @stable ICU 4.4
1.1363 + */
1.1364 + UCAL_WEEKEND_CEASE
1.1365 +};
1.1366 +
1.1367 +/** @stable ICU 4.4 */
1.1368 +typedef enum UCalendarWeekdayType UCalendarWeekdayType;
1.1369 +
1.1370 +/**
1.1371 + * Returns whether the given day of the week is a weekday, a weekend day,
1.1372 + * or a day that transitions from one to the other, for the locale and
1.1373 + * calendar system associated with this UCalendar (the locale's region is
1.1374 + * often the most determinant factor). If a transition occurs at midnight,
1.1375 + * then the days before and after the transition will have the
1.1376 + * type UCAL_WEEKDAY or UCAL_WEEKEND. If a transition occurs at a time
1.1377 + * other than midnight, then the day of the transition will have
1.1378 + * the type UCAL_WEEKEND_ONSET or UCAL_WEEKEND_CEASE. In this case, the
1.1379 + * function ucal_getWeekendTransition() will return the point of
1.1380 + * transition.
1.1381 + * @param cal The UCalendar to query.
1.1382 + * @param dayOfWeek The day of the week whose type is desired (UCAL_SUNDAY..UCAL_SATURDAY).
1.1383 + * @param status The error code for the operation.
1.1384 + * @return The UCalendarWeekdayType for the day of the week.
1.1385 + * @stable ICU 4.4
1.1386 + */
1.1387 +U_STABLE UCalendarWeekdayType U_EXPORT2
1.1388 +ucal_getDayOfWeekType(const UCalendar *cal, UCalendarDaysOfWeek dayOfWeek, UErrorCode* status);
1.1389 +
1.1390 +/**
1.1391 + * Returns the time during the day at which the weekend begins or ends in
1.1392 + * this calendar system. If ucal_getDayOfWeekType() returns UCAL_WEEKEND_ONSET
1.1393 + * for the specified dayOfWeek, return the time at which the weekend begins.
1.1394 + * If ucal_getDayOfWeekType() returns UCAL_WEEKEND_CEASE for the specified dayOfWeek,
1.1395 + * return the time at which the weekend ends. If ucal_getDayOfWeekType() returns
1.1396 + * some other UCalendarWeekdayType for the specified dayOfWeek, is it an error condition
1.1397 + * (U_ILLEGAL_ARGUMENT_ERROR).
1.1398 + * @param cal The UCalendar to query.
1.1399 + * @param dayOfWeek The day of the week for which the weekend transition time is
1.1400 + * desired (UCAL_SUNDAY..UCAL_SATURDAY).
1.1401 + * @param status The error code for the operation.
1.1402 + * @return The milliseconds after midnight at which the weekend begins or ends.
1.1403 + * @stable ICU 4.4
1.1404 + */
1.1405 +U_STABLE int32_t U_EXPORT2
1.1406 +ucal_getWeekendTransition(const UCalendar *cal, UCalendarDaysOfWeek dayOfWeek, UErrorCode *status);
1.1407 +
1.1408 +/**
1.1409 + * Returns TRUE if the given UDate is in the weekend in
1.1410 + * this calendar system.
1.1411 + * @param cal The UCalendar to query.
1.1412 + * @param date The UDate in question.
1.1413 + * @param status The error code for the operation.
1.1414 + * @return TRUE if the given UDate is in the weekend in
1.1415 + * this calendar system, FALSE otherwise.
1.1416 + * @stable ICU 4.4
1.1417 + */
1.1418 +U_STABLE UBool U_EXPORT2
1.1419 +ucal_isWeekend(const UCalendar *cal, UDate date, UErrorCode *status);
1.1420 +
1.1421 +/**
1.1422 + * Return the difference between the target time and the time this calendar object is currently set to.
1.1423 + * If the target time is after the current calendar setting, the the returned value will be positive.
1.1424 + * The field parameter specifies the units of the return value. For example, if field is UCAL_MONTH
1.1425 + * and ucal_getFieldDifference returns 3, then the target time is 3 to less than 4 months after the
1.1426 + * current calendar setting.
1.1427 + *
1.1428 + * As a side effect of this call, this calendar is advanced toward target by the given amount. That is,
1.1429 + * calling this function has the side effect of calling ucal_add on this calendar with the specified
1.1430 + * field and an amount equal to the return value from this function.
1.1431 + *
1.1432 + * A typical way of using this function is to call it first with the largest field of interest, then
1.1433 + * with progressively smaller fields.
1.1434 + *
1.1435 + * @param cal The UCalendar to compare and update.
1.1436 + * @param target The target date to compare to the current calendar setting.
1.1437 + * @param field The field to compare; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
1.1438 + * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
1.1439 + * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
1.1440 + * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
1.1441 + * @param status A pointer to an UErrorCode to receive any errors
1.1442 + * @return The date difference for the specified field.
1.1443 + * @stable ICU 4.8
1.1444 + */
1.1445 +U_STABLE int32_t U_EXPORT2
1.1446 +ucal_getFieldDifference(UCalendar* cal,
1.1447 + UDate target,
1.1448 + UCalendarDateFields field,
1.1449 + UErrorCode* status);
1.1450 +
1.1451 +/**
1.1452 + * Time zone transition types for ucal_getTimeZoneTransitionDate
1.1453 + * @stable ICU 50
1.1454 + */
1.1455 +enum UTimeZoneTransitionType {
1.1456 + /**
1.1457 + * Get the next transition after the current date,
1.1458 + * i.e. excludes the current date
1.1459 + * @stable ICU 50
1.1460 + */
1.1461 + UCAL_TZ_TRANSITION_NEXT,
1.1462 + /**
1.1463 + * Get the next transition on or after the current date,
1.1464 + * i.e. may include the current date
1.1465 + * @stable ICU 50
1.1466 + */
1.1467 + UCAL_TZ_TRANSITION_NEXT_INCLUSIVE,
1.1468 + /**
1.1469 + * Get the previous transition before the current date,
1.1470 + * i.e. excludes the current date
1.1471 + * @stable ICU 50
1.1472 + */
1.1473 + UCAL_TZ_TRANSITION_PREVIOUS,
1.1474 + /**
1.1475 + * Get the previous transition on or before the current date,
1.1476 + * i.e. may include the current date
1.1477 + * @stable ICU 50
1.1478 + */
1.1479 + UCAL_TZ_TRANSITION_PREVIOUS_INCLUSIVE
1.1480 +};
1.1481 +
1.1482 +typedef enum UTimeZoneTransitionType UTimeZoneTransitionType; /**< @stable ICU 50 */
1.1483 +
1.1484 +/**
1.1485 +* Get the UDate for the next/previous time zone transition relative to
1.1486 +* the calendar's current date, in the time zone to which the calendar
1.1487 +* is currently set. If there is no known time zone transition of the
1.1488 +* requested type relative to the calendar's date, the function returns
1.1489 +* FALSE.
1.1490 +* @param cal The UCalendar to query.
1.1491 +* @param type The type of transition desired.
1.1492 +* @param transition A pointer to a UDate to be set to the transition time.
1.1493 +* If the function returns FALSE, the value set is unspecified.
1.1494 +* @param status A pointer to a UErrorCode to receive any errors.
1.1495 +* @return TRUE if a valid transition time is set in *transition, FALSE
1.1496 +* otherwise.
1.1497 +* @stable ICU 50
1.1498 +*/
1.1499 +U_DRAFT UBool U_EXPORT2
1.1500 +ucal_getTimeZoneTransitionDate(const UCalendar* cal, UTimeZoneTransitionType type,
1.1501 + UDate* transition, UErrorCode* status);
1.1502 +
1.1503 +#ifndef U_HIDE_DRAFT_API
1.1504 +/**
1.1505 +* Converts a system time zone ID to an equivalent Windows time zone ID. For example,
1.1506 +* Windows time zone ID "Pacific Standard Time" is returned for input "America/Los_Angeles".
1.1507 +*
1.1508 +* <p>There are system time zones that cannot be mapped to Windows zones. When the input
1.1509 +* system time zone ID is unknown or unmappable to a Windows time zone, then this
1.1510 +* function returns 0 as the result length, but the operation itself remains successful
1.1511 +* (no error status set on return).
1.1512 +*
1.1513 +* <p>This implementation utilizes <a href="http://unicode.org/cldr/charts/supplemental/zone_tzid.html">
1.1514 +* Zone-Tzid mapping data</a>. The mapping data is updated time to time. To get the latest changes,
1.1515 +* please read the ICU user guide section <a href="http://userguide.icu-project.org/datetime/timezone#TOC-Updating-the-Time-Zone-Data">
1.1516 +* Updating the Time Zone Data</a>.
1.1517 +*
1.1518 +* @param id A system time zone ID.
1.1519 +* @param len The length of <code>id</code>, or -1 if null-terminated.
1.1520 +* @param winid A buffer to receive a Windows time zone ID.
1.1521 +* @param winidCapacity The capacity of the result buffer <code>winid</code>.
1.1522 +* @param status Receives the status.
1.1523 +* @return The result string length, not including the terminating null.
1.1524 +* @see ucal_getTimeZoneIDForWindowsID
1.1525 +*
1.1526 +* @draft ICU 52
1.1527 +*/
1.1528 +U_DRAFT int32_t U_EXPORT2
1.1529 +ucal_getWindowsTimeZoneID(const UChar* id, int32_t len,
1.1530 + UChar* winid, int32_t winidCapacity, UErrorCode* status);
1.1531 +
1.1532 +/**
1.1533 +* Converts a Windows time zone ID to an equivalent system time zone ID
1.1534 +* for a region. For example, system time zone ID "America/Los_Angeles" is returned
1.1535 +* for input Windows ID "Pacific Standard Time" and region "US" (or <code>null</code>),
1.1536 +* "America/Vancouver" is returned for the same Windows ID "Pacific Standard Time" and
1.1537 +* region "CA".
1.1538 +*
1.1539 +* <p>Not all Windows time zones can be mapped to system time zones. When the input
1.1540 +* Windows time zone ID is unknown or unmappable to a system time zone, then this
1.1541 +* function returns 0 as the result length, but the operation itself remains successful
1.1542 +* (no error status set on return).
1.1543 +*
1.1544 +* <p>This implementation utilizes <a href="http://unicode.org/cldr/charts/supplemental/zone_tzid.html">
1.1545 +* Zone-Tzid mapping data</a>. The mapping data is updated time to time. To get the latest changes,
1.1546 +* please read the ICU user guide section <a href="http://userguide.icu-project.org/datetime/timezone#TOC-Updating-the-Time-Zone-Data">
1.1547 +* Updating the Time Zone Data</a>.
1.1548 +*
1.1549 +* @param winid A Windows time zone ID.
1.1550 +* @param len The length of <code>winid</code>, or -1 if null-terminated.
1.1551 +* @param region A null-terminated region code, or <code>NULL</code> if no regional preference.
1.1552 +* @param id A buffer to receive a system time zone ID.
1.1553 +* @param idCapacity The capacity of the result buffer <code>id</code>.
1.1554 +* @param status Receives the status.
1.1555 +* @return The result string length, not including the terminating null.
1.1556 +* @see ucal_getWindowsTimeZoneID
1.1557 +*
1.1558 +* @draft ICU 52
1.1559 +*/
1.1560 +U_DRAFT int32_t U_EXPORT2
1.1561 +ucal_getTimeZoneIDForWindowsID(const UChar* winid, int32_t len, const char* region,
1.1562 + UChar* id, int32_t idCapacity, UErrorCode* status);
1.1563 +
1.1564 +#endif /* U_HIDE_DRAFT_API */
1.1565 +
1.1566 +#endif /* #if !UCONFIG_NO_FORMATTING */
1.1567 +
1.1568 +#endif
