Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(7)

Side by Side Diff: public/i18n/unicode/ucal.h

Issue 18836004: Move ICU headers from public/{common,i18n} to source/{common,i18n} (Closed) Base URL: https://chromium.googlesource.com/chromium/deps/icu46.git@master
Patch Set: same as ps #3. retry uploading Created 7 years, 5 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
« no previous file with comments | « public/i18n/unicode/tztrans.h ('k') | public/i18n/unicode/ucol.h » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
(Empty)
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 circumstanc es
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) c alendar.
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 examp le,
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. O n a day
407 * of DST onset, it will jump forward. On a day of DST cessation, it will jum p
408 * backward. This reflects the fact that it must be combined with the DST_OFF SET 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., UC AL_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 cal endar 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, UC AL_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 resultLengt h, 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 fro m
747 * Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, Oct ober
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 fr om
770 * Julian dates to Gregorian dates occurred. Default is 00:00:00 local time, Oct ober
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_WEE K,
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_WEE K,
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_MARC H, UCAL_APRIL, UCAL_MAY,
898 * UCAL_JUNE, UCAL_JULY, UCAL_AUGUST, UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBE R, 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_MARC H, UCAL_APRIL, UCAL_MAY,
919 * UCAL_JUNE, UCAL_JULY, UCAL_AUGUST, UCAL_SEPTEMBER, UCAL_OCTOBER, UCAL_NOVEMBE R, 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, UCA L_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_MINU TE, 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 val ue
962 * to exceed to maximum or minimum values for that field, other fields are modif ied
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, UCA L_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_MINU TE, 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 val ue
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_MINU TE, 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_MINU TE, 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_MINU TE, 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_MINU TE, 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_MINU TE, UCAL_SECOND,
1115 * UCAL_MILLISECOND, UCAL_ZONE_OFFSET, UCAL_DST_OFFSET.
1116 * @param type The desired critical point; one of UCAL_MINIMUM, UCAL_MAXIMUM, UC AL_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 ac tual 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 *isSyst emID, UErrorCode* status);
1168 /**
1169 * Get the resource keyword value string designating the calendar type for the U Calendar.
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 loca le
1182 * plus input keyword and that value has different behavior than creation with t he
1183 * input locale alone.
1184 * @param key one of the keys supported by this service. For now, onl y
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 lo cale.
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, UErro rCode* 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 dayOf Week,
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 c ondition
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, U ErrorCode *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
OLDNEW
« no previous file with comments | « public/i18n/unicode/tztrans.h ('k') | public/i18n/unicode/ucol.h » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698