codekingpro/portable-devtools
114k
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 < 24:00 on Jan 1, 1970 < 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) < 12:01 am, and 12:00 pm (noon) < 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#ifndef U_FORCE_HIDE_DEPRECATED_API
445 /**
446 * One more than the highest normal UCalendarDateFields value.
447 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
448 */
449 UCAL_FIELD_COUNT,
450#endif // U_FORCE_HIDE_DEPRECATED_API
451
452 /**
453 * Field number indicating the
454 * day of the month. This is a synonym for <code>UCAL_DATE</code>.
455 * The first day of the month has value 1.
456 * @see #UCAL_DATE
457 * Synonym for UCAL_DATE
458 * @stable ICU 2.8
459 **/
460 UCAL_DAY_OF_MONTH=UCAL_DATE
461};
462
463/** @stable ICU 2.0 */
464typedef enum UCalendarDateFields UCalendarDateFields;
465 /**
466 * Useful constant for days of week. Note: Calendar day-of-week is 1-based. Clients
467 * who create locale resources for the field of first-day-of-week should be aware of
468 * this. For instance, in US locale, first-day-of-week is set to 1, i.e., UCAL_SUNDAY.
469 */
470/** Possible days of the week in a UCalendar
471 * @stable ICU 2.0
472 */
473enum UCalendarDaysOfWeek {
474 /** Sunday */
475 UCAL_SUNDAY = 1,
476 /** Monday */
477 UCAL_MONDAY,
478 /** Tuesday */
479 UCAL_TUESDAY,
480 /** Wednesday */
481 UCAL_WEDNESDAY,
482 /** Thursday */
483 UCAL_THURSDAY,
484 /** Friday */
485 UCAL_FRIDAY,
486 /** Saturday */
487 UCAL_SATURDAY
488};
489
490/** @stable ICU 2.0 */
491typedef enum UCalendarDaysOfWeek UCalendarDaysOfWeek;
492
493/** Possible months in a UCalendar. Note: Calendar month is 0-based.
494 * @stable ICU 2.0
495 */
496enum UCalendarMonths {
497 /** January */
498 UCAL_JANUARY,
499 /** February */
500 UCAL_FEBRUARY,
501 /** March */
502 UCAL_MARCH,
503 /** April */
504 UCAL_APRIL,
505 /** May */
506 UCAL_MAY,
507 /** June */
508 UCAL_JUNE,
509 /** July */
510 UCAL_JULY,
511 /** August */
512 UCAL_AUGUST,
513 /** September */
514 UCAL_SEPTEMBER,
515 /** October */
516 UCAL_OCTOBER,
517 /** November */
518 UCAL_NOVEMBER,
519 /** December */
520 UCAL_DECEMBER,
521 /** Value of the <code>UCAL_MONTH</code> field indicating the
522 * thirteenth month of the year. Although the Gregorian calendar
523 * does not use this value, lunar calendars do.
524 */
525 UCAL_UNDECIMBER
526};
527
528/** @stable ICU 2.0 */
529typedef enum UCalendarMonths UCalendarMonths;
530
531/** Possible AM/PM values in a UCalendar
532 * @stable ICU 2.0
533 */
534enum UCalendarAMPMs {
535 /** AM */
536 UCAL_AM,
537 /** PM */
538 UCAL_PM
539};
540
541/** @stable ICU 2.0 */
542typedef enum UCalendarAMPMs UCalendarAMPMs;
543
544/**
545 * System time zone type constants used by filtering zones
546 * in ucal_openTimeZoneIDEnumeration.
547 * @see ucal_openTimeZoneIDEnumeration
548 * @stable ICU 4.8
549 */
550enum USystemTimeZoneType {
551 /**
552 * Any system zones.
553 * @stable ICU 4.8
554 */
555 UCAL_ZONE_TYPE_ANY,
556 /**
557 * Canonical system zones.
558 * @stable ICU 4.8
559 */
560 UCAL_ZONE_TYPE_CANONICAL,
561 /**
562 * Canonical system zones associated with actual locations.
563 * @stable ICU 4.8
564 */
565 UCAL_ZONE_TYPE_CANONICAL_LOCATION
566};
567
568/** @stable ICU 4.8 */
569typedef enum USystemTimeZoneType USystemTimeZoneType;
570
571/**
572 * Create an enumeration over system time zone IDs with the given
573 * filter conditions.
574 * @param zoneType The system time zone type.
575 * @param region The ISO 3166 two-letter country code or UN M.49
576 * three-digit area code. When NULL, no filtering
577 * done by region.
578 * @param rawOffset An offset from GMT in milliseconds, ignoring the
579 * effect of daylight savings time, if any. When NULL,
580 * no filtering done by zone offset.
581 * @param ec A pointer to an UErrorCode to receive any errors
582 * @return an enumeration object that the caller must dispose of
583 * using enum_close(), or NULL upon failure. In case of failure,
584 * *ec will indicate the error.
585 * @stable ICU 4.8
586 */
587U_STABLE UEnumeration* U_EXPORT2
588ucal_openTimeZoneIDEnumeration(USystemTimeZoneType zoneType, const char* region,
589 const int32_t* rawOffset, UErrorCode* ec);
590
591/**
592 * Create an enumeration over all time zones.
593 *
594 * @param ec input/output error code
595 *
596 * @return an enumeration object that the caller must dispose of using
597 * uenum_close(), or NULL upon failure. In case of failure *ec will
598 * indicate the error.
599 *
600 * @stable ICU 2.6
601 */
602U_STABLE UEnumeration* U_EXPORT2
603ucal_openTimeZones(UErrorCode* ec);
604
605/**
606 * Create an enumeration over all time zones associated with the given
607 * country. Some zones are affiliated with no country (e.g., "UTC");
608 * these may also be retrieved, as a group.
609 *
610 * @param country the ISO 3166 two-letter country code, or NULL to
611 * retrieve zones not affiliated with any country
612 *
613 * @param ec input/output error code
614 *
615 * @return an enumeration object that the caller must dispose of using
616 * uenum_close(), or NULL upon failure. In case of failure *ec will
617 * indicate the error.
618 *
619 * @stable ICU 2.6
620 */
621U_STABLE UEnumeration* U_EXPORT2
622ucal_openCountryTimeZones(const char* country, UErrorCode* ec);
623
624/**
625 * Return the default time zone. The default is determined initially
626 * by querying the host operating system. If the host system detection
627 * routines fail, or if they specify a TimeZone or TimeZone offset
628 * which is not recognized, then the special TimeZone "Etc/Unknown"
629 * is returned.
630 *
631 * The default may be changed with `ucal_setDefaultTimeZone()` or with
632 * the C++ TimeZone API, `TimeZone::adoptDefault(TimeZone*)`.
633 *
634 * @param result A buffer to receive the result, or NULL
635 *
636 * @param resultCapacity The capacity of the result buffer
637 *
638 * @param ec input/output error code
639 *
640 * @return The result string length, not including the terminating
641 * null
642 *
643 * @see #UCAL_UNKNOWN_ZONE_ID
644 *
645 * @stable ICU 2.6
646 */
647U_STABLE int32_t U_EXPORT2
648ucal_getDefaultTimeZone(UChar* result, int32_t resultCapacity, UErrorCode* ec);
649
650/**
651 * Set the default time zone.
652 *
653 * @param zoneID null-terminated time zone ID
654 *
655 * @param ec input/output error code
656 *
657 * @stable ICU 2.6
658 */
659U_STABLE void U_EXPORT2
660ucal_setDefaultTimeZone(const UChar* zoneID, UErrorCode* ec);
661
662#ifndef U_HIDE_DRAFT_API
663
664/**
665 * Return the current host time zone. The host time zone is detected from
666 * the current host system configuration by querying the host operating
667 * system. If the host system detection routines fail, or if they specify
668 * a TimeZone or TimeZone offset which is not recognized, then the special
669 * TimeZone "Etc/Unknown" is returned.
670 *
671 * Note that host time zone and the ICU default time zone can be different.
672 *
673 * The ICU default time zone does not change once initialized unless modified
674 * by calling `ucal_setDefaultTimeZone()` or with the C++ TimeZone API,
675 * `TimeZone::adoptDefault(TimeZone*)`.
676 *
677 * If the host operating system configuration has changed since ICU has
678 * initialized then the returned value can be different than the ICU default
679 * time zone, even if the default has not changed.
680 *
681 * <p>This function is not thread safe.</p>
682 *
683 * @param result A buffer to receive the result, or NULL
684 * @param resultCapacity The capacity of the result buffer
685 * @param ec input/output error code
686 * @return The result string length, not including the terminating
687 * null
688 *
689 * @see #UCAL_UNKNOWN_ZONE_ID
690 *
691 * @draft ICU 65
692 */
693U_DRAFT int32_t U_EXPORT2
694ucal_getHostTimeZone(UChar *result, int32_t resultCapacity, UErrorCode *ec);
695
696#endif // U_HIDE_DRAFT_API
697
698/**
699 * Return the amount of time in milliseconds that the clock is
700 * advanced during daylight savings time for the given time zone, or
701 * zero if the time zone does not observe daylight savings time.
702 *
703 * @param zoneID null-terminated time zone ID
704 *
705 * @param ec input/output error code
706 *
707 * @return the number of milliseconds the time is advanced with
708 * respect to standard time when the daylight savings rules are in
709 * effect. This is always a non-negative number, most commonly either
710 * 3,600,000 (one hour) or zero.
711 *
712 * @stable ICU 2.6
713 */
714U_STABLE int32_t U_EXPORT2
715ucal_getDSTSavings(const UChar* zoneID, UErrorCode* ec);
716
717/**
718 * Get the current date and time.
719 * The value returned is represented as milliseconds from the epoch.
720 * @return The current date and time.
721 * @stable ICU 2.0
722 */
723U_STABLE UDate U_EXPORT2
724ucal_getNow(void);
725
726/**
727 * Open a UCalendar.
728 * A UCalendar may be used to convert a millisecond value to a year,
729 * month, and day.
730 * <p>
731 * Note: When unknown TimeZone ID is specified or if the TimeZone ID specified is "Etc/Unknown",
732 * the UCalendar returned by the function is initialized with GMT zone with TimeZone ID
733 * <code>UCAL_UNKNOWN_ZONE_ID</code> ("Etc/Unknown") without any errors/warnings. If you want
734 * to check if a TimeZone ID is valid prior to this function, use <code>ucal_getCanonicalTimeZoneID</code>.
735 *
736 * @param zoneID The desired TimeZone ID. If 0, use the default time zone.
737 * @param len The length of zoneID, or -1 if null-terminated.
738 * @param locale The desired locale
739 * @param type The type of UCalendar to open. This can be UCAL_GREGORIAN to open the Gregorian
740 * calendar for the locale, or UCAL_DEFAULT to open the default calendar for the locale (the
741 * default calendar may also be Gregorian). To open a specific non-Gregorian calendar for the
742 * locale, use uloc_setKeywordValue to set the value of the calendar keyword for the locale
743 * and then pass the locale to ucal_open with UCAL_DEFAULT as the type.
744 * @param status A pointer to an UErrorCode to receive any errors
745 * @return A pointer to a UCalendar, or 0 if an error occurred.
746 * @see #UCAL_UNKNOWN_ZONE_ID
747 * @stable ICU 2.0
748 */
749U_STABLE UCalendar* U_EXPORT2
750ucal_open(const UChar* zoneID,
751 int32_t len,
752 const char* locale,
753 UCalendarType type,
754 UErrorCode* status);
755
756/**
757 * Close a UCalendar.
758 * Once closed, a UCalendar may no longer be used.
759 * @param cal The UCalendar to close.
760 * @stable ICU 2.0
761 */
762U_STABLE void U_EXPORT2
763ucal_close(UCalendar *cal);
764
765#if U_SHOW_CPLUSPLUS_API
766
767U_NAMESPACE_BEGIN
768
769/**
770 * \class LocalUCalendarPointer
771 * "Smart pointer" class, closes a UCalendar via ucal_close().
772 * For most methods see the LocalPointerBase base class.
773 *
774 * @see LocalPointerBase
775 * @see LocalPointer
776 * @stable ICU 4.4
777 */
778U_DEFINE_LOCAL_OPEN_POINTER(LocalUCalendarPointer, UCalendar, ucal_close);
779
780U_NAMESPACE_END
781
782#endif
783
784/**
785 * Open a copy of a UCalendar.
786 * This function performs a deep copy.
787 * @param cal The calendar to copy
788 * @param status A pointer to an UErrorCode to receive any errors.
789 * @return A pointer to a UCalendar identical to cal.
790 * @stable ICU 4.0
791 */
792U_STABLE UCalendar* U_EXPORT2
793ucal_clone(const UCalendar* cal,
794 UErrorCode* status);
795
796/**
797 * Set the TimeZone used by a UCalendar.
798 * A UCalendar uses a timezone for converting from Greenwich time to local time.
799 * @param cal The UCalendar to set.
800 * @param zoneID The desired TimeZone ID. If 0, use the default time zone.
801 * @param len The length of zoneID, or -1 if null-terminated.
802 * @param status A pointer to an UErrorCode to receive any errors.
803 * @stable ICU 2.0
804 */
805U_STABLE void U_EXPORT2
806ucal_setTimeZone(UCalendar* cal,
807 const UChar* zoneID,
808 int32_t len,
809 UErrorCode* status);
810
811/**
812 * Get the ID of the UCalendar's time zone.
813 *
814 * @param cal The UCalendar to query.
815 * @param result Receives the UCalendar's time zone ID.
816 * @param resultLength The maximum size of result.
817 * @param status Receives the status.
818 * @return The total buffer size needed; if greater than resultLength, the output was truncated.
819 * @stable ICU 51
820 */
821U_STABLE int32_t U_EXPORT2
822ucal_getTimeZoneID(const UCalendar *cal,
823 UChar *result,
824 int32_t resultLength,
825 UErrorCode *status);
826
827/**
828 * Possible formats for a UCalendar's display name
829 * @stable ICU 2.0
830 */
831enum UCalendarDisplayNameType {
832 /** Standard display name */
833 UCAL_STANDARD,
834 /** Short standard display name */
835 UCAL_SHORT_STANDARD,
836 /** Daylight savings display name */
837 UCAL_DST,
838 /** Short daylight savings display name */
839 UCAL_SHORT_DST
840};
841
842/** @stable ICU 2.0 */
843typedef enum UCalendarDisplayNameType UCalendarDisplayNameType;
844
845/**
846 * Get the display name for a UCalendar's TimeZone.
847 * A display name is suitable for presentation to a user.
848 * @param cal The UCalendar to query.
849 * @param type The desired display name format; one of UCAL_STANDARD, UCAL_SHORT_STANDARD,
850 * UCAL_DST, UCAL_SHORT_DST
851 * @param locale The desired locale for the display name.
852 * @param result A pointer to a buffer to receive the formatted number.
853 * @param resultLength The maximum size of result.
854 * @param status A pointer to an UErrorCode to receive any errors
855 * @return The total buffer size needed; if greater than resultLength, the output was truncated.
856 * @stable ICU 2.0
857 */
858U_STABLE int32_t U_EXPORT2
859ucal_getTimeZoneDisplayName(const UCalendar* cal,
860 UCalendarDisplayNameType type,
861 const char* locale,
862 UChar* result,
863 int32_t resultLength,
864 UErrorCode* status);
865
866/**
867 * Determine if a UCalendar is currently in daylight savings time.
868 * Daylight savings time is not used in all parts of the world.
869 * @param cal The UCalendar to query.
870 * @param status A pointer to an UErrorCode to receive any errors
871 * @return TRUE if cal is currently in daylight savings time, FALSE otherwise
872 * @stable ICU 2.0
873 */
874U_STABLE UBool U_EXPORT2
875ucal_inDaylightTime(const UCalendar* cal,
876 UErrorCode* status );
877
878/**
879 * Sets the GregorianCalendar change date. This is the point when the switch from
880 * Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October
881 * 15, 1582. Previous to this time and date will be Julian dates.
882 *
883 * This function works only for Gregorian calendars. If the UCalendar is not
884 * an instance of a Gregorian calendar, then a U_UNSUPPORTED_ERROR
885 * error code is set.
886 *
887 * @param cal The calendar object.
888 * @param date The given Gregorian cutover date.
889 * @param pErrorCode Pointer to a standard ICU error code. Its input value must
890 * pass the U_SUCCESS() test, or else the function returns
891 * immediately. Check for U_FAILURE() on output or use with
892 * function chaining. (See User Guide for details.)
893 *
894 * @see GregorianCalendar::setGregorianChange
895 * @see ucal_getGregorianChange
896 * @stable ICU 3.6
897 */
898U_STABLE void U_EXPORT2
899ucal_setGregorianChange(UCalendar *cal, UDate date, UErrorCode *pErrorCode);
900
901/**
902 * Gets the Gregorian Calendar change date. This is the point when the switch from
903 * Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October
904 * 15, 1582. Previous to this time and date will be Julian dates.
905 *
906 * This function works only for Gregorian calendars. If the UCalendar is not
907 * an instance of a Gregorian calendar, then a U_UNSUPPORTED_ERROR
908 * error code is set.
909 *
910 * @param cal The calendar object.
911 * @param pErrorCode Pointer to a standard ICU error code. Its input value must
912 * pass the U_SUCCESS() test, or else the function returns
913 * immediately. Check for U_FAILURE() on output or use with
914 * function chaining. (See User Guide for details.)
915 * @return The Gregorian cutover time for this calendar.
916 *
917 * @see GregorianCalendar::getGregorianChange
918 * @see ucal_setGregorianChange
919 * @stable ICU 3.6
920 */
921U_STABLE UDate U_EXPORT2
922ucal_getGregorianChange(const UCalendar *cal, UErrorCode *pErrorCode);
923
924/**
925 * Types of UCalendar attributes
926 * @stable ICU 2.0
927 */
928enum UCalendarAttribute {
929 /**
930 * Lenient parsing
931 * @stable ICU 2.0
932 */
933 UCAL_LENIENT,
934 /**
935 * First day of week
936 * @stable ICU 2.0
937 */
938 UCAL_FIRST_DAY_OF_WEEK,
939 /**
940 * Minimum number of days in first week
941 * @stable ICU 2.0
942 */
943 UCAL_MINIMAL_DAYS_IN_FIRST_WEEK,
944 /**
945 * The behavior for handling wall time repeating multiple times
946 * at negative time zone offset transitions
947 * @stable ICU 49
948 */
949 UCAL_REPEATED_WALL_TIME,
950 /**
951 * The behavior for handling skipped wall time at positive time
952 * zone offset transitions.
953 * @stable ICU 49
954 */
955 UCAL_SKIPPED_WALL_TIME
956};
957
958/** @stable ICU 2.0 */
959typedef enum UCalendarAttribute UCalendarAttribute;
960
961/**
962 * Options for handling ambiguous wall time at time zone
963 * offset transitions.
964 * @stable ICU 49
965 */
966enum UCalendarWallTimeOption {
967 /**
968 * An ambiguous wall time to be interpreted as the latest.
969 * This option is valid for UCAL_REPEATED_WALL_TIME and
970 * UCAL_SKIPPED_WALL_TIME.
971 * @stable ICU 49
972 */
973 UCAL_WALLTIME_LAST,
974 /**
975 * An ambiguous wall time to be interpreted as the earliest.
976 * This option is valid for UCAL_REPEATED_WALL_TIME and
977 * UCAL_SKIPPED_WALL_TIME.
978 * @stable ICU 49
979 */
980 UCAL_WALLTIME_FIRST,
981 /**
982 * An ambiguous wall time to be interpreted as the next valid
983 * wall time. This option is valid for UCAL_SKIPPED_WALL_TIME.
984 * @stable ICU 49
985 */
986 UCAL_WALLTIME_NEXT_VALID
987};
988/** @stable ICU 49 */
989typedef enum UCalendarWallTimeOption UCalendarWallTimeOption;
990
991/**
992 * Get a numeric attribute associated with a UCalendar.
993 * Numeric attributes include the first day of the week, or the minimal numbers
994 * of days in the first week of the month.
995 * @param cal The UCalendar to query.
996 * @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK,
997 * UCAL_MINIMAL_DAYS_IN_FIRST_WEEK, UCAL_REPEATED_WALL_TIME or UCAL_SKIPPED_WALL_TIME
998 * @return The value of attr.
999 * @see ucal_setAttribute
1000 * @stable ICU 2.0
1001 */
1002U_STABLE int32_t U_EXPORT2
1003ucal_getAttribute(const UCalendar* cal,
1004 UCalendarAttribute attr);
1005
1006/**
1007 * Set a numeric attribute associated with a UCalendar.
1008 * Numeric attributes include the first day of the week, or the minimal numbers
1009 * of days in the first week of the month.
1010 * @param cal The UCalendar to set.
1011 * @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK,
1012 * UCAL_MINIMAL_DAYS_IN_FIRST_WEEK, UCAL_REPEATED_WALL_TIME or UCAL_SKIPPED_WALL_TIME
1013 * @param newValue The new value of attr.
1014 * @see ucal_getAttribute
1015 * @stable ICU 2.0
1016 */
1017U_STABLE void U_EXPORT2
1018ucal_setAttribute(UCalendar* cal,
1019 UCalendarAttribute attr,
1020 int32_t newValue);
1021
1022/**
1023 * Get a locale for which calendars are available.
1024 * A UCalendar in a locale returned by this function will contain the correct
1025 * day and month names for the locale.
1026 * @param localeIndex The index of the desired locale.
1027 * @return A locale for which calendars are available, or 0 if none.
1028 * @see ucal_countAvailable
1029 * @stable ICU 2.0
1030 */
1031U_STABLE const char* U_EXPORT2
1032ucal_getAvailable(int32_t localeIndex);
1033
1034/**
1035 * Determine how many locales have calendars available.
1036 * This function is most useful as determining the loop ending condition for
1037 * calls to \ref ucal_getAvailable.
1038 * @return The number of locales for which calendars are available.
1039 * @see ucal_getAvailable
1040 * @stable ICU 2.0
1041 */
1042U_STABLE int32_t U_EXPORT2
1043ucal_countAvailable(void);
1044
1045/**
1046 * Get a UCalendar's current time in millis.
1047 * The time is represented as milliseconds from the epoch.
1048 * @param cal The UCalendar to query.
1049 * @param status A pointer to an UErrorCode to receive any errors
1050 * @return The calendar's current time in millis.
1051 * @see ucal_setMillis
1052 * @see ucal_setDate
1053 * @see ucal_setDateTime
1054 * @stable ICU 2.0
1055 */
1056U_STABLE UDate U_EXPORT2
1057ucal_getMillis(const UCalendar* cal,
1058 UErrorCode* status);
1059
1060/**
1061 * Set a UCalendar's current time in millis.
1062 * The time is represented as milliseconds from the epoch.
1063 * @param cal The UCalendar to set.
1064 * @param dateTime The desired date and time.
1065 * @param status A pointer to an UErrorCode to receive any errors
1066 * @see ucal_getMillis
1067 * @see ucal_setDate
1068 * @see ucal_setDateTime
1069 * @stable ICU 2.0
1070 */
1071U_STABLE void U_EXPORT2
1072ucal_setMillis(UCalendar* cal,
1073 UDate dateTime,
1074 UErrorCode* status );
1075
1076/**
1077 * Set a UCalendar's current date.
1078 * The date is represented as a series of 32-bit integers.
1079 * @param cal The UCalendar to set.
1080 * @param year The desired year.
1081 * @param month The desired month; one of UCAL_JANUARY, UCAL_FEBRUARY, UCAL_MARCH, UCAL_APRIL, UCAL_MAY,
1082 * UCAL_JUNE, UCAL_JULY, UCAL_AUGUST, UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBER, UCAL_DECEMBER, UCAL_UNDECIMBER
1083 * @param date The desired day of the month.
1084 * @param status A pointer to an UErrorCode to receive any errors
1085 * @see ucal_getMillis
1086 * @see ucal_setMillis
1087 * @see ucal_setDateTime
1088 * @stable ICU 2.0
1089 */
1090U_STABLE void U_EXPORT2
1091ucal_setDate(UCalendar* cal,
1092 int32_t year,
1093 int32_t month,
1094 int32_t date,
1095 UErrorCode* status);
1096
1097/**
1098 * Set a UCalendar's current date.
1099 * The date is represented as a series of 32-bit integers.
1100 * @param cal The UCalendar to set.
1101 * @param year The desired year.
1102 * @param month The desired month; one of UCAL_JANUARY, UCAL_FEBRUARY, UCAL_MARCH, UCAL_APRIL, UCAL_MAY,
1103 * UCAL_JUNE, UCAL_JULY, UCAL_AUGUST, UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBER, UCAL_DECEMBER, UCAL_UNDECIMBER
1104 * @param date The desired day of the month.
1105 * @param hour The desired hour of day.
1106 * @param minute The desired minute.
1107 * @param second The desirec second.
1108 * @param status A pointer to an UErrorCode to receive any errors
1109 * @see ucal_getMillis
1110 * @see ucal_setMillis
1111 * @see ucal_setDate
1112 * @stable ICU 2.0
1113 */
1114U_STABLE void U_EXPORT2
1115ucal_setDateTime(UCalendar* cal,
1116 int32_t year,
1117 int32_t month,
1118 int32_t date,
1119 int32_t hour,
1120 int32_t minute,
1121 int32_t second,
1122 UErrorCode* status);
1123
1124/**
1125 * Returns TRUE if two UCalendars are equivalent. Equivalent
1126 * UCalendars will behave identically, but they may be set to
1127 * different times.
1128 * @param cal1 The first of the UCalendars to compare.
1129 * @param cal2 The second of the UCalendars to compare.
1130 * @return TRUE if cal1 and cal2 are equivalent, FALSE otherwise.
1131 * @stable ICU 2.0
1132 */
1133U_STABLE UBool U_EXPORT2
1134ucal_equivalentTo(const UCalendar* cal1,
1135 const UCalendar* cal2);
1136
1137/**
1138 * Add a specified signed amount to a particular field in a UCalendar.
1139 * This can modify more significant fields in the calendar.
1140 * Adding a positive value always means moving forward in time, so for the Gregorian calendar,
1141 * starting with 100 BC and adding +1 to year results in 99 BC (even though this actually reduces
1142 * the numeric value of the field itself).
1143 * @param cal The UCalendar to which to add.
1144 * @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
1145 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
1146 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
1147 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
1148 * @param amount The signed amount to add to field. If the amount causes the value
1149 * to exceed to maximum or minimum values for that field, other fields are modified
1150 * to preserve the magnitude of the change.
1151 * @param status A pointer to an UErrorCode to receive any errors
1152 * @see ucal_roll
1153 * @stable ICU 2.0
1154 */
1155U_STABLE void U_EXPORT2
1156ucal_add(UCalendar* cal,
1157 UCalendarDateFields field,
1158 int32_t amount,
1159 UErrorCode* status);
1160
1161/**
1162 * Add a specified signed amount to a particular field in a UCalendar.
1163 * This will not modify more significant fields in the calendar.
1164 * Rolling by a positive value always means moving forward in time (unless the limit of the
1165 * field is reached, in which case it may pin or wrap), so for Gregorian calendar,
1166 * starting with 100 BC and rolling the year by +1 results in 99 BC.
1167 * When eras have a definite beginning and end (as in the Chinese calendar, or as in most eras in the
1168 * Japanese calendar) then rolling the year past either limit of the era will cause the year to wrap around.
1169 * When eras only have a limit at one end, then attempting to roll the year past that limit will result in
1170 * pinning the year at that limit. Note that for most calendars in which era 0 years move forward in time
1171 * (such as Buddhist, Hebrew, or Islamic), it is possible for add or roll to result in negative years for
1172 * era 0 (that is the only way to represent years before the calendar epoch).
1173 * @param cal The UCalendar to which to add.
1174 * @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
1175 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
1176 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
1177 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
1178 * @param amount The signed amount to add to field. If the amount causes the value
1179 * to exceed to maximum or minimum values for that field, the field is pinned to a permissible
1180 * value.
1181 * @param status A pointer to an UErrorCode to receive any errors
1182 * @see ucal_add
1183 * @stable ICU 2.0
1184 */
1185U_STABLE void U_EXPORT2
1186ucal_roll(UCalendar* cal,
1187 UCalendarDateFields field,
1188 int32_t amount,
1189 UErrorCode* status);
1190
1191/**
1192 * Get the current value of a field from a UCalendar.
1193 * All fields are represented as 32-bit integers.
1194 * @param cal The UCalendar to query.
1195 * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
1196 * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
1197 * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
1198 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
1199 * @param status A pointer to an UErrorCode to receive any errors
1200 * @return The value of the desired field.