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>
38 * according to the rules of a specific calendar system. The C API
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 &lt; 24:00 on Jan 1, 1970 &lt; 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) &lt; 12:01 am, and 12:00 pm (noon) &lt; 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 */
172typedef void* UCalendar;
173
174/** Possible types of UCalendars
175 * @stable ICU 2.0
176 */
177enum 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 */
197typedef enum UCalendarType UCalendarType;
198
199/** Possible fields in a UCalendar
200 * @stable ICU 2.0
201 */
202enum 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#ifndef U_HIDE_DRAFT_API
446 /**
447 * Field number indicating the month. This is a calendar-specific value.
448 * Differ from UCAL_MONTH, this value is continuous and unique within a
449 * year and range from 0 to 11 or 0 to 12 depending on how many months in a
450 * year, the calendar system has leap month or not, and in leap year or not.
451 * It is the ordinal position of that month in the corresponding year of
452 * the calendar. For Chinese, Dangi, and Hebrew calendar, the range is
453 * 0 to 11 in non-leap years and 0 to 12 in leap years. For Coptic and Ethiopian
454 * calendar, the range is always 0 to 12. For other calendars supported by
455 * ICU now, the range is 0 to 11. When the number of months in a year of the
456 * identified calendar is variable, a different UCAL_ORDINAL_MONTH value can
457 * be used for dates that are part of the same named month in different years.
458 * For example, in the Hebrew calendar, "1 Nisan 5781" is associated with
459 * UCAL_ORDINAL_MONTH value 6 while "1 Nisan 5782" is associated with
460 * UCAL_ORDINAL_MONTH value 7 because 5782 is a leap year and Nisan follows
461 * the insertion of Adar I. In Chinese calendar, "Year 4664 Month 6 Day 2"
462 * is associated with UCAL_ORDINAL_MONTH value 5 while "Year 4665 Month 6 Day 2"
463 * is associated with UCAL_ORDINAL_MONTH value 6 because 4665 is a leap year
464 * and there is an extra "Leap Month 5" which associated with UCAL_ORDINAL_MONTH
465 * value 5 before "Month 6" of year 4664.
466 *
467 * @draft ICU 73
468 */
469 UCAL_ORDINAL_MONTH,
470#endif // U_HIDE_DRAFT_API
471
472 /* Do not conditionalize the following with #ifndef U_HIDE_DEPRECATED_API,
473 * it is needed for layout of Calendar, DateFormat, and other objects */
474#ifndef U_FORCE_HIDE_DEPRECATED_API
475 /**
476 * One more than the highest normal UCalendarDateFields value.
477 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
478 */
479#ifdef U_HIDE_DRAFT_API
480 // Must include all fields that will be in structs
481 UCAL_FIELD_COUNT = UCAL_IS_LEAP_MONTH + 2,
482#else // U_HIDE_DRAFT_API (for UCAL_ORDINAL_MONTH)
483 UCAL_FIELD_COUNT = UCAL_ORDINAL_MONTH + 1,
484#endif // U_HIDE_DRAFT_API (for UCAL_ORDINAL_MONTH)
485
486#endif // U_FORCE_HIDE_DEPRECATED_API
487
488 /**
489 * Field number indicating the
490 * day of the month. This is a synonym for <code>UCAL_DATE</code>.
491 * The first day of the month has value 1.
492 * @see #UCAL_DATE
493 * Synonym for UCAL_DATE
494 * @stable ICU 2.8
495 **/
496 UCAL_DAY_OF_MONTH=UCAL_DATE
497};
498
499/** @stable ICU 2.0 */
500typedef enum UCalendarDateFields UCalendarDateFields;
501 /**
502 * Useful constant for days of week. Note: Calendar day-of-week is 1-based. Clients
503 * who create locale resources for the field of first-day-of-week should be aware of
504 * this. For instance, in US locale, first-day-of-week is set to 1, i.e., UCAL_SUNDAY.
505 */
506/** Possible days of the week in a UCalendar
507 * @stable ICU 2.0
508 */
509enum UCalendarDaysOfWeek {
510 /** Sunday */
511 UCAL_SUNDAY = 1,
512 /** Monday */
513 UCAL_MONDAY,
514 /** Tuesday */
515 UCAL_TUESDAY,
516 /** Wednesday */
517 UCAL_WEDNESDAY,
518 /** Thursday */
519 UCAL_THURSDAY,
520 /** Friday */
521 UCAL_FRIDAY,
522 /** Saturday */
523 UCAL_SATURDAY
524};
525
526/** @stable ICU 2.0 */
527typedef enum UCalendarDaysOfWeek UCalendarDaysOfWeek;
528
529/** Possible months in a UCalendar. Note: Calendar month is 0-based.
530 * @stable ICU 2.0
531 */
532enum UCalendarMonths {
533 /** January */
534 UCAL_JANUARY,
535 /** February */
536 UCAL_FEBRUARY,
537 /** March */
538 UCAL_MARCH,
539 /** April */
540 UCAL_APRIL,
541 /** May */
542 UCAL_MAY,
543 /** June */
544 UCAL_JUNE,
545 /** July */
546 UCAL_JULY,
547 /** August */
548 UCAL_AUGUST,
549 /** September */
550 UCAL_SEPTEMBER,
551 /** October */
552 UCAL_OCTOBER,
553 /** November */
554 UCAL_NOVEMBER,
555 /** December */
556 UCAL_DECEMBER,
557 /** Value of the <code>UCAL_MONTH</code> field indicating the
558 * thirteenth month of the year. Although the Gregorian calendar
559 * does not use this value, lunar calendars do.
560 */
561 UCAL_UNDECIMBER
562};
563
564/** @stable ICU 2.0 */
565typedef enum UCalendarMonths UCalendarMonths;
566
567/** Possible AM/PM values in a UCalendar
568 * @stable ICU 2.0
569 */
570enum UCalendarAMPMs {
571 /** AM */
572 UCAL_AM,
573 /** PM */
574 UCAL_PM
575};
576
577/** @stable ICU 2.0 */
578typedef enum UCalendarAMPMs UCalendarAMPMs;
579
580/**
581 * System time zone type constants used by filtering zones
582 * in ucal_openTimeZoneIDEnumeration.
583 * @see ucal_openTimeZoneIDEnumeration
584 * @stable ICU 4.8
585 */
586enum USystemTimeZoneType {
587 /**
588 * Any system zones.
589 * @stable ICU 4.8
590 */
591 UCAL_ZONE_TYPE_ANY,
592 /**
593 * Canonical system zones.
594 * @stable ICU 4.8
595 */
596 UCAL_ZONE_TYPE_CANONICAL,
597 /**
598 * Canonical system zones associated with actual locations.
599 * @stable ICU 4.8
600 */
601 UCAL_ZONE_TYPE_CANONICAL_LOCATION
602};
603
604/** @stable ICU 4.8 */
605typedef enum USystemTimeZoneType USystemTimeZoneType;
606
607/**
608 * Create an enumeration over system time zone IDs with the given
609 * filter conditions.
610 * @param zoneType The system time zone type.
611 * @param region The ISO 3166 two-letter country code or UN M.49
612 * three-digit area code. When NULL, no filtering
613 * done by region.
614 * @param rawOffset An offset from GMT in milliseconds, ignoring the
615 * effect of daylight savings time, if any. When NULL,
616 * no filtering done by zone offset.
617 * @param ec A pointer to an UErrorCode to receive any errors
618 * @return an enumeration object that the caller must dispose of
619 * using enum_close(), or NULL upon failure. In case of failure,
620 * *ec will indicate the error.
621 * @stable ICU 4.8
622 */
623U_CAPI UEnumeration* U_EXPORT2
624ucal_openTimeZoneIDEnumeration(USystemTimeZoneType zoneType, const char* region,
625 const int32_t* rawOffset, UErrorCode* ec);
626
627/**
628 * Create an enumeration over all time zones.
629 *
630 * @param ec input/output error code
631 *
632 * @return an enumeration object that the caller must dispose of using
633 * uenum_close(), or NULL upon failure. In case of failure *ec will
634 * indicate the error.
635 *
636 * @stable ICU 2.6
637 */
638U_CAPI UEnumeration* U_EXPORT2
639ucal_openTimeZones(UErrorCode* ec);
640
641/**
642 * Create an enumeration over all time zones associated with the given
643 * country. Some zones are affiliated with no country (e.g., "UTC");
644 * these may also be retrieved, as a group.
645 *
646 * @param country the ISO 3166 two-letter country code, or NULL to
647 * retrieve zones not affiliated with any country
648 *
649 * @param ec input/output error code
650 *
651 * @return an enumeration object that the caller must dispose of using
652 * uenum_close(), or NULL upon failure. In case of failure *ec will
653 * indicate the error.
654 *
655 * @stable ICU 2.6
656 */
657U_CAPI UEnumeration* U_EXPORT2
658ucal_openCountryTimeZones(const char* country, UErrorCode* ec);
659
660/**
661 * Return the default time zone. The default is determined initially
662 * by querying the host operating system. If the host system detection
663 * routines fail, or if they specify a TimeZone or TimeZone offset
664 * which is not recognized, then the special TimeZone "Etc/Unknown"
665 * is returned.
666 *
667 * The default may be changed with `ucal_setDefaultTimeZone()` or with
668 * the C++ TimeZone API, `TimeZone::adoptDefault(TimeZone*)`.
669 *
670 * @param result A buffer to receive the result, or NULL
671 *
672 * @param resultCapacity The capacity of the result buffer
673 *
674 * @param ec input/output error code
675 *
676 * @return The result string length, not including the terminating
677 * null
678 *
679 * @see #UCAL_UNKNOWN_ZONE_ID
680 *
681 * @stable ICU 2.6
682 */
683U_CAPI int32_t U_EXPORT2
684ucal_getDefaultTimeZone(UChar* result, int32_t resultCapacity, UErrorCode* ec);
685
686/**
687 * Set the default time zone.
688 *
689 * @param zoneID null-terminated time zone ID
690 *
691 * @param ec input/output error code
692 *
693 * @stable ICU 2.6
694 */
695U_CAPI void U_EXPORT2
696ucal_setDefaultTimeZone(const UChar* zoneID, UErrorCode* ec);
697
698/**
699 * Return the current host time zone. The host time zone is detected from
700 * the current host system configuration by querying the host operating
701 * system. If the host system detection routines fail, or if they specify
702 * a TimeZone or TimeZone offset which is not recognized, then the special
703 * TimeZone "Etc/Unknown" is returned.
704 *
705 * Note that host time zone and the ICU default time zone can be different.
706 *
707 * The ICU default time zone does not change once initialized unless modified
708 * by calling `ucal_setDefaultTimeZone()` or with the C++ TimeZone API,
709 * `TimeZone::adoptDefault(TimeZone*)`.
710 *
711 * If the host operating system configuration has changed since ICU has
712 * initialized then the returned value can be different than the ICU default
713 * time zone, even if the default has not changed.
714 *
715 * <p>This function is not thread safe.</p>
716 *
717 * @param result A buffer to receive the result, or NULL
718 * @param resultCapacity The capacity of the result buffer
719 * @param ec input/output error code
720 * @return The result string length, not including the terminating
721 * null
722 *
723 * @see #UCAL_UNKNOWN_ZONE_ID
724 *
725 * @stable ICU 65
726 */
727U_CAPI int32_t U_EXPORT2
728ucal_getHostTimeZone(UChar *result, int32_t resultCapacity, UErrorCode *ec);
729
730/**
731 * Return the amount of time in milliseconds that the clock is
732 * advanced during daylight savings time for the given time zone, or
733 * zero if the time zone does not observe daylight savings time.
734 *
735 * @param zoneID null-terminated time zone ID
736 *
737 * @param ec input/output error code
738 *
739 * @return the number of milliseconds the time is advanced with
740 * respect to standard time when the daylight savings rules are in
741 * effect. This is always a non-negative number, most commonly either
742 * 3,600,000 (one hour) or zero.
743 *
744 * @stable ICU 2.6
745 */
746U_CAPI int32_t U_EXPORT2
747ucal_getDSTSavings(const UChar* zoneID, UErrorCode* ec);
748
749/**
750 * Get the current date and time.
751 * The value returned is represented as milliseconds from the epoch.
752 * @return The current date and time.
753 * @stable ICU 2.0
754 */
755U_CAPI UDate U_EXPORT2
756ucal_getNow(void);
757
758/**
759 * Open a UCalendar.
760 * A UCalendar may be used to convert a millisecond value to a year,
761 * month, and day.
762 * <p>
763 * Note: When unknown TimeZone ID is specified or if the TimeZone ID specified is "Etc/Unknown",
764 * the UCalendar returned by the function is initialized with GMT zone with TimeZone ID
765 * <code>UCAL_UNKNOWN_ZONE_ID</code> ("Etc/Unknown") without any errors/warnings. If you want
766 * to check if a TimeZone ID is valid prior to this function, use <code>ucal_getCanonicalTimeZoneID</code>.
767 *
768 * @param zoneID The desired TimeZone ID. If 0, use the default time zone.
769 * @param len The length of zoneID, or -1 if null-terminated.
770 * @param locale The desired locale
771 * @param type The type of UCalendar to open. This can be UCAL_GREGORIAN to open the Gregorian
772 * calendar for the locale, or UCAL_DEFAULT to open the default calendar for the locale (the
773 * default calendar may also be Gregorian). To open a specific non-Gregorian calendar for the
774 * locale, use uloc_setKeywordValue to set the value of the calendar keyword for the locale
775 * and then pass the locale to ucal_open with UCAL_DEFAULT as the type.
776 * @param status A pointer to an UErrorCode to receive any errors
777 * @return A pointer to a UCalendar, or 0 if an error occurred.
778 * @see #UCAL_UNKNOWN_ZONE_ID
779 * @stable ICU 2.0
780 */
781U_CAPI UCalendar* U_EXPORT2
782ucal_open(const UChar* zoneID,
783 int32_t len,
784 const char* locale,
785 UCalendarType type,
786 UErrorCode* status);
787
788/**
789 * Close a UCalendar.
790 * Once closed, a UCalendar may no longer be used.
791 * @param cal The UCalendar to close.
792 * @stable ICU 2.0
793 */
794U_CAPI void U_EXPORT2
795ucal_close(UCalendar *cal);
796
797#if U_SHOW_CPLUSPLUS_API
798
799U_NAMESPACE_BEGIN
800
801/**
802 * \class LocalUCalendarPointer
803 * "Smart pointer" class, closes a UCalendar via ucal_close().
804 * For most methods see the LocalPointerBase base class.
805 *
806 * @see LocalPointerBase
807 * @see LocalPointer
808 * @stable ICU 4.4
809 */
810U_DEFINE_LOCAL_OPEN_POINTER(LocalUCalendarPointer, UCalendar, ucal_close);
811
812U_NAMESPACE_END
813
814#endif
815
816/**
817 * Open a copy of a UCalendar.
818 * This function performs a deep copy.
819 * @param cal The calendar to copy
820 * @param status A pointer to an UErrorCode to receive any errors.
821 * @return A pointer to a UCalendar identical to cal.
822 * @stable ICU 4.0
823 */
824U_CAPI UCalendar* U_EXPORT2
825ucal_clone(const UCalendar* cal,
826 UErrorCode* status);
827
828/**
829 * Set the TimeZone used by a UCalendar.
830 * A UCalendar uses a timezone for converting from Greenwich time to local time.
831 * @param cal The UCalendar to set.
832 * @param zoneID The desired TimeZone ID. If 0, use the default time zone.
833 * @param len The length of zoneID, or -1 if null-terminated.
834 * @param status A pointer to an UErrorCode to receive any errors.
835 * @stable ICU 2.0
836 */
837U_CAPI void U_EXPORT2
838ucal_setTimeZone(UCalendar* cal,
839 const UChar* zoneID,
840 int32_t len,
841 UErrorCode* status);
842
843/**
844 * Get the ID of the UCalendar's time zone.
845 *
846 * @param cal The UCalendar to query.
847 * @param result Receives the UCalendar's time zone ID.
848 * @param resultLength The maximum size of result.
849 * @param status Receives the status.
850 * @return The total buffer size needed; if greater than resultLength, the output was truncated.
851 * @stable ICU 51
852 */
853U_CAPI int32_t U_EXPORT2
854ucal_getTimeZoneID(const UCalendar *cal,
855 UChar *result,
856 int32_t resultLength,
857 UErrorCode *status);
858
859/**
860 * Possible formats for a UCalendar's display name
861 * @stable ICU 2.0
862 */
863enum UCalendarDisplayNameType {
864 /** Standard display name */
865 UCAL_STANDARD,
866 /** Short standard display name */
867 UCAL_SHORT_STANDARD,
868 /** Daylight savings display name */
869 UCAL_DST,
870 /** Short daylight savings display name */
871 UCAL_SHORT_DST
872};
873
874/** @stable ICU 2.0 */
875typedef enum UCalendarDisplayNameType UCalendarDisplayNameType;
876
877/**
878 * Get the display name for a UCalendar's TimeZone.
879 * A display name is suitable for presentation to a user.
880 * @param cal The UCalendar to query.
881 * @param type The desired display name format; one of UCAL_STANDARD, UCAL_SHORT_STANDARD,
882 * UCAL_DST, UCAL_SHORT_DST
883 * @param locale The desired locale for the display name.
884 * @param result A pointer to a buffer to receive the formatted number.
885 * @param resultLength The maximum size of result.
886 * @param status A pointer to an UErrorCode to receive any errors
887 * @return The total buffer size needed; if greater than resultLength, the output was truncated.
888 * @stable ICU 2.0
889 */
890U_CAPI int32_t U_EXPORT2
891ucal_getTimeZoneDisplayName(const UCalendar* cal,
892 UCalendarDisplayNameType type,
893 const char* locale,
894 UChar* result,
895 int32_t resultLength,
896 UErrorCode* status);
897
898/**
899 * Determine if a UCalendar is currently in daylight savings time.
900 * Daylight savings time is not used in all parts of the world.
901 * @param cal The UCalendar to query.
902 * @param status A pointer to an UErrorCode to receive any errors
903 * @return true if cal is currently in daylight savings time, false otherwise
904 * @stable ICU 2.0
905 */
906U_CAPI UBool U_EXPORT2
907ucal_inDaylightTime(const UCalendar* cal,
908 UErrorCode* status );
909
910/**
911 * Sets the GregorianCalendar change date. This is the point when the switch from
912 * Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October
913 * 15, 1582. Previous to this time and date will be Julian dates.
914 *
915 * This function works only for Gregorian calendars. If the UCalendar is not
916 * an instance of a Gregorian calendar, then a U_UNSUPPORTED_ERROR
917 * error code is set.
918 *
919 * @param cal The calendar object.
920 * @param date The given Gregorian cutover date.
921 * @param pErrorCode Pointer to a standard ICU error code. Its input value must
922 * pass the U_SUCCESS() test, or else the function returns
923 * immediately. Check for U_FAILURE() on output or use with
924 * function chaining. (See User Guide for details.)
925 *
926 * @see GregorianCalendar::setGregorianChange
927 * @see ucal_getGregorianChange
928 * @stable ICU 3.6
929 */
930U_CAPI void U_EXPORT2
931ucal_setGregorianChange(UCalendar *cal, UDate date, UErrorCode *pErrorCode);
932
933/**
934 * Gets the Gregorian Calendar change date. This is the point when the switch from
935 * Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October
936 * 15, 1582. Previous to this time and date will be Julian dates.
937 *
938 * This function works only for Gregorian calendars. If the UCalendar is not
939 * an instance of a Gregorian calendar, then a U_UNSUPPORTED_ERROR
940 * error code is set.
941 *
942 * @param cal The calendar object.
943 * @param pErrorCode Pointer to a standard ICU error code. Its input value must
944 * pass the U_SUCCESS() test, or else the function returns
945 * immediately. Check for U_FAILURE() on output or use with
946 * function chaining. (See User Guide for details.)
947 * @return The Gregorian cutover time for this calendar.
948 *
949 * @see GregorianCalendar::getGregorianChange
950 * @see ucal_setGregorianChange
951 * @stable ICU 3.6
952 */
953U_CAPI UDate U_EXPORT2
954ucal_getGregorianChange(const UCalendar *cal, UErrorCode *pErrorCode);
955
956/**
957 * Types of UCalendar attributes
958 * @stable ICU 2.0
959 */
960enum UCalendarAttribute {
961 /**
962 * Lenient parsing
963 * @stable ICU 2.0
964 */
965 UCAL_LENIENT,
966 /**
967 * First day of week
968 * @stable ICU 2.0
969 */
970 UCAL_FIRST_DAY_OF_WEEK,
971 /**
972 * Minimum number of days in first week
973 * @stable ICU 2.0
974 */
975 UCAL_MINIMAL_DAYS_IN_FIRST_WEEK,
976 /**
977 * The behavior for handling wall time repeating multiple times
978 * at negative time zone offset transitions
979 * @stable ICU 49
980 */
981 UCAL_REPEATED_WALL_TIME,
982 /**
983 * The behavior for handling skipped wall time at positive time
984 * zone offset transitions.
985 * @stable ICU 49
986 */
987 UCAL_SKIPPED_WALL_TIME
988};
989
990/** @stable ICU 2.0 */
991typedef enum UCalendarAttribute UCalendarAttribute;
992
993/**
994 * Options for handling ambiguous wall time at time zone
995 * offset transitions.
996 * @stable ICU 49
997 */
998enum UCalendarWallTimeOption {
999 /**
1000 * An ambiguous wall time to be interpreted as the latest.
1001 * This option is valid for UCAL_REPEATED_WALL_TIME and
1002 * UCAL_SKIPPED_WALL_TIME.
1003 * @stable ICU 49
1004 */
1005 UCAL_WALLTIME_LAST,
1006 /**
1007 * An ambiguous wall time to be interpreted as the earliest.
1008 * This option is valid for UCAL_REPEATED_WALL_TIME and
1009 * UCAL_SKIPPED_WALL_TIME.
1010 * @stable ICU 49
1011 */
1012 UCAL_WALLTIME_FIRST,
1013 /**
1014 * An ambiguous wall time to be interpreted as the next valid
1015 * wall time. This option is valid for UCAL_SKIPPED_WALL_TIME.
1016 * @stable ICU 49
1017 */
1018 UCAL_WALLTIME_NEXT_VALID
1019};
1020/** @stable ICU 49 */
1021typedef enum UCalendarWallTimeOption UCalendarWallTimeOption;
1022
1023/**
1024 * Get a numeric attribute associated with a UCalendar.
1025 * Numeric attributes include the first day of the week, or the minimal numbers
1026 * of days in the first week of the month.
1027 * @param cal The UCalendar to query.
1028 * @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK,
1029 * UCAL_MINIMAL_DAYS_IN_FIRST_WEEK, UCAL_REPEATED_WALL_TIME or UCAL_SKIPPED_WALL_TIME
1030 * @return The value of attr.
1031 * @see ucal_setAttribute
1032 * @stable ICU 2.0
1033 */
1034U_CAPI int32_t U_EXPORT2
1035ucal_getAttribute(const UCalendar* cal,
1036 UCalendarAttribute attr);
1037
1038/**
1039 * Set a numeric attribute associated with a UCalendar.
1040 * Numeric attributes include the first day of the week, or the minimal numbers
1041 * of days in the first week of the month.
1042 * @param cal The UCalendar to set.
1043 * @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK,
1044 * UCAL_MINIMAL_DAYS_IN_FIRST_WEEK, UCAL_REPEATED_WALL_TIME or UCAL_SKIPPED_WALL_TIME
1045 * @param newValue The new value of attr.
1046 * @see ucal_getAttribute
1047 * @stable ICU 2.0
1048 */
1049U_CAPI void U_EXPORT2
1050ucal_setAttribute(UCalendar* cal,
1051 UCalendarAttribute attr,
1052 int32_t newValue);
1053
1054/**
1055 * Get a locale for which calendars are available.
1056 * A UCalendar in a locale returned by this function will contain the correct
1057 * day and month names for the locale.
1058 * @param localeIndex The index of the desired locale.
1059 * @return A locale for which calendars are available, or 0 if none.
1060 * @see ucal_countAvailable
1061 * @stable ICU 2.0
1062 */
1063U_CAPI const char* U_EXPORT2
1064ucal_getAvailable(int32_t localeIndex);
1065
1066/**
1067 * Determine how many locales have calendars available.
1068 * This function is most useful as determining the loop ending condition for
1069 * calls to \ref ucal_getAvailable.
1070 * @return The number of locales for which calendars are available.
1071 * @see ucal_getAvailable
1072 * @stable ICU 2.0
1073 */
1074U_CAPI int32_t U_EXPORT2
1075ucal_countAvailable(void);
1076
1077/**
1078 * Get a UCalendar's current time in millis.
1079 * The time is represented as milliseconds from the epoch.
1080 * @param cal The UCalendar to query.
1081 * @param status A pointer to an UErrorCode to receive any errors
1082 * @return The calendar's current time in millis.
1083 * @see ucal_setMillis
1084 * @see ucal_setDate
1085 * @see ucal_setDateTime
1086 * @stable ICU 2.0
1087 */
1088U_CAPI UDate U_EXPORT2
1089ucal_getMillis(const UCalendar* cal,
1090 UErrorCode* status);
1091
1092/**
1093 * Set a UCalendar's current time in millis.
1094 * The time is represented as milliseconds from the epoch.
1095 * @param cal The UCalendar to set.
1096 * @param dateTime The desired date and time.
1097 * @param status A pointer to an UErrorCode to receive any errors
1098 * @see ucal_getMillis
1099 * @see ucal_setDate
1100 * @see ucal_setDateTime
1101 * @stable ICU 2.0
1102 */
1103U_CAPI void U_EXPORT2
1104ucal_setMillis(UCalendar* cal,
1105 UDate dateTime,
1106 UErrorCode* status );
1107
1108/**
1109 * Set a UCalendar's current date.
1110 * The date is represented as a series of 32-bit integers.
1111 * @param cal The UCalendar to set.
1112 * @param year The desired year.
1113 * @param month The desired month; one of UCAL_JANUARY, UCAL_FEBRUARY, UCAL_MARCH, UCAL_APRIL, UCAL_MAY,
1114 * UCAL_JUNE, UCAL_JULY, UCAL_AUGUST, UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBER, UCAL_DECEMBER, UCAL_UNDECIMBER
1115 * @param date The desired day of the month.
1116 * @param status A pointer to an UErrorCode to receive any errors
1117 * @see ucal_getMillis
1118 * @see ucal_setMillis
1119 * @see ucal_setDateTime
1120 * @stable ICU 2.0
1121 */
1122U_CAPI void U_EXPORT2
1123ucal_setDate(UCalendar* cal,
1124 int32_t year,
1125 int32_t month,
1126 int32_t date,
1127 UErrorCode* status);
1128
1129/**
1130 * Set a UCalendar's current date.
1131 * The date is represented as a series of 32-bit integers.
1132 * @param cal The UCalendar to set.
1133 * @param year The desired year.
1134 * @param month The desired month; one of UCAL_JANUARY, UCAL_FEBRUARY, UCAL_MARCH, UCAL_APRIL, UCAL_MAY,
1135 * UCAL_JUNE, UCAL_JULY, UCAL_AUGUST, UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBER, UCAL_DECEMBER, UCAL_UNDECIMBER
1136 * @param date The desired day of the month.
1137 * @param hour The desired hour of day.
1138 * @param minute The desired minute.
1139 * @param second The desirec second.
1140 * @param status A pointer to an UErrorCode to receive any errors
1141 * @see ucal_getMillis
1142 * @see ucal_setMillis
1143 * @see ucal_setDate
1144 * @stable ICU 2.0
1145 */
1146U_CAPI void U_EXPORT2
1147ucal_setDateTime(UCalendar* cal,
1148 int32_t year,
1149 int32_t month,
1150 int32_t date,
1151 int32_t hour,
1152 int32_t minute,
1153 int32_t second,
1154 UErrorCode* status);
1155
1156/**
1157 * Returns true if two UCalendars are equivalent. Equivalent
1158 * UCalendars will behave identically, but they may be set to
1159 * different times.
1160 * @param cal1 The first of the UCalendars to compare.
1161 * @param cal2 The second of the UCalendars to compare.
1162 * @return true if cal1 and cal2 are equivalent, false otherwise.
1163 * @stable ICU 2.0
1164 */
1165U_CAPI UBool U_EXPORT2
1166ucal_equivalentTo(const UCalendar* cal1,
1167 const UCalendar* cal2);
1168
1169/**
1170 * Add a specified signed amount to a particular field in a UCalendar.
1171 * This can modify more significant fields in the calendar.
1172 * Adding a positive value always means moving forward in time, so for the Gregorian calendar,
1173 * starting with 100 BC and adding +1 to year results in 99 BC (even though this actually reduces
1174 * the numeric value of the field itself).
1175 * @param cal The UCalendar to which to add.
1176 * @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
1177 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
1178 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
1179 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
1180 * @param amount The signed amount to add to field. If the amount causes the value
1181 * to exceed to maximum or minimum values for that field, other fields are modified
1182 * to preserve the magnitude of the change.
1183 * @param status A pointer to an UErrorCode to receive any errors
1184 * @see ucal_roll
1185 * @stable ICU 2.0
1186 */
1187U_CAPI void U_EXPORT2
1188ucal_add(UCalendar* cal,
1189 UCalendarDateFields field,
1190 int32_t amount,
1191 UErrorCode* status);
1192
1193/**
1194 * Add a specified signed amount to a particular field in a UCalendar.
1195 * This will not modify more significant fields in the calendar.
1196 * Rolling by a positive value always means moving forward in time (unless the limit of the
1197 * field is reached, in which case it may pin or wrap), so for Gregorian calendar,
1198 * starting with 100 BC and rolling the year by +1 results in 99 BC.
1199 * When eras have a definite beginning and end (as in the Chinese calendar, or as in most eras in the
1200 * Japanese calendar) then rolling the year past either limit of the era will cause the year to wrap around.
1201 * When eras only have a limit at one end, then attempting to roll the year past that limit will result in
1202 * pinning the year at that limit. Note that for most calendars in which era 0 years move forward in time
1203 * (such as Buddhist, Hebrew, or Islamic), it is possible for add or roll to result in negative years for
1204 * era 0 (that is the only way to represent years before the calendar epoch).
1205 * @param cal The UCalendar to which to add.
1206 * @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
1207 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
1208 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
1209 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
1210 * @param amount The signed amount to add to field. If the amount causes the value
1211 * to exceed to maximum or minimum values for that field, the field is pinned to a permissible
1212 * value.
1213 * @param status A pointer to an UErrorCode to receive any errors
1214 * @see ucal_add
1215 * @stable ICU 2.0
1216 */
1217U_CAPI void U_EXPORT2
1218ucal_roll(UCalendar* cal,
1219 UCalendarDateFields field,
1220 int32_t amount,
1221 UErrorCode* status);
1222
1223/**
1224 * Get the current value of a field from a UCalendar.
1225 * All fields are represented as 32-bit integers.
1226 * @param cal The UCalendar to query.
1227 * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
1228 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
1229 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
1230 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
1231 * @param status A pointer to an UErrorCode to receive any errors
1232 * @return The value of the desired field.
1233 * @see ucal_set
1234 * @see ucal_isSet
1235 * @see ucal_clearField
1236 * @see ucal_clear
1237 * @stable ICU 2.0
1238 */
1239U_CAPI int32_t U_EXPORT2
1240ucal_get(const UCalendar* cal,
1241 UCalendarDateFields field,
1242 UErrorCode* status );
1243
1244/**
1245 * Set the value of a field in a UCalendar.
1246 * All fields are represented as 32-bit integers.
1247 * @param cal The UCalendar to set.
1248 * @param field The field to set; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
1249 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
1250 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
1251 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
1252 * @param value The desired value of field.
1253 * @see ucal_get
1254 * @see ucal_isSet
1255 * @see ucal_clearField
1256 * @see ucal_clear
1257 * @stable ICU 2.0
1258 */
1259U_CAPI void U_EXPORT2
1260ucal_set(UCalendar* cal,
1261 UCalendarDateFields field,
1262 int32_t value);
1263
1264/**
1265 * Determine if a field in a UCalendar is set.
1266 * All fields are represented as 32-bit integers.
1267 * @param cal The UCalendar to query.
1268 * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
1269 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
1270 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
1271 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
1272 * @return true if field is set, false otherwise.
1273 * @see ucal_get
1274 * @see ucal_set
1275 * @see ucal_clearField
1276 * @see ucal_clear
1277 * @stable ICU 2.0
1278 */
1279U_CAPI UBool U_EXPORT2
1280ucal_isSet(const UCalendar* cal,
1281 UCalendarDateFields field);
1282
1283/**
1284 * Clear a field in a UCalendar.
1285 * All fields are represented as 32-bit integers.
1286 * @param cal The UCalendar containing the field to clear.
1287 * @param field The field to clear; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
1288 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
1289 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
1290 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
1291 * @see ucal_get
1292 * @see ucal_set
1293 * @see ucal_isSet
1294 * @see ucal_clear
1295 * @stable ICU 2.0
1296 */
1297U_CAPI void U_EXPORT2
1298ucal_clearField(UCalendar* cal,
1299 UCalendarDateFields field);
1300
1301/**
1302 * Clear all fields in a UCalendar.
1303 * All fields are represented as 32-bit integers.
1304 * @param calendar The UCalendar to clear.
1305 * @see ucal_get
1306 * @see ucal_set
1307 * @see ucal_isSet
1308 * @see ucal_clearField
1309 * @stable ICU 2.0
1310 */
1311U_CAPI void U_EXPORT2
1312ucal_clear(UCalendar* calendar);
1313
1314/**
1315 * Possible limit values for a UCalendar
1316 * @stable ICU 2.0
1317 */
1318enum UCalendarLimitType {
1319 /** Minimum value */
1320 UCAL_MINIMUM,
1321 /** Maximum value */
1322 UCAL_MAXIMUM,
1323 /** Greatest minimum value */
1324 UCAL_GREATEST_MINIMUM,
1325 /** Least maximum value */
1326 UCAL_LEAST_MAXIMUM,
1327 /** Actual minimum value */
1328 UCAL_ACTUAL_MINIMUM,
1329 /** Actual maximum value */
1330 UCAL_ACTUAL_MAXIMUM
1331};
1332
1333/** @stable ICU 2.0 */
1334typedef enum UCalendarLimitType UCalendarLimitType;
1335
1336/**
1337 * Determine a limit for a field in a UCalendar.
1338 * A limit is a maximum or minimum value for a field.
1339 * @param cal The UCalendar to query.
1340 * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
1341 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
1342 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
1343 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
1344 * @param type The desired critical point; one of UCAL_MINIMUM, UCAL_MAXIMUM, UCAL_GREATEST_MINIMUM,
1345 * UCAL_LEAST_MAXIMUM, UCAL_ACTUAL_MINIMUM, UCAL_ACTUAL_MAXIMUM
1346 * @param status A pointer to an UErrorCode to receive any errors.
1347 * @return The requested value.
1348 * @stable ICU 2.0
1349 */
1350U_CAPI int32_t U_EXPORT2
1351ucal_getLimit(const UCalendar* cal,
1352 UCalendarDateFields field,
1353 UCalendarLimitType type,
1354 UErrorCode* status);
1355
1356/** Get the locale for this calendar object. You can choose between valid and actual locale.
1357 * @param cal The calendar object
1358 * @param type type of the locale we're looking for (valid or actual)
1359 * @param status error code for the operation
1360 * @return the locale name
1361 * @stable ICU 2.8
1362 */
1363U_CAPI const char * U_EXPORT2
1364ucal_getLocaleByType(const UCalendar *cal, ULocDataLocaleType type, UErrorCode* status);
1365
1366/**
1367 * Returns the timezone data version currently used by ICU.
1368 * @param status error code for the operation
1369 * @return the version string, such as "2007f"
1370 * @stable ICU 3.8
1371 */
1372U_CAPI const char * U_EXPORT2
1373ucal_getTZDataVersion(UErrorCode* status);
1374
1375/**
1376 * Returns the canonical system timezone ID or the normalized
1377 * custom time zone ID for the given time zone ID.
1378 * @param id The input timezone ID to be canonicalized.
1379 * @param len The length of id, or -1 if null-terminated.
1380 * @param result The buffer receives the canonical system timezone ID
1381 * or the custom timezone ID in normalized format.
1382 * @param resultCapacity The capacity of the result buffer.
1383 * @param isSystemID Receives if the given ID is a known system
1384 * timezone ID.
1385 * @param status Receives the status. When the given timezone ID
1386 * is neither a known system time zone ID nor a
1387 * valid custom timezone ID, U_ILLEGAL_ARGUMENT_ERROR
1388 * is set.
1389 * @return The result string length, not including the terminating
1390 * null.
1391 * @stable ICU 4.0
1392 */
1393U_CAPI int32_t U_EXPORT2
1394ucal_getCanonicalTimeZoneID(const UChar* id, int32_t len,
1395 UChar* result, int32_t resultCapacity, UBool *isSystemID, UErrorCode* status);
1396
1397#ifndef U_HIDE_DRAFT_API
1398/**
1399 * Returns the preferred time zone ID in the IANA time zone database for the given time zone ID.
1400 * There are two types of preferred IDs. The first type is the one defined in zone.tab file,
1401 * such as "America/Los_Angeles". The second types is the one defined for zones not associated
1402 * with a specific region, but not defined with "Link" syntax such as "Etc/GMT+10".
1403 *
1404 * <p>Note: For most of valid time zone IDs, this method returns an ID same as ucal_getCanonicalTimeZoneID().
1405 * ucal_getCanonicalTimeZoneID() is based on canonical time zone IDs defined in Unicode CLDR.
1406 * These canonical time zone IDs in CLDR were based on very old version of the time zone database.
1407 * In the IANA time zone database, some IDs were updated since then. This API returns a newer
1408 * time zone ID. For example, CLDR defines "Asia/Calcutta" as the canonical time zone ID. This
1409 * method returns "Asia/Kolkata" instead.
1410 * <p> "Etc/Unknown" is a special time zone ID defined by CLDR. There are no corresponding zones
1411 * in the IANA time zone database. Therefore, this API returns U_ILLEGAL_ARGUMENT_ERROR when the
1412 * input ID is "Etc/Unknown".
1413 *
1414 * @param id The input time zone ID.
1415 * @param len The length of the input time zone ID.
1416 * @param result The buffer receives the preferred time zone ID in the IANA time zone database.
1417 * @param resultCapacity The capacity of the result buffer.
1418 * @param status Receives the status. When the given time zone ID is not a known system time zone
1419 * ID, U_ILLEGAL_ARGUMENT_ERROR is set.
1420 * @return The result string length, not including the terminating null.
1421 * @draft ICU 74
1422 */
1423U_CAPI int32_t U_EXPORT2
1424ucal_getIanaTimeZoneID(const UChar* id, int32_t len,
1425 UChar* result, int32_t resultCapacity, UErrorCode* status);
1426#endif // U_HIDE_DRAFT_API
1427
1428/**
1429 * Get the resource keyword value string designating the calendar type for the UCalendar.
1430 * @param cal The UCalendar to query.
1431 * @param status The error code for the operation.
1432 * @return The resource keyword value string.
1433 * @stable ICU 4.2
1434 */
1435U_CAPI const char * U_EXPORT2
1436ucal_getType(const UCalendar *cal, UErrorCode* status);
1437
1438/**
1439 * Given a key and a locale, returns an array of string values in a preferred
1440 * order that would make a difference. These are all and only those values where
1441 * the open (creation) of the service with the locale formed from the input locale
1442 * plus input keyword and that value has different behavior than creation with the
1443 * input locale alone.
1444 * @param key one of the keys supported by this service. For now, only
1445 * "calendar" is supported.
1446 * @param locale the locale
1447 * @param commonlyUsed if set to true it will return only commonly used values
1448 * with the given locale in preferred order. Otherwise,
1449 * it will return all the available values for the locale.
1450 * @param status error status
1451 * @return a string enumeration over keyword values for the given key and the locale.
1452 * @stable ICU 4.2
1453 */
1454U_CAPI UEnumeration* U_EXPORT2
1455ucal_getKeywordValuesForLocale(const char* key,
1456 const char* locale,
1457 UBool commonlyUsed,
1458 UErrorCode* status);
1459
1460
1461/** Weekday types, as returned by ucal_getDayOfWeekType().
1462 * @stable ICU 4.4
1463 */
1464enum UCalendarWeekdayType {
1465 /**
1466 * Designates a full weekday (no part of the day is included in the weekend).
1467 * @stable ICU 4.4
1468 */
1469 UCAL_WEEKDAY,
1470 /**
1471 * Designates a full weekend day (the entire day is included in the weekend).
1472 * @stable ICU 4.4
1473 */
1474 UCAL_WEEKEND,
1475 /**
1476 * Designates a day that starts as a weekday and transitions to the weekend.
1477 * Call ucal_getWeekendTransition() to get the time of transition.
1478 * @stable ICU 4.4
1479 */
1480 UCAL_WEEKEND_ONSET,
1481 /**
1482 * Designates a day that starts as the weekend and transitions to a weekday.
1483 * Call ucal_getWeekendTransition() to get the time of transition.
1484 * @stable ICU 4.4
1485 */
1486 UCAL_WEEKEND_CEASE
1487};
1488
1489/** @stable ICU 4.4 */
1490typedef enum UCalendarWeekdayType UCalendarWeekdayType;
1491
1492/**
1493 * Returns whether the given day of the week is a weekday, a weekend day,
1494 * or a day that transitions from one to the other, for the locale and
1495 * calendar system associated with this UCalendar (the locale's region is
1496 * often the most determinant factor). If a transition occurs at midnight,
1497 * then the days before and after the transition will have the
1498 * type UCAL_WEEKDAY or UCAL_WEEKEND. If a transition occurs at a time
1499 * other than midnight, then the day of the transition will have
1500 * the type UCAL_WEEKEND_ONSET or UCAL_WEEKEND_CEASE. In this case, the
1501 * function ucal_getWeekendTransition() will return the point of
1502 * transition.
1503 * @param cal The UCalendar to query.
1504 * @param dayOfWeek The day of the week whose type is desired (UCAL_SUNDAY..UCAL_SATURDAY).
1505 * @param status The error code for the operation.
1506 * @return The UCalendarWeekdayType for the day of the week.
1507 * @stable ICU 4.4
1508 */
1509U_CAPI UCalendarWeekdayType U_EXPORT2
1510ucal_getDayOfWeekType(const UCalendar *cal, UCalendarDaysOfWeek dayOfWeek, UErrorCode* status);
1511
1512/**
1513 * Returns the time during the day at which the weekend begins or ends in
1514 * this calendar system. If ucal_getDayOfWeekType() returns UCAL_WEEKEND_ONSET
1515 * for the specified dayOfWeek, return the time at which the weekend begins.
1516 * If ucal_getDayOfWeekType() returns UCAL_WEEKEND_CEASE for the specified dayOfWeek,
1517 * return the time at which the weekend ends. If ucal_getDayOfWeekType() returns
1518 * some other UCalendarWeekdayType for the specified dayOfWeek, is it an error condition
1519 * (U_ILLEGAL_ARGUMENT_ERROR).
1520 * @param cal The UCalendar to query.
1521 * @param dayOfWeek The day of the week for which the weekend transition time is
1522 * desired (UCAL_SUNDAY..UCAL_SATURDAY).
1523 * @param status The error code for the operation.
1524 * @return The milliseconds after midnight at which the weekend begins or ends.
1525 * @stable ICU 4.4
1526 */
1527U_CAPI int32_t U_EXPORT2
1528ucal_getWeekendTransition(const UCalendar *cal, UCalendarDaysOfWeek dayOfWeek, UErrorCode *status);
1529
1530/**
1531 * Returns true if the given UDate is in the weekend in
1532 * this calendar system.
1533 * @param cal The UCalendar to query.
1534 * @param date The UDate in question.
1535 * @param status The error code for the operation.
1536 * @return true if the given UDate is in the weekend in
1537 * this calendar system, false otherwise.
1538 * @stable ICU 4.4
1539 */
1540U_CAPI UBool U_EXPORT2
1541ucal_isWeekend(const UCalendar *cal, UDate date, UErrorCode *status);
1542
1543/**
1544 * Return the difference between the target time and the time this calendar object is currently set to.
1545 * If the target time is after the current calendar setting, the the returned value will be positive.
1546 * The field parameter specifies the units of the return value. For example, if field is UCAL_MONTH
1547 * and ucal_getFieldDifference returns 3, then the target time is 3 to less than 4 months after the
1548 * current calendar setting.
1549 *
1550 * As a side effect of this call, this calendar is advanced toward target by the given amount. That is,
1551 * calling this function has the side effect of calling ucal_add on this calendar with the specified
1552 * field and an amount equal to the return value from this function.
1553 *
1554 * A typical way of using this function is to call it first with the largest field of interest, then
1555 * with progressively smaller fields.
1556 *
1557 * @param cal The UCalendar to compare and update.
1558 * @param target The target date to compare to the current calendar setting.
1559 * @param field The field to compare; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
1560 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
1561 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
1562 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
1563 * @param status A pointer to an UErrorCode to receive any errors
1564 * @return The date difference for the specified field.
1565 * @stable ICU 4.8
1566 */
1567U_CAPI int32_t U_EXPORT2
1568ucal_getFieldDifference(UCalendar* cal,
1569 UDate target,
1570 UCalendarDateFields field,
1571 UErrorCode* status);
1572
1573/**
1574 * Time zone transition types for ucal_getTimeZoneTransitionDate
1575 * @stable ICU 50
1576 */
1577enum UTimeZoneTransitionType {
1578 /**
1579 * Get the next transition after the current date,
1580 * i.e. excludes the current date
1581 * @stable ICU 50
1582 */
1583 UCAL_TZ_TRANSITION_NEXT,
1584 /**
1585 * Get the next transition on or after the current date,
1586 * i.e. may include the current date
1587 * @stable ICU 50
1588 */
1589 UCAL_TZ_TRANSITION_NEXT_INCLUSIVE,
1590 /**
1591 * Get the previous transition before the current date,
1592 * i.e. excludes the current date
1593 * @stable ICU 50
1594 */
1595 UCAL_TZ_TRANSITION_PREVIOUS,
1596 /**
1597 * Get the previous transition on or before the current date,
1598 * i.e. may include the current date
1599 * @stable ICU 50
1600 */
1601 UCAL_TZ_TRANSITION_PREVIOUS_INCLUSIVE
1602};
1603
1604typedef enum UTimeZoneTransitionType UTimeZoneTransitionType; /**< @stable ICU 50 */
1605
1606/**
1607* Get the UDate for the next/previous time zone transition relative to
1608* the calendar's current date, in the time zone to which the calendar
1609* is currently set. If there is no known time zone transition of the
1610* requested type relative to the calendar's date, the function returns
1611* false.
1612* @param cal The UCalendar to query.
1613* @param type The type of transition desired.
1614* @param transition A pointer to a UDate to be set to the transition time.
1615* If the function returns false, the value set is unspecified.
1616* @param status A pointer to a UErrorCode to receive any errors.
1617* @return true if a valid transition time is set in *transition, false
1618* otherwise.
1619* @stable ICU 50
1620*/
1621U_CAPI UBool U_EXPORT2
1622ucal_getTimeZoneTransitionDate(const UCalendar* cal, UTimeZoneTransitionType type,
1623 UDate* transition, UErrorCode* status);
1624
1625/**
1626* Converts a system time zone ID to an equivalent Windows time zone ID. For example,
1627* Windows time zone ID "Pacific Standard Time" is returned for input "America/Los_Angeles".
1628*
1629* <p>There are system time zones that cannot be mapped to Windows zones. When the input
1630* system time zone ID is unknown or unmappable to a Windows time zone, then this
1631* function returns 0 as the result length, but the operation itself remains successful
1632* (no error status set on return).
1633*
1634* <p>This implementation utilizes <a href="http://unicode.org/cldr/charts/supplemental/zone_tzid.html">
1635* Zone-Tzid mapping data</a>. The mapping data is updated time to time. To get the latest changes,
1636* please read the ICU user guide section <a href="https://unicode-org.github.io/icu/userguide/datetime/timezone#updating-the-time-zone-data">
1637* Updating the Time Zone Data</a>.
1638*
1639* @param id A system time zone ID.
1640* @param len The length of <code>id</code>, or -1 if null-terminated.
1641* @param winid A buffer to receive a Windows time zone ID.
1642* @param winidCapacity The capacity of the result buffer <code>winid</code>.
1643* @param status Receives the status.
1644* @return The result string length, not including the terminating null.
1645* @see ucal_getTimeZoneIDForWindowsID
1646*
1647* @stable ICU 52
1648*/
1649U_CAPI int32_t U_EXPORT2
1650ucal_getWindowsTimeZoneID(const UChar* id, int32_t len,
1651 UChar* winid, int32_t winidCapacity, UErrorCode* status);
1652
1653/**
1654* Converts a Windows time zone ID to an equivalent system time zone ID
1655* for a region. For example, system time zone ID "America/Los_Angeles" is returned
1656* for input Windows ID "Pacific Standard Time" and region "US" (or <code>null</code>),
1657* "America/Vancouver" is returned for the same Windows ID "Pacific Standard Time" and
1658* region "CA".
1659*
1660* <p>Not all Windows time zones can be mapped to system time zones. When the input
1661* Windows time zone ID is unknown or unmappable to a system time zone, then this
1662* function returns 0 as the result length, but the operation itself remains successful
1663* (no error status set on return).
1664*
1665* <p>This implementation utilizes <a href="http://unicode.org/cldr/charts/supplemental/zone_tzid.html">
1666* Zone-Tzid mapping data</a>. The mapping data is updated time to time. To get the latest changes,
1667* please read the ICU user guide section <a href="https://unicode-org.github.io/icu/userguide/datetime/timezone#updating-the-time-zone-data">
1668* Updating the Time Zone Data</a>.
1669*
1670* @param winid A Windows time zone ID.
1671* @param len The length of <code>winid</code>, or -1 if null-terminated.
1672* @param region A null-terminated region code, or <code>NULL</code> if no regional preference.
1673* @param id A buffer to receive a system time zone ID.
1674* @param idCapacity The capacity of the result buffer <code>id</code>.
1675* @param status Receives the status.
1676* @return The result string length, not including the terminating null.
1677* @see ucal_getWindowsTimeZoneID
1678*
1679* @stable ICU 52
1680*/
1681U_CAPI int32_t U_EXPORT2
1682ucal_getTimeZoneIDForWindowsID(const UChar* winid, int32_t len, const char* region,
1683 UChar* id, int32_t idCapacity, UErrorCode* status);
1684
1685/**
1686 * Options used by ucal_getTimeZoneOffsetFromLocal and BasicTimeZone::getOffsetFromLocal()
1687 * to specify how to interpret an input time when it does not exist, or when it is ambiguous,
1688 * around a time zone transition.
1689 * @stable ICU 69
1690 */
1691enum UTimeZoneLocalOption {
1692 /**
1693 * An input time is always interpreted as local time before
1694 * a time zone transition.
1695 * @stable ICU 69
1696 */
1697 UCAL_TZ_LOCAL_FORMER = 0x04,
1698 /**
1699 * An input time is always interpreted as local time after
1700 * a time zone transition.
1701 * @stable ICU 69
1702 */
1703 UCAL_TZ_LOCAL_LATTER = 0x0C,
1704 /**
1705 * An input time is interpreted as standard time when local
1706 * time is switched to/from daylight saving time. When both
1707 * sides of a time zone transition are standard time,
1708 * or daylight saving time, the local time before the
1709 * transition is used.
1710 * @stable ICU 69
1711 */
1712 UCAL_TZ_LOCAL_STANDARD_FORMER = UCAL_TZ_LOCAL_FORMER | 0x01,
1713 /**
1714 * An input time is interpreted as standard time when local
1715 * time is switched to/from daylight saving time. When both
1716 * sides of a time zone transition are standard time,
1717 * or daylight saving time, the local time after the
1718 * transition is used.
1719 * @stable ICU 69
1720 */
1721 UCAL_TZ_LOCAL_STANDARD_LATTER = UCAL_TZ_LOCAL_LATTER | 0x01,
1722 /**
1723 * An input time is interpreted as daylight saving time when
1724 * local time is switched to/from standard time. When both
1725 * sides of a time zone transition are standard time,
1726 * or daylight saving time, the local time before the
1727 * transition is used.
1728 * @stable ICU 69
1729 */
1730 UCAL_TZ_LOCAL_DAYLIGHT_FORMER = UCAL_TZ_LOCAL_FORMER | 0x03,
1731 /**
1732 * An input time is interpreted as daylight saving time when
1733 * local time is switched to/from standard time. When both
1734 * sides of a time zone transition are standard time,
1735 * or daylight saving time, the local time after the
1736 * transition is used.
1737 * @stable ICU 69
1738 */
1739 UCAL_TZ_LOCAL_DAYLIGHT_LATTER = UCAL_TZ_LOCAL_LATTER | 0x03,
1740};
1741typedef enum UTimeZoneLocalOption UTimeZoneLocalOption; /**< @stable ICU 69 */
1742
1743/**
1744* Returns the time zone raw and GMT offset for the given moment
1745* in time. Upon return, local-millis = GMT-millis + rawOffset +
1746* dstOffset. All computations are performed in the proleptic
1747* Gregorian calendar.
1748*
1749* @param cal The UCalendar which specify the local date and time value to query.
1750* @param nonExistingTimeOpt The option to indicate how to interpret the date and
1751* time in the calendar represent a local time that skipped at a positive time
1752* zone transitions (e.g. when the daylight saving time starts or the time zone
1753* offset is increased due to a time zone rule change).
1754* @param duplicatedTimeOpt The option to indicate how to interpret the date and
1755* time in the calendar represent a local time that repeating multiple times at a
1756* negative time zone transition (e.g. when the daylight saving time ends or the
1757* time zone offset is decreased due to a time zone rule change)
1758* @param rawOffset output parameter to receive the raw offset, that
1759* is, the offset not including DST adjustments.
1760* If the status is set to one of the error code, the value set is unspecified.
1761* @param dstOffset output parameter to receive the DST offset,
1762* that is, the offset to be added to `rawOffset' to obtain the
1763* total offset between local and GMT time. If DST is not in
1764* effect, this value is zero; otherwise it is a positive value,
1765* typically one hour.
1766* If the status is set to one of the error code, the value set is unspecified.
1767* @param status A pointer to a UErrorCode to receive any errors.
1768* @stable ICU 69
1769*/
1770U_CAPI void U_EXPORT2
1771ucal_getTimeZoneOffsetFromLocal(
1772 const UCalendar* cal,
1773 UTimeZoneLocalOption nonExistingTimeOpt,
1774 UTimeZoneLocalOption duplicatedTimeOpt,
1775 int32_t* rawOffset, int32_t* dstOffset, UErrorCode* status);
1776
1777#endif /* #if !UCONFIG_NO_FORMATTING */
1778
1779#endif
1780

source code of include/unicode/ucal.h