1/*
2 *******************************************************************************
3 * Copyright (C) 1996-2014, 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#include "unicode/udisplaycontext.h"
19/**
20 * \file
21 * \brief C API: DateFormat
22 *
23 * <h2> Date Format C API</h2>
24 *
25 * Date Format C API  consists of functions that convert dates and
26 * times from their internal representations to textual form and back again in a
27 * language-independent manner. Converting from the internal representation (milliseconds
28 * since midnight, January 1, 1970) to text is known as "formatting," and converting
29 * from text to millis is known as "parsing."  We currently define only one concrete
30 * structure UDateFormat, which can handle pretty much all normal
31 * date formatting and parsing actions.
32 * <P>
33 * Date Format helps you to format and parse dates for any locale. Your code can
34 * be completely independent of the locale conventions for months, days of the
35 * week, or even the calendar format: lunar vs. solar.
36 * <P>
37 * To format a date for the current Locale with default time and date style,
38 * use one of the static factory methods:
39 * <pre>
40 * \code
41 *  UErrorCode status = U_ZERO_ERROR;
42 *  UChar *myString;
43 *  int32_t myStrlen = 0;
44 *  UDateFormat* dfmt = udat_open(UDAT_DEFAULT, UDAT_DEFAULT, NULL, NULL, -1, NULL, -1, &status);
45 *  myStrlen = udat_format(dfmt, myDate, NULL, myStrlen, NULL, &status);
46 *  if (status==U_BUFFER_OVERFLOW_ERROR){
47 *      status=U_ZERO_ERROR;
48 *      myString=(UChar*)malloc(sizeof(UChar) * (myStrlen+1) );
49 *      udat_format(dfmt, myDate, myString, myStrlen+1, NULL, &status);
50 *  }
51 * \endcode
52 * </pre>
53 * If you are formatting multiple numbers, it is more efficient to get the
54 * format and use it multiple times so that the system doesn't have to fetch the
55 * information about the local language and country conventions multiple times.
56 * <pre>
57 * \code
58 *  UErrorCode status = U_ZERO_ERROR;
59 *  int32_t i, myStrlen = 0;
60 *  UChar* myString;
61 *  char buffer[1024];
62 *  UDate myDateArr[] = { 0.0, 100000000.0, 2000000000.0 }; // test values
63 *  UDateFormat* df = udat_open(UDAT_DEFAULT, UDAT_DEFAULT, NULL, NULL, -1, NULL, 0, &status);
64 *  for (i = 0; i < 3; i++) {
65 *      myStrlen = udat_format(df, myDateArr[i], NULL, myStrlen, NULL, &status);
66 *      if(status == U_BUFFER_OVERFLOW_ERROR){
67 *          status = U_ZERO_ERROR;
68 *          myString = (UChar*)malloc(sizeof(UChar) * (myStrlen+1) );
69 *          udat_format(df, myDateArr[i], myString, myStrlen+1, NULL, &status);
70 *          printf("%s\n", u_austrcpy(buffer, myString) );
71 *          free(myString);
72 *      }
73 *  }
74 * \endcode
75 * </pre>
76 * To get specific fields of a date, you can use UFieldPosition to
77 * get specific fields.
78 * <pre>
79 * \code
80 *  UErrorCode status = U_ZERO_ERROR;
81 *  UFieldPosition pos;
82 *  UChar *myString;
83 *  int32_t myStrlen = 0;
84 *  char buffer[1024];
85 *
86 *  pos.field = 1;  // Same as the DateFormat::EField enum
87 *  UDateFormat* dfmt = udat_open(UDAT_DEFAULT, UDAT_DEFAULT, NULL, -1, NULL, 0, &status);
88 *  myStrlen = udat_format(dfmt, myDate, NULL, myStrlen, &pos, &status);
89 *  if (status==U_BUFFER_OVERFLOW_ERROR){
90 *      status=U_ZERO_ERROR;
91 *      myString=(UChar*)malloc(sizeof(UChar) * (myStrlen+1) );
92 *      udat_format(dfmt, myDate, myString, myStrlen+1, &pos, &status);
93 *  }
94 *  printf("date format: %s\n", u_austrcpy(buffer, myString));
95 *  buffer[pos.endIndex] = 0;   // NULL terminate the string.
96 *  printf("UFieldPosition position equals %s\n", &buffer[pos.beginIndex]);
97 * \endcode
98 * </pre>
99 * To format a date for a different Locale, specify it in the call to
100 * udat_open()
101 * <pre>
102 * \code
103 *        UDateFormat* df = udat_open(UDAT_SHORT, UDAT_SHORT, "fr_FR", NULL, -1, NULL, 0, &status);
104 * \endcode
105 * </pre>
106 * You can use a DateFormat API udat_parse() to parse.
107 * <pre>
108 * \code
109 *  UErrorCode status = U_ZERO_ERROR;
110 *  int32_t parsepos=0;
111 *  UDate myDate = udat_parse(df, myString, u_strlen(myString), &parsepos, &status);
112 * \endcode
113 * </pre>
114 *  You can pass in different options for the arguments for date and time style
115 *  to control the length of the result; from SHORT to MEDIUM to LONG to FULL.
116 *  The exact result depends on the locale, but generally:
117 *  see UDateFormatStyle for more details
118 * <ul type=round>
119 *   <li>   UDAT_SHORT is completely numeric, such as 12/13/52 or 3:30pm
120 *   <li>   UDAT_MEDIUM is longer, such as Jan 12, 1952
121 *   <li>   UDAT_LONG is longer, such as January 12, 1952 or 3:30:32pm
122 *   <li>   UDAT_FULL is pretty completely specified, such as
123 *          Tuesday, April 12, 1952 AD or 3:30:42pm PST.
124 * </ul>
125 * You can also set the time zone on the format if you wish.
126 * <P>
127 * You can also use forms of the parse and format methods with Parse Position and
128 * UFieldPosition to allow you to
129 * <ul type=round>
130 *   <li>   Progressively parse through pieces of a string.
131 *   <li>   Align any particular field, or find out where it is for selection
132 *          on the screen.
133 * </ul>
134 * <p><strong>Date and Time Patterns:</strong></p>
135 *
136 * <p>Date and time formats are specified by <em>date and time pattern</em> strings.
137 * Within date and time pattern strings, all unquoted ASCII letters [A-Za-z] are reserved
138 * as pattern letters representing calendar fields. <code>UDateFormat</code> supports
139 * the date and time formatting algorithm and pattern letters defined by
140 * <a href="http://www.unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table">UTS#35
141 * Unicode Locale Data Markup Language (LDML)</a> and further documented for ICU in the
142 * <a href="https://sites.google.com/site/icuprojectuserguide/formatparse/datetime?pli=1#TOC-Date-Field-Symbol-Table">ICU
143 * User Guide</a>.</p>
144 */
145
146/** A date formatter.
147 *  For usage in C programs.
148 *  @stable ICU 2.6
149 */
150typedef void* UDateFormat;
151
152/** The possible date/time format styles
153 *  @stable ICU 2.6
154 */
155typedef enum UDateFormatStyle {
156    /** Full style */
157    UDAT_FULL,
158    /** Long style */
159    UDAT_LONG,
160    /** Medium style */
161    UDAT_MEDIUM,
162    /** Short style */
163    UDAT_SHORT,
164    /** Default style */
165    UDAT_DEFAULT = UDAT_MEDIUM,
166
167    /** Bitfield for relative date */
168    UDAT_RELATIVE = (1 << 7),
169
170    UDAT_FULL_RELATIVE = UDAT_FULL | UDAT_RELATIVE,
171
172    UDAT_LONG_RELATIVE = UDAT_LONG | UDAT_RELATIVE,
173
174    UDAT_MEDIUM_RELATIVE = UDAT_MEDIUM | UDAT_RELATIVE,
175
176    UDAT_SHORT_RELATIVE = UDAT_SHORT | UDAT_RELATIVE,
177
178
179    /** No style */
180    UDAT_NONE = -1,
181
182    /**
183     * Use the pattern given in the parameter to udat_open
184     * @see udat_open
185     * @stable ICU 50
186     */
187    UDAT_PATTERN = -2,
188
189#ifndef U_HIDE_INTERNAL_API
190    /** @internal alias to UDAT_PATTERN */
191    UDAT_IGNORE = UDAT_PATTERN
192#endif /* U_HIDE_INTERNAL_API */
193} UDateFormatStyle;
194
195/* Skeletons for dates. */
196
197/**
198 * Constant for date skeleton with year.
199 * @stable ICU 4.0
200 */
201#define UDAT_YEAR                       "y"
202/**
203 * Constant for date skeleton with quarter.
204 * @stable ICU 51
205 */
206#define UDAT_QUARTER                    "QQQQ"
207/**
208 * Constant for date skeleton with abbreviated quarter.
209 * @stable ICU 51
210 */
211#define UDAT_ABBR_QUARTER               "QQQ"
212/**
213 * Constant for date skeleton with year and quarter.
214 * @stable ICU 4.0
215 */
216#define UDAT_YEAR_QUARTER               "yQQQQ"
217/**
218 * Constant for date skeleton with year and abbreviated quarter.
219 * @stable ICU 4.0
220 */
221#define UDAT_YEAR_ABBR_QUARTER          "yQQQ"
222/**
223 * Constant for date skeleton with month.
224 * @stable ICU 4.0
225 */
226#define UDAT_MONTH                      "MMMM"
227/**
228 * Constant for date skeleton with abbreviated month.
229 * @stable ICU 4.0
230 */
231#define UDAT_ABBR_MONTH                 "MMM"
232/**
233 * Constant for date skeleton with numeric month.
234 * @stable ICU 4.0
235 */
236#define UDAT_NUM_MONTH                  "M"
237/**
238 * Constant for date skeleton with year and month.
239 * @stable ICU 4.0
240 */
241#define UDAT_YEAR_MONTH                 "yMMMM"
242/**
243 * Constant for date skeleton with year and abbreviated month.
244 * @stable ICU 4.0
245 */
246#define UDAT_YEAR_ABBR_MONTH            "yMMM"
247/**
248 * Constant for date skeleton with year and numeric month.
249 * @stable ICU 4.0
250 */
251#define UDAT_YEAR_NUM_MONTH             "yM"
252/**
253 * Constant for date skeleton with day.
254 * @stable ICU 4.0
255 */
256#define UDAT_DAY                        "d"
257/**
258 * Constant for date skeleton with year, month, and day.
259 * Used in combinations date + time, date + time + zone, or time + zone.
260 * @stable ICU 4.0
261 */
262#define UDAT_YEAR_MONTH_DAY             "yMMMMd"
263/**
264 * Constant for date skeleton with year, abbreviated month, and day.
265 * Used in combinations date + time, date + time + zone, or time + zone.
266 * @stable ICU 4.0
267 */
268#define UDAT_YEAR_ABBR_MONTH_DAY        "yMMMd"
269/**
270 * Constant for date skeleton with year, numeric month, and day.
271 * Used in combinations date + time, date + time + zone, or time + zone.
272 * @stable ICU 4.0
273 */
274#define UDAT_YEAR_NUM_MONTH_DAY         "yMd"
275/**
276 * Constant for date skeleton with weekday.
277 * @stable ICU 51
278 */
279#define UDAT_WEEKDAY                    "EEEE"
280/**
281 * Constant for date skeleton with abbreviated weekday.
282 * @stable ICU 51
283 */
284#define UDAT_ABBR_WEEKDAY               "E"
285/**
286 * Constant for date skeleton with year, month, weekday, and day.
287 * Used in combinations date + time, date + time + zone, or time + zone.
288 * @stable ICU 4.0
289 */
290#define UDAT_YEAR_MONTH_WEEKDAY_DAY     "yMMMMEEEEd"
291/**
292 * Constant for date skeleton with year, abbreviated month, weekday, and day.
293 * Used in combinations date + time, date + time + zone, or time + zone.
294 * @stable ICU 4.0
295 */
296#define UDAT_YEAR_ABBR_MONTH_WEEKDAY_DAY "yMMMEd"
297/**
298 * Constant for date skeleton with year, numeric month, weekday, and day.
299 * Used in combinations date + time, date + time + zone, or time + zone.
300 * @stable ICU 4.0
301 */
302#define UDAT_YEAR_NUM_MONTH_WEEKDAY_DAY "yMEd"
303/**
304 * Constant for date skeleton with long month and day.
305 * Used in combinations date + time, date + time + zone, or time + zone.
306 * @stable ICU 4.0
307 */
308#define UDAT_MONTH_DAY                  "MMMMd"
309/**
310 * Constant for date skeleton with abbreviated month and day.
311 * Used in combinations date + time, date + time + zone, or time + zone.
312 * @stable ICU 4.0
313 */
314#define UDAT_ABBR_MONTH_DAY             "MMMd"
315/**
316 * Constant for date skeleton with numeric month and day.
317 * Used in combinations date + time, date + time + zone, or time + zone.
318 * @stable ICU 4.0
319 */
320#define UDAT_NUM_MONTH_DAY              "Md"
321/**
322 * Constant for date skeleton with month, weekday, and day.
323 * Used in combinations date + time, date + time + zone, or time + zone.
324 * @stable ICU 4.0
325 */
326#define UDAT_MONTH_WEEKDAY_DAY          "MMMMEEEEd"
327/**
328 * Constant for date skeleton with abbreviated month, weekday, and day.
329 * Used in combinations date + time, date + time + zone, or time + zone.
330 * @stable ICU 4.0
331 */
332#define UDAT_ABBR_MONTH_WEEKDAY_DAY     "MMMEd"
333/**
334 * Constant for date skeleton with numeric month, weekday, and day.
335 * Used in combinations date + time, date + time + zone, or time + zone.
336 * @stable ICU 4.0
337 */
338#define UDAT_NUM_MONTH_WEEKDAY_DAY      "MEd"
339
340/* Skeletons for times. */
341
342/**
343 * Constant for date skeleton with hour, with the locale's preferred hour format (12 or 24).
344 * @stable ICU 4.0
345 */
346#define UDAT_HOUR                       "j"
347/**
348 * Constant for date skeleton with hour in 24-hour presentation.
349 * @stable ICU 51
350 */
351#define UDAT_HOUR24                     "H"
352/**
353 * Constant for date skeleton with minute.
354 * @stable ICU 51
355 */
356#define UDAT_MINUTE                     "m"
357/**
358 * Constant for date skeleton with hour and minute, with the locale's preferred hour format (12 or 24).
359 * Used in combinations date + time, date + time + zone, or time + zone.
360 * @stable ICU 4.0
361 */
362#define UDAT_HOUR_MINUTE                "jm"
363/**
364 * Constant for date skeleton with hour and minute in 24-hour presentation.
365 * Used in combinations date + time, date + time + zone, or time + zone.
366 * @stable ICU 4.0
367 */
368#define UDAT_HOUR24_MINUTE              "Hm"
369/**
370 * Constant for date skeleton with second.
371 * @stable ICU 51
372 */
373#define UDAT_SECOND                     "s"
374/**
375 * Constant for date skeleton with hour, minute, and second,
376 * with the locale's preferred hour format (12 or 24).
377 * Used in combinations date + time, date + time + zone, or time + zone.
378 * @stable ICU 4.0
379 */
380#define UDAT_HOUR_MINUTE_SECOND         "jms"
381/**
382 * Constant for date skeleton with hour, minute, and second in
383 * 24-hour presentation.
384 * Used in combinations date + time, date + time + zone, or time + zone.
385 * @stable ICU 4.0
386 */
387#define UDAT_HOUR24_MINUTE_SECOND       "Hms"
388/**
389 * Constant for date skeleton with minute and second.
390 * Used in combinations date + time, date + time + zone, or time + zone.
391 * @stable ICU 4.0
392 */
393#define UDAT_MINUTE_SECOND              "ms"
394
395/* Skeletons for time zones. */
396
397/**
398 * Constant for <i>generic location format</i>, such as Los Angeles Time;
399 * used in combinations date + time + zone, or time + zone.
400 * @see <a href="http://unicode.org/reports/tr35/#Date_Format_Patterns">LDML Date Format Patterns</a>
401 * @see <a href="http://unicode.org/reports/tr35/#Time_Zone_Fallback">LDML Time Zone Fallback</a>
402 * @stable ICU 51
403 */
404#define UDAT_LOCATION_TZ "VVVV"
405/**
406 * Constant for <i>generic non-location format</i>, such as Pacific Time;
407 * used in combinations date + time + zone, or time + zone.
408 * @see <a href="http://unicode.org/reports/tr35/#Date_Format_Patterns">LDML Date Format Patterns</a>
409 * @see <a href="http://unicode.org/reports/tr35/#Time_Zone_Fallback">LDML Time Zone Fallback</a>
410 * @stable ICU 51
411 */
412#define UDAT_GENERIC_TZ "vvvv"
413/**
414 * Constant for <i>generic non-location format</i>, abbreviated if possible, such as PT;
415 * used in combinations date + time + zone, or time + zone.
416 * @see <a href="http://unicode.org/reports/tr35/#Date_Format_Patterns">LDML Date Format Patterns</a>
417 * @see <a href="http://unicode.org/reports/tr35/#Time_Zone_Fallback">LDML Time Zone Fallback</a>
418 * @stable ICU 51
419 */
420#define UDAT_ABBR_GENERIC_TZ "v"
421/**
422 * Constant for <i>specific non-location format</i>, such as Pacific Daylight Time;
423 * used in combinations date + time + zone, or time + zone.
424 * @see <a href="http://unicode.org/reports/tr35/#Date_Format_Patterns">LDML Date Format Patterns</a>
425 * @see <a href="http://unicode.org/reports/tr35/#Time_Zone_Fallback">LDML Time Zone Fallback</a>
426 * @stable ICU 51
427 */
428#define UDAT_SPECIFIC_TZ "zzzz"
429/**
430 * Constant for <i>specific non-location format</i>, abbreviated if possible, such as PDT;
431 * used in combinations date + time + zone, or time + zone.
432 * @see <a href="http://unicode.org/reports/tr35/#Date_Format_Patterns">LDML Date Format Patterns</a>
433 * @see <a href="http://unicode.org/reports/tr35/#Time_Zone_Fallback">LDML Time Zone Fallback</a>
434 * @stable ICU 51
435 */
436#define UDAT_ABBR_SPECIFIC_TZ "z"
437/**
438 * Constant for <i>localized GMT/UTC format</i>, such as GMT+8:00 or HPG-8:00;
439 * used in combinations date + time + zone, or time + zone.
440 * @see <a href="http://unicode.org/reports/tr35/#Date_Format_Patterns">LDML Date Format Patterns</a>
441 * @see <a href="http://unicode.org/reports/tr35/#Time_Zone_Fallback">LDML Time Zone Fallback</a>
442 * @stable ICU 51
443 */
444#define UDAT_ABBR_UTC_TZ "ZZZZ"
445
446/* deprecated skeleton constants */
447
448#ifndef U_HIDE_DEPRECATED_API
449/**
450 * Constant for date skeleton with standalone month.
451 * @deprecated ICU 50 Use UDAT_MONTH instead.
452 */
453#define UDAT_STANDALONE_MONTH           "LLLL"
454/**
455 * Constant for date skeleton with standalone abbreviated month.
456 * @deprecated ICU 50 Use UDAT_ABBR_MONTH instead.
457 */
458#define UDAT_ABBR_STANDALONE_MONTH      "LLL"
459
460/**
461 * Constant for date skeleton with hour, minute, and generic timezone.
462 * @deprecated ICU 50 Use instead UDAT_HOUR_MINUTE UDAT_ABBR_GENERIC_TZ or some other timezone presentation.
463 */
464#define UDAT_HOUR_MINUTE_GENERIC_TZ     "jmv"
465/**
466 * Constant for date skeleton with hour, minute, and timezone.
467 * @deprecated ICU 50 Use instead UDAT_HOUR_MINUTE UDAT_ABBR_SPECIFIC_TZ or some other timezone presentation.
468 */
469#define UDAT_HOUR_MINUTE_TZ             "jmz"
470/**
471 * Constant for date skeleton with hour and generic timezone.
472 * @deprecated ICU 50 Use instead UDAT_HOUR UDAT_ABBR_GENERIC_TZ or some other timezone presentation.
473 */
474#define UDAT_HOUR_GENERIC_TZ            "jv"
475/**
476 * Constant for date skeleton with hour and timezone.
477 * @deprecated ICU 50 Use instead UDAT_HOUR UDAT_ABBR_SPECIFIC_TZ or some other timezone presentation.
478 */
479#define UDAT_HOUR_TZ                    "jz"
480#endif  /* U_HIDE_DEPRECATED_API */
481
482/**
483 * FieldPosition and UFieldPosition selectors for format fields
484 * defined by DateFormat and UDateFormat.
485 * @stable ICU 3.0
486 */
487typedef enum UDateFormatField {
488    /**
489     * FieldPosition and UFieldPosition selector for 'G' field alignment,
490     * corresponding to the UCAL_ERA field.
491     * @stable ICU 3.0
492     */
493    UDAT_ERA_FIELD = 0,
494
495    /**
496     * FieldPosition and UFieldPosition selector for 'y' field alignment,
497     * corresponding to the UCAL_YEAR field.
498     * @stable ICU 3.0
499     */
500    UDAT_YEAR_FIELD = 1,
501
502    /**
503     * FieldPosition and UFieldPosition selector for 'M' field alignment,
504     * corresponding to the UCAL_MONTH field.
505     * @stable ICU 3.0
506     */
507    UDAT_MONTH_FIELD = 2,
508
509    /**
510     * FieldPosition and UFieldPosition selector for 'd' field alignment,
511     * corresponding to the UCAL_DATE field.
512     * @stable ICU 3.0
513     */
514    UDAT_DATE_FIELD = 3,
515
516    /**
517     * FieldPosition and UFieldPosition selector for 'k' field alignment,
518     * corresponding to the UCAL_HOUR_OF_DAY field.
519     * UDAT_HOUR_OF_DAY1_FIELD is used for the one-based 24-hour clock.
520     * For example, 23:59 + 01:00 results in 24:59.
521     * @stable ICU 3.0
522     */
523    UDAT_HOUR_OF_DAY1_FIELD = 4,
524
525    /**
526     * FieldPosition and UFieldPosition selector for 'H' field alignment,
527     * corresponding to the UCAL_HOUR_OF_DAY field.
528     * UDAT_HOUR_OF_DAY0_FIELD is used for the zero-based 24-hour clock.
529     * For example, 23:59 + 01:00 results in 00:59.
530     * @stable ICU 3.0
531     */
532    UDAT_HOUR_OF_DAY0_FIELD = 5,
533
534    /**
535     * FieldPosition and UFieldPosition selector for 'm' field alignment,
536     * corresponding to the UCAL_MINUTE field.
537     * @stable ICU 3.0
538     */
539    UDAT_MINUTE_FIELD = 6,
540
541    /**
542     * FieldPosition and UFieldPosition selector for 's' field alignment,
543     * corresponding to the UCAL_SECOND field.
544     * @stable ICU 3.0
545     */
546    UDAT_SECOND_FIELD = 7,
547
548    /**
549     * FieldPosition and UFieldPosition selector for 'S' field alignment,
550     * corresponding to the UCAL_MILLISECOND field.
551     *
552     * Note: Time formats that use 'S' can display a maximum of three
553     * significant digits for fractional seconds, corresponding to millisecond
554     * resolution and a fractional seconds sub-pattern of SSS. If the
555     * sub-pattern is S or SS, the fractional seconds value will be truncated
556     * (not rounded) to the number of display places specified. If the
557     * fractional seconds sub-pattern is longer than SSS, the additional
558     * display places will be filled with zeros.
559     * @stable ICU 3.0
560     */
561    UDAT_FRACTIONAL_SECOND_FIELD = 8,
562
563    /**
564     * FieldPosition and UFieldPosition selector for 'E' field alignment,
565     * corresponding to the UCAL_DAY_OF_WEEK field.
566     * @stable ICU 3.0
567     */
568    UDAT_DAY_OF_WEEK_FIELD = 9,
569
570    /**
571     * FieldPosition and UFieldPosition selector for 'D' field alignment,
572     * corresponding to the UCAL_DAY_OF_YEAR field.
573     * @stable ICU 3.0
574     */
575    UDAT_DAY_OF_YEAR_FIELD = 10,
576
577    /**
578     * FieldPosition and UFieldPosition selector for 'F' field alignment,
579     * corresponding to the UCAL_DAY_OF_WEEK_IN_MONTH field.
580     * @stable ICU 3.0
581     */
582    UDAT_DAY_OF_WEEK_IN_MONTH_FIELD = 11,
583
584    /**
585     * FieldPosition and UFieldPosition selector for 'w' field alignment,
586     * corresponding to the UCAL_WEEK_OF_YEAR field.
587     * @stable ICU 3.0
588     */
589    UDAT_WEEK_OF_YEAR_FIELD = 12,
590
591    /**
592     * FieldPosition and UFieldPosition selector for 'W' field alignment,
593     * corresponding to the UCAL_WEEK_OF_MONTH field.
594     * @stable ICU 3.0
595     */
596    UDAT_WEEK_OF_MONTH_FIELD = 13,
597
598    /**
599     * FieldPosition and UFieldPosition selector for 'a' field alignment,
600     * corresponding to the UCAL_AM_PM field.
601     * @stable ICU 3.0
602     */
603    UDAT_AM_PM_FIELD = 14,
604
605    /**
606     * FieldPosition and UFieldPosition selector for 'h' field alignment,
607     * corresponding to the UCAL_HOUR field.
608     * UDAT_HOUR1_FIELD is used for the one-based 12-hour clock.
609     * For example, 11:30 PM + 1 hour results in 12:30 AM.
610     * @stable ICU 3.0
611     */
612    UDAT_HOUR1_FIELD = 15,
613
614    /**
615     * FieldPosition and UFieldPosition selector for 'K' field alignment,
616     * corresponding to the UCAL_HOUR field.
617     * UDAT_HOUR0_FIELD is used for the zero-based 12-hour clock.
618     * For example, 11:30 PM + 1 hour results in 00:30 AM.
619     * @stable ICU 3.0
620     */
621    UDAT_HOUR0_FIELD = 16,
622
623    /**
624     * FieldPosition and UFieldPosition selector for 'z' field alignment,
625     * corresponding to the UCAL_ZONE_OFFSET and
626     * UCAL_DST_OFFSET fields.
627     * @stable ICU 3.0
628     */
629    UDAT_TIMEZONE_FIELD = 17,
630
631    /**
632     * FieldPosition and UFieldPosition selector for 'Y' field alignment,
633     * corresponding to the UCAL_YEAR_WOY field.
634     * @stable ICU 3.0
635     */
636    UDAT_YEAR_WOY_FIELD = 18,
637
638    /**
639     * FieldPosition and UFieldPosition selector for 'e' field alignment,
640     * corresponding to the UCAL_DOW_LOCAL field.
641     * @stable ICU 3.0
642     */
643    UDAT_DOW_LOCAL_FIELD = 19,
644
645    /**
646     * FieldPosition and UFieldPosition selector for 'u' field alignment,
647     * corresponding to the UCAL_EXTENDED_YEAR field.
648     * @stable ICU 3.0
649     */
650    UDAT_EXTENDED_YEAR_FIELD = 20,
651
652    /**
653     * FieldPosition and UFieldPosition selector for 'g' field alignment,
654     * corresponding to the UCAL_JULIAN_DAY field.
655     * @stable ICU 3.0
656     */
657    UDAT_JULIAN_DAY_FIELD = 21,
658
659    /**
660     * FieldPosition and UFieldPosition selector for 'A' field alignment,
661     * corresponding to the UCAL_MILLISECONDS_IN_DAY field.
662     * @stable ICU 3.0
663     */
664    UDAT_MILLISECONDS_IN_DAY_FIELD = 22,
665
666    /**
667     * FieldPosition and UFieldPosition selector for 'Z' field alignment,
668     * corresponding to the UCAL_ZONE_OFFSET and
669     * UCAL_DST_OFFSET fields.
670     * @stable ICU 3.0
671     */
672    UDAT_TIMEZONE_RFC_FIELD = 23,
673
674    /**
675     * FieldPosition and UFieldPosition selector for 'v' field alignment,
676     * corresponding to the UCAL_ZONE_OFFSET field.
677     * @stable ICU 3.4
678     */
679    UDAT_TIMEZONE_GENERIC_FIELD = 24,
680    /**
681     * FieldPosition selector for 'c' field alignment,
682     * corresponding to the {@link #UCAL_DOW_LOCAL} field.
683     * This displays the stand alone day name, if available.
684     * @stable ICU 3.4
685     */
686    UDAT_STANDALONE_DAY_FIELD = 25,
687
688    /**
689     * FieldPosition selector for 'L' field alignment,
690     * corresponding to the {@link #UCAL_MONTH} field.
691     * This displays the stand alone month name, if available.
692     * @stable ICU 3.4
693     */
694    UDAT_STANDALONE_MONTH_FIELD = 26,
695
696    /**
697     * FieldPosition selector for "Q" field alignment,
698     * corresponding to quarters. This is implemented
699     * using the {@link #UCAL_MONTH} field. This
700     * displays the quarter.
701     * @stable ICU 3.6
702     */
703    UDAT_QUARTER_FIELD = 27,
704
705    /**
706     * FieldPosition selector for the "q" field alignment,
707     * corresponding to stand-alone quarters. This is
708     * implemented using the {@link #UCAL_MONTH} field.
709     * This displays the stand-alone quarter.
710     * @stable ICU 3.6
711     */
712    UDAT_STANDALONE_QUARTER_FIELD = 28,
713
714    /**
715     * FieldPosition and UFieldPosition selector for 'V' field alignment,
716     * corresponding to the UCAL_ZONE_OFFSET field.
717     * @stable ICU 3.8
718     */
719    UDAT_TIMEZONE_SPECIAL_FIELD = 29,
720
721    /**
722     * FieldPosition selector for "U" field alignment,
723     * corresponding to cyclic year names. This is implemented
724     * using the {@link #UCAL_YEAR} field. This displays
725     * the cyclic year name, if available.
726     * @stable ICU 49
727     */
728    UDAT_YEAR_NAME_FIELD = 30,
729
730    /**
731     * FieldPosition selector for 'O' field alignment,
732     * corresponding to the UCAL_ZONE_OFFSET and UCAL_DST_OFFSETfields.
733     * This displays the localized GMT format.
734     * @stable ICU 51
735     */
736    UDAT_TIMEZONE_LOCALIZED_GMT_OFFSET_FIELD = 31,
737
738    /**
739     * FieldPosition selector for 'X' field alignment,
740     * corresponding to the UCAL_ZONE_OFFSET and UCAL_DST_OFFSETfields.
741     * This displays the ISO 8601 local time offset format or UTC indicator ("Z").
742     * @stable ICU 51
743     */
744    UDAT_TIMEZONE_ISO_FIELD = 32,
745
746    /**
747     * FieldPosition selector for 'x' field alignment,
748     * corresponding to the UCAL_ZONE_OFFSET and UCAL_DST_OFFSET fields.
749     * This displays the ISO 8601 local time offset format.
750     * @stable ICU 51
751     */
752    UDAT_TIMEZONE_ISO_LOCAL_FIELD = 33,
753
754#ifndef U_HIDE_INTERNAL_API
755    /**
756     * FieldPosition and UFieldPosition selector for 'r' field alignment,
757     * no directly corresponding UCAL_ field.
758     * @internal ICU 53
759     */
760    UDAT_RELATED_YEAR_FIELD = 34,
761#endif /* U_HIDE_INTERNAL_API */
762
763   /**
764     * Number of FieldPosition and UFieldPosition selectors for
765     * DateFormat and UDateFormat.
766     * Valid selectors range from 0 to UDAT_FIELD_COUNT-1.
767     * This value is subject to change if new fields are defined
768     * in the future.
769     * @stable ICU 3.0
770     */
771    UDAT_FIELD_COUNT = 35
772
773} UDateFormatField;
774
775
776/**
777 * Maps from a UDateFormatField to the corresponding UCalendarDateFields.
778 * Note: since the mapping is many-to-one, there is no inverse mapping.
779 * @param field the UDateFormatField.
780 * @return the UCalendarDateField.  This will be UCAL_FIELD_COUNT in case
781 * of error (e.g., the input field is UDAT_FIELD_COUNT).
782 * @stable ICU 4.4
783 */
784U_STABLE UCalendarDateFields U_EXPORT2
785udat_toCalendarDateField(UDateFormatField field);
786
787
788/**
789 * Open a new UDateFormat for formatting and parsing dates and times.
790 * A UDateFormat may be used to format dates in calls to {@link #udat_format },
791 * and to parse dates in calls to {@link #udat_parse }.
792 * @param timeStyle The style used to format times; one of UDAT_FULL, UDAT_LONG,
793 * UDAT_MEDIUM, UDAT_SHORT, UDAT_DEFAULT, or UDAT_NONE (relative time styles
794 * are not currently supported).
795 * When the pattern parameter is used, pass in UDAT_PATTERN for both timeStyle and dateStyle.
796 * @param dateStyle The style used to format dates; one of UDAT_FULL, UDAT_LONG,
797 * UDAT_MEDIUM, UDAT_SHORT, UDAT_DEFAULT, UDAT_FULL_RELATIVE, UDAT_LONG_RELATIVE,
798 * UDAT_MEDIUM_RELATIVE, UDAT_SHORT_RELATIVE, or UDAT_NONE.
799 * When the pattern parameter is used, pass in UDAT_PATTERN for both timeStyle and dateStyle.
800 * As currently implemented,
801 * relative date formatting only affects a limited range of calendar days before or
802 * after the current date, based on the CLDR &lt;field type="day"&gt;/&lt;relative&gt; data: For
803 * example, in English, "Yesterday", "Today", and "Tomorrow". Outside of this range,
804 * dates are formatted using the corresponding non-relative style.
805 * @param locale The locale specifying the formatting conventions
806 * @param tzID A timezone ID specifying the timezone to use.  If 0, use
807 * the default timezone.
808 * @param tzIDLength The length of tzID, or -1 if null-terminated.
809 * @param pattern A pattern specifying the format to use.
810 * @param patternLength The number of characters in the pattern, or -1 if null-terminated.
811 * @param status A pointer to an UErrorCode to receive any errors
812 * @return A pointer to a UDateFormat to use for formatting dates and times, or 0 if
813 * an error occurred.
814 * @stable ICU 2.0
815 */
816U_STABLE UDateFormat* U_EXPORT2
817udat_open(UDateFormatStyle  timeStyle,
818          UDateFormatStyle  dateStyle,
819          const char        *locale,
820          const UChar       *tzID,
821          int32_t           tzIDLength,
822          const UChar       *pattern,
823          int32_t           patternLength,
824          UErrorCode        *status);
825
826
827/**
828* Close a UDateFormat.
829* Once closed, a UDateFormat may no longer be used.
830* @param format The formatter to close.
831* @stable ICU 2.0
832*/
833U_STABLE void U_EXPORT2
834udat_close(UDateFormat* format);
835
836
837/* Dont hide UDateFormatBooleanAttribute type with #ifndef U_HIDE_DRAFT_API, needed by virtual methods */
838/* Also don't hide UDAT_BOOLEAN_ATTRIBUTE_COUNT, needed by template class EnumSet<UDateFormatBooleanAttribute,...> */
839/**
840 * DateFormat boolean attributes
841 *
842 * @draft ICU 53
843 */
844typedef enum UDateFormatBooleanAttribute {
845#ifndef U_HIDE_DRAFT_API
846   /**
847     * indicates whether whitespace is allowed. Includes trailing dot tolerance.
848     * @draft ICU 53
849     */
850    UDAT_PARSE_ALLOW_WHITESPACE = 0,
851    /**
852     * indicates tolerance of numeric data when String data may be assumed. eg: UDAT_YEAR_NAME_FIELD,
853     * 		UDAT_STANDALONE_MONTH_FIELD, UDAT_DAY_OF_WEEK_FIELD
854     * @draft ICU 53
855     */
856    UDAT_PARSE_ALLOW_NUMERIC = 1,
857    /**
858     * indicates tolerance of a partial literal match
859     * @draft ICU 53
860     */
861    UDAT_PARSE_PARTIAL_MATCH = 2,
862    /**
863     * indicates tolerance of pattern mismatch between input data and specified format pattern.
864     * e.g. accepting "September" for a month pattern of MMM ("Sep")
865     * @draft ICU 53
866     */
867    UDAT_PARSE_MULTIPLE_PATTERNS_FOR_MATCH = 3,
868#endif /* U_HIDE_DRAFT_API */
869    /**
870     * count boolean date format constants
871     * @draft ICU 53
872     */
873    UDAT_BOOLEAN_ATTRIBUTE_COUNT = 4
874} UDateFormatBooleanAttribute;
875
876#ifndef U_HIDE_DRAFT_API
877/**
878 * Get a boolean attribute associated with a UDateFormat.
879 * An example would be a true value for a key of UDAT_PARSE_ALLOW_WHITESPACE indicating allowing whitespace leniency.
880 * If the formatter does not understand the attribute, -1 is returned.
881 * @param fmt The formatter to query.
882 * @param attr The attribute to query; e.g. UDAT_PARSE_ALLOW_WHITESPACE.
883 * @param status A pointer to an UErrorCode to receive any errors
884 * @return The value of attr.
885 * @draft ICU 53
886 */
887U_DRAFT UBool U_EXPORT2
888udat_getBooleanAttribute(const UDateFormat* fmt, UDateFormatBooleanAttribute attr, UErrorCode* status);
889
890/**
891 * Set a boolean attribute associated with a UDateFormat.
892 * An example of a boolean attribute is parse leniency control.  If the formatter does not understand
893 * the attribute, the call is ignored.
894 * @param fmt The formatter to set.
895 * @param attr The attribute to set; one of UDAT_PARSE_ALLOW_WHITESPACE or UDAT_PARSE_ALLOW_NUMERIC
896 * @param newValue The new value of attr.
897 * @param status A pointer to an UErrorCode to receive any errors
898 * @draft ICU 53
899 */
900U_DRAFT void U_EXPORT2
901udat_setBooleanAttribute(UDateFormat *fmt, UDateFormatBooleanAttribute attr, UBool newValue, UErrorCode* status);
902
903#endif /* U_HIDE_DRAFT_API */
904
905
906
907#if U_SHOW_CPLUSPLUS_API
908
909U_NAMESPACE_BEGIN
910
911/**
912 * \class LocalUDateFormatPointer
913 * "Smart pointer" class, closes a UDateFormat via udat_close().
914 * For most methods see the LocalPointerBase base class.
915 *
916 * @see LocalPointerBase
917 * @see LocalPointer
918 * @stable ICU 4.4
919 */
920U_DEFINE_LOCAL_OPEN_POINTER(LocalUDateFormatPointer, UDateFormat, udat_close);
921
922U_NAMESPACE_END
923
924#endif
925
926/**
927 * Open a copy of a UDateFormat.
928 * This function performs a deep copy.
929 * @param fmt The format to copy
930 * @param status A pointer to an UErrorCode to receive any errors.
931 * @return A pointer to a UDateFormat identical to fmt.
932 * @stable ICU 2.0
933 */
934U_STABLE UDateFormat* U_EXPORT2
935udat_clone(const UDateFormat *fmt,
936       UErrorCode *status);
937
938/**
939* Format a date using an UDateFormat.
940* The date will be formatted using the conventions specified in {@link #udat_open }
941* @param format The formatter to use
942* @param dateToFormat The date to format
943* @param result A pointer to a buffer to receive the formatted number.
944* @param resultLength The maximum size of result.
945* @param position A pointer to a UFieldPosition.  On input, position->field
946* is read.  On output, position->beginIndex and position->endIndex indicate
947* the beginning and ending indices of field number position->field, if such
948* a field exists.  This parameter may be NULL, in which case no field
949* position data is returned.
950* @param status A pointer to an UErrorCode to receive any errors
951* @return The total buffer size needed; if greater than resultLength, the output was truncated.
952* @see udat_parse
953* @see UFieldPosition
954* @stable ICU 2.0
955*/
956U_STABLE int32_t U_EXPORT2
957udat_format(    const    UDateFormat*    format,
958                        UDate           dateToFormat,
959                        UChar*          result,
960                        int32_t         resultLength,
961                        UFieldPosition* position,
962                        UErrorCode*     status);
963
964/**
965* Parse a string into an date/time using a UDateFormat.
966* The date will be parsed using the conventions specified in {@link #udat_open }.
967* <P>
968* Note that the normal date formats associated with some calendars - such
969* as the Chinese lunar calendar - do not specify enough fields to enable
970* dates to be parsed unambiguously. In the case of the Chinese lunar
971* calendar, while the year within the current 60-year cycle is specified,
972* the number of such cycles since the start date of the calendar (in the
973* UCAL_ERA field of the UCalendar object) is not normally part of the format,
974* and parsing may assume the wrong era. For cases such as this it is
975* recommended that clients parse using udat_parseCalendar with the UCalendar
976* passed in set to the current date, or to a date within the era/cycle that
977* should be assumed if absent in the format.
978*
979* @param format The formatter to use.
980* @param text The text to parse.
981* @param textLength The length of text, or -1 if null-terminated.
982* @param parsePos If not 0, on input a pointer to an integer specifying the offset at which
983* to begin parsing.  If not 0, on output the offset at which parsing ended.
984* @param status A pointer to an UErrorCode to receive any errors
985* @return The value of the parsed date/time
986* @see udat_format
987* @stable ICU 2.0
988*/
989U_STABLE UDate U_EXPORT2
990udat_parse(const    UDateFormat*    format,
991           const    UChar*          text,
992                    int32_t         textLength,
993                    int32_t         *parsePos,
994                    UErrorCode      *status);
995
996/**
997* Parse a string into an date/time using a UDateFormat.
998* The date will be parsed using the conventions specified in {@link #udat_open }.
999* @param format The formatter to use.
1000* @param calendar A calendar set on input to the date and time to be used for
1001*                 missing values in the date/time string being parsed, and set
1002*                 on output to the parsed date/time. When the calendar type is
1003*                 different from the internal calendar held by the UDateFormat
1004*                 instance, the internal calendar will be cloned to a work
1005*                 calendar set to the same milliseconds and time zone as this
1006*                 calendar parameter, field values will be parsed based on the
1007*                 work calendar, then the result (milliseconds and time zone)
1008*                 will be set in this calendar.
1009* @param text The text to parse.
1010* @param textLength The length of text, or -1 if null-terminated.
1011* @param parsePos If not 0, on input a pointer to an integer specifying the offset at which
1012* to begin parsing.  If not 0, on output the offset at which parsing ended.
1013* @param status A pointer to an UErrorCode to receive any errors
1014* @see udat_format
1015* @stable ICU 2.0
1016*/
1017U_STABLE void U_EXPORT2
1018udat_parseCalendar(const    UDateFormat*    format,
1019                            UCalendar*      calendar,
1020                   const    UChar*          text,
1021                            int32_t         textLength,
1022                            int32_t         *parsePos,
1023                            UErrorCode      *status);
1024
1025/**
1026* Determine if an UDateFormat will perform lenient parsing.
1027* With lenient parsing, the parser may use heuristics to interpret inputs that do not
1028* precisely match the pattern. With strict parsing, inputs must match the pattern.
1029* @param fmt The formatter to query
1030* @return TRUE if fmt is set to perform lenient parsing, FALSE otherwise.
1031* @see udat_setLenient
1032* @stable ICU 2.0
1033*/
1034U_STABLE UBool U_EXPORT2
1035udat_isLenient(const UDateFormat* fmt);
1036
1037/**
1038* Specify whether an UDateFormat will perform lenient parsing.
1039* With lenient parsing, the parser may use heuristics to interpret inputs that do not
1040* precisely match the pattern. With strict parsing, inputs must match the pattern.
1041* @param fmt The formatter to set
1042* @param isLenient TRUE if fmt should perform lenient parsing, FALSE otherwise.
1043* @see dat_isLenient
1044* @stable ICU 2.0
1045*/
1046U_STABLE void U_EXPORT2
1047udat_setLenient(    UDateFormat*    fmt,
1048                    UBool          isLenient);
1049
1050/**
1051* Get the UCalendar associated with an UDateFormat.
1052* A UDateFormat uses a UCalendar to convert a raw value to, for example,
1053* the day of the week.
1054* @param fmt The formatter to query.
1055* @return A pointer to the UCalendar used by fmt.
1056* @see udat_setCalendar
1057* @stable ICU 2.0
1058*/
1059U_STABLE const UCalendar* U_EXPORT2
1060udat_getCalendar(const UDateFormat* fmt);
1061
1062/**
1063* Set the UCalendar associated with an UDateFormat.
1064* A UDateFormat uses a UCalendar to convert a raw value to, for example,
1065* the day of the week.
1066* @param fmt The formatter to set.
1067* @param calendarToSet A pointer to an UCalendar to be used by fmt.
1068* @see udat_setCalendar
1069* @stable ICU 2.0
1070*/
1071U_STABLE void U_EXPORT2
1072udat_setCalendar(            UDateFormat*    fmt,
1073                    const   UCalendar*      calendarToSet);
1074
1075/**
1076* Get the UNumberFormat associated with an UDateFormat.
1077* A UDateFormat uses a UNumberFormat to format numbers within a date,
1078* for example the day number.
1079* @param fmt The formatter to query.
1080* @return A pointer to the UNumberFormat used by fmt to format numbers.
1081* @see udat_setNumberFormat
1082* @stable ICU 2.0
1083*/
1084U_STABLE const UNumberFormat* U_EXPORT2
1085udat_getNumberFormat(const UDateFormat* fmt);
1086
1087/**
1088* Set the UNumberFormat associated with an UDateFormat.
1089* A UDateFormat uses a UNumberFormat to format numbers within a date,
1090* for example the day number.
1091* @param fmt The formatter to set.
1092* @param numberFormatToSet A pointer to the UNumberFormat to be used by fmt to format numbers.
1093* @see udat_getNumberFormat
1094* @stable ICU 2.0
1095*/
1096U_STABLE void U_EXPORT2
1097udat_setNumberFormat(            UDateFormat*    fmt,
1098                        const   UNumberFormat*  numberFormatToSet);
1099
1100/**
1101* Get a locale for which date/time formatting patterns are available.
1102* A UDateFormat in a locale returned by this function will perform the correct
1103* formatting and parsing for the locale.
1104* @param localeIndex The index of the desired locale.
1105* @return A locale for which date/time formatting patterns are available, or 0 if none.
1106* @see udat_countAvailable
1107* @stable ICU 2.0
1108*/
1109U_STABLE const char* U_EXPORT2
1110udat_getAvailable(int32_t localeIndex);
1111
1112/**
1113* Determine how many locales have date/time  formatting patterns available.
1114* This function is most useful as determining the loop ending condition for
1115* calls to {@link #udat_getAvailable }.
1116* @return The number of locales for which date/time formatting patterns are available.
1117* @see udat_getAvailable
1118* @stable ICU 2.0
1119*/
1120U_STABLE int32_t U_EXPORT2
1121udat_countAvailable(void);
1122
1123/**
1124* Get the year relative to which all 2-digit years are interpreted.
1125* For example, if the 2-digit start year is 2100, the year 99 will be
1126* interpreted as 2199.
1127* @param fmt The formatter to query.
1128* @param status A pointer to an UErrorCode to receive any errors
1129* @return The year relative to which all 2-digit years are interpreted.
1130* @see udat_Set2DigitYearStart
1131* @stable ICU 2.0
1132*/
1133U_STABLE UDate U_EXPORT2
1134udat_get2DigitYearStart(    const   UDateFormat     *fmt,
1135                                    UErrorCode      *status);
1136
1137/**
1138* Set the year relative to which all 2-digit years will be interpreted.
1139* For example, if the 2-digit start year is 2100, the year 99 will be
1140* interpreted as 2199.
1141* @param fmt The formatter to set.
1142* @param d The year relative to which all 2-digit years will be interpreted.
1143* @param status A pointer to an UErrorCode to receive any errors
1144* @see udat_Set2DigitYearStart
1145* @stable ICU 2.0
1146*/
1147U_STABLE void U_EXPORT2
1148udat_set2DigitYearStart(    UDateFormat     *fmt,
1149                            UDate           d,
1150                            UErrorCode      *status);
1151
1152/**
1153* Extract the pattern from a UDateFormat.
1154* The pattern will follow the pattern syntax rules.
1155* @param fmt The formatter to query.
1156* @param localized TRUE if the pattern should be localized, FALSE otherwise.
1157* @param result A pointer to a buffer to receive the pattern.
1158* @param resultLength The maximum size of result.
1159* @param status A pointer to an UErrorCode to receive any errors
1160* @return The total buffer size needed; if greater than resultLength, the output was truncated.
1161* @see udat_applyPattern
1162* @stable ICU 2.0
1163*/
1164U_STABLE int32_t U_EXPORT2
1165udat_toPattern(    const   UDateFormat     *fmt,
1166                        UBool          localized,
1167                        UChar           *result,
1168                        int32_t         resultLength,
1169                        UErrorCode      *status);
1170
1171/**
1172* Set the pattern used by an UDateFormat.
1173* The pattern should follow the pattern syntax rules.
1174* @param format The formatter to set.
1175* @param localized TRUE if the pattern is localized, FALSE otherwise.
1176* @param pattern The new pattern
1177* @param patternLength The length of pattern, or -1 if null-terminated.
1178* @see udat_toPattern
1179* @stable ICU 2.0
1180*/
1181U_STABLE void U_EXPORT2
1182udat_applyPattern(            UDateFormat     *format,
1183                            UBool          localized,
1184                    const   UChar           *pattern,
1185                            int32_t         patternLength);
1186
1187/**
1188 * The possible types of date format symbols
1189 * @stable ICU 2.6
1190 */
1191typedef enum UDateFormatSymbolType {
1192    /** The era names, for example AD */
1193    UDAT_ERAS,
1194    /** The month names, for example February */
1195    UDAT_MONTHS,
1196    /** The short month names, for example Feb. */
1197    UDAT_SHORT_MONTHS,
1198    /** The CLDR-style format "wide" weekday names, for example Monday */
1199    UDAT_WEEKDAYS,
1200    /**
1201     * The CLDR-style format "abbreviated" (not "short") weekday names, for example "Mon."
1202     * For the CLDR-style format "short" weekday names, use UDAT_SHORTER_WEEKDAYS.
1203     */
1204    UDAT_SHORT_WEEKDAYS,
1205    /** The AM/PM names, for example AM */
1206    UDAT_AM_PMS,
1207    /** The localized characters */
1208    UDAT_LOCALIZED_CHARS,
1209    /** The long era names, for example Anno Domini */
1210    UDAT_ERA_NAMES,
1211    /** The narrow month names, for example F */
1212    UDAT_NARROW_MONTHS,
1213    /** The CLDR-style format "narrow" weekday names, for example "M" */
1214    UDAT_NARROW_WEEKDAYS,
1215    /** Standalone context versions of months */
1216    UDAT_STANDALONE_MONTHS,
1217    UDAT_STANDALONE_SHORT_MONTHS,
1218    UDAT_STANDALONE_NARROW_MONTHS,
1219    /** The CLDR-style stand-alone "wide" weekday names */
1220    UDAT_STANDALONE_WEEKDAYS,
1221    /**
1222     * The CLDR-style stand-alone "abbreviated" (not "short") weekday names.
1223     * For the CLDR-style stand-alone "short" weekday names, use UDAT_STANDALONE_SHORTER_WEEKDAYS.
1224     */
1225    UDAT_STANDALONE_SHORT_WEEKDAYS,
1226    /** The CLDR-style stand-alone "narrow" weekday names */
1227    UDAT_STANDALONE_NARROW_WEEKDAYS,
1228    /** The quarters, for example 1st Quarter */
1229    UDAT_QUARTERS,
1230    /** The short quarter names, for example Q1 */
1231    UDAT_SHORT_QUARTERS,
1232    /** Standalone context versions of quarters */
1233    UDAT_STANDALONE_QUARTERS,
1234    UDAT_STANDALONE_SHORT_QUARTERS,
1235    /**
1236     * The CLDR-style short weekday names, e.g. "Su", Mo", etc.
1237     * These are named "SHORTER" to contrast with the constants using _SHORT_
1238     * above, which actually get the CLDR-style *abbreviated* versions of the
1239     * corresponding names.
1240     * @stable ICU 51
1241     */
1242    UDAT_SHORTER_WEEKDAYS,
1243    /**
1244     * Standalone version of UDAT_SHORTER_WEEKDAYS.
1245     * @stable ICU 51
1246     */
1247    UDAT_STANDALONE_SHORTER_WEEKDAYS
1248} UDateFormatSymbolType;
1249
1250struct UDateFormatSymbols;
1251/** Date format symbols.
1252 *  For usage in C programs.
1253 *  @stable ICU 2.6
1254 */
1255typedef struct UDateFormatSymbols UDateFormatSymbols;
1256
1257/**
1258* Get the symbols associated with an UDateFormat.
1259* The symbols are what a UDateFormat uses to represent locale-specific data,
1260* for example month or day names.
1261* @param fmt The formatter to query.
1262* @param type The type of symbols to get.  One of UDAT_ERAS, UDAT_MONTHS, UDAT_SHORT_MONTHS,
1263* UDAT_WEEKDAYS, UDAT_SHORT_WEEKDAYS, UDAT_AM_PMS, or UDAT_LOCALIZED_CHARS
1264* @param symbolIndex The desired symbol of type type.
1265* @param result A pointer to a buffer to receive the pattern.
1266* @param resultLength The maximum size of result.
1267* @param status A pointer to an UErrorCode to receive any errors
1268* @return The total buffer size needed; if greater than resultLength, the output was truncated.
1269* @see udat_countSymbols
1270* @see udat_setSymbols
1271* @stable ICU 2.0
1272*/
1273U_STABLE int32_t U_EXPORT2
1274udat_getSymbols(const   UDateFormat             *fmt,
1275                        UDateFormatSymbolType   type,
1276                        int32_t                 symbolIndex,
1277                        UChar                   *result,
1278                        int32_t                 resultLength,
1279                        UErrorCode              *status);
1280
1281/**
1282* Count the number of particular symbols for an UDateFormat.
1283* This function is most useful as for detemining the loop termination condition
1284* for calls to {@link #udat_getSymbols }.
1285* @param fmt The formatter to query.
1286* @param type The type of symbols to count.  One of UDAT_ERAS, UDAT_MONTHS, UDAT_SHORT_MONTHS,
1287* UDAT_WEEKDAYS, UDAT_SHORT_WEEKDAYS, UDAT_AM_PMS, or UDAT_LOCALIZED_CHARS
1288* @return The number of symbols of type type.
1289* @see udat_getSymbols
1290* @see udat_setSymbols
1291* @stable ICU 2.0
1292*/
1293U_STABLE int32_t U_EXPORT2
1294udat_countSymbols(    const    UDateFormat                *fmt,
1295                            UDateFormatSymbolType    type);
1296
1297/**
1298* Set the symbols associated with an UDateFormat.
1299* The symbols are what a UDateFormat uses to represent locale-specific data,
1300* for example month or day names.
1301* @param format The formatter to set
1302* @param type The type of symbols to set.  One of UDAT_ERAS, UDAT_MONTHS, UDAT_SHORT_MONTHS,
1303* UDAT_WEEKDAYS, UDAT_SHORT_WEEKDAYS, UDAT_AM_PMS, or UDAT_LOCALIZED_CHARS
1304* @param symbolIndex The index of the symbol to set of type type.
1305* @param value The new value
1306* @param valueLength The length of value, or -1 if null-terminated
1307* @param status A pointer to an UErrorCode to receive any errors
1308* @see udat_getSymbols
1309* @see udat_countSymbols
1310* @stable ICU 2.0
1311*/
1312U_STABLE void U_EXPORT2
1313udat_setSymbols(    UDateFormat             *format,
1314                    UDateFormatSymbolType   type,
1315                    int32_t                 symbolIndex,
1316                    UChar                   *value,
1317                    int32_t                 valueLength,
1318                    UErrorCode              *status);
1319
1320/**
1321 * Get the locale for this date format object.
1322 * You can choose between valid and actual locale.
1323 * @param fmt The formatter to get the locale from
1324 * @param type type of the locale we're looking for (valid or actual)
1325 * @param status error code for the operation
1326 * @return the locale name
1327 * @stable ICU 2.8
1328 */
1329U_STABLE const char* U_EXPORT2
1330udat_getLocaleByType(const UDateFormat *fmt,
1331                     ULocDataLocaleType type,
1332                     UErrorCode* status);
1333
1334/**
1335 * Set a particular UDisplayContext value in the formatter, such as
1336 * UDISPCTX_CAPITALIZATION_FOR_STANDALONE.
1337 * @param fmt The formatter for which to set a UDisplayContext value.
1338 * @param value The UDisplayContext value to set.
1339 * @param status A pointer to an UErrorCode to receive any errors
1340 * @stable ICU 51
1341 */
1342U_DRAFT void U_EXPORT2
1343udat_setContext(UDateFormat* fmt, UDisplayContext value, UErrorCode* status);
1344
1345#ifndef U_HIDE_DRAFT_API
1346/**
1347 * Get the formatter's UDisplayContext value for the specified UDisplayContextType,
1348 * such as UDISPCTX_TYPE_CAPITALIZATION.
1349 * @param fmt The formatter to query.
1350 * @param type The UDisplayContextType whose value to return
1351 * @param status A pointer to an UErrorCode to receive any errors
1352 * @return The UDisplayContextValue for the specified type.
1353 * @draft ICU 53
1354 */
1355U_DRAFT UDisplayContext U_EXPORT2
1356udat_getContext(const UDateFormat* fmt, UDisplayContextType type, UErrorCode* status);
1357
1358#endif  /* U_HIDE_DRAFT_API */
1359
1360#ifndef U_HIDE_INTERNAL_API
1361/**
1362* Extract the date pattern from a UDateFormat set for relative date formatting.
1363* The pattern will follow the pattern syntax rules.
1364* @param fmt The formatter to query.
1365* @param result A pointer to a buffer to receive the pattern.
1366* @param resultLength The maximum size of result.
1367* @param status A pointer to a UErrorCode to receive any errors
1368* @return The total buffer size needed; if greater than resultLength, the output was truncated.
1369* @see udat_applyPatternRelative
1370* @internal ICU 4.2 technology preview
1371*/
1372U_INTERNAL int32_t U_EXPORT2
1373udat_toPatternRelativeDate(const UDateFormat *fmt,
1374                           UChar             *result,
1375                           int32_t           resultLength,
1376                           UErrorCode        *status);
1377
1378/**
1379* Extract the time pattern from a UDateFormat set for relative date formatting.
1380* The pattern will follow the pattern syntax rules.
1381* @param fmt The formatter to query.
1382* @param result A pointer to a buffer to receive the pattern.
1383* @param resultLength The maximum size of result.
1384* @param status A pointer to a UErrorCode to receive any errors
1385* @return The total buffer size needed; if greater than resultLength, the output was truncated.
1386* @see udat_applyPatternRelative
1387* @internal ICU 4.2 technology preview
1388*/
1389U_INTERNAL int32_t U_EXPORT2
1390udat_toPatternRelativeTime(const UDateFormat *fmt,
1391                           UChar             *result,
1392                           int32_t           resultLength,
1393                           UErrorCode        *status);
1394
1395/**
1396* Set the date & time patterns used by a UDateFormat set for relative date formatting.
1397* The patterns should follow the pattern syntax rules.
1398* @param format The formatter to set.
1399* @param datePattern The new date pattern
1400* @param datePatternLength The length of datePattern, or -1 if null-terminated.
1401* @param timePattern The new time pattern
1402* @param timePatternLength The length of timePattern, or -1 if null-terminated.
1403* @param status A pointer to a UErrorCode to receive any errors
1404* @see udat_toPatternRelativeDate, udat_toPatternRelativeTime
1405* @internal ICU 4.2 technology preview
1406*/
1407U_INTERNAL void U_EXPORT2
1408udat_applyPatternRelative(UDateFormat *format,
1409                          const UChar *datePattern,
1410                          int32_t     datePatternLength,
1411                          const UChar *timePattern,
1412                          int32_t     timePatternLength,
1413                          UErrorCode  *status);
1414
1415/**
1416 * @internal
1417 * @see udat_open
1418 */
1419typedef UDateFormat* (U_EXPORT2 *UDateFormatOpener) (UDateFormatStyle  timeStyle,
1420                                                    UDateFormatStyle  dateStyle,
1421                                                    const char        *locale,
1422                                                    const UChar       *tzID,
1423                                                    int32_t           tzIDLength,
1424                                                    const UChar       *pattern,
1425                                                    int32_t           patternLength,
1426                                                    UErrorCode        *status);
1427
1428/**
1429 * Register a provider factory
1430 * @internal ICU 49
1431 */
1432U_INTERNAL void U_EXPORT2
1433udat_registerOpener(UDateFormatOpener opener, UErrorCode *status);
1434
1435/**
1436 * Un-Register a provider factory
1437 * @internal ICU 49
1438 */
1439U_INTERNAL UDateFormatOpener U_EXPORT2
1440udat_unregisterOpener(UDateFormatOpener opener, UErrorCode *status);
1441#endif  /* U_HIDE_INTERNAL_API */
1442
1443
1444#endif /* #if !UCONFIG_NO_FORMATTING */
1445
1446#endif
1447