[INTL] Implement supportedLocalesOf on Intl Constructors
[WebKit.git] / Source / JavaScriptCore / icu / unicode / ucal.h
1 /*
2  *******************************************************************************
3  * Copyright (C) 1996-2010, 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 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 /** A calendar.
144  *  For usage in C programs.
145  * @stable ICU 2.0
146  */
147 typedef void* UCalendar;
148
149 /** Possible types of UCalendars 
150  * @stable ICU 2.0
151  */
152 enum UCalendarType {
153   /**
154    * Despite the name, UCAL_TRADITIONAL designates the locale's default calendar,
155    * which may be the Gregorian calendar or some other calendar.
156    * @stable ICU 2.0
157    */
158   UCAL_TRADITIONAL,
159   /**
160    * A better name for UCAL_TRADITIONAL.
161    * @stable ICU 4.2
162    */
163   UCAL_DEFAULT = UCAL_TRADITIONAL,
164   /**
165    * Unambiguously designates the Gregorian calendar for the locale.
166    * @stable ICU 2.0
167    */
168   UCAL_GREGORIAN
169 };
170
171 /** @stable ICU 2.0 */
172 typedef enum UCalendarType UCalendarType;
173
174 /** Possible fields in a UCalendar 
175  * @stable ICU 2.0
176  */
177 enum UCalendarDateFields {
178   /** 
179    * Field number indicating the era, e.g., AD or BC in the Gregorian (Julian) calendar. 
180    * This is a calendar-specific value.
181    * @stable ICU 2.6 
182    */
183   UCAL_ERA,
184
185   /**
186    * Field number indicating the year. This is a calendar-specific value.
187    * @stable ICU 2.6 
188    */
189   UCAL_YEAR,
190
191   /**
192    * Field number indicating the month. This is a calendar-specific value. 
193    * The first month of the year is
194    * <code>JANUARY</code>; the last depends on the number of months in a year.
195    * @see #UCAL_JANUARY
196    * @see #UCAL_FEBRUARY
197    * @see #UCAL_MARCH
198    * @see #UCAL_APRIL
199    * @see #UCAL_MAY
200    * @see #UCAL_JUNE
201    * @see #UCAL_JULY
202    * @see #UCAL_AUGUST
203    * @see #UCAL_SEPTEMBER
204    * @see #UCAL_OCTOBER
205    * @see #UCAL_NOVEMBER
206    * @see #UCAL_DECEMBER
207    * @see #UCAL_UNDECIMBER
208    * @stable ICU 2.6 
209    */
210   UCAL_MONTH,
211
212   /**
213    * Field number indicating the
214    * week number within the current year.  The first week of the year, as
215    * defined by <code>UCAL_FIRST_DAY_OF_WEEK</code> and <code>UCAL_MINIMAL_DAYS_IN_FIRST_WEEK</code>
216    * attributes, has value 1.  Subclasses define
217    * the value of <code>UCAL_WEEK_OF_YEAR</code> for days before the first week of
218    * the year.
219    * @see ucal_getAttribute
220    * @see ucal_setAttribute
221    * @stable ICU 2.6 
222    */
223   UCAL_WEEK_OF_YEAR,
224
225  /**
226    * Field number indicating the
227    * week number within the current month.  The first week of the month, as
228    * defined by <code>UCAL_FIRST_DAY_OF_WEEK</code> and <code>UCAL_MINIMAL_DAYS_IN_FIRST_WEEK</code>
229    * attributes, has value 1.  Subclasses define
230    * the value of <code>WEEK_OF_MONTH</code> for days before the first week of
231    * the month.
232    * @see ucal_getAttribute
233    * @see ucal_setAttribute
234    * @see #UCAL_FIRST_DAY_OF_WEEK
235    * @see #UCAL_MINIMAL_DAYS_IN_FIRST_WEEK
236    * @stable ICU 2.6 
237    */
238   UCAL_WEEK_OF_MONTH,
239
240  /**
241    * Field number indicating the
242    * day of the month. This is a synonym for <code>DAY_OF_MONTH</code>.
243    * The first day of the month has value 1.
244    * @see #UCAL_DAY_OF_MONTH
245    * @stable ICU 2.6 
246    */
247   UCAL_DATE,
248
249  /**
250    * Field number indicating the day
251    * number within the current year.  The first day of the year has value 1.
252    * @stable ICU 2.6 
253    */
254   UCAL_DAY_OF_YEAR,
255
256  /**
257    * Field number indicating the day
258    * of the week.  This field takes values <code>SUNDAY</code>,
259    * <code>MONDAY</code>, <code>TUESDAY</code>, <code>WEDNESDAY</code>,
260    * <code>THURSDAY</code>, <code>FRIDAY</code>, and <code>SATURDAY</code>.
261    * @see #UCAL_SUNDAY
262    * @see #UCAL_MONDAY
263    * @see #UCAL_TUESDAY
264    * @see #UCAL_WEDNESDAY
265    * @see #UCAL_THURSDAY
266    * @see #UCAL_FRIDAY
267    * @see #UCAL_SATURDAY
268    * @stable ICU 2.6 
269    */
270   UCAL_DAY_OF_WEEK,
271
272  /**
273    * Field number indicating the
274    * ordinal number of the day of the week within the current month. Together
275    * with the <code>DAY_OF_WEEK</code> field, this uniquely specifies a day
276    * within a month.  Unlike <code>WEEK_OF_MONTH</code> and
277    * <code>WEEK_OF_YEAR</code>, this field's value does <em>not</em> depend on
278    * <code>getFirstDayOfWeek()</code> or
279    * <code>getMinimalDaysInFirstWeek()</code>.  <code>DAY_OF_MONTH 1</code>
280    * through <code>7</code> always correspond to <code>DAY_OF_WEEK_IN_MONTH
281    * 1</code>; <code>8</code> through <code>15</code> correspond to
282    * <code>DAY_OF_WEEK_IN_MONTH 2</code>, and so on.
283    * <code>DAY_OF_WEEK_IN_MONTH 0</code> indicates the week before
284    * <code>DAY_OF_WEEK_IN_MONTH 1</code>.  Negative values count back from the
285    * end of the month, so the last Sunday of a month is specified as
286    * <code>DAY_OF_WEEK = SUNDAY, DAY_OF_WEEK_IN_MONTH = -1</code>.  Because
287    * negative values count backward they will usually be aligned differently
288    * within the month than positive values.  For example, if a month has 31
289    * days, <code>DAY_OF_WEEK_IN_MONTH -1</code> will overlap
290    * <code>DAY_OF_WEEK_IN_MONTH 5</code> and the end of <code>4</code>.
291    * @see #UCAL_DAY_OF_WEEK
292    * @see #UCAL_WEEK_OF_MONTH
293    * @stable ICU 2.6 
294    */
295   UCAL_DAY_OF_WEEK_IN_MONTH,
296
297  /**
298    * Field number indicating
299    * whether the <code>HOUR</code> is before or after noon.
300    * E.g., at 10:04:15.250 PM the <code>AM_PM</code> is <code>PM</code>.
301    * @see #UCAL_AM
302    * @see #UCAL_PM
303    * @see #UCAL_HOUR
304    * @stable ICU 2.6 
305    */
306   UCAL_AM_PM,
307
308  /**
309    * Field number indicating the
310    * hour of the morning or afternoon. <code>HOUR</code> is used for the 12-hour
311    * clock.
312    * E.g., at 10:04:15.250 PM the <code>HOUR</code> is 10.
313    * @see #UCAL_AM_PM
314    * @see #UCAL_HOUR_OF_DAY
315    * @stable ICU 2.6 
316    */
317   UCAL_HOUR,
318
319  /**
320    * Field number indicating the
321    * hour of the day. <code>HOUR_OF_DAY</code> is used for the 24-hour clock.
322    * E.g., at 10:04:15.250 PM the <code>HOUR_OF_DAY</code> is 22.
323    * @see #UCAL_HOUR
324    * @stable ICU 2.6 
325    */
326   UCAL_HOUR_OF_DAY,
327
328  /**
329    * Field number indicating the
330    * minute within the hour.
331    * E.g., at 10:04:15.250 PM the <code>UCAL_MINUTE</code> is 4.
332    * @stable ICU 2.6 
333    */
334   UCAL_MINUTE,
335
336  /**
337    * Field number indicating the
338    * second within the minute.
339    * E.g., at 10:04:15.250 PM the <code>UCAL_SECOND</code> is 15.
340    * @stable ICU 2.6 
341    */
342   UCAL_SECOND,
343
344  /**
345    * Field number indicating the
346    * millisecond within the second.
347    * E.g., at 10:04:15.250 PM the <code>UCAL_MILLISECOND</code> is 250.
348    * @stable ICU 2.6 
349    */
350   UCAL_MILLISECOND,
351
352  /**
353    * Field number indicating the
354    * raw offset from GMT in milliseconds.
355    * @stable ICU 2.6 
356    */
357   UCAL_ZONE_OFFSET,
358
359  /**
360    * Field number indicating the
361    * daylight savings offset in milliseconds.
362    * @stable ICU 2.6 
363    */
364   UCAL_DST_OFFSET,
365   
366  /**
367    * Field number 
368    * indicating the extended year corresponding to the
369    * <code>UCAL_WEEK_OF_YEAR</code> field.  This may be one greater or less
370    * than the value of <code>UCAL_EXTENDED_YEAR</code>.
371    * @stable ICU 2.6
372    */
373   UCAL_YEAR_WOY,
374
375  /**
376    * Field number 
377    * indicating the localized day of week.  This will be a value from 1
378    * to 7 inclusive, with 1 being the localized first day of the week.
379    * @stable ICU 2.6
380    */
381   UCAL_DOW_LOCAL,
382
383   /**
384    * Year of this calendar system, encompassing all supra-year fields. For example, 
385    * in Gregorian/Julian calendars, positive Extended Year values indicate years AD,
386    *  1 BC = 0 extended, 2 BC = -1 extended, and so on. 
387    * @stable ICU 2.8 
388    */
389   UCAL_EXTENDED_YEAR,
390
391  /**
392    * Field number 
393    * indicating the modified Julian day number.  This is different from
394    * the conventional Julian day number in two regards.  First, it
395    * demarcates days at local zone midnight, rather than noon GMT.
396    * Second, it is a local number; that is, it depends on the local time
397    * zone.  It can be thought of as a single number that encompasses all
398    * the date-related fields.
399    * @stable ICU 2.8
400    */
401   UCAL_JULIAN_DAY, 
402
403   /**
404    * Ranges from 0 to 23:59:59.999 (regardless of DST).  This field behaves <em>exactly</em> 
405    * like a composite of all time-related fields, not including the zone fields.  As such, 
406    * it also reflects discontinuities of those fields on DST transition days.  On a day
407    * of DST onset, it will jump forward.  On a day of DST cessation, it will jump 
408    * backward.  This reflects the fact that it must be combined with the DST_OFFSET field
409    * to obtain a unique local time value.
410    * @stable ICU 2.8
411    */
412   UCAL_MILLISECONDS_IN_DAY,
413
414   /**
415    * Whether or not the current month is a leap month (0 or 1). See the Chinese calendar for
416    * an example of this.
417    */
418   UCAL_IS_LEAP_MONTH,
419   
420   /**
421    * Field count
422    * @stable ICU 2.6
423    */
424   UCAL_FIELD_COUNT,
425
426  /**
427    * Field number indicating the
428    * day of the month. This is a synonym for <code>UCAL_DATE</code>.
429    * The first day of the month has value 1.
430    * @see #UCAL_DATE
431    * Synonym for UCAL_DATE
432    * @stable ICU 2.8
433    **/
434   UCAL_DAY_OF_MONTH=UCAL_DATE
435 };
436
437 /** @stable ICU 2.0 */
438 typedef enum UCalendarDateFields UCalendarDateFields;
439     /**
440      * Useful constant for days of week. Note: Calendar day-of-week is 1-based. Clients
441      * who create locale resources for the field of first-day-of-week should be aware of
442      * this. For instance, in US locale, first-day-of-week is set to 1, i.e., UCAL_SUNDAY.
443      */
444 /** Possible days of the week in a UCalendar 
445  * @stable ICU 2.0
446  */
447 enum UCalendarDaysOfWeek {
448   /** Sunday */
449   UCAL_SUNDAY = 1,
450   /** Monday */
451   UCAL_MONDAY,
452   /** Tuesday */
453   UCAL_TUESDAY,
454   /** Wednesday */
455   UCAL_WEDNESDAY,
456   /** Thursday */
457   UCAL_THURSDAY,
458   /** Friday */
459   UCAL_FRIDAY,
460   /** Saturday */
461   UCAL_SATURDAY
462 };
463
464 /** @stable ICU 2.0 */
465 typedef enum UCalendarDaysOfWeek UCalendarDaysOfWeek;
466
467 /** Possible months in a UCalendar. Note: Calendar month is 0-based.
468  * @stable ICU 2.0
469  */
470 enum UCalendarMonths {
471   /** January */
472   UCAL_JANUARY,
473   /** February */
474   UCAL_FEBRUARY,
475   /** March */
476   UCAL_MARCH,
477   /** April */
478   UCAL_APRIL,
479   /** May */
480   UCAL_MAY,
481   /** June */
482   UCAL_JUNE,
483   /** July */
484   UCAL_JULY,
485   /** August */
486   UCAL_AUGUST,
487   /** September */
488   UCAL_SEPTEMBER,
489   /** October */
490   UCAL_OCTOBER,
491   /** November */
492   UCAL_NOVEMBER,
493   /** December */
494   UCAL_DECEMBER,
495   /** Value of the <code>UCAL_MONTH</code> field indicating the
496     * thirteenth month of the year. Although the Gregorian calendar
497     * does not use this value, lunar calendars do.
498     */
499   UCAL_UNDECIMBER
500 };
501
502 /** @stable ICU 2.0 */
503 typedef enum UCalendarMonths UCalendarMonths;
504
505 /** Possible AM/PM values in a UCalendar 
506  * @stable ICU 2.0
507  */
508 enum UCalendarAMPMs {
509     /** AM */
510   UCAL_AM,
511   /** PM */
512   UCAL_PM
513 };
514
515 /** @stable ICU 2.0 */
516 typedef enum UCalendarAMPMs UCalendarAMPMs;
517
518 /**
519  * Create an enumeration over all time zones.
520  *
521  * @param ec input/output error code
522  *
523  * @return an enumeration object that the caller must dispose of using
524  * uenum_close(), or NULL upon failure. In case of failure *ec will
525  * indicate the error.
526  *
527  * @stable ICU 2.6
528  */
529 U_STABLE UEnumeration* U_EXPORT2
530 ucal_openTimeZones(UErrorCode* ec);
531
532 /**
533  * Create an enumeration over all time zones associated with the given
534  * country. Some zones are affiliated with no country (e.g., "UTC");
535  * these may also be retrieved, as a group.
536  *
537  * @param country the ISO 3166 two-letter country code, or NULL to
538  * retrieve zones not affiliated with any country
539  *
540  * @param ec input/output error code
541  *
542  * @return an enumeration object that the caller must dispose of using
543  * uenum_close(), or NULL upon failure. In case of failure *ec will
544  * indicate the error.
545  *
546  * @stable ICU 2.6
547  */
548 U_STABLE UEnumeration* U_EXPORT2
549 ucal_openCountryTimeZones(const char* country, UErrorCode* ec);
550
551 /**
552  * Return the default time zone. The default is determined initially
553  * by querying the host operating system. It may be changed with
554  * ucal_setDefaultTimeZone() or with the C++ TimeZone API.
555  *
556  * @param result A buffer to receive the result, or NULL
557  *
558  * @param resultCapacity The capacity of the result buffer
559  *
560  * @param ec input/output error code
561  *
562  * @return The result string length, not including the terminating
563  * null
564  *
565  * @stable ICU 2.6
566  */
567 U_STABLE int32_t U_EXPORT2
568 ucal_getDefaultTimeZone(UChar* result, int32_t resultCapacity, UErrorCode* ec);
569
570 /**
571  * Set the default time zone.
572  *
573  * @param zoneID null-terminated time zone ID
574  *
575  * @param ec input/output error code
576  *
577  * @stable ICU 2.6
578  */
579 U_STABLE void U_EXPORT2
580 ucal_setDefaultTimeZone(const UChar* zoneID, UErrorCode* ec);
581
582 /**
583  * Return the amount of time in milliseconds that the clock is
584  * advanced during daylight savings time for the given time zone, or
585  * zero if the time zone does not observe daylight savings time.
586  *
587  * @param zoneID null-terminated time zone ID
588  *
589  * @param ec input/output error code
590  *
591  * @return the number of milliseconds the time is advanced with
592  * respect to standard time when the daylight savings rules are in
593  * effect. This is always a non-negative number, most commonly either
594  * 3,600,000 (one hour) or zero.
595  *
596  * @stable ICU 2.6
597  */
598 U_STABLE int32_t U_EXPORT2
599 ucal_getDSTSavings(const UChar* zoneID, UErrorCode* ec);
600
601 /**
602  * Get the current date and time.
603  * The value returned is represented as milliseconds from the epoch.
604  * @return The current date and time.
605  * @stable ICU 2.0
606  */
607 U_STABLE UDate U_EXPORT2 
608 ucal_getNow(void);
609
610 /**
611  * Open a UCalendar.
612  * A UCalendar may be used to convert a millisecond value to a year,
613  * month, and day.
614  * <p>
615  * Note: When unknown TimeZone ID is specified, the UCalendar returned
616  * by the function is initialized with GMT ("Etc/GMT") without any
617  * errors/warnings.  If you want to check if a TimeZone ID is valid,
618  * use ucal_getCanonicalTimeZoneID prior to this function.
619  * 
620  * @param zoneID The desired TimeZone ID.  If 0, use the default time zone.
621  * @param len The length of zoneID, or -1 if null-terminated.
622  * @param locale The desired locale
623  * @param type The type of UCalendar to open. This can be UCAL_GREGORIAN to open the Gregorian
624  * calendar for the locale, or UCAL_DEFAULT to open the default calendar for the locale (the
625  * default calendar may also be Gregorian). To open a specific non-Gregorian calendar for the
626  * locale, use uloc_setKeywordValue to set the value of the calendar keyword for the locale
627  * and then pass the locale to ucal_open with UCAL_DEFAULT as the type.
628  * @param status A pointer to an UErrorCode to receive any errors
629  * @return A pointer to a UCalendar, or 0 if an error occurred.
630  * @stable ICU 2.0
631  */
632 U_STABLE UCalendar* U_EXPORT2 
633 ucal_open(const UChar*   zoneID,
634           int32_t        len,
635           const char*    locale,
636           UCalendarType  type,
637           UErrorCode*    status);
638
639 /**
640  * Close a UCalendar.
641  * Once closed, a UCalendar may no longer be used.
642  * @param cal The UCalendar to close.
643  * @stable ICU 2.0
644  */
645 U_STABLE void U_EXPORT2 
646 ucal_close(UCalendar *cal);
647
648 #if U_SHOW_CPLUSPLUS_API
649
650 U_NAMESPACE_BEGIN
651
652 /**
653  * \class LocalUCalendarPointer
654  * "Smart pointer" class, closes a UCalendar via ucal_close().
655  * For most methods see the LocalPointerBase base class.
656  *
657  * @see LocalPointerBase
658  * @see LocalPointer
659  * @stable ICU 4.4
660  */
661 U_DEFINE_LOCAL_OPEN_POINTER(LocalUCalendarPointer, UCalendar, ucal_close);
662
663 U_NAMESPACE_END
664
665 #endif
666
667 /**
668  * Open a copy of a UCalendar.
669  * This function performs a deep copy.
670  * @param cal The calendar to copy
671  * @param status A pointer to an UErrorCode to receive any errors.
672  * @return A pointer to a UCalendar identical to cal.
673  * @stable ICU 4.0
674  */
675 U_STABLE UCalendar* U_EXPORT2 
676 ucal_clone(const UCalendar* cal,
677            UErrorCode*      status);
678
679 /**
680  * Set the TimeZone used by a UCalendar.
681  * A UCalendar uses a timezone for converting from Greenwich time to local time.
682  * @param cal The UCalendar to set.
683  * @param zoneID The desired TimeZone ID.  If 0, use the default time zone.
684  * @param len The length of zoneID, or -1 if null-terminated.
685  * @param status A pointer to an UErrorCode to receive any errors.
686  * @stable ICU 2.0
687  */
688 U_STABLE void U_EXPORT2 
689 ucal_setTimeZone(UCalendar*    cal,
690                  const UChar*  zoneID,
691                  int32_t       len,
692                  UErrorCode*   status);
693
694 /**
695  * Possible formats for a UCalendar's display name 
696  * @stable ICU 2.0
697  */
698 enum UCalendarDisplayNameType {
699   /** Standard display name */
700   UCAL_STANDARD,
701   /** Short standard display name */
702   UCAL_SHORT_STANDARD,
703   /** Daylight savings display name */
704   UCAL_DST,
705   /** Short daylight savings display name */
706   UCAL_SHORT_DST
707 };
708
709 /** @stable ICU 2.0 */
710 typedef enum UCalendarDisplayNameType UCalendarDisplayNameType;
711
712 /**
713  * Get the display name for a UCalendar's TimeZone.
714  * A display name is suitable for presentation to a user.
715  * @param cal          The UCalendar to query.
716  * @param type         The desired display name format; one of UCAL_STANDARD, UCAL_SHORT_STANDARD,
717  *                     UCAL_DST, UCAL_SHORT_DST
718  * @param locale       The desired locale for the display name.
719  * @param result       A pointer to a buffer to receive the formatted number.
720  * @param resultLength The maximum size of result.
721  * @param status       A pointer to an UErrorCode to receive any errors
722  * @return             The total buffer size needed; if greater than resultLength, the output was truncated.
723  * @stable ICU 2.0
724  */
725 U_STABLE int32_t U_EXPORT2 
726 ucal_getTimeZoneDisplayName(const UCalendar*          cal,
727                             UCalendarDisplayNameType  type,
728                             const char*               locale,
729                             UChar*                    result,
730                             int32_t                   resultLength,
731                             UErrorCode*               status);
732
733 /**
734  * Determine if a UCalendar is currently in daylight savings time.
735  * Daylight savings time is not used in all parts of the world.
736  * @param cal The UCalendar to query.
737  * @param status A pointer to an UErrorCode to receive any errors
738  * @return TRUE if cal is currently in daylight savings time, FALSE otherwise
739  * @stable ICU 2.0
740  */
741 U_STABLE UBool U_EXPORT2 
742 ucal_inDaylightTime(const UCalendar*  cal,
743                     UErrorCode*       status );
744
745 /**
746  * Sets the GregorianCalendar change date. This is the point when the switch from
747  * Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October
748  * 15, 1582. Previous to this time and date will be Julian dates.
749  *
750  * This function works only for Gregorian calendars. If the UCalendar is not
751  * an instance of a Gregorian calendar, then a U_UNSUPPORTED_ERROR
752  * error code is set.
753  *
754  * @param cal        The calendar object.
755  * @param date       The given Gregorian cutover date.
756  * @param pErrorCode Pointer to a standard ICU error code. Its input value must
757  *                   pass the U_SUCCESS() test, or else the function returns
758  *                   immediately. Check for U_FAILURE() on output or use with
759  *                   function chaining. (See User Guide for details.)
760  *
761  * @see GregorianCalendar::setGregorianChange
762  * @see ucal_getGregorianChange
763  * @stable ICU 3.6
764  */
765 U_STABLE void U_EXPORT2
766 ucal_setGregorianChange(UCalendar *cal, UDate date, UErrorCode *pErrorCode);
767
768 /**
769  * Gets the Gregorian Calendar change date. This is the point when the switch from
770  * Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, October
771  * 15, 1582. Previous to this time and date will be Julian dates.
772  *
773  * This function works only for Gregorian calendars. If the UCalendar is not
774  * an instance of a Gregorian calendar, then a U_UNSUPPORTED_ERROR
775  * error code is set.
776  *
777  * @param cal        The calendar object.
778  * @param pErrorCode Pointer to a standard ICU error code. Its input value must
779  *                   pass the U_SUCCESS() test, or else the function returns
780  *                   immediately. Check for U_FAILURE() on output or use with
781  *                   function chaining. (See User Guide for details.)
782  * @return   The Gregorian cutover time for this calendar.
783  *
784  * @see GregorianCalendar::getGregorianChange
785  * @see ucal_setGregorianChange
786  * @stable ICU 3.6
787  */
788 U_STABLE UDate U_EXPORT2
789 ucal_getGregorianChange(const UCalendar *cal, UErrorCode *pErrorCode);
790
791 /**
792  * Types of UCalendar attributes 
793  * @stable ICU 2.0
794  */
795 enum UCalendarAttribute {
796     /** Lenient parsing */
797   UCAL_LENIENT,
798   /** First day of week */
799   UCAL_FIRST_DAY_OF_WEEK,
800   /** Minimum number of days in first week */
801   UCAL_MINIMAL_DAYS_IN_FIRST_WEEK
802 };
803
804 /** @stable ICU 2.0 */
805 typedef enum UCalendarAttribute UCalendarAttribute;
806
807 /**
808  * Get a numeric attribute associated with a UCalendar.
809  * Numeric attributes include the first day of the week, or the minimal numbers
810  * of days in the first week of the month.
811  * @param cal The UCalendar to query.
812  * @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK,
813  * or UCAL_MINIMAL_DAYS_IN_FIRST_WEEK
814  * @return The value of attr.
815  * @see ucal_setAttribute
816  * @stable ICU 2.0
817  */
818 U_STABLE int32_t U_EXPORT2 
819 ucal_getAttribute(const UCalendar*    cal,
820                   UCalendarAttribute  attr);
821
822 /**
823  * Set a numeric attribute associated with a UCalendar.
824  * Numeric attributes include the first day of the week, or the minimal numbers
825  * of days in the first week of the month.
826  * @param cal The UCalendar to set.
827  * @param attr The desired attribute; one of UCAL_LENIENT, UCAL_FIRST_DAY_OF_WEEK,
828  * or UCAL_MINIMAL_DAYS_IN_FIRST_WEEK
829  * @param newValue The new value of attr.
830  * @see ucal_getAttribute
831  * @stable ICU 2.0
832  */
833 U_STABLE void U_EXPORT2 
834 ucal_setAttribute(UCalendar*          cal,
835                   UCalendarAttribute  attr,
836                   int32_t             newValue);
837
838 /**
839  * Get a locale for which calendars are available.
840  * A UCalendar in a locale returned by this function will contain the correct
841  * day and month names for the locale.
842  * @param localeIndex The index of the desired locale.
843  * @return A locale for which calendars are available, or 0 if none.
844  * @see ucal_countAvailable
845  * @stable ICU 2.0
846  */
847 U_STABLE const char* U_EXPORT2 
848 ucal_getAvailable(int32_t localeIndex);
849
850 /**
851  * Determine how many locales have calendars available.
852  * This function is most useful as determining the loop ending condition for
853  * calls to \ref ucal_getAvailable.
854  * @return The number of locales for which calendars are available.
855  * @see ucal_getAvailable
856  * @stable ICU 2.0
857  */
858 U_STABLE int32_t U_EXPORT2 
859 ucal_countAvailable(void);
860
861 /**
862  * Get a UCalendar's current time in millis.
863  * The time is represented as milliseconds from the epoch.
864  * @param cal The UCalendar to query.
865  * @param status A pointer to an UErrorCode to receive any errors
866  * @return The calendar's current time in millis.
867  * @see ucal_setMillis
868  * @see ucal_setDate
869  * @see ucal_setDateTime
870  * @stable ICU 2.0
871  */
872 U_STABLE UDate U_EXPORT2 
873 ucal_getMillis(const UCalendar*  cal,
874                UErrorCode*       status);
875
876 /**
877  * Set a UCalendar's current time in millis.
878  * The time is represented as milliseconds from the epoch.
879  * @param cal The UCalendar to set.
880  * @param dateTime The desired date and time.
881  * @param status A pointer to an UErrorCode to receive any errors
882  * @see ucal_getMillis
883  * @see ucal_setDate
884  * @see ucal_setDateTime
885  * @stable ICU 2.0
886  */
887 U_STABLE void U_EXPORT2 
888 ucal_setMillis(UCalendar*   cal,
889                UDate        dateTime,
890                UErrorCode*  status );
891
892 /**
893  * Set a UCalendar's current date.
894  * The date is represented as a series of 32-bit integers.
895  * @param cal The UCalendar to set.
896  * @param year The desired year.
897  * @param month The desired month; one of UCAL_JANUARY, UCAL_FEBRUARY, UCAL_MARCH, UCAL_APRIL, UCAL_MAY,
898  * UCAL_JUNE, UCAL_JULY, UCAL_AUGUST, UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBER, UCAL_DECEMBER, UCAL_UNDECIMBER
899  * @param date The desired day of the month.
900  * @param status A pointer to an UErrorCode to receive any errors
901  * @see ucal_getMillis
902  * @see ucal_setMillis
903  * @see ucal_setDateTime
904  * @stable ICU 2.0
905  */
906 U_STABLE void U_EXPORT2 
907 ucal_setDate(UCalendar*   cal,
908              int32_t      year,
909              int32_t      month,
910              int32_t      date,
911              UErrorCode*  status);
912
913 /**
914  * Set a UCalendar's current date.
915  * The date is represented as a series of 32-bit integers.
916  * @param cal The UCalendar to set.
917  * @param year The desired year.
918  * @param month The desired month; one of UCAL_JANUARY, UCAL_FEBRUARY, UCAL_MARCH, UCAL_APRIL, UCAL_MAY,
919  * UCAL_JUNE, UCAL_JULY, UCAL_AUGUST, UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBER, UCAL_DECEMBER, UCAL_UNDECIMBER
920  * @param date The desired day of the month.
921  * @param hour The desired hour of day.
922  * @param minute The desired minute.
923  * @param second The desirec second.
924  * @param status A pointer to an UErrorCode to receive any errors
925  * @see ucal_getMillis
926  * @see ucal_setMillis
927  * @see ucal_setDate
928  * @stable ICU 2.0
929  */
930 U_STABLE void U_EXPORT2 
931 ucal_setDateTime(UCalendar*   cal,
932                  int32_t      year,
933                  int32_t      month,
934                  int32_t      date,
935                  int32_t      hour,
936                  int32_t      minute,
937                  int32_t      second,
938                  UErrorCode*  status);
939
940 /**
941  * Returns TRUE if two UCalendars are equivalent.  Equivalent
942  * UCalendars will behave identically, but they may be set to
943  * different times.
944  * @param cal1 The first of the UCalendars to compare.
945  * @param cal2 The second of the UCalendars to compare.
946  * @return TRUE if cal1 and cal2 are equivalent, FALSE otherwise.
947  * @stable ICU 2.0
948  */
949 U_STABLE UBool U_EXPORT2 
950 ucal_equivalentTo(const UCalendar*  cal1,
951                   const UCalendar*  cal2);
952
953 /**
954  * Add a specified signed amount to a particular field in a UCalendar.
955  * This can modify more significant fields in the calendar.
956  * @param cal The UCalendar to which to add.
957  * @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
958  * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
959  * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
960  * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
961  * @param amount The signed amount to add to field. If the amount causes the value
962  * to exceed to maximum or minimum values for that field, other fields are modified
963  * to preserve the magnitude of the change.
964  * @param status A pointer to an UErrorCode to receive any errors
965  * @see ucal_roll
966  * @stable ICU 2.0
967  */
968 U_STABLE void U_EXPORT2 
969 ucal_add(UCalendar*           cal,
970          UCalendarDateFields  field,
971          int32_t              amount,
972          UErrorCode*          status);
973
974 /**
975  * Add a specified signed amount to a particular field in a UCalendar.
976  * This will not modify more significant fields in the calendar.
977  * @param cal The UCalendar to which to add.
978  * @param field The field to which to add the signed value; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
979  * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
980  * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
981  * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
982  * @param amount The signed amount to add to field. If the amount causes the value
983  * to exceed to maximum or minimum values for that field, the field is pinned to a permissible
984  * value.
985  * @param status A pointer to an UErrorCode to receive any errors
986  * @see ucal_add
987  * @stable ICU 2.0
988  */
989 U_STABLE void U_EXPORT2 
990 ucal_roll(UCalendar*           cal,
991           UCalendarDateFields  field,
992           int32_t              amount,
993           UErrorCode*          status);
994
995 /**
996  * Get the current value of a field from a UCalendar.
997  * All fields are represented as 32-bit integers.
998  * @param cal The UCalendar to query.
999  * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
1000  * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
1001  * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
1002  * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
1003  * @param status A pointer to an UErrorCode to receive any errors
1004  * @return The value of the desired field.
1005  * @see ucal_set
1006  * @see ucal_isSet
1007  * @see ucal_clearField
1008  * @see ucal_clear
1009  * @stable ICU 2.0
1010  */
1011 U_STABLE int32_t U_EXPORT2 
1012 ucal_get(const UCalendar*     cal,
1013          UCalendarDateFields  field,
1014          UErrorCode*          status );
1015
1016 /**
1017  * Set the value of a field in a UCalendar.
1018  * All fields are represented as 32-bit integers.
1019  * @param cal The UCalendar to set.
1020  * @param field The field to set; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
1021  * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
1022  * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
1023  * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
1024  * @param value The desired value of field.
1025  * @see ucal_get
1026  * @see ucal_isSet
1027  * @see ucal_clearField
1028  * @see ucal_clear
1029  * @stable ICU 2.0
1030  */
1031 U_STABLE void U_EXPORT2 
1032 ucal_set(UCalendar*           cal,
1033          UCalendarDateFields  field,
1034          int32_t              value);
1035
1036 /**
1037  * Determine if a field in a UCalendar is set.
1038  * All fields are represented as 32-bit integers.
1039  * @param cal The UCalendar to query.
1040  * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
1041  * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
1042  * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
1043  * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
1044  * @return TRUE if field is set, FALSE otherwise.
1045  * @see ucal_get
1046  * @see ucal_set
1047  * @see ucal_clearField
1048  * @see ucal_clear
1049  * @stable ICU 2.0
1050  */
1051 U_STABLE UBool U_EXPORT2 
1052 ucal_isSet(const UCalendar*     cal,
1053            UCalendarDateFields  field);
1054
1055 /**
1056  * Clear a field in a UCalendar.
1057  * All fields are represented as 32-bit integers.
1058  * @param cal The UCalendar containing the field to clear.
1059  * @param field The field to clear; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
1060  * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
1061  * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
1062  * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
1063  * @see ucal_get
1064  * @see ucal_set
1065  * @see ucal_isSet
1066  * @see ucal_clear
1067  * @stable ICU 2.0
1068  */
1069 U_STABLE void U_EXPORT2 
1070 ucal_clearField(UCalendar*           cal,
1071                 UCalendarDateFields  field);
1072
1073 /**
1074  * Clear all fields in a UCalendar.
1075  * All fields are represented as 32-bit integers.
1076  * @param calendar The UCalendar to clear.
1077  * @see ucal_get
1078  * @see ucal_set
1079  * @see ucal_isSet
1080  * @see ucal_clearField
1081  * @stable ICU 2.0
1082  */
1083 U_STABLE void U_EXPORT2 
1084 ucal_clear(UCalendar* calendar);
1085
1086 /**
1087  * Possible limit values for a UCalendar 
1088  * @stable ICU 2.0
1089  */
1090 enum UCalendarLimitType {
1091   /** Minimum value */
1092   UCAL_MINIMUM,
1093   /** Maximum value */
1094   UCAL_MAXIMUM,
1095   /** Greatest minimum value */
1096   UCAL_GREATEST_MINIMUM,
1097   /** Leaest maximum value */
1098   UCAL_LEAST_MAXIMUM,
1099   /** Actual minimum value */
1100   UCAL_ACTUAL_MINIMUM,
1101   /** Actual maximum value */
1102   UCAL_ACTUAL_MAXIMUM
1103 };
1104
1105 /** @stable ICU 2.0 */
1106 typedef enum UCalendarLimitType UCalendarLimitType;
1107
1108 /**
1109  * Determine a limit for a field in a UCalendar.
1110  * A limit is a maximum or minimum value for a field.
1111  * @param cal The UCalendar to query.
1112  * @param field The desired field; one of UCAL_ERA, UCAL_YEAR, UCAL_MONTH,
1113  * UCAL_WEEK_OF_YEAR, UCAL_WEEK_OF_MONTH, UCAL_DATE, UCAL_DAY_OF_YEAR, UCAL_DAY_OF_WEEK,
1114  * UCAL_DAY_OF_WEEK_IN_MONTH, UCAL_AM_PM, UCAL_HOUR, UCAL_HOUR_OF_DAY, UCAL_MINUTE, UCAL_SECOND,
1115  * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
1116  * @param type The desired critical point; one of UCAL_MINIMUM, UCAL_MAXIMUM, UCAL_GREATEST_MINIMUM,
1117  * UCAL_LEAST_MAXIMUM, UCAL_ACTUAL_MINIMUM, UCAL_ACTUAL_MAXIMUM
1118  * @param status A pointer to an UErrorCode to receive any errors.
1119  * @return The requested value.
1120  * @stable ICU 2.0
1121  */
1122 U_STABLE int32_t U_EXPORT2 
1123 ucal_getLimit(const UCalendar*     cal,
1124               UCalendarDateFields  field,
1125               UCalendarLimitType   type,
1126               UErrorCode*          status);
1127
1128 /** Get the locale for this calendar object. You can choose between valid and actual locale.
1129  *  @param cal The calendar object
1130  *  @param type type of the locale we're looking for (valid or actual) 
1131  *  @param status error code for the operation
1132  *  @return the locale name
1133  *  @stable ICU 2.8
1134  */
1135 U_STABLE const char * U_EXPORT2
1136 ucal_getLocaleByType(const UCalendar *cal, ULocDataLocaleType type, UErrorCode* status);
1137
1138 /**
1139  * Returns the timezone data version currently used by ICU.
1140  * @param status error code for the operation
1141  * @return the version string, such as "2007f"
1142  * @stable ICU 3.8
1143  */
1144 U_STABLE const char * U_EXPORT2
1145 ucal_getTZDataVersion(UErrorCode* status);
1146
1147 /**
1148  * Returns the canonical system timezone ID or the normalized
1149  * custom time zone ID for the given time zone ID.
1150  * @param id        The input timezone ID to be canonicalized.
1151  * @param len       The length of id, or -1 if null-terminated.
1152  * @param result    The buffer receives the canonical system timezone ID
1153  *                  or the custom timezone ID in normalized format.
1154  * @param resultCapacity    The capacity of the result buffer.
1155  * @param isSystemID        Receives if the given ID is a known system
1156      *                      timezone ID.
1157  * @param status    Recevies the status.  When the given timezone ID
1158  *                  is neither a known system time zone ID nor a
1159  *                  valid custom timezone ID, U_ILLEGAL_ARGUMENT_ERROR
1160  *                  is set.
1161  * @return          The result string length, not including the terminating
1162  *                  null.
1163  * @stable ICU 4.0
1164  */
1165 U_STABLE int32_t U_EXPORT2
1166 ucal_getCanonicalTimeZoneID(const UChar* id, int32_t len,
1167                             UChar* result, int32_t resultCapacity, UBool *isSystemID, UErrorCode* status);
1168 /**
1169  * Get the resource keyword value string designating the calendar type for the UCalendar.
1170  * @param cal The UCalendar to query.
1171  * @param status The error code for the operation.
1172  * @return The resource keyword value string.
1173  * @stable ICU 4.2
1174  */
1175 U_STABLE const char * U_EXPORT2
1176 ucal_getType(const UCalendar *cal, UErrorCode* status);
1177
1178 /**
1179  * Given a key and a locale, returns an array of string values in a preferred
1180  * order that would make a difference. These are all and only those values where
1181  * the open (creation) of the service with the locale formed from the input locale
1182  * plus input keyword and that value has different behavior than creation with the
1183  * input locale alone.
1184  * @param key           one of the keys supported by this service.  For now, only
1185  *                      "calendar" is supported.
1186  * @param locale        the locale
1187  * @param commonlyUsed  if set to true it will return only commonly used values
1188  *                      with the given locale in preferred order.  Otherwise,
1189  *                      it will return all the available values for the locale.
1190  * @param status error status
1191  * @return a string enumeration over keyword values for the given key and the locale.
1192  * @stable ICU 4.2
1193  */
1194 U_STABLE UEnumeration* U_EXPORT2
1195 ucal_getKeywordValuesForLocale(const char* key,
1196                                const char* locale,
1197                                UBool commonlyUsed,
1198                                UErrorCode* status);
1199
1200
1201 /** Weekday types, as returned by ucal_getDayOfWeekType().
1202  * @stable ICU 4.4
1203  */
1204 enum UCalendarWeekdayType {
1205   /**
1206    * Designates a full weekday (no part of the day is included in the weekend).
1207    * @stable ICU 4.4 
1208    */
1209   UCAL_WEEKDAY,
1210   /**
1211    * Designates a full weekend day (the entire day is included in the weekend).
1212    * @stable ICU 4.4 
1213    */
1214   UCAL_WEEKEND,
1215   /**
1216    * Designates a day that starts as a weekday and transitions to the weekend.
1217    * Call ucal_getWeekendTransition() to get the time of transition.
1218    * @stable ICU 4.4 
1219    */
1220   UCAL_WEEKEND_ONSET,
1221   /**
1222    * Designates a day that starts as the weekend and transitions to a weekday.
1223    * Call ucal_getWeekendTransition() to get the time of transition.
1224    * @stable ICU 4.4 
1225    */
1226   UCAL_WEEKEND_CEASE
1227 };
1228
1229 /** @stable ICU 4.4 */
1230 typedef enum UCalendarWeekdayType UCalendarWeekdayType;
1231
1232 /**
1233  * Returns whether the given day of the week is a weekday, a
1234  * weekend day, or a day that transitions from one to the other,
1235  * in this calendar system. If a transition occurs at midnight,
1236  * then the days before and after the transition will have the
1237  * type UCAL_WEEKDAY or UCAL_WEEKEND. If a transition occurs at a time
1238  * other than midnight, then the day of the transition will have
1239  * the type UCAL_WEEKEND_ONSET or UCAL_WEEKEND_CEASE. In this case, the
1240  * method getWeekendTransition() will return the point of
1241  * transition.
1242  * @param cal The UCalendar to query.
1243  * @param dayOfWeek The day of the week whose type is desired (UCAL_SUNDAY..UCAL_SATURDAY).
1244  * @param status The error code for the operation.
1245  * @return The UCalendarWeekdayType for the day of the week.
1246  * @stable ICU 4.4
1247  */
1248 U_STABLE UCalendarWeekdayType U_EXPORT2
1249 ucal_getDayOfWeekType(const UCalendar *cal, UCalendarDaysOfWeek dayOfWeek, UErrorCode* status);
1250
1251 /**
1252  * Returns the time during the day at which the weekend begins or ends in
1253  * this calendar system.  If ucal_getDayOfWeekType() rerturns UCAL_WEEKEND_ONSET
1254  * for the specified dayOfWeek, return the time at which the weekend begins.
1255  * If ucal_getDayOfWeekType() returns UCAL_WEEKEND_CEASE for the specified dayOfWeek,
1256  * return the time at which the weekend ends. If ucal_getDayOfWeekType() returns
1257  * some other UCalendarWeekdayType for the specified dayOfWeek, is it an error condition
1258  * (U_ILLEGAL_ARGUMENT_ERROR).
1259  * @param cal The UCalendar to query.
1260  * @param dayOfWeek The day of the week for which the weekend transition time is
1261  * desired (UCAL_SUNDAY..UCAL_SATURDAY).
1262  * @param status The error code for the operation.
1263  * @return The milliseconds after midnight at which the weekend begins or ends.
1264  * @stable ICU 4.4
1265  */
1266 U_STABLE int32_t U_EXPORT2
1267 ucal_getWeekendTransition(const UCalendar *cal, UCalendarDaysOfWeek dayOfWeek, UErrorCode *status);
1268
1269 /**
1270  * Returns TRUE if the given UDate is in the weekend in
1271  * this calendar system.
1272  * @param cal The UCalendar to query.
1273  * @param date The UDate in question.
1274  * @param status The error code for the operation.
1275  * @return TRUE if the given UDate is in the weekend in
1276  * this calendar system, FALSE otherwise.
1277  * @stable ICU 4.4
1278  */
1279 U_STABLE UBool U_EXPORT2
1280 ucal_isWeekend(const UCalendar *cal, UDate date, UErrorCode *status);
1281
1282
1283 #endif /* #if !UCONFIG_NO_FORMATTING */
1284
1285 #endif