Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1 | // © 2016 and later: Unicode, Inc. and others. |
| 2 | // License & terms of use: http://www.unicode.org/copyright.html |
| 3 | /* |
| 4 | ******************************************************************************* |
| 5 | * Copyright (C) 1996-2015, International Business Machines Corporation and |
| 6 | * others. All Rights Reserved. |
| 7 | ******************************************************************************* |
| 8 | */ |
| 9 | |
| 10 | #ifndef UCAL_H |
| 11 | #define UCAL_H |
| 12 | |
| 13 | #include "unicode/utypes.h" |
| 14 | #include "unicode/uenum.h" |
| 15 | #include "unicode/uloc.h" |
| 16 | |
| 17 | #if U_SHOW_CPLUSPLUS_API |
| 18 | #include "unicode/localpointer.h" |
| 19 | #endif // U_SHOW_CPLUSPLUS_API |
| 20 | |
| 21 | #if !UCONFIG_NO_FORMATTING |
| 22 | |
| 23 | /** |
| 24 | * \file |
| 25 | * \brief C API: Calendar |
| 26 | * |
| 27 | * <h2>Calendar C API</h2> |
| 28 | * |
| 29 | * UCalendar C API is used for converting between a <code>UDate</code> object |
| 30 | * and a set of integer fields such as <code>UCAL_YEAR</code>, <code>UCAL_MONTH</code>, |
| 31 | * <code>UCAL_DAY</code>, <code>UCAL_HOUR</code>, and so on. |
| 32 | * (A <code>UDate</code> object represents a specific instant in |
| 33 | * time with millisecond precision. See UDate |
| 34 | * for information about the <code>UDate</code> .) |
| 35 | * |
| 36 | * <p> |
| 37 | * Types of <code>UCalendar</code> interpret a <code>UDate</code> |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 38 | * according to the rules of a specific calendar system. The C API |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 39 | * provides the enum UCalendarType with UCAL_TRADITIONAL and |
| 40 | * UCAL_GREGORIAN. |
| 41 | * <p> |
| 42 | * Like other locale-sensitive C API, calendar API provides a |
| 43 | * function, <code>ucal_open()</code>, which returns a pointer to |
| 44 | * <code>UCalendar</code> whose time fields have been initialized |
| 45 | * with the current date and time. We need to specify the type of |
| 46 | * calendar to be opened and the timezoneId. |
| 47 | * \htmlonly<blockquote>\endhtmlonly |
| 48 | * <pre> |
| 49 | * \code |
| 50 | * UCalendar *caldef; |
| 51 | * UChar *tzId; |
| 52 | * UErrorCode status; |
| 53 | * tzId=(UChar*)malloc(sizeof(UChar) * (strlen("PST") +1) ); |
| 54 | * u_uastrcpy(tzId, "PST"); |
| 55 | * caldef=ucal_open(tzID, u_strlen(tzID), NULL, UCAL_TRADITIONAL, &status); |
| 56 | * \endcode |
| 57 | * </pre> |
| 58 | * \htmlonly</blockquote>\endhtmlonly |
| 59 | * |
| 60 | * <p> |
| 61 | * A <code>UCalendar</code> object can produce all the time field values |
| 62 | * needed to implement the date-time formatting for a particular language |
| 63 | * and calendar style (for example, Japanese-Gregorian, Japanese-Traditional). |
| 64 | * |
| 65 | * <p> |
| 66 | * When computing a <code>UDate</code> from time fields, two special circumstances |
| 67 | * may arise: there may be insufficient information to compute the |
| 68 | * <code>UDate</code> (such as only year and month but no day in the month), |
| 69 | * or there may be inconsistent information (such as "Tuesday, July 15, 1996" |
| 70 | * -- July 15, 1996 is actually a Monday). |
| 71 | * |
| 72 | * <p> |
| 73 | * <strong>Insufficient information.</strong> The calendar will use default |
| 74 | * information to specify the missing fields. This may vary by calendar; for |
| 75 | * the Gregorian calendar, the default for a field is the same as that of the |
| 76 | * start of the epoch: i.e., UCAL_YEAR = 1970, UCAL_MONTH = JANUARY, UCAL_DATE = 1, etc. |
| 77 | * |
| 78 | * <p> |
| 79 | * <strong>Inconsistent information.</strong> If fields conflict, the calendar |
| 80 | * will give preference to fields set more recently. For example, when |
| 81 | * determining the day, the calendar will look for one of the following |
| 82 | * combinations of fields. The most recent combination, as determined by the |
| 83 | * most recently set single field, will be used. |
| 84 | * |
| 85 | * \htmlonly<blockquote>\endhtmlonly |
| 86 | * <pre> |
| 87 | * \code |
| 88 | * UCAL_MONTH + UCAL_DAY_OF_MONTH |
| 89 | * UCAL_MONTH + UCAL_WEEK_OF_MONTH + UCAL_DAY_OF_WEEK |
| 90 | * UCAL_MONTH + UCAL_DAY_OF_WEEK_IN_MONTH + UCAL_DAY_OF_WEEK |
| 91 | * UCAL_DAY_OF_YEAR |
| 92 | * UCAL_DAY_OF_WEEK + UCAL_WEEK_OF_YEAR |
| 93 | * \endcode |
| 94 | * </pre> |
| 95 | * \htmlonly</blockquote>\endhtmlonly |
| 96 | * |
| 97 | * For the time of day: |
| 98 | * |
| 99 | * \htmlonly<blockquote>\endhtmlonly |
| 100 | * <pre> |
| 101 | * \code |
| 102 | * UCAL_HOUR_OF_DAY |
| 103 | * UCAL_AM_PM + UCAL_HOUR |
| 104 | * \endcode |
| 105 | * </pre> |
| 106 | * \htmlonly</blockquote>\endhtmlonly |
| 107 | * |
| 108 | * <p> |
| 109 | * <strong>Note:</strong> for some non-Gregorian calendars, different |
| 110 | * fields may be necessary for complete disambiguation. For example, a full |
| 111 | * specification of the historical Arabic astronomical calendar requires year, |
| 112 | * month, day-of-month <em>and</em> day-of-week in some cases. |
| 113 | * |
| 114 | * <p> |
| 115 | * <strong>Note:</strong> There are certain possible ambiguities in |
| 116 | * interpretation of certain singular times, which are resolved in the |
| 117 | * following ways: |
| 118 | * <ol> |
| 119 | * <li> 24:00:00 "belongs" to the following day. That is, |
| 120 | * 23:59 on Dec 31, 1969 < 24:00 on Jan 1, 1970 < 24:01:00 on Jan 1, 1970 |
| 121 | * |
| 122 | * <li> Although historically not precise, midnight also belongs to "am", |
| 123 | * and noon belongs to "pm", so on the same day, |
| 124 | * 12:00 am (midnight) < 12:01 am, and 12:00 pm (noon) < 12:01 pm |
| 125 | * </ol> |
| 126 | * |
| 127 | * <p> |
| 128 | * The date or time format strings are not part of the definition of a |
| 129 | * calendar, as those must be modifiable or overridable by the user at |
| 130 | * runtime. Use {@link icu::DateFormat} |
| 131 | * to format dates. |
| 132 | * |
| 133 | * <p> |
| 134 | * <code>Calendar</code> provides an API for field "rolling", where fields |
| 135 | * can be incremented or decremented, but wrap around. For example, rolling the |
| 136 | * month up in the date <code>December 12, <b>1996</b></code> results in |
| 137 | * <code>January 12, <b>1996</b></code>. |
| 138 | * |
| 139 | * <p> |
| 140 | * <code>Calendar</code> also provides a date arithmetic function for |
| 141 | * adding the specified (signed) amount of time to a particular time field. |
| 142 | * For example, subtracting 5 days from the date <code>September 12, 1996</code> |
| 143 | * results in <code>September 7, 1996</code>. |
| 144 | * |
| 145 | * <p> |
| 146 | * The Japanese calendar uses a combination of era name and year number. |
| 147 | * When an emperor of Japan abdicates and a new emperor ascends the throne, |
| 148 | * a new era is declared and year number is reset to 1. Even if the date of |
| 149 | * abdication is scheduled ahead of time, the new era name might not be |
| 150 | * announced until just before the date. In such case, ICU4C may include |
| 151 | * a start date of future era without actual era name, but not enabled |
| 152 | * by default. ICU4C users who want to test the behavior of the future era |
| 153 | * can enable the tentative era by: |
| 154 | * <ul> |
| 155 | * <li>Environment variable <code>ICU_ENABLE_TENTATIVE_ERA=true</code>.</li> |
| 156 | * </ul> |
| 157 | * |
| 158 | * @stable ICU 2.0 |
| 159 | */ |
| 160 | |
| 161 | /** |
| 162 | * The time zone ID reserved for unknown time zone. |
| 163 | * It behaves like the GMT/UTC time zone but has the special ID "Etc/Unknown". |
| 164 | * @stable ICU 4.8 |
| 165 | */ |
| 166 | #define UCAL_UNKNOWN_ZONE_ID "Etc/Unknown" |
| 167 | |
| 168 | /** A calendar. |
| 169 | * For usage in C programs. |
| 170 | * @stable ICU 2.0 |
| 171 | */ |
| 172 | typedef void* UCalendar; |
| 173 | |
| 174 | /** Possible types of UCalendars |
| 175 | * @stable ICU 2.0 |
| 176 | */ |
| 177 | enum UCalendarType { |
| 178 | /** |
| 179 | * Despite the name, UCAL_TRADITIONAL designates the locale's default calendar, |
| 180 | * which may be the Gregorian calendar or some other calendar. |
| 181 | * @stable ICU 2.0 |
| 182 | */ |
| 183 | UCAL_TRADITIONAL, |
| 184 | /** |
| 185 | * A better name for UCAL_TRADITIONAL. |
| 186 | * @stable ICU 4.2 |
| 187 | */ |
| 188 | UCAL_DEFAULT = UCAL_TRADITIONAL, |
| 189 | /** |
| 190 | * Unambiguously designates the Gregorian calendar for the locale. |
| 191 | * @stable ICU 2.0 |
| 192 | */ |
| 193 | UCAL_GREGORIAN |
| 194 | }; |
| 195 | |
| 196 | /** @stable ICU 2.0 */ |
| 197 | typedef enum UCalendarType UCalendarType; |
| 198 | |
| 199 | /** Possible fields in a UCalendar |
| 200 | * @stable ICU 2.0 |
| 201 | */ |
| 202 | enum UCalendarDateFields { |
| 203 | /** |
| 204 | * Field number indicating the era, e.g., AD or BC in the Gregorian (Julian) calendar. |
| 205 | * This is a calendar-specific value. |
| 206 | * @stable ICU 2.6 |
| 207 | */ |
| 208 | UCAL_ERA, |
| 209 | |
| 210 | /** |
| 211 | * Field number indicating the year. This is a calendar-specific value. |
| 212 | * @stable ICU 2.6 |
| 213 | */ |
| 214 | UCAL_YEAR, |
| 215 | |
| 216 | /** |
| 217 | * Field number indicating the month. This is a calendar-specific value. |
| 218 | * The first month of the year is |
| 219 | * <code>JANUARY</code>; the last depends on the number of months in a year. |
| 220 | * @see #UCAL_JANUARY |
| 221 | * @see #UCAL_FEBRUARY |
| 222 | * @see #UCAL_MARCH |
| 223 | * @see #UCAL_APRIL |
| 224 | * @see #UCAL_MAY |
| 225 | * @see #UCAL_JUNE |
| 226 | * @see #UCAL_JULY |
| 227 | * @see #UCAL_AUGUST |
| 228 | * @see #UCAL_SEPTEMBER |
| 229 | * @see #UCAL_OCTOBER |
| 230 | * @see #UCAL_NOVEMBER |
| 231 | * @see #UCAL_DECEMBER |
| 232 | * @see #UCAL_UNDECIMBER |
| 233 | * @stable ICU 2.6 |
| 234 | */ |
| 235 | UCAL_MONTH, |
| 236 | |
| 237 | /** |
| 238 | * Field number indicating the |
| 239 | * week number within the current year. The first week of the year, as |
| 240 | * defined by <code>UCAL_FIRST_DAY_OF_WEEK</code> and <code>UCAL_MINIMAL_DAYS_IN_FIRST_WEEK</code> |
| 241 | * attributes, has value 1. Subclasses define |
| 242 | * the value of <code>UCAL_WEEK_OF_YEAR</code> for days before the first week of |
| 243 | * the year. |
| 244 | * @see ucal_getAttribute |
| 245 | * @see ucal_setAttribute |
| 246 | * @stable ICU 2.6 |
| 247 | */ |
| 248 | UCAL_WEEK_OF_YEAR, |
| 249 | |
| 250 | /** |
| 251 | * Field number indicating the |
| 252 | * week number within the current month. The first week of the month, as |
| 253 | * defined by <code>UCAL_FIRST_DAY_OF_WEEK</code> and <code>UCAL_MINIMAL_DAYS_IN_FIRST_WEEK</code> |
| 254 | * attributes, has value 1. Subclasses define |
| 255 | * the value of <code>WEEK_OF_MONTH</code> for days before the first week of |
| 256 | * the month. |
| 257 | * @see ucal_getAttribute |
| 258 | * @see ucal_setAttribute |
| 259 | * @see #UCAL_FIRST_DAY_OF_WEEK |
| 260 | * @see #UCAL_MINIMAL_DAYS_IN_FIRST_WEEK |
| 261 | * @stable ICU 2.6 |
| 262 | */ |
| 263 | UCAL_WEEK_OF_MONTH, |
| 264 | |
| 265 | /** |
| 266 | * Field number indicating the |
| 267 | * day of the month. This is a synonym for <code>DAY_OF_MONTH</code>. |
| 268 | * The first day of the month has value 1. |
| 269 | * @see #UCAL_DAY_OF_MONTH |
| 270 | * @stable ICU 2.6 |
| 271 | */ |
| 272 | UCAL_DATE, |
| 273 | |
| 274 | /** |
| 275 | * Field number indicating the day |
| 276 | * number within the current year. The first day of the year has value 1. |
| 277 | * @stable ICU 2.6 |
| 278 | */ |
| 279 | UCAL_DAY_OF_YEAR, |
| 280 | |
| 281 | /** |
| 282 | * Field number indicating the day |
| 283 | * of the week. This field takes values <code>SUNDAY</code>, |
| 284 | * <code>MONDAY</code>, <code>TUESDAY</code>, <code>WEDNESDAY</code>, |
| 285 | * <code>THURSDAY</code>, <code>FRIDAY</code>, and <code>SATURDAY</code>. |
| 286 | * @see #UCAL_SUNDAY |
| 287 | * @see #UCAL_MONDAY |
| 288 | * @see #UCAL_TUESDAY |
| 289 | * @see #UCAL_WEDNESDAY |
| 290 | * @see #UCAL_THURSDAY |
| 291 | * @see #UCAL_FRIDAY |
| 292 | * @see #UCAL_SATURDAY |
| 293 | * @stable ICU 2.6 |
| 294 | */ |
| 295 | UCAL_DAY_OF_WEEK, |
| 296 | |
| 297 | /** |
| 298 | * Field number indicating the |
| 299 | * ordinal number of the day of the week within the current month. Together |
| 300 | * with the <code>DAY_OF_WEEK</code> field, this uniquely specifies a day |
| 301 | * within a month. Unlike <code>WEEK_OF_MONTH</code> and |
| 302 | * <code>WEEK_OF_YEAR</code>, this field's value does <em>not</em> depend on |
| 303 | * <code>getFirstDayOfWeek()</code> or |
| 304 | * <code>getMinimalDaysInFirstWeek()</code>. <code>DAY_OF_MONTH 1</code> |
| 305 | * through <code>7</code> always correspond to <code>DAY_OF_WEEK_IN_MONTH |
| 306 | * 1</code>; <code>8</code> through <code>15</code> correspond to |
| 307 | * <code>DAY_OF_WEEK_IN_MONTH 2</code>, and so on. |
| 308 | * <code>DAY_OF_WEEK_IN_MONTH 0</code> indicates the week before |
| 309 | * <code>DAY_OF_WEEK_IN_MONTH 1</code>. Negative values count back from the |
| 310 | * end of the month, so the last Sunday of a month is specified as |
| 311 | * <code>DAY_OF_WEEK = SUNDAY, DAY_OF_WEEK_IN_MONTH = -1</code>. Because |
| 312 | * negative values count backward they will usually be aligned differently |
| 313 | * within the month than positive values. For example, if a month has 31 |
| 314 | * days, <code>DAY_OF_WEEK_IN_MONTH -1</code> will overlap |
| 315 | * <code>DAY_OF_WEEK_IN_MONTH 5</code> and the end of <code>4</code>. |
| 316 | * @see #UCAL_DAY_OF_WEEK |
| 317 | * @see #UCAL_WEEK_OF_MONTH |
| 318 | * @stable ICU 2.6 |
| 319 | */ |
| 320 | UCAL_DAY_OF_WEEK_IN_MONTH, |
| 321 | |
| 322 | /** |
| 323 | * Field number indicating |
| 324 | * whether the <code>HOUR</code> is before or after noon. |
| 325 | * E.g., at 10:04:15.250 PM the <code>AM_PM</code> is <code>PM</code>. |
| 326 | * @see #UCAL_AM |
| 327 | * @see #UCAL_PM |
| 328 | * @see #UCAL_HOUR |
| 329 | * @stable ICU 2.6 |
| 330 | */ |
| 331 | UCAL_AM_PM, |
| 332 | |
| 333 | /** |
| 334 | * Field number indicating the |
| 335 | * hour of the morning or afternoon. <code>HOUR</code> is used for the 12-hour |
| 336 | * clock. |
| 337 | * E.g., at 10:04:15.250 PM the <code>HOUR</code> is 10. |
| 338 | * @see #UCAL_AM_PM |
| 339 | * @see #UCAL_HOUR_OF_DAY |
| 340 | * @stable ICU 2.6 |
| 341 | */ |
| 342 | UCAL_HOUR, |
| 343 | |
| 344 | /** |
| 345 | * Field number indicating the |
| 346 | * hour of the day. <code>HOUR_OF_DAY</code> is used for the 24-hour clock. |
| 347 | * E.g., at 10:04:15.250 PM the <code>HOUR_OF_DAY</code> is 22. |
| 348 | * @see #UCAL_HOUR |
| 349 | * @stable ICU 2.6 |
| 350 | */ |
| 351 | UCAL_HOUR_OF_DAY, |
| 352 | |
| 353 | /** |
| 354 | * Field number indicating the |
| 355 | * minute within the hour. |
| 356 | * E.g., at 10:04:15.250 PM the <code>UCAL_MINUTE</code> is 4. |
| 357 | * @stable ICU 2.6 |
| 358 | */ |
| 359 | UCAL_MINUTE, |
| 360 | |
| 361 | /** |
| 362 | * Field number indicating the |
| 363 | * second within the minute. |
| 364 | * E.g., at 10:04:15.250 PM the <code>UCAL_SECOND</code> is 15. |
| 365 | * @stable ICU 2.6 |
| 366 | */ |
| 367 | UCAL_SECOND, |
| 368 | |
| 369 | /** |
| 370 | * Field number indicating the |
| 371 | * millisecond within the second. |
| 372 | * E.g., at 10:04:15.250 PM the <code>UCAL_MILLISECOND</code> is 250. |
| 373 | * @stable ICU 2.6 |
| 374 | */ |
| 375 | UCAL_MILLISECOND, |
| 376 | |
| 377 | /** |
| 378 | * Field number indicating the |
| 379 | * raw offset from GMT in milliseconds. |
| 380 | * @stable ICU 2.6 |
| 381 | */ |
| 382 | UCAL_ZONE_OFFSET, |
| 383 | |
| 384 | /** |
| 385 | * Field number indicating the |
| 386 | * daylight savings offset in milliseconds. |
| 387 | * @stable ICU 2.6 |
| 388 | */ |
| 389 | UCAL_DST_OFFSET, |
| 390 | |
| 391 | /** |
| 392 | * Field number |
| 393 | * indicating the extended year corresponding to the |
| 394 | * <code>UCAL_WEEK_OF_YEAR</code> field. This may be one greater or less |
| 395 | * than the value of <code>UCAL_EXTENDED_YEAR</code>. |
| 396 | * @stable ICU 2.6 |
| 397 | */ |
| 398 | UCAL_YEAR_WOY, |
| 399 | |
| 400 | /** |
| 401 | * Field number |
| 402 | * indicating the localized day of week. This will be a value from 1 |
| 403 | * to 7 inclusive, with 1 being the localized first day of the week. |
| 404 | * @stable ICU 2.6 |
| 405 | */ |
| 406 | UCAL_DOW_LOCAL, |
| 407 | |
| 408 | /** |
| 409 | * Year of this calendar system, encompassing all supra-year fields. For example, |
| 410 | * in Gregorian/Julian calendars, positive Extended Year values indicate years AD, |
| 411 | * 1 BC = 0 extended, 2 BC = -1 extended, and so on. |
| 412 | * @stable ICU 2.8 |
| 413 | */ |
| 414 | UCAL_EXTENDED_YEAR, |
| 415 | |
| 416 | /** |
| 417 | * Field number |
| 418 | * indicating the modified Julian day number. This is different from |
| 419 | * the conventional Julian day number in two regards. First, it |
| 420 | * demarcates days at local zone midnight, rather than noon GMT. |
| 421 | * Second, it is a local number; that is, it depends on the local time |
| 422 | * zone. It can be thought of as a single number that encompasses all |
| 423 | * the date-related fields. |
| 424 | * @stable ICU 2.8 |
| 425 | */ |
| 426 | UCAL_JULIAN_DAY, |
| 427 | |
| 428 | /** |
| 429 | * Ranges from 0 to 23:59:59.999 (regardless of DST). This field behaves <em>exactly</em> |
| 430 | * like a composite of all time-related fields, not including the zone fields. As such, |
| 431 | * it also reflects discontinuities of those fields on DST transition days. On a day |
| 432 | * of DST onset, it will jump forward. On a day of DST cessation, it will jump |
| 433 | * backward. This reflects the fact that it must be combined with the DST_OFFSET field |
| 434 | * to obtain a unique local time value. |
| 435 | * @stable ICU 2.8 |
| 436 | */ |
| 437 | UCAL_MILLISECONDS_IN_DAY, |
| 438 | |
| 439 | /** |
| 440 | * Whether or not the current month is a leap month (0 or 1). See the Chinese calendar for |
| 441 | * an example of this. |
| 442 | */ |
| 443 | UCAL_IS_LEAP_MONTH, |
| 444 | |
| 445 | /* Do not conditionalize the following with #ifndef U_HIDE_DEPRECATED_API, |
| 446 | * it is needed for layout of Calendar, DateFormat, and other objects */ |
| 447 | #ifndef U_FORCE_HIDE_DEPRECATED_API |
| 448 | /** |
| 449 | * One more than the highest normal UCalendarDateFields value. |
| 450 | * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. |
| 451 | */ |
| 452 | UCAL_FIELD_COUNT, |
| 453 | #endif // U_FORCE_HIDE_DEPRECATED_API |
| 454 | |
| 455 | /** |
| 456 | * Field number indicating the |
| 457 | * day of the month. This is a synonym for <code>UCAL_DATE</code>. |
| 458 | * The first day of the month has value 1. |
| 459 | * @see #UCAL_DATE |
| 460 | * Synonym for UCAL_DATE |
| 461 | * @stable ICU 2.8 |
| 462 | **/ |
| 463 | UCAL_DAY_OF_MONTH=UCAL_DATE |
| 464 | }; |
| 465 | |
| 466 | /** @stable ICU 2.0 */ |
| 467 | typedef enum UCalendarDateFields UCalendarDateFields; |
| 468 | /** |
| 469 | * Useful constant for days of week. Note: Calendar day-of-week is 1-based. Clients |
| 470 | * who create locale resources for the field of first-day-of-week should be aware of |
| 471 | * this. For instance, in US locale, first-day-of-week is set to 1, i.e., UCAL_SUNDAY. |
| 472 | */ |
| 473 | /** Possible days of the week in a UCalendar |
| 474 | * @stable ICU 2.0 |
| 475 | */ |
| 476 | enum UCalendarDaysOfWeek { |
| 477 | /** Sunday */ |
| 478 | UCAL_SUNDAY = 1, |
| 479 | /** Monday */ |
| 480 | UCAL_MONDAY, |
| 481 | /** Tuesday */ |
| 482 | UCAL_TUESDAY, |
| 483 | /** Wednesday */ |
| 484 | UCAL_WEDNESDAY, |
| 485 | /** Thursday */ |
| 486 | UCAL_THURSDAY, |
| 487 | /** Friday */ |
| 488 | UCAL_FRIDAY, |
| 489 | /** Saturday */ |
| 490 | UCAL_SATURDAY |
| 491 | }; |
| 492 | |
| 493 | /** @stable ICU 2.0 */ |
| 494 | typedef enum UCalendarDaysOfWeek UCalendarDaysOfWeek; |
| 495 | |
| 496 | /** Possible months in a UCalendar. Note: Calendar month is 0-based. |
| 497 | * @stable ICU 2.0 |
| 498 | */ |
| 499 | enum UCalendarMonths { |
| 500 | /** January */ |
| 501 | UCAL_JANUARY, |
| 502 | /** February */ |
| 503 | UCAL_FEBRUARY, |
| 504 | /** March */ |
| 505 | UCAL_MARCH, |
| 506 | /** April */ |
| 507 | UCAL_APRIL, |
| 508 | /** May */ |
| 509 | UCAL_MAY, |
| 510 | /** June */ |
| 511 | UCAL_JUNE, |
| 512 | /** July */ |
| 513 | UCAL_JULY, |
| 514 | /** August */ |
| 515 | UCAL_AUGUST, |
| 516 | /** September */ |
| 517 | UCAL_SEPTEMBER, |
| 518 | /** October */ |
| 519 | UCAL_OCTOBER, |
| 520 | /** November */ |
| 521 | UCAL_NOVEMBER, |
| 522 | /** December */ |
| 523 | UCAL_DECEMBER, |
| 524 | /** Value of the <code>UCAL_MONTH</code> field indicating the |
| 525 | * thirteenth month of the year. Although the Gregorian calendar |
| 526 | * does not use this value, lunar calendars do. |
| 527 | */ |
| 528 | UCAL_UNDECIMBER |
| 529 | }; |
| 530 | |
| 531 | /** @stable ICU 2.0 */ |
| 532 | typedef enum UCalendarMonths UCalendarMonths; |
| 533 | |
| 534 | /** Possible AM/PM values in a UCalendar |
| 535 | * @stable ICU 2.0 |
| 536 | */ |
| 537 | enum UCalendarAMPMs { |
| 538 | /** AM */ |
| 539 | UCAL_AM, |
| 540 | /** PM */ |
| 541 | UCAL_PM |
| 542 | }; |
| 543 | |
| 544 | /** @stable ICU 2.0 */ |
| 545 | typedef enum UCalendarAMPMs UCalendarAMPMs; |
| 546 | |
| 547 | /** |
| 548 | * System time zone type constants used by filtering zones |
| 549 | * in ucal_openTimeZoneIDEnumeration. |
| 550 | * @see ucal_openTimeZoneIDEnumeration |
| 551 | * @stable ICU 4.8 |
| 552 | */ |
| 553 | enum USystemTimeZoneType { |
| 554 | /** |
| 555 | * Any system zones. |
| 556 | * @stable ICU 4.8 |
| 557 | */ |
| 558 | UCAL_ZONE_TYPE_ANY, |
| 559 | /** |
| 560 | * Canonical system zones. |
| 561 | * @stable ICU 4.8 |
| 562 | */ |
| 563 | UCAL_ZONE_TYPE_CANONICAL, |
| 564 | /** |
| 565 | * Canonical system zones associated with actual locations. |
| 566 | * @stable ICU 4.8 |
| 567 | */ |
| 568 | UCAL_ZONE_TYPE_CANONICAL_LOCATION |
| 569 | }; |
| 570 | |
| 571 | /** @stable ICU 4.8 */ |
| 572 | typedef enum USystemTimeZoneType USystemTimeZoneType; |
| 573 | |
| 574 | /** |
| 575 | * Create an enumeration over system time zone IDs with the given |
| 576 | * filter conditions. |
| 577 | * @param zoneType The system time zone type. |
| 578 | * @param region The ISO 3166 two-letter country code or UN M.49 |
| 579 | * three-digit area code. When NULL, no filtering |
| 580 | * done by region. |
| 581 | * @param rawOffset An offset from GMT in milliseconds, ignoring the |
| 582 | * effect of daylight savings time, if any. When NULL, |
| 583 | * no filtering done by zone offset. |
| 584 | * @param ec A pointer to an UErrorCode to receive any errors |
| 585 | * @return an enumeration object that the caller must dispose of |
| 586 | * using enum_close(), or NULL upon failure. In case of failure, |
| 587 | * *ec will indicate the error. |
| 588 | * @stable ICU 4.8 |
| 589 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 590 | U_CAPI UEnumeration* U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 591 | ucal_openTimeZoneIDEnumeration(USystemTimeZoneType zoneType, const char* region, |
| 592 | const int32_t* rawOffset, UErrorCode* ec); |
| 593 | |
| 594 | /** |
| 595 | * Create an enumeration over all time zones. |
| 596 | * |
| 597 | * @param ec input/output error code |
| 598 | * |
| 599 | * @return an enumeration object that the caller must dispose of using |
| 600 | * uenum_close(), or NULL upon failure. In case of failure *ec will |
| 601 | * indicate the error. |
| 602 | * |
| 603 | * @stable ICU 2.6 |
| 604 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 605 | U_CAPI UEnumeration* U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 606 | ucal_openTimeZones(UErrorCode* ec); |
| 607 | |
| 608 | /** |
| 609 | * Create an enumeration over all time zones associated with the given |
| 610 | * country. Some zones are affiliated with no country (e.g., "UTC"); |
| 611 | * these may also be retrieved, as a group. |
| 612 | * |
| 613 | * @param country the ISO 3166 two-letter country code, or NULL to |
| 614 | * retrieve zones not affiliated with any country |
| 615 | * |
| 616 | * @param ec input/output error code |
| 617 | * |
| 618 | * @return an enumeration object that the caller must dispose of using |
| 619 | * uenum_close(), or NULL upon failure. In case of failure *ec will |
| 620 | * indicate the error. |
| 621 | * |
| 622 | * @stable ICU 2.6 |
| 623 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 624 | U_CAPI UEnumeration* U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 625 | ucal_openCountryTimeZones(const char* country, UErrorCode* ec); |
| 626 | |
| 627 | /** |
| 628 | * Return the default time zone. The default is determined initially |
| 629 | * by querying the host operating system. If the host system detection |
| 630 | * routines fail, or if they specify a TimeZone or TimeZone offset |
| 631 | * which is not recognized, then the special TimeZone "Etc/Unknown" |
| 632 | * is returned. |
| 633 | * |
| 634 | * The default may be changed with `ucal_setDefaultTimeZone()` or with |
| 635 | * the C++ TimeZone API, `TimeZone::adoptDefault(TimeZone*)`. |
| 636 | * |
| 637 | * @param result A buffer to receive the result, or NULL |
| 638 | * |
| 639 | * @param resultCapacity The capacity of the result buffer |
| 640 | * |
| 641 | * @param ec input/output error code |
| 642 | * |
| 643 | * @return The result string length, not including the terminating |
| 644 | * null |
| 645 | * |
| 646 | * @see #UCAL_UNKNOWN_ZONE_ID |
| 647 | * |
| 648 | * @stable ICU 2.6 |
| 649 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 650 | U_CAPI int32_t U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 651 | ucal_getDefaultTimeZone(UChar* result, int32_t resultCapacity, UErrorCode* ec); |
| 652 | |
| 653 | /** |
| 654 | * Set the default time zone. |
| 655 | * |
| 656 | * @param zoneID null-terminated time zone ID |
| 657 | * |
| 658 | * @param ec input/output error code |
| 659 | * |
| 660 | * @stable ICU 2.6 |
| 661 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 662 | U_CAPI void U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 663 | ucal_setDefaultTimeZone(const UChar* zoneID, UErrorCode* ec); |
| 664 | |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 665 | /** |
| 666 | * Return the current host time zone. The host time zone is detected from |
| 667 | * the current host system configuration by querying the host operating |
| 668 | * system. If the host system detection routines fail, or if they specify |
| 669 | * a TimeZone or TimeZone offset which is not recognized, then the special |
| 670 | * TimeZone "Etc/Unknown" is returned. |
| 671 | * |
| 672 | * Note that host time zone and the ICU default time zone can be different. |
| 673 | * |
| 674 | * The ICU default time zone does not change once initialized unless modified |
| 675 | * by calling `ucal_setDefaultTimeZone()` or with the C++ TimeZone API, |
| 676 | * `TimeZone::adoptDefault(TimeZone*)`. |
| 677 | * |
| 678 | * If the host operating system configuration has changed since ICU has |
| 679 | * initialized then the returned value can be different than the ICU default |
| 680 | * time zone, even if the default has not changed. |
| 681 | * |
| 682 | * <p>This function is not thread safe.</p> |
| 683 | * |
| 684 | * @param result A buffer to receive the result, or NULL |
| 685 | * @param resultCapacity The capacity of the result buffer |
| 686 | * @param ec input/output error code |
| 687 | * @return The result string length, not including the terminating |
| 688 | * null |
| 689 | * |
| 690 | * @see #UCAL_UNKNOWN_ZONE_ID |
| 691 | * |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 692 | * @stable ICU 65 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 693 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 694 | U_CAPI int32_t U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 695 | ucal_getHostTimeZone(UChar *result, int32_t resultCapacity, UErrorCode *ec); |
| 696 | |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 697 | /** |
| 698 | * Return the amount of time in milliseconds that the clock is |
| 699 | * advanced during daylight savings time for the given time zone, or |
| 700 | * zero if the time zone does not observe daylight savings time. |
| 701 | * |
| 702 | * @param zoneID null-terminated time zone ID |
| 703 | * |
| 704 | * @param ec input/output error code |
| 705 | * |
| 706 | * @return the number of milliseconds the time is advanced with |
| 707 | * respect to standard time when the daylight savings rules are in |
| 708 | * effect. This is always a non-negative number, most commonly either |
| 709 | * 3,600,000 (one hour) or zero. |
| 710 | * |
| 711 | * @stable ICU 2.6 |
| 712 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 713 | U_CAPI int32_t U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 714 | ucal_getDSTSavings(const UChar* zoneID, UErrorCode* ec); |
| 715 | |
| 716 | /** |
| 717 | * Get the current date and time. |
| 718 | * The value returned is represented as milliseconds from the epoch. |
| 719 | * @return The current date and time. |
| 720 | * @stable ICU 2.0 |
| 721 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 722 | U_CAPI UDate U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 723 | ucal_getNow(void); |
| 724 | |
| 725 | /** |
| 726 | * Open a UCalendar. |
| 727 | * A UCalendar may be used to convert a millisecond value to a year, |
| 728 | * month, and day. |
| 729 | * <p> |
| 730 | * Note: When unknown TimeZone ID is specified or if the TimeZone ID specified is "Etc/Unknown", |
| 731 | * the UCalendar returned by the function is initialized with GMT zone with TimeZone ID |
| 732 | * <code>UCAL_UNKNOWN_ZONE_ID</code> ("Etc/Unknown") without any errors/warnings. If you want |
| 733 | * to check if a TimeZone ID is valid prior to this function, use <code>ucal_getCanonicalTimeZoneID</code>. |
| 734 | * |
| 735 | * @param zoneID The desired TimeZone ID. If 0, use the default time zone. |
| 736 | * @param len The length of zoneID, or -1 if null-terminated. |
| 737 | * @param locale The desired locale |
| 738 | * @param type The type of UCalendar to open. This can be UCAL_GREGORIAN to open the Gregorian |
| 739 | * calendar for the locale, or UCAL_DEFAULT to open the default calendar for the locale (the |
| 740 | * default calendar may also be Gregorian). To open a specific non-Gregorian calendar for the |
| 741 | * locale, use uloc_setKeywordValue to set the value of the calendar keyword for the locale |
| 742 | * and then pass the locale to ucal_open with UCAL_DEFAULT as the type. |
| 743 | * @param status A pointer to an UErrorCode to receive any errors |
| 744 | * @return A pointer to a UCalendar, or 0 if an error occurred. |
| 745 | * @see #UCAL_UNKNOWN_ZONE_ID |
| 746 | * @stable ICU 2.0 |
| 747 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 748 | U_CAPI UCalendar* U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 749 | ucal_open(const UChar* zoneID, |
| 750 | int32_t len, |
| 751 | const char* locale, |
| 752 | UCalendarType type, |
| 753 | UErrorCode* status); |
| 754 | |
| 755 | /** |
| 756 | * Close a UCalendar. |
| 757 | * Once closed, a UCalendar may no longer be used. |
| 758 | * @param cal The UCalendar to close. |
| 759 | * @stable ICU 2.0 |
| 760 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 761 | U_CAPI void U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 762 | ucal_close(UCalendar *cal); |
| 763 | |
| 764 | #if U_SHOW_CPLUSPLUS_API |
| 765 | |
| 766 | U_NAMESPACE_BEGIN |
| 767 | |
| 768 | /** |
| 769 | * \class LocalUCalendarPointer |
| 770 | * "Smart pointer" class, closes a UCalendar via ucal_close(). |
| 771 | * For most methods see the LocalPointerBase base class. |
| 772 | * |
| 773 | * @see LocalPointerBase |
| 774 | * @see LocalPointer |
| 775 | * @stable ICU 4.4 |
| 776 | */ |
| 777 | U_DEFINE_LOCAL_OPEN_POINTER(LocalUCalendarPointer, UCalendar, ucal_close); |
| 778 | |
| 779 | U_NAMESPACE_END |
| 780 | |
| 781 | #endif |
| 782 | |
| 783 | /** |
| 784 | * Open a copy of a UCalendar. |
| 785 | * This function performs a deep copy. |
| 786 | * @param cal The calendar to copy |
| 787 | * @param status A pointer to an UErrorCode to receive any errors. |
| 788 | * @return A pointer to a UCalendar identical to cal. |
| 789 | * @stable ICU 4.0 |
| 790 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 791 | U_CAPI UCalendar* U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 792 | ucal_clone(const UCalendar* cal, |
| 793 | UErrorCode* status); |
| 794 | |
| 795 | /** |
| 796 | * Set the TimeZone used by a UCalendar. |
| 797 | * A UCalendar uses a timezone for converting from Greenwich time to local time. |
| 798 | * @param cal The UCalendar to set. |
| 799 | * @param zoneID The desired TimeZone ID. If 0, use the default time zone. |
| 800 | * @param len The length of zoneID, or -1 if null-terminated. |
| 801 | * @param status A pointer to an UErrorCode to receive any errors. |
| 802 | * @stable ICU 2.0 |
| 803 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 804 | U_CAPI void U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 805 | ucal_setTimeZone(UCalendar* cal, |
| 806 | const UChar* zoneID, |
| 807 | int32_t len, |
| 808 | UErrorCode* status); |
| 809 | |
| 810 | /** |
| 811 | * Get the ID of the UCalendar's time zone. |
| 812 | * |
| 813 | * @param cal The UCalendar to query. |
| 814 | * @param result Receives the UCalendar's time zone ID. |
| 815 | * @param resultLength The maximum size of result. |
| 816 | * @param status Receives the status. |
| 817 | * @return The total buffer size needed; if greater than resultLength, the output was truncated. |
| 818 | * @stable ICU 51 |
| 819 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 820 | U_CAPI int32_t U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 821 | ucal_getTimeZoneID(const UCalendar *cal, |
| 822 | UChar *result, |
| 823 | int32_t resultLength, |
| 824 | UErrorCode *status); |
| 825 | |
| 826 | /** |
| 827 | * Possible formats for a UCalendar's display name |
| 828 | * @stable ICU 2.0 |
| 829 | */ |
| 830 | enum UCalendarDisplayNameType { |
| 831 | /** Standard display name */ |
| 832 | UCAL_STANDARD, |
| 833 | /** Short standard display name */ |
| 834 | UCAL_SHORT_STANDARD, |
| 835 | /** Daylight savings display name */ |
| 836 | UCAL_DST, |
| 837 | /** Short daylight savings display name */ |
| 838 | UCAL_SHORT_DST |
| 839 | }; |
| 840 | |
| 841 | /** @stable ICU 2.0 */ |
| 842 | typedef enum UCalendarDisplayNameType UCalendarDisplayNameType; |
| 843 | |
| 844 | /** |
| 845 | * Get the display name for a UCalendar's TimeZone. |
| 846 | * A display name is suitable for presentation to a user. |
| 847 | * @param cal The UCalendar to query. |
| 848 | * @param type The desired display name format; one of UCAL_STANDARD, UCAL_SHORT_STANDARD, |
| 849 | * UCAL_DST, UCAL_SHORT_DST |
| 850 | * @param locale The desired locale for the display name. |
| 851 | * @param result A pointer to a buffer to receive the formatted number. |
| 852 | * @param resultLength The maximum size of result. |
| 853 | * @param status A pointer to an UErrorCode to receive any errors |
| 854 | * @return The total buffer size needed; if greater than resultLength, the output was truncated. |
| 855 | * @stable ICU 2.0 |
| 856 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 857 | U_CAPI int32_t U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 858 | ucal_getTimeZoneDisplayName(const UCalendar* cal, |
| 859 | UCalendarDisplayNameType type, |
| 860 | const char* locale, |
| 861 | UChar* result, |
| 862 | int32_t resultLength, |
| 863 | UErrorCode* status); |
| 864 | |
| 865 | /** |
| 866 | * Determine if a UCalendar is currently in daylight savings time. |
| 867 | * Daylight savings time is not used in all parts of the world. |
| 868 | * @param cal The UCalendar to query. |
| 869 | * @param status A pointer to an UErrorCode to receive any errors |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 870 | * @return true if cal is currently in daylight savings time, false otherwise |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 871 | * @stable ICU 2.0 |
| 872 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 873 | U_CAPI UBool U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 874 | ucal_inDaylightTime(const UCalendar* cal, |
| 875 | UErrorCode* status ); |
| 876 | |
| 877 | /** |
| 878 | * Sets the GregorianCalendar change date. This is the point when the switch from |
| 879 | * Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October |
| 880 | * 15, 1582. Previous to this time and date will be Julian dates. |
| 881 | * |
| 882 | * This function works only for Gregorian calendars. If the UCalendar is not |
| 883 | * an instance of a Gregorian calendar, then a U_UNSUPPORTED_ERROR |
| 884 | * error code is set. |
| 885 | * |
| 886 | * @param cal The calendar object. |
| 887 | * @param date The given Gregorian cutover date. |
| 888 | * @param pErrorCode Pointer to a standard ICU error code. Its input value must |
| 889 | * pass the U_SUCCESS() test, or else the function returns |
| 890 | * immediately. Check for U_FAILURE() on output or use with |
| 891 | * function chaining. (See User Guide for details.) |
| 892 | * |
| 893 | * @see GregorianCalendar::setGregorianChange |
| 894 | * @see ucal_getGregorianChange |
| 895 | * @stable ICU 3.6 |
| 896 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 897 | U_CAPI void U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 898 | ucal_setGregorianChange(UCalendar *cal, UDate date, UErrorCode *pErrorCode); |
| 899 | |
| 900 | /** |
| 901 | * Gets the Gregorian Calendar change date. This is the point when the switch from |
| 902 | * Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October |
| 903 | * 15, 1582. Previous to this time and date will be Julian dates. |
| 904 | * |
| 905 | * This function works only for Gregorian calendars. If the UCalendar is not |
| 906 | * an instance of a Gregorian calendar, then a U_UNSUPPORTED_ERROR |
| 907 | * error code is set. |
| 908 | * |
| 909 | * @param cal The calendar object. |
| 910 | * @param pErrorCode Pointer to a standard ICU error code. Its input value must |
| 911 | * pass the U_SUCCESS() test, or else the function returns |
| 912 | * immediately. Check for U_FAILURE() on output or use with |
| 913 | * function chaining. (See User Guide for details.) |
| 914 | * @return The Gregorian cutover time for this calendar. |
| 915 | * |
| 916 | * @see GregorianCalendar::getGregorianChange |
| 917 | * @see ucal_setGregorianChange |
| 918 | * @stable ICU 3.6 |
| 919 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 920 | U_CAPI UDate U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 921 | ucal_getGregorianChange(const UCalendar *cal, UErrorCode *pErrorCode); |
| 922 | |
| 923 | /** |
| 924 | * Types of UCalendar attributes |
| 925 | * @stable ICU 2.0 |
| 926 | */ |
| 927 | enum UCalendarAttribute { |
| 928 | /** |
| 929 | * Lenient parsing |
| 930 | * @stable ICU 2.0 |
| 931 | */ |
| 932 | UCAL_LENIENT, |
| 933 | /** |
| 934 | * First day of week |
| 935 | * @stable ICU 2.0 |
| 936 | */ |
| 937 | UCAL_FIRST_DAY_OF_WEEK, |
| 938 | /** |
| 939 | * Minimum number of days in first week |
| 940 | * @stable ICU 2.0 |
| 941 | */ |
| 942 | UCAL_MINIMAL_DAYS_IN_FIRST_WEEK, |
| 943 | /** |
| 944 | * The behavior for handling wall time repeating multiple times |
| 945 | * at negative time zone offset transitions |
| 946 | * @stable ICU 49 |
| 947 | */ |
| 948 | UCAL_REPEATED_WALL_TIME, |
| 949 | /** |
| 950 | * The behavior for handling skipped wall time at positive time |
| 951 | * zone offset transitions. |
| 952 | * @stable ICU 49 |
| 953 | */ |
| 954 | UCAL_SKIPPED_WALL_TIME |
| 955 | }; |
| 956 | |
| 957 | /** @stable ICU 2.0 */ |
| 958 | typedef enum UCalendarAttribute UCalendarAttribute; |
| 959 | |
| 960 | /** |
| 961 | * Options for handling ambiguous wall time at time zone |
| 962 | * offset transitions. |
| 963 | * @stable ICU 49 |
| 964 | */ |
| 965 | enum UCalendarWallTimeOption { |
| 966 | /** |
| 967 | * An ambiguous wall time to be interpreted as the latest. |
| 968 | * This option is valid for UCAL_REPEATED_WALL_TIME and |
| 969 | * UCAL_SKIPPED_WALL_TIME. |
| 970 | * @stable ICU 49 |
| 971 | */ |
| 972 | UCAL_WALLTIME_LAST, |
| 973 | /** |
| 974 | * An ambiguous wall time to be interpreted as the earliest. |
| 975 | * This option is valid for UCAL_REPEATED_WALL_TIME and |
| 976 | * UCAL_SKIPPED_WALL_TIME. |
| 977 | * @stable ICU 49 |
| 978 | */ |
| 979 | UCAL_WALLTIME_FIRST, |
| 980 | /** |
| 981 | * An ambiguous wall time to be interpreted as the next valid |
| 982 | * wall time. This option is valid for UCAL_SKIPPED_WALL_TIME. |
| 983 | * @stable ICU 49 |
| 984 | */ |
| 985 | UCAL_WALLTIME_NEXT_VALID |
| 986 | }; |
| 987 | /** @stable ICU 49 */ |
| 988 | typedef enum UCalendarWallTimeOption UCalendarWallTimeOption; |
| 989 | |
| 990 | /** |
| 991 | * Get a numeric attribute associated with a UCalendar. |
| 992 | * Numeric attributes include the first day of the week, or the minimal numbers |
| 993 | * of days in the first week of the month. |
| 994 | * @param cal The UCalendar to query. |
| 995 | * @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK, |
| 996 | * UCAL_MINIMAL_DAYS_IN_FIRST_WEEK, UCAL_REPEATED_WALL_TIME or UCAL_SKIPPED_WALL_TIME |
| 997 | * @return The value of attr. |
| 998 | * @see ucal_setAttribute |
| 999 | * @stable ICU 2.0 |
| 1000 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1001 | U_CAPI int32_t U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1002 | ucal_getAttribute(const UCalendar* cal, |
| 1003 | UCalendarAttribute attr); |
| 1004 | |
| 1005 | /** |
| 1006 | * Set a numeric attribute associated with a UCalendar. |
| 1007 | * Numeric attributes include the first day of the week, or the minimal numbers |
| 1008 | * of days in the first week of the month. |
| 1009 | * @param cal The UCalendar to set. |
| 1010 | * @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK, |
| 1011 | * UCAL_MINIMAL_DAYS_IN_FIRST_WEEK, UCAL_REPEATED_WALL_TIME or UCAL_SKIPPED_WALL_TIME |
| 1012 | * @param newValue The new value of attr. |
| 1013 | * @see ucal_getAttribute |
| 1014 | * @stable ICU 2.0 |
| 1015 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1016 | U_CAPI void U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1017 | ucal_setAttribute(UCalendar* cal, |
| 1018 | UCalendarAttribute attr, |
| 1019 | int32_t newValue); |
| 1020 | |
| 1021 | /** |
| 1022 | * Get a locale for which calendars are available. |
| 1023 | * A UCalendar in a locale returned by this function will contain the correct |
| 1024 | * day and month names for the locale. |
| 1025 | * @param localeIndex The index of the desired locale. |
| 1026 | * @return A locale for which calendars are available, or 0 if none. |
| 1027 | * @see ucal_countAvailable |
| 1028 | * @stable ICU 2.0 |
| 1029 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1030 | U_CAPI const char* U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1031 | ucal_getAvailable(int32_t localeIndex); |
| 1032 | |
| 1033 | /** |
| 1034 | * Determine how many locales have calendars available. |
| 1035 | * This function is most useful as determining the loop ending condition for |
| 1036 | * calls to \ref ucal_getAvailable. |
| 1037 | * @return The number of locales for which calendars are available. |
| 1038 | * @see ucal_getAvailable |
| 1039 | * @stable ICU 2.0 |
| 1040 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1041 | U_CAPI int32_t U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1042 | ucal_countAvailable(void); |
| 1043 | |
| 1044 | /** |
| 1045 | * Get a UCalendar's current time in millis. |
| 1046 | * The time is represented as milliseconds from the epoch. |
| 1047 | * @param cal The UCalendar to query. |
| 1048 | * @param status A pointer to an UErrorCode to receive any errors |
| 1049 | * @return The calendar's current time in millis. |
| 1050 | * @see ucal_setMillis |
| 1051 | * @see ucal_setDate |
| 1052 | * @see ucal_setDateTime |
| 1053 | * @stable ICU 2.0 |
| 1054 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1055 | U_CAPI UDate U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1056 | ucal_getMillis(const UCalendar* cal, |
| 1057 | UErrorCode* status); |
| 1058 | |
| 1059 | /** |
| 1060 | * Set a UCalendar's current time in millis. |
| 1061 | * The time is represented as milliseconds from the epoch. |
| 1062 | * @param cal The UCalendar to set. |
| 1063 | * @param dateTime The desired date and time. |
| 1064 | * @param status A pointer to an UErrorCode to receive any errors |
| 1065 | * @see ucal_getMillis |
| 1066 | * @see ucal_setDate |
| 1067 | * @see ucal_setDateTime |
| 1068 | * @stable ICU 2.0 |
| 1069 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1070 | U_CAPI void U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1071 | ucal_setMillis(UCalendar* cal, |
| 1072 | UDate dateTime, |
| 1073 | UErrorCode* status ); |
| 1074 | |
| 1075 | /** |
| 1076 | * Set a UCalendar's current date. |
| 1077 | * The date is represented as a series of 32-bit integers. |
| 1078 | * @param cal The UCalendar to set. |
| 1079 | * @param year The desired year. |
| 1080 | * @param month The desired month; one of UCAL_JANUARY, UCAL_FEBRUARY, UCAL_MARCH, UCAL_APRIL, UCAL_MAY, |
| 1081 | * UCAL_JUNE, UCAL_JULY, UCAL_AUGUST, UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBER, UCAL_DECEMBER, UCAL_UNDECIMBER |
| 1082 | * @param date The desired day of the month. |
| 1083 | * @param status A pointer to an UErrorCode to receive any errors |
| 1084 | * @see ucal_getMillis |
| 1085 | * @see ucal_setMillis |
| 1086 | * @see ucal_setDateTime |
| 1087 | * @stable ICU 2.0 |
| 1088 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1089 | U_CAPI void U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1090 | ucal_setDate(UCalendar* cal, |
| 1091 | int32_t year, |
| 1092 | int32_t month, |
| 1093 | int32_t date, |
| 1094 | UErrorCode* status); |
| 1095 | |
| 1096 | /** |
| 1097 | * Set a UCalendar's current date. |
| 1098 | * The date is represented as a series of 32-bit integers. |
| 1099 | * @param cal The UCalendar to set. |
| 1100 | * @param year The desired year. |
| 1101 | * @param month The desired month; one of UCAL_JANUARY, UCAL_FEBRUARY, UCAL_MARCH, UCAL_APRIL, UCAL_MAY, |
| 1102 | * UCAL_JUNE, UCAL_JULY, UCAL_AUGUST, UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBER, UCAL_DECEMBER, UCAL_UNDECIMBER |
| 1103 | * @param date The desired day of the month. |
| 1104 | * @param hour The desired hour of day. |
| 1105 | * @param minute The desired minute. |
| 1106 | * @param second The desirec second. |
| 1107 | * @param status A pointer to an UErrorCode to receive any errors |
| 1108 | * @see ucal_getMillis |
| 1109 | * @see ucal_setMillis |
| 1110 | * @see ucal_setDate |
| 1111 | * @stable ICU 2.0 |
| 1112 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1113 | U_CAPI void U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1114 | ucal_setDateTime(UCalendar* cal, |
| 1115 | int32_t year, |
| 1116 | int32_t month, |
| 1117 | int32_t date, |
| 1118 | int32_t hour, |
| 1119 | int32_t minute, |
| 1120 | int32_t second, |
| 1121 | UErrorCode* status); |
| 1122 | |
| 1123 | /** |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1124 | * Returns true if two UCalendars are equivalent. Equivalent |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1125 | * UCalendars will behave identically, but they may be set to |
| 1126 | * different times. |
| 1127 | * @param cal1 The first of the UCalendars to compare. |
| 1128 | * @param cal2 The second of the UCalendars to compare. |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1129 | * @return true if cal1 and cal2 are equivalent, false otherwise. |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1130 | * @stable ICU 2.0 |
| 1131 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1132 | U_CAPI UBool U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1133 | ucal_equivalentTo(const UCalendar* cal1, |
| 1134 | const UCalendar* cal2); |
| 1135 | |
| 1136 | /** |
| 1137 | * Add a specified signed amount to a particular field in a UCalendar. |
| 1138 | * This can modify more significant fields in the calendar. |
| 1139 | * Adding a positive value always means moving forward in time, so for the Gregorian calendar, |
| 1140 | * starting with 100 BC and adding +1 to year results in 99 BC (even though this actually reduces |
| 1141 | * the numeric value of the field itself). |
| 1142 | * @param cal The UCalendar to which to add. |
| 1143 | * @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, |
| 1144 | * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, |
| 1145 | * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, |
| 1146 | * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. |
| 1147 | * @param amount The signed amount to add to field. If the amount causes the value |
| 1148 | * to exceed to maximum or minimum values for that field, other fields are modified |
| 1149 | * to preserve the magnitude of the change. |
| 1150 | * @param status A pointer to an UErrorCode to receive any errors |
| 1151 | * @see ucal_roll |
| 1152 | * @stable ICU 2.0 |
| 1153 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1154 | U_CAPI void U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1155 | ucal_add(UCalendar* cal, |
| 1156 | UCalendarDateFields field, |
| 1157 | int32_t amount, |
| 1158 | UErrorCode* status); |
| 1159 | |
| 1160 | /** |
| 1161 | * Add a specified signed amount to a particular field in a UCalendar. |
| 1162 | * This will not modify more significant fields in the calendar. |
| 1163 | * Rolling by a positive value always means moving forward in time (unless the limit of the |
| 1164 | * field is reached, in which case it may pin or wrap), so for Gregorian calendar, |
| 1165 | * starting with 100 BC and rolling the year by +1 results in 99 BC. |
| 1166 | * When eras have a definite beginning and end (as in the Chinese calendar, or as in most eras in the |
| 1167 | * Japanese calendar) then rolling the year past either limit of the era will cause the year to wrap around. |
| 1168 | * When eras only have a limit at one end, then attempting to roll the year past that limit will result in |
| 1169 | * pinning the year at that limit. Note that for most calendars in which era 0 years move forward in time |
| 1170 | * (such as Buddhist, Hebrew, or Islamic), it is possible for add or roll to result in negative years for |
| 1171 | * era 0 (that is the only way to represent years before the calendar epoch). |
| 1172 | * @param cal The UCalendar to which to add. |
| 1173 | * @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, |
| 1174 | * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, |
| 1175 | * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, |
| 1176 | * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. |
| 1177 | * @param amount The signed amount to add to field. If the amount causes the value |
| 1178 | * to exceed to maximum or minimum values for that field, the field is pinned to a permissible |
| 1179 | * value. |
| 1180 | * @param status A pointer to an UErrorCode to receive any errors |
| 1181 | * @see ucal_add |
| 1182 | * @stable ICU 2.0 |
| 1183 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1184 | U_CAPI void U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1185 | ucal_roll(UCalendar* cal, |
| 1186 | UCalendarDateFields field, |
| 1187 | int32_t amount, |
| 1188 | UErrorCode* status); |
| 1189 | |
| 1190 | /** |
| 1191 | * Get the current value of a field from a UCalendar. |
| 1192 | * All fields are represented as 32-bit integers. |
| 1193 | * @param cal The UCalendar to query. |
| 1194 | * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, |
| 1195 | * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, |
| 1196 | * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, |
| 1197 | * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. |
| 1198 | * @param status A pointer to an UErrorCode to receive any errors |
| 1199 | * @return The value of the desired field. |
| 1200 | * @see ucal_set |
| 1201 | * @see ucal_isSet |
| 1202 | * @see ucal_clearField |
| 1203 | * @see ucal_clear |
| 1204 | * @stable ICU 2.0 |
| 1205 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1206 | U_CAPI int32_t U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1207 | ucal_get(const UCalendar* cal, |
| 1208 | UCalendarDateFields field, |
| 1209 | UErrorCode* status ); |
| 1210 | |
| 1211 | /** |
| 1212 | * Set the value of a field in a UCalendar. |
| 1213 | * All fields are represented as 32-bit integers. |
| 1214 | * @param cal The UCalendar to set. |
| 1215 | * @param field The field to set; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, |
| 1216 | * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, |
| 1217 | * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, |
| 1218 | * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. |
| 1219 | * @param value The desired value of field. |
| 1220 | * @see ucal_get |
| 1221 | * @see ucal_isSet |
| 1222 | * @see ucal_clearField |
| 1223 | * @see ucal_clear |
| 1224 | * @stable ICU 2.0 |
| 1225 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1226 | U_CAPI void U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1227 | ucal_set(UCalendar* cal, |
| 1228 | UCalendarDateFields field, |
| 1229 | int32_t value); |
| 1230 | |
| 1231 | /** |
| 1232 | * Determine if a field in a UCalendar is set. |
| 1233 | * All fields are represented as 32-bit integers. |
| 1234 | * @param cal The UCalendar to query. |
| 1235 | * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, |
| 1236 | * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, |
| 1237 | * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, |
| 1238 | * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1239 | * @return true if field is set, false otherwise. |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1240 | * @see ucal_get |
| 1241 | * @see ucal_set |
| 1242 | * @see ucal_clearField |
| 1243 | * @see ucal_clear |
| 1244 | * @stable ICU 2.0 |
| 1245 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1246 | U_CAPI UBool U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1247 | ucal_isSet(const UCalendar* cal, |
| 1248 | UCalendarDateFields field); |
| 1249 | |
| 1250 | /** |
| 1251 | * Clear a field in a UCalendar. |
| 1252 | * All fields are represented as 32-bit integers. |
| 1253 | * @param cal The UCalendar containing the field to clear. |
| 1254 | * @param field The field to clear; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, |
| 1255 | * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, |
| 1256 | * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, |
| 1257 | * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. |
| 1258 | * @see ucal_get |
| 1259 | * @see ucal_set |
| 1260 | * @see ucal_isSet |
| 1261 | * @see ucal_clear |
| 1262 | * @stable ICU 2.0 |
| 1263 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1264 | U_CAPI void U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1265 | ucal_clearField(UCalendar* cal, |
| 1266 | UCalendarDateFields field); |
| 1267 | |
| 1268 | /** |
| 1269 | * Clear all fields in a UCalendar. |
| 1270 | * All fields are represented as 32-bit integers. |
| 1271 | * @param calendar The UCalendar to clear. |
| 1272 | * @see ucal_get |
| 1273 | * @see ucal_set |
| 1274 | * @see ucal_isSet |
| 1275 | * @see ucal_clearField |
| 1276 | * @stable ICU 2.0 |
| 1277 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1278 | U_CAPI void U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1279 | ucal_clear(UCalendar* calendar); |
| 1280 | |
| 1281 | /** |
| 1282 | * Possible limit values for a UCalendar |
| 1283 | * @stable ICU 2.0 |
| 1284 | */ |
| 1285 | enum UCalendarLimitType { |
| 1286 | /** Minimum value */ |
| 1287 | UCAL_MINIMUM, |
| 1288 | /** Maximum value */ |
| 1289 | UCAL_MAXIMUM, |
| 1290 | /** Greatest minimum value */ |
| 1291 | UCAL_GREATEST_MINIMUM, |
| 1292 | /** Leaest maximum value */ |
| 1293 | UCAL_LEAST_MAXIMUM, |
| 1294 | /** Actual minimum value */ |
| 1295 | UCAL_ACTUAL_MINIMUM, |
| 1296 | /** Actual maximum value */ |
| 1297 | UCAL_ACTUAL_MAXIMUM |
| 1298 | }; |
| 1299 | |
| 1300 | /** @stable ICU 2.0 */ |
| 1301 | typedef enum UCalendarLimitType UCalendarLimitType; |
| 1302 | |
| 1303 | /** |
| 1304 | * Determine a limit for a field in a UCalendar. |
| 1305 | * A limit is a maximum or minimum value for a field. |
| 1306 | * @param cal The UCalendar to query. |
| 1307 | * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, |
| 1308 | * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, |
| 1309 | * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, |
| 1310 | * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. |
| 1311 | * @param type The desired critical point; one of UCAL_MINIMUM, UCAL_MAXIMUM, UCAL_GREATEST_MINIMUM, |
| 1312 | * UCAL_LEAST_MAXIMUM, UCAL_ACTUAL_MINIMUM, UCAL_ACTUAL_MAXIMUM |
| 1313 | * @param status A pointer to an UErrorCode to receive any errors. |
| 1314 | * @return The requested value. |
| 1315 | * @stable ICU 2.0 |
| 1316 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1317 | U_CAPI int32_t U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1318 | ucal_getLimit(const UCalendar* cal, |
| 1319 | UCalendarDateFields field, |
| 1320 | UCalendarLimitType type, |
| 1321 | UErrorCode* status); |
| 1322 | |
| 1323 | /** Get the locale for this calendar object. You can choose between valid and actual locale. |
| 1324 | * @param cal The calendar object |
| 1325 | * @param type type of the locale we're looking for (valid or actual) |
| 1326 | * @param status error code for the operation |
| 1327 | * @return the locale name |
| 1328 | * @stable ICU 2.8 |
| 1329 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1330 | U_CAPI const char * U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1331 | ucal_getLocaleByType(const UCalendar *cal, ULocDataLocaleType type, UErrorCode* status); |
| 1332 | |
| 1333 | /** |
| 1334 | * Returns the timezone data version currently used by ICU. |
| 1335 | * @param status error code for the operation |
| 1336 | * @return the version string, such as "2007f" |
| 1337 | * @stable ICU 3.8 |
| 1338 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1339 | U_CAPI const char * U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1340 | ucal_getTZDataVersion(UErrorCode* status); |
| 1341 | |
| 1342 | /** |
| 1343 | * Returns the canonical system timezone ID or the normalized |
| 1344 | * custom time zone ID for the given time zone ID. |
| 1345 | * @param id The input timezone ID to be canonicalized. |
| 1346 | * @param len The length of id, or -1 if null-terminated. |
| 1347 | * @param result The buffer receives the canonical system timezone ID |
| 1348 | * or the custom timezone ID in normalized format. |
| 1349 | * @param resultCapacity The capacity of the result buffer. |
| 1350 | * @param isSystemID Receives if the given ID is a known system |
| 1351 | * timezone ID. |
| 1352 | * @param status Receives the status. When the given timezone ID |
| 1353 | * is neither a known system time zone ID nor a |
| 1354 | * valid custom timezone ID, U_ILLEGAL_ARGUMENT_ERROR |
| 1355 | * is set. |
| 1356 | * @return The result string length, not including the terminating |
| 1357 | * null. |
| 1358 | * @stable ICU 4.0 |
| 1359 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1360 | U_CAPI int32_t U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1361 | ucal_getCanonicalTimeZoneID(const UChar* id, int32_t len, |
| 1362 | UChar* result, int32_t resultCapacity, UBool *isSystemID, UErrorCode* status); |
| 1363 | /** |
| 1364 | * Get the resource keyword value string designating the calendar type for the UCalendar. |
| 1365 | * @param cal The UCalendar to query. |
| 1366 | * @param status The error code for the operation. |
| 1367 | * @return The resource keyword value string. |
| 1368 | * @stable ICU 4.2 |
| 1369 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1370 | U_CAPI const char * U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1371 | ucal_getType(const UCalendar *cal, UErrorCode* status); |
| 1372 | |
| 1373 | /** |
| 1374 | * Given a key and a locale, returns an array of string values in a preferred |
| 1375 | * order that would make a difference. These are all and only those values where |
| 1376 | * the open (creation) of the service with the locale formed from the input locale |
| 1377 | * plus input keyword and that value has different behavior than creation with the |
| 1378 | * input locale alone. |
| 1379 | * @param key one of the keys supported by this service. For now, only |
| 1380 | * "calendar" is supported. |
| 1381 | * @param locale the locale |
| 1382 | * @param commonlyUsed if set to true it will return only commonly used values |
| 1383 | * with the given locale in preferred order. Otherwise, |
| 1384 | * it will return all the available values for the locale. |
| 1385 | * @param status error status |
| 1386 | * @return a string enumeration over keyword values for the given key and the locale. |
| 1387 | * @stable ICU 4.2 |
| 1388 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1389 | U_CAPI UEnumeration* U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1390 | ucal_getKeywordValuesForLocale(const char* key, |
| 1391 | const char* locale, |
| 1392 | UBool commonlyUsed, |
| 1393 | UErrorCode* status); |
| 1394 | |
| 1395 | |
| 1396 | /** Weekday types, as returned by ucal_getDayOfWeekType(). |
| 1397 | * @stable ICU 4.4 |
| 1398 | */ |
| 1399 | enum UCalendarWeekdayType { |
| 1400 | /** |
| 1401 | * Designates a full weekday (no part of the day is included in the weekend). |
| 1402 | * @stable ICU 4.4 |
| 1403 | */ |
| 1404 | UCAL_WEEKDAY, |
| 1405 | /** |
| 1406 | * Designates a full weekend day (the entire day is included in the weekend). |
| 1407 | * @stable ICU 4.4 |
| 1408 | */ |
| 1409 | UCAL_WEEKEND, |
| 1410 | /** |
| 1411 | * Designates a day that starts as a weekday and transitions to the weekend. |
| 1412 | * Call ucal_getWeekendTransition() to get the time of transition. |
| 1413 | * @stable ICU 4.4 |
| 1414 | */ |
| 1415 | UCAL_WEEKEND_ONSET, |
| 1416 | /** |
| 1417 | * Designates a day that starts as the weekend and transitions to a weekday. |
| 1418 | * Call ucal_getWeekendTransition() to get the time of transition. |
| 1419 | * @stable ICU 4.4 |
| 1420 | */ |
| 1421 | UCAL_WEEKEND_CEASE |
| 1422 | }; |
| 1423 | |
| 1424 | /** @stable ICU 4.4 */ |
| 1425 | typedef enum UCalendarWeekdayType UCalendarWeekdayType; |
| 1426 | |
| 1427 | /** |
| 1428 | * Returns whether the given day of the week is a weekday, a weekend day, |
| 1429 | * or a day that transitions from one to the other, for the locale and |
| 1430 | * calendar system associated with this UCalendar (the locale's region is |
| 1431 | * often the most determinant factor). If a transition occurs at midnight, |
| 1432 | * then the days before and after the transition will have the |
| 1433 | * type UCAL_WEEKDAY or UCAL_WEEKEND. If a transition occurs at a time |
| 1434 | * other than midnight, then the day of the transition will have |
| 1435 | * the type UCAL_WEEKEND_ONSET or UCAL_WEEKEND_CEASE. In this case, the |
| 1436 | * function ucal_getWeekendTransition() will return the point of |
| 1437 | * transition. |
| 1438 | * @param cal The UCalendar to query. |
| 1439 | * @param dayOfWeek The day of the week whose type is desired (UCAL_SUNDAY..UCAL_SATURDAY). |
| 1440 | * @param status The error code for the operation. |
| 1441 | * @return The UCalendarWeekdayType for the day of the week. |
| 1442 | * @stable ICU 4.4 |
| 1443 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1444 | U_CAPI UCalendarWeekdayType U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1445 | ucal_getDayOfWeekType(const UCalendar *cal, UCalendarDaysOfWeek dayOfWeek, UErrorCode* status); |
| 1446 | |
| 1447 | /** |
| 1448 | * Returns the time during the day at which the weekend begins or ends in |
| 1449 | * this calendar system. If ucal_getDayOfWeekType() returns UCAL_WEEKEND_ONSET |
| 1450 | * for the specified dayOfWeek, return the time at which the weekend begins. |
| 1451 | * If ucal_getDayOfWeekType() returns UCAL_WEEKEND_CEASE for the specified dayOfWeek, |
| 1452 | * return the time at which the weekend ends. If ucal_getDayOfWeekType() returns |
| 1453 | * some other UCalendarWeekdayType for the specified dayOfWeek, is it an error condition |
| 1454 | * (U_ILLEGAL_ARGUMENT_ERROR). |
| 1455 | * @param cal The UCalendar to query. |
| 1456 | * @param dayOfWeek The day of the week for which the weekend transition time is |
| 1457 | * desired (UCAL_SUNDAY..UCAL_SATURDAY). |
| 1458 | * @param status The error code for the operation. |
| 1459 | * @return The milliseconds after midnight at which the weekend begins or ends. |
| 1460 | * @stable ICU 4.4 |
| 1461 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1462 | U_CAPI int32_t U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1463 | ucal_getWeekendTransition(const UCalendar *cal, UCalendarDaysOfWeek dayOfWeek, UErrorCode *status); |
| 1464 | |
| 1465 | /** |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1466 | * Returns true if the given UDate is in the weekend in |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1467 | * this calendar system. |
| 1468 | * @param cal The UCalendar to query. |
| 1469 | * @param date The UDate in question. |
| 1470 | * @param status The error code for the operation. |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1471 | * @return true if the given UDate is in the weekend in |
| 1472 | * this calendar system, false otherwise. |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1473 | * @stable ICU 4.4 |
| 1474 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1475 | U_CAPI UBool U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1476 | ucal_isWeekend(const UCalendar *cal, UDate date, UErrorCode *status); |
| 1477 | |
| 1478 | /** |
| 1479 | * Return the difference between the target time and the time this calendar object is currently set to. |
| 1480 | * If the target time is after the current calendar setting, the the returned value will be positive. |
| 1481 | * The field parameter specifies the units of the return value. For example, if field is UCAL_MONTH |
| 1482 | * and ucal_getFieldDifference returns 3, then the target time is 3 to less than 4 months after the |
| 1483 | * current calendar setting. |
| 1484 | * |
| 1485 | * As a side effect of this call, this calendar is advanced toward target by the given amount. That is, |
| 1486 | * calling this function has the side effect of calling ucal_add on this calendar with the specified |
| 1487 | * field and an amount equal to the return value from this function. |
| 1488 | * |
| 1489 | * A typical way of using this function is to call it first with the largest field of interest, then |
| 1490 | * with progressively smaller fields. |
| 1491 | * |
| 1492 | * @param cal The UCalendar to compare and update. |
| 1493 | * @param target The target date to compare to the current calendar setting. |
| 1494 | * @param field The field to compare; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH, |
| 1495 | * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK, |
| 1496 | * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND, |
| 1497 | * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET. |
| 1498 | * @param status A pointer to an UErrorCode to receive any errors |
| 1499 | * @return The date difference for the specified field. |
| 1500 | * @stable ICU 4.8 |
| 1501 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1502 | U_CAPI int32_t U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1503 | ucal_getFieldDifference(UCalendar* cal, |
| 1504 | UDate target, |
| 1505 | UCalendarDateFields field, |
| 1506 | UErrorCode* status); |
| 1507 | |
| 1508 | /** |
| 1509 | * Time zone transition types for ucal_getTimeZoneTransitionDate |
| 1510 | * @stable ICU 50 |
| 1511 | */ |
| 1512 | enum UTimeZoneTransitionType { |
| 1513 | /** |
| 1514 | * Get the next transition after the current date, |
| 1515 | * i.e. excludes the current date |
| 1516 | * @stable ICU 50 |
| 1517 | */ |
| 1518 | UCAL_TZ_TRANSITION_NEXT, |
| 1519 | /** |
| 1520 | * Get the next transition on or after the current date, |
| 1521 | * i.e. may include the current date |
| 1522 | * @stable ICU 50 |
| 1523 | */ |
| 1524 | UCAL_TZ_TRANSITION_NEXT_INCLUSIVE, |
| 1525 | /** |
| 1526 | * Get the previous transition before the current date, |
| 1527 | * i.e. excludes the current date |
| 1528 | * @stable ICU 50 |
| 1529 | */ |
| 1530 | UCAL_TZ_TRANSITION_PREVIOUS, |
| 1531 | /** |
| 1532 | * Get the previous transition on or before the current date, |
| 1533 | * i.e. may include the current date |
| 1534 | * @stable ICU 50 |
| 1535 | */ |
| 1536 | UCAL_TZ_TRANSITION_PREVIOUS_INCLUSIVE |
| 1537 | }; |
| 1538 | |
| 1539 | typedef enum UTimeZoneTransitionType UTimeZoneTransitionType; /**< @stable ICU 50 */ |
| 1540 | |
| 1541 | /** |
| 1542 | * Get the UDate for the next/previous time zone transition relative to |
| 1543 | * the calendar's current date, in the time zone to which the calendar |
| 1544 | * is currently set. If there is no known time zone transition of the |
| 1545 | * requested type relative to the calendar's date, the function returns |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1546 | * false. |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1547 | * @param cal The UCalendar to query. |
| 1548 | * @param type The type of transition desired. |
| 1549 | * @param transition A pointer to a UDate to be set to the transition time. |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1550 | * If the function returns false, the value set is unspecified. |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1551 | * @param status A pointer to a UErrorCode to receive any errors. |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1552 | * @return true if a valid transition time is set in *transition, false |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1553 | * otherwise. |
| 1554 | * @stable ICU 50 |
| 1555 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1556 | U_CAPI UBool U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1557 | ucal_getTimeZoneTransitionDate(const UCalendar* cal, UTimeZoneTransitionType type, |
| 1558 | UDate* transition, UErrorCode* status); |
| 1559 | |
| 1560 | /** |
| 1561 | * Converts a system time zone ID to an equivalent Windows time zone ID. For example, |
| 1562 | * Windows time zone ID "Pacific Standard Time" is returned for input "America/Los_Angeles". |
| 1563 | * |
| 1564 | * <p>There are system time zones that cannot be mapped to Windows zones. When the input |
| 1565 | * system time zone ID is unknown or unmappable to a Windows time zone, then this |
| 1566 | * function returns 0 as the result length, but the operation itself remains successful |
| 1567 | * (no error status set on return). |
| 1568 | * |
| 1569 | * <p>This implementation utilizes <a href="http://unicode.org/cldr/charts/supplemental/zone_tzid.html"> |
| 1570 | * Zone-Tzid mapping data</a>. The mapping data is updated time to time. To get the latest changes, |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1571 | * please read the ICU user guide section <a href="https://unicode-org.github.io/icu/userguide/datetime/timezone#updating-the-time-zone-data"> |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1572 | * Updating the Time Zone Data</a>. |
| 1573 | * |
| 1574 | * @param id A system time zone ID. |
| 1575 | * @param len The length of <code>id</code>, or -1 if null-terminated. |
| 1576 | * @param winid A buffer to receive a Windows time zone ID. |
| 1577 | * @param winidCapacity The capacity of the result buffer <code>winid</code>. |
| 1578 | * @param status Receives the status. |
| 1579 | * @return The result string length, not including the terminating null. |
| 1580 | * @see ucal_getTimeZoneIDForWindowsID |
| 1581 | * |
| 1582 | * @stable ICU 52 |
| 1583 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1584 | U_CAPI int32_t U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1585 | ucal_getWindowsTimeZoneID(const UChar* id, int32_t len, |
| 1586 | UChar* winid, int32_t winidCapacity, UErrorCode* status); |
| 1587 | |
| 1588 | /** |
| 1589 | * Converts a Windows time zone ID to an equivalent system time zone ID |
| 1590 | * for a region. For example, system time zone ID "America/Los_Angeles" is returned |
| 1591 | * for input Windows ID "Pacific Standard Time" and region "US" (or <code>null</code>), |
| 1592 | * "America/Vancouver" is returned for the same Windows ID "Pacific Standard Time" and |
| 1593 | * region "CA". |
| 1594 | * |
| 1595 | * <p>Not all Windows time zones can be mapped to system time zones. When the input |
| 1596 | * Windows time zone ID is unknown or unmappable to a system time zone, then this |
| 1597 | * function returns 0 as the result length, but the operation itself remains successful |
| 1598 | * (no error status set on return). |
| 1599 | * |
| 1600 | * <p>This implementation utilizes <a href="http://unicode.org/cldr/charts/supplemental/zone_tzid.html"> |
| 1601 | * Zone-Tzid mapping data</a>. The mapping data is updated time to time. To get the latest changes, |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1602 | * please read the ICU user guide section <a href="https://unicode-org.github.io/icu/userguide/datetime/timezone#updating-the-time-zone-data"> |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1603 | * Updating the Time Zone Data</a>. |
| 1604 | * |
| 1605 | * @param winid A Windows time zone ID. |
| 1606 | * @param len The length of <code>winid</code>, or -1 if null-terminated. |
| 1607 | * @param region A null-terminated region code, or <code>NULL</code> if no regional preference. |
| 1608 | * @param id A buffer to receive a system time zone ID. |
| 1609 | * @param idCapacity The capacity of the result buffer <code>id</code>. |
| 1610 | * @param status Receives the status. |
| 1611 | * @return The result string length, not including the terminating null. |
| 1612 | * @see ucal_getWindowsTimeZoneID |
| 1613 | * |
| 1614 | * @stable ICU 52 |
| 1615 | */ |
Victor Chang | ce4bf3c | 2021-01-19 16:34:24 +0000 | [diff] [blame] | 1616 | U_CAPI int32_t U_EXPORT2 |
Victor Chang | 7322950 | 2020-09-17 13:39:19 +0100 | [diff] [blame] | 1617 | ucal_getTimeZoneIDForWindowsID(const UChar* winid, int32_t len, const char* region, |
| 1618 | UChar* id, int32_t idCapacity, UErrorCode* status); |
| 1619 | |
| 1620 | #endif /* #if !UCONFIG_NO_FORMATTING */ |
| 1621 | |
| 1622 | #endif |