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 /* 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 */
467typedef 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 */
476enum 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 */
494typedef enum UCalendarDaysOfWeek UCalendarDaysOfWeek;
495
496/** Possible months in a UCalendar. Note: Calendar month is 0-based.
497 * @stable ICU 2.0
498 */
499enum 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 */
532typedef enum UCalendarMonths UCalendarMonths;
533
534/** Possible AM/PM values in a UCalendar
535 * @stable ICU 2.0
536 */
537enum UCalendarAMPMs {
538 /** AM */
539 UCAL_AM,
540 /** PM */
541 UCAL_PM
542};
543
544/** @stable ICU 2.0 */
545typedef 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 */
553enum 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 */
572typedef 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 */
590U_CAPI UEnumeration* U_EXPORT2
591ucal_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 */
605U_CAPI UEnumeration* U_EXPORT2
606ucal_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 */
624U_CAPI UEnumeration* U_EXPORT2
625ucal_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 */
650U_CAPI int32_t U_EXPORT2
651ucal_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 */
662U_CAPI void U_EXPORT2
663ucal_setDefaultTimeZone(const UChar* zoneID, UErrorCode* ec);
664
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 *
692 * @stable ICU 65
693 */
694U_CAPI int32_t U_EXPORT2
695ucal_getHostTimeZone(UChar *result, int32_t resultCapacity, UErrorCode *ec);
696
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 */
713U_CAPI int32_t U_EXPORT2
714ucal_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 */
722U_CAPI UDate U_EXPORT2
723ucal_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 */
748U_CAPI UCalendar* U_EXPORT2
749ucal_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 */
761U_CAPI void U_EXPORT2
762ucal_close(UCalendar *cal);
763
764#if U_SHOW_CPLUSPLUS_API
765
766U_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 */
777U_DEFINE_LOCAL_OPEN_POINTER(LocalUCalendarPointer, UCalendar, ucal_close);
778
779U_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 */
791U_CAPI UCalendar* U_EXPORT2
792ucal_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 */
804U_CAPI void U_EXPORT2
805ucal_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 */
820U_CAPI int32_t U_EXPORT2
821ucal_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 */
830enum 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 */
842typedef 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 */
857U_CAPI int32_t U_EXPORT2
858ucal_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
870 * @return true if cal is currently in daylight savings time, false otherwise
871 * @stable ICU 2.0
872 */
873U_CAPI UBool U_EXPORT2
874ucal_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 */
897U_CAPI void U_EXPORT2
898ucal_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 */
920U_CAPI UDate U_EXPORT2
921ucal_getGregorianChange(const UCalendar *cal, UErrorCode *pErrorCode);
922
923/**
924 * Types of UCalendar attributes
925 * @stable ICU 2.0
926 */
927enum 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 */
958typedef enum UCalendarAttribute UCalendarAttribute;
959
960/**
961 * Options for handling ambiguous wall time at time zone
962 * offset transitions.
963 * @stable ICU 49
964 */
965enum 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 */
988typedef 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 */
1001U_CAPI int32_t U_EXPORT2
1002ucal_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 */
1016U_CAPI void U_EXPORT2
1017ucal_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 */
1030U_CAPI const char* U_EXPORT2
1031ucal_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 */
1041U_CAPI int32_t U_EXPORT2
1042ucal_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 */
1055U_CAPI UDate U_EXPORT2
1056ucal_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 */
1070U_CAPI void U_EXPORT2
1071ucal_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 */
1089U_CAPI void U_EXPORT2
1090ucal_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 */
1113U_CAPI void U_EXPORT2
1114ucal_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/**
1124 * Returns true if two UCalendars are equivalent. Equivalent
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.
1129 * @return true if cal1 and cal2 are equivalent, false otherwise.
1130 * @stable ICU 2.0
1131 */
1132U_CAPI UBool U_EXPORT2
1133ucal_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 */
1154U_CAPI void U_EXPORT2
1155ucal_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 */
1184U_CAPI void U_EXPORT2
1185ucal_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 */
1206U_CAPI int32_t U_EXPORT2
1207ucal_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 */
1226U_CAPI void U_EXPORT2
1227ucal_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.
1239 * @return true if field is set, false otherwise.
1240 * @see ucal_get
1241 * @see ucal_set
1242 * @see ucal_clearField
1243 * @see ucal_clear
1244 * @stable ICU 2.0
1245 */
1246U_CAPI UBool U_EXPORT2
1247ucal_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 */
1264U_CAPI void U_EXPORT2
1265ucal_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 */
1278U_CAPI void U_EXPORT2
1279ucal_clear(UCalendar* calendar);
1280
1281/**
1282 * Possible limit values for a UCalendar
1283 * @stable ICU 2.0
1284 */
1285enum UCalendarLimitType {
1286 /** Minimum value */
1287 UCAL_MINIMUM,
1288 /** Maximum value */
1289 UCAL_MAXIMUM,
1290 /** Greatest minimum value */
1291 UCAL_GREATEST_MINIMUM,
1292 /** Least 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 */
1301typedef 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 */
1317U_CAPI int32_t U_EXPORT2
1318ucal_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 */
1330U_CAPI const char * U_EXPORT2
1331ucal_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 */
1339U_CAPI const char * U_EXPORT2
1340ucal_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 */
1360U_CAPI int32_t U_EXPORT2
1361ucal_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 */
1370U_CAPI const char * U_EXPORT2
1371ucal_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 */
1389U_CAPI UEnumeration* U_EXPORT2
1390ucal_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 */
1399enum 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 */
1425typedef 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 */
1444U_CAPI UCalendarWeekdayType U_EXPORT2
1445ucal_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 */
1462U_CAPI int32_t U_EXPORT2
1463ucal_getWeekendTransition(const UCalendar *cal, UCalendarDaysOfWeek dayOfWeek, UErrorCode *status);
1464
1465/**
1466 * Returns true if the given UDate is in the weekend in
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.
1471 * @return true if the given UDate is in the weekend in
1472 * this calendar system, false otherwise.
1473 * @stable ICU 4.4
1474 */
1475U_CAPI UBool U_EXPORT2
1476ucal_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 */
1502U_CAPI int32_t U_EXPORT2
1503ucal_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 */
1512enum 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
1539typedef 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
1546* false.
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.
1550* If the function returns false, the value set is unspecified.
1551* @param status A pointer to a UErrorCode to receive any errors.
1552* @return true if a valid transition time is set in *transition, false
1553* otherwise.
1554* @stable ICU 50
1555*/
1556U_CAPI UBool U_EXPORT2
1557ucal_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,
1571* please read the ICU user guide section <a href="https://unicode-org.github.io/icu/userguide/datetime/timezone#updating-the-time-zone-data">
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*/
1584U_CAPI int32_t U_EXPORT2
1585ucal_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,
1602* please read the ICU user guide section <a href="https://unicode-org.github.io/icu/userguide/datetime/timezone#updating-the-time-zone-data">
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*/
1616U_CAPI int32_t U_EXPORT2
1617ucal_getTimeZoneIDForWindowsID(const UChar* winid, int32_t len, const char* region,
1618 UChar* id, int32_t idCapacity, UErrorCode* status);
1619
1620#ifndef U_FORCE_HIDE_DRAFT_API
1621/**
1622 * Options used by ucal_getTimeZoneOffsetFromLocal and BasicTimeZone::getOffsetFromLocal()
1623 * to specify how to interpret an input time when it does not exist, or when it is ambiguous,
1624 * around a time zone transition.
1625 * @draft ICU 69
1626 */
1627enum UTimeZoneLocalOption {
1628#ifndef U_HIDE_DRAFT_API
1629 /**
1630 * An input time is always interpreted as local time before
1631 * a time zone transition.
1632 * @draft ICU 69
1633 */
1634 UCAL_TZ_LOCAL_FORMER = 0x04,
1635 /**
1636 * An input time is always interpreted as local time after
1637 * a time zone transition.
1638 * @draft ICU 69
1639 */
1640 UCAL_TZ_LOCAL_LATTER = 0x0C,
1641 /**
1642 * An input time is interpreted as standard time when local
1643 * time is switched to/from daylight saving time. When both
1644 * sides of a time zone transition are standard time,
1645 * or daylight saving time, the local time before the
1646 * transition is used.
1647 * @draft ICU 69
1648 */
1649 UCAL_TZ_LOCAL_STANDARD_FORMER = UCAL_TZ_LOCAL_FORMER | 0x01,
1650 /**
1651 * An input time is interpreted as standard time when local
1652 * time is switched to/from daylight saving time. When both
1653 * sides of a time zone transition are standard time,
1654 * or daylight saving time, the local time after the
1655 * transition is used.
1656 * @draft ICU 69
1657 */
1658 UCAL_TZ_LOCAL_STANDARD_LATTER = UCAL_TZ_LOCAL_LATTER | 0x01,
1659 /**
1660 * An input time is interpreted as daylight saving time when
1661 * local time is switched to/from standard time. When both
1662 * sides of a time zone transition are standard time,
1663 * or daylight saving time, the local time before the
1664 * transition is used.
1665 * @draft ICU 69
1666 */
1667 UCAL_TZ_LOCAL_DAYLIGHT_FORMER = UCAL_TZ_LOCAL_FORMER | 0x03,
1668 /**
1669 * An input time is interpreted as daylight saving time when
1670 * local time is switched to/from standard time. When both
1671 * sides of a time zone transition are standard time,
1672 * or daylight saving time, the local time after the
1673 * transition is used.
1674 * @draft ICU 69
1675 */
1676 UCAL_TZ_LOCAL_DAYLIGHT_LATTER = UCAL_TZ_LOCAL_LATTER | 0x03,
1677#else /* U_HIDE_DRAFT_API */
1678 /**
1679 * Dummy value to prevent empty enum if U_HIDE_DRAFT_API.
1680 * This will go away when draft conditionals are removed.
1681 * @internal
1682 */
1683 UCAL_TZ_LOCAL_NONE = 0,
1684#endif /* U_HIDE_DRAFT_API */
1685};
1686typedef enum UTimeZoneLocalOption UTimeZoneLocalOption; /**< @draft ICU 69 */
1687
1688/**
1689* Returns the time zone raw and GMT offset for the given moment
1690* in time. Upon return, local-millis = GMT-millis + rawOffset +
1691* dstOffset. All computations are performed in the proleptic
1692* Gregorian calendar.
1693*
1694* @param cal The UCalendar which specify the local date and time value to query.
1695* @param nonExistingTimeOpt The option to indicate how to interpret the date and
1696* time in the calendar represent a local time that skipped at a positive time
1697* zone transitions (e.g. when the daylight saving time starts or the time zone
1698* offset is increased due to a time zone rule change).
1699* @param duplicatedTimeOpt The option to indicate how to interpret the date and
1700* time in the calendar represent a local time that repeating multiple times at a
1701* negative time zone transition (e.g. when the daylight saving time ends or the
1702* time zone offset is decreased due to a time zone rule change)
1703* @param rawOffset output parameter to receive the raw offset, that
1704* is, the offset not including DST adjustments.
1705* If the status is set to one of the error code, the value set is unspecified.
1706* @param dstOffset output parameter to receive the DST offset,
1707* that is, the offset to be added to `rawOffset' to obtain the
1708* total offset between local and GMT time. If DST is not in
1709* effect, this value is zero; otherwise it is a positive value,
1710* typically one hour.
1711* If the status is set to one of the error code, the value set is unspecified.
1712* @param status A pointer to a UErrorCode to receive any errors.
1713* @draft ICU 69
1714*/
1715U_CAPI void U_EXPORT2
1716ucal_getTimeZoneOffsetFromLocal(
1717 const UCalendar* cal,
1718 UTimeZoneLocalOption nonExistingTimeOpt,
1719 UTimeZoneLocalOption duplicatedTimeOpt,
1720 int32_t* rawOffset, int32_t* dstOffset, UErrorCode* status);
1721#endif /* U_FORCE_HIDE_DRAFT_API */
1722
1723#endif /* #if !UCONFIG_NO_FORMATTING */
1724
1725#endif
1726

source code of include/unicode/ucal.h