The Tor Browser / file comparison

comparison: intl/icu/source/i18n/unicode/ucal.h

intl/icu/source/i18n/unicode/ucal.h

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

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial