[INTL] Implement supportedLocalesOf on Intl Constructors
[WebKit.git] / Source / JavaScriptCore / icu / unicode / udat.h
1 /*
2  *******************************************************************************
3  * Copyright (C) 1996-2010, International Business Machines
4  * Corporation and others. All Rights Reserved.
5  *******************************************************************************
6 */
7
8 #ifndef UDAT_H
9 #define UDAT_H
10
11 #include "unicode/utypes.h"
12
13 #if !UCONFIG_NO_FORMATTING
14
15 #include "unicode/localpointer.h"
16 #include "unicode/ucal.h"
17 #include "unicode/unum.h"
18 /**
19  * \file
20  * \brief C API: DateFormat
21  *
22  * <h2> Date Format C API</h2>
23  *
24  * Date Format C API  consists of functions that convert dates and
25  * times from their internal representations to textual form and back again in a
26  * language-independent manner. Converting from the internal representation (milliseconds
27  * since midnight, January 1, 1970) to text is known as "formatting," and converting
28  * from text to millis is known as "parsing."  We currently define only one concrete
29  * structure UDateFormat, which can handle pretty much all normal
30  * date formatting and parsing actions.
31  * <P>
32  * Date Format helps you to format and parse dates for any locale. Your code can
33  * be completely independent of the locale conventions for months, days of the
34  * week, or even the calendar format: lunar vs. solar.
35  * <P>
36  * To format a date for the current Locale with default time and date style,
37  * use one of the static factory methods:
38  * <pre>
39  * \code
40  *  UErrorCode status = U_ZERO_ERROR;
41  *  UChar *myString;
42  *  int32_t myStrlen = 0;
43  *  UDateFormat* dfmt = udat_open(UDAT_DEFAULT, UDAT_DEFAULT, NULL, NULL, -1, NULL, -1, &status);
44  *  myStrlen = udat_format(dfmt, myDate, NULL, myStrlen, NULL, &status);
45  *  if (status==U_BUFFER_OVERFLOW_ERROR){
46  *      status=U_ZERO_ERROR;
47  *      myString=(UChar*)malloc(sizeof(UChar) * (myStrlen+1) );
48  *      udat_format(dfmt, myDate, myString, myStrlen+1, NULL, &status);
49  *  }
50  * \endcode
51  * </pre>
52  * If you are formatting multiple numbers, it is more efficient to get the
53  * format and use it multiple times so that the system doesn't have to fetch the
54  * information about the local language and country conventions multiple times.
55  * <pre>
56  * \code
57  *  UErrorCode status = U_ZERO_ERROR;
58  *  int32_t i, myStrlen = 0;
59  *  UChar* myString;
60  *  char buffer[1024];
61  *  UDate myDateArr[] = { 0.0, 100000000.0, 2000000000.0 }; // test values
62  *  UDateFormat* df = udat_open(UDAT_DEFAULT, UDAT_DEFAULT, NULL, NULL, -1, NULL, 0, &status);
63  *  for (i = 0; i < 3; i++) {
64  *      myStrlen = udat_format(df, myDateArr[i], NULL, myStrlen, NULL, &status);
65  *      if(status == U_BUFFER_OVERFLOW_ERROR){
66  *          status = U_ZERO_ERROR;
67  *          myString = (UChar*)malloc(sizeof(UChar) * (myStrlen+1) );
68  *          udat_format(df, myDateArr[i], myString, myStrlen+1, NULL, &status);
69  *          printf("%s\n", u_austrcpy(buffer, myString) );
70  *          free(myString);
71  *      }
72  *  }
73  * \endcode
74  * </pre>
75  * To get specific fields of a date, you can use UFieldPosition to
76  * get specific fields.
77  * <pre>
78  * \code
79  *  UErrorCode status = U_ZERO_ERROR;
80  *  UFieldPosition pos;
81  *  UChar *myString;
82  *  int32_t myStrlen = 0;
83  *  char buffer[1024];
84  *
85  *  pos.field = 1;  // Same as the DateFormat::EField enum
86  *  UDateFormat* dfmt = udat_open(UDAT_DEFAULT, UDAT_DEFAULT, NULL, -1, NULL, 0, &status);
87  *  myStrlen = udat_format(dfmt, myDate, NULL, myStrlen, &pos, &status);
88  *  if (status==U_BUFFER_OVERFLOW_ERROR){
89  *      status=U_ZERO_ERROR;
90  *      myString=(UChar*)malloc(sizeof(UChar) * (myStrlen+1) );
91  *      udat_format(dfmt, myDate, myString, myStrlen+1, &pos, &status);
92  *  }
93  *  printf("date format: %s\n", u_austrcpy(buffer, myString));
94  *  buffer[pos.endIndex] = 0;   // NULL terminate the string.
95  *  printf("UFieldPosition position equals %s\n", &buffer[pos.beginIndex]);
96  * \endcode
97  * </pre>
98  * To format a date for a different Locale, specify it in the call to
99  * udat_open()
100  * <pre>
101  * \code
102  *        UDateFormat* df = udat_open(UDAT_SHORT, UDAT_SHORT, "fr_FR", NULL, -1, NULL, 0, &status);
103  * \endcode
104  * </pre>
105  * You can use a DateFormat API udat_parse() to parse.
106  * <pre>
107  * \code
108  *  UErrorCode status = U_ZERO_ERROR;
109  *  int32_t parsepos=0;
110  *  UDate myDate = udat_parse(df, myString, u_strlen(myString), &parsepos, &status);
111  * \endcode
112  * </pre>
113  *  You can pass in different options for the arguments for date and time style
114  *  to control the length of the result; from SHORT to MEDIUM to LONG to FULL.
115  *  The exact result depends on the locale, but generally:
116  *  see UDateFormatStyle for more details
117  * <ul type=round>
118  *   <li>   UDAT_SHORT is completely numeric, such as 12/13/52 or 3:30pm
119  *   <li>   UDAT_MEDIUM is longer, such as Jan 12, 1952
120  *   <li>   UDAT_LONG is longer, such as January 12, 1952 or 3:30:32pm
121  *   <li>   UDAT_FULL is pretty completely specified, such as
122  *          Tuesday, April 12, 1952 AD or 3:30:42pm PST.
123  * </ul>
124  * You can also set the time zone on the format if you wish.
125  * <P>
126  * You can also use forms of the parse and format methods with Parse Position and
127  * UFieldPosition to allow you to
128  * <ul type=round>
129  *   <li>   Progressively parse through pieces of a string.
130  *   <li>   Align any particular field, or find out where it is for selection
131  *          on the screen.
132  * </ul>
133  */
134
135 /** A date formatter.
136  *  For usage in C programs.
137  *  @stable ICU 2.6
138  */
139 typedef void* UDateFormat;
140
141 /** The possible date/time format styles 
142  *  @stable ICU 2.6
143  */
144 typedef enum UDateFormatStyle {
145     /** Full style */
146     UDAT_FULL,
147     /** Long style */
148     UDAT_LONG,
149     /** Medium style */
150     UDAT_MEDIUM,
151     /** Short style */
152     UDAT_SHORT,
153     /** Default style */
154     UDAT_DEFAULT = UDAT_MEDIUM,
155
156     /** Bitfield for relative date */
157     UDAT_RELATIVE = (1 << 7),
158     
159     UDAT_FULL_RELATIVE = UDAT_FULL | UDAT_RELATIVE,
160         
161     UDAT_LONG_RELATIVE = UDAT_LONG | UDAT_RELATIVE,
162     
163     UDAT_MEDIUM_RELATIVE = UDAT_MEDIUM | UDAT_RELATIVE,
164     
165     UDAT_SHORT_RELATIVE = UDAT_SHORT | UDAT_RELATIVE,
166     
167     
168     /** No style */
169     UDAT_NONE = -1,
170     /** for internal API use only */
171     UDAT_IGNORE = -2
172
173 } UDateFormatStyle;
174
175
176 /**
177  * @{
178  * Below are a set of pre-defined skeletons.
179  *
180  * <P>
181  * A skeleton 
182  * <ol>
183  * <li>
184  *    only keeps the field pattern letter and ignores all other parts 
185  *    in a pattern, such as space, punctuations, and string literals.
186  * </li>
187  * <li>
188  *    hides the order of fields. 
189  * </li>
190  * <li>
191  *    might hide a field's pattern letter length.
192  *
193  *    For those non-digit calendar fields, the pattern letter length is 
194  *    important, such as MMM, MMMM, and MMMMM; EEE and EEEE, 
195  *    and the field's pattern letter length is honored.
196  *    
197  *    For the digit calendar fields,  such as M or MM, d or dd, yy or yyyy, 
198  *    the field pattern length is ignored and the best match, which is defined 
199  *    in date time patterns, will be returned without honor the field pattern
200  *    letter length in skeleton.
201  * </li>
202  * </ol>
203  *
204  * @stable ICU 4.0
205  */
206
207 #define UDAT_MINUTE_SECOND              "ms"
208 #define UDAT_HOUR24_MINUTE              "Hm"
209 #define UDAT_HOUR24_MINUTE_SECOND       "Hms"      
210 #define UDAT_HOUR_MINUTE_SECOND         "hms"
211 #define UDAT_STANDALONE_MONTH           "LLLL"
212 #define UDAT_ABBR_STANDALONE_MONTH      "LLL"
213 #define UDAT_YEAR_QUARTER               "yQQQ"
214 #define UDAT_YEAR_ABBR_QUARTER          "yQ"
215
216 /** @} */
217
218 /**
219  * @{
220  * Below are a set of pre-defined skeletons that 
221  * have pre-defined interval patterns in resource files.
222  * Users are encouraged to use them in date interval format factory methods.
223  * 
224  * @stable ICU 4.0
225  */
226 #define UDAT_HOUR_MINUTE                "hm"
227 #define UDAT_YEAR                       "y"
228 #define UDAT_DAY                        "d"
229 #define UDAT_NUM_MONTH_WEEKDAY_DAY      "MEd"
230 #define UDAT_YEAR_NUM_MONTH             "yM"              
231 #define UDAT_NUM_MONTH_DAY              "Md"
232 #define UDAT_YEAR_NUM_MONTH_WEEKDAY_DAY "yMEd"
233 #define UDAT_ABBR_MONTH_WEEKDAY_DAY     "MMMEd"
234 #define UDAT_YEAR_MONTH                 "yMMMM"
235 #define UDAT_YEAR_ABBR_MONTH            "yMMM"
236 #define UDAT_MONTH_DAY                  "MMMMd"
237 #define UDAT_ABBR_MONTH_DAY             "MMMd" 
238 #define UDAT_MONTH_WEEKDAY_DAY          "MMMMEEEEd"
239 #define UDAT_YEAR_ABBR_MONTH_WEEKDAY_DAY "yMMMEd" 
240 #define UDAT_YEAR_MONTH_WEEKDAY_DAY     "yMMMMEEEEd"
241 #define UDAT_YEAR_MONTH_DAY             "yMMMMd"
242 #define UDAT_YEAR_ABBR_MONTH_DAY        "yMMMd"
243 #define UDAT_YEAR_NUM_MONTH_DAY         "yMd"
244 #define UDAT_NUM_MONTH                  "M"
245 #define UDAT_ABBR_MONTH                 "MMM"
246 #define UDAT_MONTH                      "MMMM"
247 #define UDAT_HOUR_MINUTE_GENERIC_TZ     "hmv"
248 #define UDAT_HOUR_MINUTE_TZ             "hmz"
249 #define UDAT_HOUR                       "h"
250 #define UDAT_HOUR_GENERIC_TZ            "hv"
251 #define UDAT_HOUR_TZ                    "hz"
252
253 /** @} */
254
255
256 /**
257  * FieldPosition and UFieldPosition selectors for format fields
258  * defined by DateFormat and UDateFormat.
259  * @stable ICU 3.0
260  */
261 typedef enum UDateFormatField {
262     /**
263      * FieldPosition and UFieldPosition selector for 'G' field alignment,
264      * corresponding to the UCAL_ERA field.
265      * @stable ICU 3.0
266      */
267     UDAT_ERA_FIELD = 0,
268
269     /**
270      * FieldPosition and UFieldPosition selector for 'y' field alignment,
271      * corresponding to the UCAL_YEAR field.
272      * @stable ICU 3.0
273      */
274     UDAT_YEAR_FIELD = 1,
275
276     /**
277      * FieldPosition and UFieldPosition selector for 'M' field alignment,
278      * corresponding to the UCAL_MONTH field.
279      * @stable ICU 3.0
280      */
281     UDAT_MONTH_FIELD = 2,
282
283     /**
284      * FieldPosition and UFieldPosition selector for 'd' field alignment,
285      * corresponding to the UCAL_DATE field.
286      * @stable ICU 3.0
287      */
288     UDAT_DATE_FIELD = 3,
289
290     /**
291      * FieldPosition and UFieldPosition selector for 'k' field alignment,
292      * corresponding to the UCAL_HOUR_OF_DAY field.
293      * UDAT_HOUR_OF_DAY1_FIELD is used for the one-based 24-hour clock.
294      * For example, 23:59 + 01:00 results in 24:59.
295      * @stable ICU 3.0
296      */
297     UDAT_HOUR_OF_DAY1_FIELD = 4,
298
299     /**
300      * FieldPosition and UFieldPosition selector for 'H' field alignment,
301      * corresponding to the UCAL_HOUR_OF_DAY field.
302      * UDAT_HOUR_OF_DAY0_FIELD is used for the zero-based 24-hour clock.
303      * For example, 23:59 + 01:00 results in 00:59.
304      * @stable ICU 3.0
305      */
306     UDAT_HOUR_OF_DAY0_FIELD = 5,
307
308     /**
309      * FieldPosition and UFieldPosition selector for 'm' field alignment,
310      * corresponding to the UCAL_MINUTE field.
311      * @stable ICU 3.0
312      */
313     UDAT_MINUTE_FIELD = 6,
314
315     /**
316      * FieldPosition and UFieldPosition selector for 's' field alignment,
317      * corresponding to the UCAL_SECOND field.
318      * @stable ICU 3.0
319      */
320     UDAT_SECOND_FIELD = 7,
321
322     /**
323      * FieldPosition and UFieldPosition selector for 'S' field alignment,
324      * corresponding to the UCAL_MILLISECOND field.
325      * @stable ICU 3.0
326      */
327     UDAT_FRACTIONAL_SECOND_FIELD = 8,
328
329     /**
330      * FieldPosition and UFieldPosition selector for 'E' field alignment,
331      * corresponding to the UCAL_DAY_OF_WEEK field.
332      * @stable ICU 3.0
333      */
334     UDAT_DAY_OF_WEEK_FIELD = 9,
335
336     /**
337      * FieldPosition and UFieldPosition selector for 'D' field alignment,
338      * corresponding to the UCAL_DAY_OF_YEAR field.
339      * @stable ICU 3.0
340      */
341     UDAT_DAY_OF_YEAR_FIELD = 10,
342
343     /**
344      * FieldPosition and UFieldPosition selector for 'F' field alignment,
345      * corresponding to the UCAL_DAY_OF_WEEK_IN_MONTH field.
346      * @stable ICU 3.0
347      */
348     UDAT_DAY_OF_WEEK_IN_MONTH_FIELD = 11,
349
350     /**
351      * FieldPosition and UFieldPosition selector for 'w' field alignment,
352      * corresponding to the UCAL_WEEK_OF_YEAR field.
353      * @stable ICU 3.0
354      */
355     UDAT_WEEK_OF_YEAR_FIELD = 12,
356
357     /**
358      * FieldPosition and UFieldPosition selector for 'W' field alignment,
359      * corresponding to the UCAL_WEEK_OF_MONTH field.
360      * @stable ICU 3.0
361      */
362     UDAT_WEEK_OF_MONTH_FIELD = 13,
363
364     /**
365      * FieldPosition and UFieldPosition selector for 'a' field alignment,
366      * corresponding to the UCAL_AM_PM field.
367      * @stable ICU 3.0
368      */
369     UDAT_AM_PM_FIELD = 14,
370
371     /**
372      * FieldPosition and UFieldPosition selector for 'h' field alignment,
373      * corresponding to the UCAL_HOUR field.
374      * UDAT_HOUR1_FIELD is used for the one-based 12-hour clock.
375      * For example, 11:30 PM + 1 hour results in 12:30 AM.
376      * @stable ICU 3.0
377      */
378     UDAT_HOUR1_FIELD = 15,
379
380     /**
381      * FieldPosition and UFieldPosition selector for 'K' field alignment,
382      * corresponding to the UCAL_HOUR field.
383      * UDAT_HOUR0_FIELD is used for the zero-based 12-hour clock.
384      * For example, 11:30 PM + 1 hour results in 00:30 AM.
385      * @stable ICU 3.0
386      */
387     UDAT_HOUR0_FIELD = 16,
388
389     /**
390      * FieldPosition and UFieldPosition selector for 'z' field alignment,
391      * corresponding to the UCAL_ZONE_OFFSET and
392      * UCAL_DST_OFFSET fields.
393      * @stable ICU 3.0
394      */
395     UDAT_TIMEZONE_FIELD = 17,
396
397     /**
398      * FieldPosition and UFieldPosition selector for 'Y' field alignment,
399      * corresponding to the UCAL_YEAR_WOY field.
400      * @stable ICU 3.0
401      */
402     UDAT_YEAR_WOY_FIELD = 18,
403
404     /**
405      * FieldPosition and UFieldPosition selector for 'e' field alignment,
406      * corresponding to the UCAL_DOW_LOCAL field.
407      * @stable ICU 3.0
408      */
409     UDAT_DOW_LOCAL_FIELD = 19,
410
411     /**
412      * FieldPosition and UFieldPosition selector for 'u' field alignment,
413      * corresponding to the UCAL_EXTENDED_YEAR field.
414      * @stable ICU 3.0
415      */
416     UDAT_EXTENDED_YEAR_FIELD = 20,
417
418     /**
419      * FieldPosition and UFieldPosition selector for 'g' field alignment,
420      * corresponding to the UCAL_JULIAN_DAY field.
421      * @stable ICU 3.0
422      */
423     UDAT_JULIAN_DAY_FIELD = 21,
424
425     /**
426      * FieldPosition and UFieldPosition selector for 'A' field alignment,
427      * corresponding to the UCAL_MILLISECONDS_IN_DAY field.
428      * @stable ICU 3.0
429      */
430     UDAT_MILLISECONDS_IN_DAY_FIELD = 22,
431
432     /**
433      * FieldPosition and UFieldPosition selector for 'Z' field alignment,
434      * corresponding to the UCAL_ZONE_OFFSET and
435      * UCAL_DST_OFFSET fields.
436      * @stable ICU 3.0
437      */
438     UDAT_TIMEZONE_RFC_FIELD = 23,
439
440     /**
441      * FieldPosition and UFieldPosition selector for 'v' field alignment,
442      * corresponding to the UCAL_ZONE_OFFSET field.
443      * @stable ICU 3.4
444      */
445     UDAT_TIMEZONE_GENERIC_FIELD = 24,
446     /**
447      * FieldPosition selector for 'c' field alignment,
448      * corresponding to the {@link #UCAL_DOW_LOCAL} field.
449      * This displays the stand alone day name, if available.
450      * @stable ICU 3.4
451      */
452     UDAT_STANDALONE_DAY_FIELD = 25,
453
454     /**
455      * FieldPosition selector for 'L' field alignment,
456      * corresponding to the {@link #UCAL_MONTH} field.
457      * This displays the stand alone month name, if available.
458      * @stable ICU 3.4
459      */
460     UDAT_STANDALONE_MONTH_FIELD = 26,
461
462     /**
463      * FieldPosition selector for "Q" field alignment,
464      * corresponding to quarters. This is implemented
465      * using the {@link #UCAL_MONTH} field. This
466      * displays the quarter.
467      * @stable ICU 3.6
468      */
469     UDAT_QUARTER_FIELD = 27,
470
471     /**
472      * FieldPosition selector for the "q" field alignment,
473      * corresponding to stand-alone quarters. This is
474      * implemented using the {@link #UCAL_MONTH} field.
475      * This displays the stand-alone quarter.
476      * @stable ICU 3.6
477      */
478     UDAT_STANDALONE_QUARTER_FIELD = 28,
479
480     /**
481      * FieldPosition and UFieldPosition selector for 'V' field alignment,
482      * corresponding to the UCAL_ZONE_OFFSET field.
483      * @stable ICU 3.8
484      */
485     UDAT_TIMEZONE_SPECIAL_FIELD = 29,
486
487    /**
488      * Number of FieldPosition and UFieldPosition selectors for
489      * DateFormat and UDateFormat.
490      * Valid selectors range from 0 to UDAT_FIELD_COUNT-1.
491      * This value is subject to change if new fields are defined
492      * in the future.
493      * @stable ICU 3.0
494      */
495     UDAT_FIELD_COUNT = 30
496
497 } UDateFormatField;
498
499
500 /**
501  * Maps from a UDateFormatField to the corresponding UCalendarDateFields.
502  * Note: since the mapping is many-to-one, there is no inverse mapping.
503  * @param field the UDateFormatField.
504  * @return the UCalendarDateField.  This will be UCAL_FIELD_COUNT in case
505  * of error (e.g., the input field is UDAT_FIELD_COUNT).
506  * @stable ICU 4.4
507  */
508 U_STABLE UCalendarDateFields U_EXPORT2
509 udat_toCalendarDateField(UDateFormatField field);
510
511
512 /**
513  * Open a new UDateFormat for formatting and parsing dates and times.
514  * A UDateFormat may be used to format dates in calls to {@link #udat_format },
515  * and to parse dates in calls to {@link #udat_parse }.
516  * @param timeStyle The style used to format times; one of UDAT_FULL, UDAT_LONG,
517  * UDAT_MEDIUM, UDAT_SHORT, UDAT_DEFAULT, or UDAT_NONE (relative time styles
518  * are not currently supported)
519  * @param dateStyle The style used to format dates; one of UDAT_FULL, UDAT_LONG,
520  * UDAT_MEDIUM, UDAT_SHORT, UDAT_DEFAULT, UDAT_FULL_RELATIVE, UDAT_LONG_RELATIVE,
521  * UDAT_MEDIUM_RELATIVE, UDAT_SHORT_RELATIVE, or UDAT_NONE
522  * @param locale The locale specifying the formatting conventions
523  * @param tzID A timezone ID specifying the timezone to use.  If 0, use
524  * the default timezone.
525  * @param tzIDLength The length of tzID, or -1 if null-terminated.
526  * @param pattern A pattern specifying the format to use.
527  * @param patternLength The number of characters in the pattern, or -1 if null-terminated.
528  * @param status A pointer to an UErrorCode to receive any errors
529  * @return A pointer to a UDateFormat to use for formatting dates and times, or 0 if
530  * an error occurred.
531  * @stable ICU 2.0
532  */
533 U_STABLE UDateFormat* U_EXPORT2 
534 udat_open(UDateFormatStyle  timeStyle,
535           UDateFormatStyle  dateStyle,
536           const char        *locale,
537           const UChar       *tzID,
538           int32_t           tzIDLength,
539           const UChar       *pattern,
540           int32_t           patternLength,
541           UErrorCode        *status);
542
543
544 /**
545 * Close a UDateFormat.
546 * Once closed, a UDateFormat may no longer be used.
547 * @param format The formatter to close.
548 * @stable ICU 2.0
549 */
550 U_STABLE void U_EXPORT2 
551 udat_close(UDateFormat* format);
552
553 #if U_SHOW_CPLUSPLUS_API
554
555 U_NAMESPACE_BEGIN
556
557 /**
558  * \class LocalUDateFormatPointer
559  * "Smart pointer" class, closes a UDateFormat via udat_close().
560  * For most methods see the LocalPointerBase base class.
561  *
562  * @see LocalPointerBase
563  * @see LocalPointer
564  * @stable ICU 4.4
565  */
566 U_DEFINE_LOCAL_OPEN_POINTER(LocalUDateFormatPointer, UDateFormat, udat_close);
567
568 U_NAMESPACE_END
569
570 #endif
571
572 /**
573  * Open a copy of a UDateFormat.
574  * This function performs a deep copy.
575  * @param fmt The format to copy
576  * @param status A pointer to an UErrorCode to receive any errors.
577  * @return A pointer to a UDateFormat identical to fmt.
578  * @stable ICU 2.0
579  */
580 U_STABLE UDateFormat* U_EXPORT2 
581 udat_clone(const UDateFormat *fmt,
582        UErrorCode *status);
583
584 /**
585 * Format a date using an UDateFormat.
586 * The date will be formatted using the conventions specified in {@link #udat_open }
587 * @param format The formatter to use
588 * @param dateToFormat The date to format
589 * @param result A pointer to a buffer to receive the formatted number.
590 * @param resultLength The maximum size of result.
591 * @param position A pointer to a UFieldPosition.  On input, position->field
592 * is read.  On output, position->beginIndex and position->endIndex indicate
593 * the beginning and ending indices of field number position->field, if such
594 * a field exists.  This parameter may be NULL, in which case no field
595 * position data is returned.
596 * @param status A pointer to an UErrorCode to receive any errors
597 * @return The total buffer size needed; if greater than resultLength, the output was truncated.
598 * @see udat_parse
599 * @see UFieldPosition
600 * @stable ICU 2.0
601 */
602 U_STABLE int32_t U_EXPORT2 
603 udat_format(    const    UDateFormat*    format,
604                         UDate           dateToFormat,
605                         UChar*          result,
606                         int32_t         resultLength,
607                         UFieldPosition* position,
608                         UErrorCode*     status);
609
610 /**
611 * Parse a string into an date/time using a UDateFormat.
612 * The date will be parsed using the conventions specified in {@link #udat_open }
613 * @param format The formatter to use.
614 * @param text The text to parse.
615 * @param textLength The length of text, or -1 if null-terminated.
616 * @param parsePos If not 0, on input a pointer to an integer specifying the offset at which
617 * to begin parsing.  If not 0, on output the offset at which parsing ended.
618 * @param status A pointer to an UErrorCode to receive any errors
619 * @return The value of the parsed date/time
620 * @see udat_format
621 * @stable ICU 2.0
622 */
623 U_STABLE UDate U_EXPORT2 
624 udat_parse(    const    UDateFormat*    format,
625             const    UChar*          text,
626                     int32_t         textLength,
627                     int32_t         *parsePos,
628                     UErrorCode      *status);
629
630 /**
631 * Parse a string into an date/time using a UDateFormat.
632 * The date will be parsed using the conventions specified in {@link #udat_open }
633 * @param format The formatter to use.
634 * @param calendar The calendar in which to store the parsed data.
635 * @param text The text to parse.
636 * @param textLength The length of text, or -1 if null-terminated.
637 * @param parsePos If not 0, on input a pointer to an integer specifying the offset at which
638 * to begin parsing.  If not 0, on output the offset at which parsing ended.
639 * @param status A pointer to an UErrorCode to receive any errors
640 * @see udat_format
641 * @stable ICU 2.0
642 */
643 U_STABLE void U_EXPORT2 
644 udat_parseCalendar(const    UDateFormat*    format,
645                             UCalendar*      calendar,
646                    const    UChar*          text,
647                             int32_t         textLength,
648                             int32_t         *parsePos,
649                             UErrorCode      *status);
650
651 /**
652 * Determine if an UDateFormat will perform lenient parsing.
653 * With lenient parsing, the parser may use heuristics to interpret inputs that do not
654 * precisely match the pattern. With strict parsing, inputs must match the pattern.
655 * @param fmt The formatter to query
656 * @return TRUE if fmt is set to perform lenient parsing, FALSE otherwise.
657 * @see udat_setLenient
658 * @stable ICU 2.0
659 */
660 U_STABLE UBool U_EXPORT2 
661 udat_isLenient(const UDateFormat* fmt);
662
663 /**
664 * Specify whether an UDateFormat will perform lenient parsing.
665 * With lenient parsing, the parser may use heuristics to interpret inputs that do not
666 * precisely match the pattern. With strict parsing, inputs must match the pattern.
667 * @param fmt The formatter to set
668 * @param isLenient TRUE if fmt should perform lenient parsing, FALSE otherwise.
669 * @see dat_isLenient
670 * @stable ICU 2.0
671 */
672 U_STABLE void U_EXPORT2 
673 udat_setLenient(    UDateFormat*    fmt,
674                     UBool          isLenient);
675
676 /**
677 * Get the UCalendar associated with an UDateFormat.
678 * A UDateFormat uses a UCalendar to convert a raw value to, for example,
679 * the day of the week.
680 * @param fmt The formatter to query.
681 * @return A pointer to the UCalendar used by fmt.
682 * @see udat_setCalendar
683 * @stable ICU 2.0
684 */
685 U_STABLE const UCalendar* U_EXPORT2 
686 udat_getCalendar(const UDateFormat* fmt);
687
688 /**
689 * Set the UCalendar associated with an UDateFormat.
690 * A UDateFormat uses a UCalendar to convert a raw value to, for example,
691 * the day of the week.
692 * @param fmt The formatter to set.
693 * @param calendarToSet A pointer to an UCalendar to be used by fmt.
694 * @see udat_setCalendar
695 * @stable ICU 2.0
696 */
697 U_STABLE void U_EXPORT2 
698 udat_setCalendar(            UDateFormat*    fmt,
699                     const   UCalendar*      calendarToSet);
700
701 /**
702 * Get the UNumberFormat associated with an UDateFormat.
703 * A UDateFormat uses a UNumberFormat to format numbers within a date,
704 * for example the day number.
705 * @param fmt The formatter to query.
706 * @return A pointer to the UNumberFormat used by fmt to format numbers.
707 * @see udat_setNumberFormat
708 * @stable ICU 2.0
709 */
710 U_STABLE const UNumberFormat* U_EXPORT2 
711 udat_getNumberFormat(const UDateFormat* fmt);
712
713 /**
714 * Set the UNumberFormat associated with an UDateFormat.
715 * A UDateFormat uses a UNumberFormat to format numbers within a date,
716 * for example the day number.
717 * @param fmt The formatter to set.
718 * @param numberFormatToSet A pointer to the UNumberFormat to be used by fmt to format numbers.
719 * @see udat_getNumberFormat
720 * @stable ICU 2.0
721 */
722 U_STABLE void U_EXPORT2 
723 udat_setNumberFormat(            UDateFormat*    fmt,
724                         const   UNumberFormat*  numberFormatToSet);
725
726 /**
727 * Get a locale for which date/time formatting patterns are available.
728 * A UDateFormat in a locale returned by this function will perform the correct
729 * formatting and parsing for the locale.
730 * @param localeIndex The index of the desired locale.
731 * @return A locale for which date/time formatting patterns are available, or 0 if none.
732 * @see udat_countAvailable
733 * @stable ICU 2.0
734 */
735 U_STABLE const char* U_EXPORT2 
736 udat_getAvailable(int32_t localeIndex);
737
738 /**
739 * Determine how many locales have date/time  formatting patterns available.
740 * This function is most useful as determining the loop ending condition for
741 * calls to {@link #udat_getAvailable }.
742 * @return The number of locales for which date/time formatting patterns are available.
743 * @see udat_getAvailable
744 * @stable ICU 2.0
745 */
746 U_STABLE int32_t U_EXPORT2 
747 udat_countAvailable(void);
748
749 /**
750 * Get the year relative to which all 2-digit years are interpreted.
751 * For example, if the 2-digit start year is 2100, the year 99 will be
752 * interpreted as 2199.
753 * @param fmt The formatter to query.
754 * @param status A pointer to an UErrorCode to receive any errors
755 * @return The year relative to which all 2-digit years are interpreted.
756 * @see udat_Set2DigitYearStart
757 * @stable ICU 2.0
758 */
759 U_STABLE UDate U_EXPORT2 
760 udat_get2DigitYearStart(    const   UDateFormat     *fmt,
761                                     UErrorCode      *status);
762
763 /**
764 * Set the year relative to which all 2-digit years will be interpreted.
765 * For example, if the 2-digit start year is 2100, the year 99 will be
766 * interpreted as 2199.
767 * @param fmt The formatter to set.
768 * @param d The year relative to which all 2-digit years will be interpreted.
769 * @param status A pointer to an UErrorCode to receive any errors
770 * @see udat_Set2DigitYearStart
771 * @stable ICU 2.0
772 */
773 U_STABLE void U_EXPORT2 
774 udat_set2DigitYearStart(    UDateFormat     *fmt,
775                             UDate           d,
776                             UErrorCode      *status);
777
778 /**
779 * Extract the pattern from a UDateFormat.
780 * The pattern will follow the pattern syntax rules.
781 * @param fmt The formatter to query.
782 * @param localized TRUE if the pattern should be localized, FALSE otherwise.
783 * @param result A pointer to a buffer to receive the pattern.
784 * @param resultLength The maximum size of result.
785 * @param status A pointer to an UErrorCode to receive any errors
786 * @return The total buffer size needed; if greater than resultLength, the output was truncated.
787 * @see udat_applyPattern
788 * @stable ICU 2.0
789 */
790 U_STABLE int32_t U_EXPORT2 
791 udat_toPattern(    const   UDateFormat     *fmt,
792                         UBool          localized,
793                         UChar           *result,
794                         int32_t         resultLength,
795                         UErrorCode      *status);
796
797 /**
798 * Set the pattern used by an UDateFormat.
799 * The pattern should follow the pattern syntax rules.
800 * @param format The formatter to set.
801 * @param localized TRUE if the pattern is localized, FALSE otherwise.
802 * @param pattern The new pattern
803 * @param patternLength The length of pattern, or -1 if null-terminated.
804 * @see udat_toPattern
805 * @stable ICU 2.0
806 */
807 U_STABLE void U_EXPORT2 
808 udat_applyPattern(            UDateFormat     *format,
809                             UBool          localized,
810                     const   UChar           *pattern,
811                             int32_t         patternLength);
812
813 /** 
814  * The possible types of date format symbols 
815  * @stable ICU 2.6
816  */
817 typedef enum UDateFormatSymbolType {
818     /** The era names, for example AD */
819     UDAT_ERAS,
820     /** The month names, for example February */
821     UDAT_MONTHS,
822     /** The short month names, for example Feb. */
823     UDAT_SHORT_MONTHS,
824     /** The weekday names, for example Monday */
825     UDAT_WEEKDAYS,
826     /** The short weekday names, for example Mon. */
827     UDAT_SHORT_WEEKDAYS,
828     /** The AM/PM names, for example AM */
829     UDAT_AM_PMS,
830     /** The localized characters */
831     UDAT_LOCALIZED_CHARS,
832     /** The long era names, for example Anno Domini */
833     UDAT_ERA_NAMES,
834     /** The narrow month names, for example F */
835     UDAT_NARROW_MONTHS,
836     /** The narrow weekday names, for example N */
837     UDAT_NARROW_WEEKDAYS,
838     /** Standalone context versions of months */
839     UDAT_STANDALONE_MONTHS,
840     UDAT_STANDALONE_SHORT_MONTHS,
841     UDAT_STANDALONE_NARROW_MONTHS,
842     /** Standalone context versions of weekdays */
843     UDAT_STANDALONE_WEEKDAYS,
844     UDAT_STANDALONE_SHORT_WEEKDAYS,
845     UDAT_STANDALONE_NARROW_WEEKDAYS,
846     /** The quarters, for example 1st Quarter */
847     UDAT_QUARTERS,
848     /** The short quarter names, for example Q1 */
849     UDAT_SHORT_QUARTERS,
850     /** Standalone context versions of quarters */
851     UDAT_STANDALONE_QUARTERS,
852     UDAT_STANDALONE_SHORT_QUARTERS
853
854 } UDateFormatSymbolType;
855
856 struct UDateFormatSymbols;
857 /** Date format symbols.
858  *  For usage in C programs.
859  *  @stable ICU 2.6
860  */
861 typedef struct UDateFormatSymbols UDateFormatSymbols;
862
863 /**
864 * Get the symbols associated with an UDateFormat.
865 * The symbols are what a UDateFormat uses to represent locale-specific data,
866 * for example month or day names.
867 * @param fmt The formatter to query.
868 * @param type The type of symbols to get.  One of UDAT_ERAS, UDAT_MONTHS, UDAT_SHORT_MONTHS,
869 * UDAT_WEEKDAYS, UDAT_SHORT_WEEKDAYS, UDAT_AM_PMS, or UDAT_LOCALIZED_CHARS
870 * @param symbolIndex The desired symbol of type type.
871 * @param result A pointer to a buffer to receive the pattern.
872 * @param resultLength The maximum size of result.
873 * @param status A pointer to an UErrorCode to receive any errors
874 * @return The total buffer size needed; if greater than resultLength, the output was truncated.
875 * @see udat_countSymbols
876 * @see udat_setSymbols
877 * @stable ICU 2.0
878 */
879 U_STABLE int32_t U_EXPORT2 
880 udat_getSymbols(const   UDateFormat             *fmt,
881                         UDateFormatSymbolType   type,
882                         int32_t                 symbolIndex,
883                         UChar                   *result,
884                         int32_t                 resultLength,
885                         UErrorCode              *status);
886
887 /**
888 * Count the number of particular symbols for an UDateFormat.
889 * This function is most useful as for detemining the loop termination condition
890 * for calls to {@link #udat_getSymbols }.
891 * @param fmt The formatter to query.
892 * @param type The type of symbols to count.  One of UDAT_ERAS, UDAT_MONTHS, UDAT_SHORT_MONTHS,
893 * UDAT_WEEKDAYS, UDAT_SHORT_WEEKDAYS, UDAT_AM_PMS, or UDAT_LOCALIZED_CHARS
894 * @return The number of symbols of type type.
895 * @see udat_getSymbols
896 * @see udat_setSymbols
897 * @stable ICU 2.0
898 */
899 U_STABLE int32_t U_EXPORT2 
900 udat_countSymbols(    const    UDateFormat                *fmt,
901                             UDateFormatSymbolType    type);
902
903 /**
904 * Set the symbols associated with an UDateFormat.
905 * The symbols are what a UDateFormat uses to represent locale-specific data,
906 * for example month or day names.
907 * @param format The formatter to set
908 * @param type The type of symbols to set.  One of UDAT_ERAS, UDAT_MONTHS, UDAT_SHORT_MONTHS,
909 * UDAT_WEEKDAYS, UDAT_SHORT_WEEKDAYS, UDAT_AM_PMS, or UDAT_LOCALIZED_CHARS
910 * @param symbolIndex The index of the symbol to set of type type.
911 * @param value The new value
912 * @param valueLength The length of value, or -1 if null-terminated
913 * @param status A pointer to an UErrorCode to receive any errors
914 * @see udat_getSymbols
915 * @see udat_countSymbols
916 * @stable ICU 2.0
917 */
918 U_STABLE void U_EXPORT2 
919 udat_setSymbols(    UDateFormat             *format,
920                     UDateFormatSymbolType   type,
921                     int32_t                 symbolIndex,
922                     UChar                   *value,
923                     int32_t                 valueLength,
924                     UErrorCode              *status);
925
926 /**
927  * Get the locale for this date format object.
928  * You can choose between valid and actual locale.
929  * @param fmt The formatter to get the locale from
930  * @param type type of the locale we're looking for (valid or actual) 
931  * @param status error code for the operation
932  * @return the locale name
933  * @stable ICU 2.8
934  */
935 U_STABLE const char* U_EXPORT2
936 udat_getLocaleByType(const UDateFormat *fmt,
937                      ULocDataLocaleType type,
938                      UErrorCode* status); 
939
940 /**
941 * Extract the date pattern from a UDateFormat set for relative date formatting.
942 * The pattern will follow the pattern syntax rules.
943 * @param fmt The formatter to query.
944 * @param result A pointer to a buffer to receive the pattern.
945 * @param resultLength The maximum size of result.
946 * @param status A pointer to a UErrorCode to receive any errors
947 * @return The total buffer size needed; if greater than resultLength, the output was truncated.
948 * @see udat_applyPatternRelative
949 * @internal ICU 4.2 technology preview
950 */
951 U_INTERNAL int32_t U_EXPORT2 
952 udat_toPatternRelativeDate(const UDateFormat *fmt,
953                            UChar             *result,
954                            int32_t           resultLength,
955                            UErrorCode        *status);
956
957 /**
958 * Extract the time pattern from a UDateFormat set for relative date formatting.
959 * The pattern will follow the pattern syntax rules.
960 * @param fmt The formatter to query.
961 * @param result A pointer to a buffer to receive the pattern.
962 * @param resultLength The maximum size of result.
963 * @param status A pointer to a UErrorCode to receive any errors
964 * @return The total buffer size needed; if greater than resultLength, the output was truncated.
965 * @see udat_applyPatternRelative
966 * @internal ICU 4.2 technology preview
967 */
968 U_INTERNAL int32_t U_EXPORT2 
969 udat_toPatternRelativeTime(const UDateFormat *fmt,
970                            UChar             *result,
971                            int32_t           resultLength,
972                            UErrorCode        *status);
973
974 /**
975 * Set the date & time patterns used by a UDateFormat set for relative date formatting.
976 * The patterns should follow the pattern syntax rules.
977 * @param format The formatter to set.
978 * @param datePattern The new date pattern
979 * @param datePatternLength The length of datePattern, or -1 if null-terminated.
980 * @param timePattern The new time pattern
981 * @param timePatternLength The length of timePattern, or -1 if null-terminated.
982 * @param status A pointer to a UErrorCode to receive any errors
983 * @see udat_toPatternRelativeDate, udat_toPatternRelativeTime
984 * @internal ICU 4.2 technology preview
985 */
986 U_INTERNAL void U_EXPORT2 
987 udat_applyPatternRelative(UDateFormat *format,
988                           const UChar *datePattern,
989                           int32_t     datePatternLength,
990                           const UChar *timePattern,
991                           int32_t     timePatternLength,
992                           UErrorCode  *status);
993
994
995 #endif /* #if !UCONFIG_NO_FORMATTING */
996
997 #endif