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