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