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