1// © 2016 and later: Unicode, Inc. and others.
2// License & terms of use: http://www.unicode.org/copyright.html
3/*
4*******************************************************************************
5*
6* Copyright (C) 2007-2015, International Business Machines
7* Corporation and others. All Rights Reserved.
8*
9*******************************************************************************
10* file name: udatpg.h
11* encoding: UTF-8
12* tab size: 8 (not used)
13* indentation:4
14*
15* created on: 2007jul30
16* created by: Markus W. Scherer
17*/
18
19#ifndef __UDATPG_H__
20#define __UDATPG_H__
21
22#include "unicode/utypes.h"
23#include "unicode/uenum.h"
24#include "unicode/localpointer.h"
25
26/**
27 * \file
28 * \brief C API: Wrapper for icu::DateTimePatternGenerator (unicode/dtptngen.h).
29 *
30 * UDateTimePatternGenerator provides flexible generation of date format patterns,
31 * like "yy-MM-dd". The user can build up the generator by adding successive
32 * patterns. Once that is done, a query can be made using a "skeleton", which is
33 * a pattern which just includes the desired fields and lengths. The generator
34 * will return the "best fit" pattern corresponding to that skeleton.
35 * <p>The main method people will use is udatpg_getBestPattern, since normally
36 * UDateTimePatternGenerator is pre-built with data from a particular locale.
37 * However, generators can be built directly from other data as well.
38 * <p><i>Issue: may be useful to also have a function that returns the list of
39 * fields in a pattern, in order, since we have that internally.
40 * That would be useful for getting the UI order of field elements.</i>
41 */
42
43/**
44 * Opaque type for a date/time pattern generator object.
45 * @stable ICU 3.8
46 */
47typedef void *UDateTimePatternGenerator;
48
49/**
50 * Field number constants for udatpg_getAppendItemFormats() and similar functions.
51 * These constants are separate from UDateFormatField despite semantic overlap
52 * because some fields are merged for the date/time pattern generator.
53 * @stable ICU 3.8
54 */
55typedef enum UDateTimePatternField {
56 /** @stable ICU 3.8 */
57 UDATPG_ERA_FIELD,
58 /** @stable ICU 3.8 */
59 UDATPG_YEAR_FIELD,
60 /** @stable ICU 3.8 */
61 UDATPG_QUARTER_FIELD,
62 /** @stable ICU 3.8 */
63 UDATPG_MONTH_FIELD,
64 /** @stable ICU 3.8 */
65 UDATPG_WEEK_OF_YEAR_FIELD,
66 /** @stable ICU 3.8 */
67 UDATPG_WEEK_OF_MONTH_FIELD,
68 /** @stable ICU 3.8 */
69 UDATPG_WEEKDAY_FIELD,
70 /** @stable ICU 3.8 */
71 UDATPG_DAY_OF_YEAR_FIELD,
72 /** @stable ICU 3.8 */
73 UDATPG_DAY_OF_WEEK_IN_MONTH_FIELD,
74 /** @stable ICU 3.8 */
75 UDATPG_DAY_FIELD,
76 /** @stable ICU 3.8 */
77 UDATPG_DAYPERIOD_FIELD,
78 /** @stable ICU 3.8 */
79 UDATPG_HOUR_FIELD,
80 /** @stable ICU 3.8 */
81 UDATPG_MINUTE_FIELD,
82 /** @stable ICU 3.8 */
83 UDATPG_SECOND_FIELD,
84 /** @stable ICU 3.8 */
85 UDATPG_FRACTIONAL_SECOND_FIELD,
86 /** @stable ICU 3.8 */
87 UDATPG_ZONE_FIELD,
88
89 /* Do not conditionalize the following with #ifndef U_HIDE_DEPRECATED_API,
90 * it is needed for layout of DateTimePatternGenerator object. */
91 /**
92 * One more than the highest normal UDateTimePatternField value.
93 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
94 */
95 UDATPG_FIELD_COUNT
96} UDateTimePatternField;
97
98/**
99 * Field display name width constants for udatpg_getFieldDisplayName().
100 * @stable ICU 61
101 */
102typedef enum UDateTimePGDisplayWidth {
103 /** @stable ICU 61 */
104 UDATPG_WIDE,
105 /** @stable ICU 61 */
106 UDATPG_ABBREVIATED,
107 /** @stable ICU 61 */
108 UDATPG_NARROW
109} UDateTimePGDisplayWidth;
110
111/**
112 * Masks to control forcing the length of specified fields in the returned
113 * pattern to match those in the skeleton (when this would not happen
114 * otherwise). These may be combined to force the length of multiple fields.
115 * Used with udatpg_getBestPatternWithOptions, udatpg_replaceFieldTypesWithOptions.
116 * @stable ICU 4.4
117 */
118typedef enum UDateTimePatternMatchOptions {
119 /** @stable ICU 4.4 */
120 UDATPG_MATCH_NO_OPTIONS = 0,
121 /** @stable ICU 4.4 */
122 UDATPG_MATCH_HOUR_FIELD_LENGTH = 1 << UDATPG_HOUR_FIELD,
123#ifndef U_HIDE_INTERNAL_API
124 /** @internal ICU 4.4 */
125 UDATPG_MATCH_MINUTE_FIELD_LENGTH = 1 << UDATPG_MINUTE_FIELD,
126 /** @internal ICU 4.4 */
127 UDATPG_MATCH_SECOND_FIELD_LENGTH = 1 << UDATPG_SECOND_FIELD,
128#endif /* U_HIDE_INTERNAL_API */
129 /** @stable ICU 4.4 */
130 UDATPG_MATCH_ALL_FIELDS_LENGTH = (1 << UDATPG_FIELD_COUNT) - 1
131} UDateTimePatternMatchOptions;
132
133/**
134 * Status return values from udatpg_addPattern().
135 * @stable ICU 3.8
136 */
137typedef enum UDateTimePatternConflict {
138 /** @stable ICU 3.8 */
139 UDATPG_NO_CONFLICT,
140 /** @stable ICU 3.8 */
141 UDATPG_BASE_CONFLICT,
142 /** @stable ICU 3.8 */
143 UDATPG_CONFLICT,
144#ifndef U_HIDE_DEPRECATED_API
145 /**
146 * One more than the highest normal UDateTimePatternConflict value.
147 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
148 */
149 UDATPG_CONFLICT_COUNT
150#endif // U_HIDE_DEPRECATED_API
151} UDateTimePatternConflict;
152
153/**
154 * Open a generator according to a given locale.
155 * @param locale
156 * @param pErrorCode a pointer to the UErrorCode which must not indicate a
157 * failure before the function call.
158 * @return a pointer to UDateTimePatternGenerator.
159 * @stable ICU 3.8
160 */
161U_STABLE UDateTimePatternGenerator * U_EXPORT2
162udatpg_open(const char *locale, UErrorCode *pErrorCode);
163
164/**
165 * Open an empty generator, to be constructed with udatpg_addPattern(...) etc.
166 * @param pErrorCode a pointer to the UErrorCode which must not indicate a
167 * failure before the function call.
168 * @return a pointer to UDateTimePatternGenerator.
169 * @stable ICU 3.8
170 */
171U_STABLE UDateTimePatternGenerator * U_EXPORT2
172udatpg_openEmpty(UErrorCode *pErrorCode);
173
174/**
175 * Close a generator.
176 * @param dtpg a pointer to UDateTimePatternGenerator.
177 * @stable ICU 3.8
178 */
179U_STABLE void U_EXPORT2
180udatpg_close(UDateTimePatternGenerator *dtpg);
181
182#if U_SHOW_CPLUSPLUS_API
183
184U_NAMESPACE_BEGIN
185
186/**
187 * \class LocalUDateTimePatternGeneratorPointer
188 * "Smart pointer" class, closes a UDateTimePatternGenerator via udatpg_close().
189 * For most methods see the LocalPointerBase base class.
190 *
191 * @see LocalPointerBase
192 * @see LocalPointer
193 * @stable ICU 4.4
194 */
195U_DEFINE_LOCAL_OPEN_POINTER(LocalUDateTimePatternGeneratorPointer, UDateTimePatternGenerator, udatpg_close);
196
197U_NAMESPACE_END
198
199#endif
200
201/**
202 * Create a copy pf a generator.
203 * @param dtpg a pointer to UDateTimePatternGenerator to be copied.
204 * @param pErrorCode a pointer to the UErrorCode which must not indicate a
205 * failure before the function call.
206 * @return a pointer to a new UDateTimePatternGenerator.
207 * @stable ICU 3.8
208 */
209U_STABLE UDateTimePatternGenerator * U_EXPORT2
210udatpg_clone(const UDateTimePatternGenerator *dtpg, UErrorCode *pErrorCode);
211
212/**
213 * Get the best pattern matching the input skeleton. It is guaranteed to
214 * have all of the fields in the skeleton.
215 *
216 * Note that this function uses a non-const UDateTimePatternGenerator:
217 * It uses a stateful pattern parser which is set up for each generator object,
218 * rather than creating one for each function call.
219 * Consecutive calls to this function do not affect each other,
220 * but this function cannot be used concurrently on a single generator object.
221 *
222 * @param dtpg a pointer to UDateTimePatternGenerator.
223 * @param skeleton
224 * The skeleton is a pattern containing only the variable fields.
225 * For example, "MMMdd" and "mmhh" are skeletons.
226 * @param length the length of skeleton
227 * @param bestPattern
228 * The best pattern found from the given skeleton.
229 * @param capacity the capacity of bestPattern.
230 * @param pErrorCode a pointer to the UErrorCode which must not indicate a
231 * failure before the function call.
232 * @return the length of bestPattern.
233 * @stable ICU 3.8
234 */
235U_STABLE int32_t U_EXPORT2
236udatpg_getBestPattern(UDateTimePatternGenerator *dtpg,
237 const UChar *skeleton, int32_t length,
238 UChar *bestPattern, int32_t capacity,
239 UErrorCode *pErrorCode);
240
241/**
242 * Get the best pattern matching the input skeleton. It is guaranteed to
243 * have all of the fields in the skeleton.
244 *
245 * Note that this function uses a non-const UDateTimePatternGenerator:
246 * It uses a stateful pattern parser which is set up for each generator object,
247 * rather than creating one for each function call.
248 * Consecutive calls to this function do not affect each other,
249 * but this function cannot be used concurrently on a single generator object.
250 *
251 * @param dtpg a pointer to UDateTimePatternGenerator.
252 * @param skeleton
253 * The skeleton is a pattern containing only the variable fields.
254 * For example, "MMMdd" and "mmhh" are skeletons.
255 * @param length the length of skeleton
256 * @param options
257 * Options for forcing the length of specified fields in the
258 * returned pattern to match those in the skeleton (when this
259 * would not happen otherwise). For default behavior, use
260 * UDATPG_MATCH_NO_OPTIONS.
261 * @param bestPattern
262 * The best pattern found from the given skeleton.
263 * @param capacity
264 * the capacity of bestPattern.
265 * @param pErrorCode
266 * a pointer to the UErrorCode which must not indicate a
267 * failure before the function call.
268 * @return the length of bestPattern.
269 * @stable ICU 4.4
270 */
271U_STABLE int32_t U_EXPORT2
272udatpg_getBestPatternWithOptions(UDateTimePatternGenerator *dtpg,
273 const UChar *skeleton, int32_t length,
274 UDateTimePatternMatchOptions options,
275 UChar *bestPattern, int32_t capacity,
276 UErrorCode *pErrorCode);
277
278/**
279 * Get a unique skeleton from a given pattern. For example,
280 * both "MMM-dd" and "dd/MMM" produce the skeleton "MMMdd".
281 *
282 * Note that this function uses a non-const UDateTimePatternGenerator:
283 * It uses a stateful pattern parser which is set up for each generator object,
284 * rather than creating one for each function call.
285 * Consecutive calls to this function do not affect each other,
286 * but this function cannot be used concurrently on a single generator object.
287 *
288 * @param unusedDtpg a pointer to UDateTimePatternGenerator.
289 * This parameter is no longer used. Callers may pass NULL.
290 * @param pattern input pattern, such as "dd/MMM".
291 * @param length the length of pattern.
292 * @param skeleton such as "MMMdd"
293 * @param capacity the capacity of skeleton.
294 * @param pErrorCode a pointer to the UErrorCode which must not indicate a
295 * failure before the function call.
296 * @return the length of skeleton.
297 * @stable ICU 3.8
298 */
299U_STABLE int32_t U_EXPORT2
300udatpg_getSkeleton(UDateTimePatternGenerator *unusedDtpg,
301 const UChar *pattern, int32_t length,
302 UChar *skeleton, int32_t capacity,
303 UErrorCode *pErrorCode);
304
305/**
306 * Get a unique base skeleton from a given pattern. This is the same
307 * as the skeleton, except that differences in length are minimized so
308 * as to only preserve the difference between string and numeric form. So
309 * for example, both "MMM-dd" and "d/MMM" produce the skeleton "MMMd"
310 * (notice the single d).
311 *
312 * Note that this function uses a non-const UDateTimePatternGenerator:
313 * It uses a stateful pattern parser which is set up for each generator object,
314 * rather than creating one for each function call.
315 * Consecutive calls to this function do not affect each other,
316 * but this function cannot be used concurrently on a single generator object.
317 *
318 * @param unusedDtpg a pointer to UDateTimePatternGenerator.
319 * This parameter is no longer used. Callers may pass NULL.
320 * @param pattern input pattern, such as "dd/MMM".
321 * @param length the length of pattern.
322 * @param baseSkeleton such as "Md"
323 * @param capacity the capacity of base skeleton.
324 * @param pErrorCode a pointer to the UErrorCode which must not indicate a
325 * failure before the function call.
326 * @return the length of baseSkeleton.
327 * @stable ICU 3.8
328 */
329U_STABLE int32_t U_EXPORT2
330udatpg_getBaseSkeleton(UDateTimePatternGenerator *unusedDtpg,
331 const UChar *pattern, int32_t length,
332 UChar *baseSkeleton, int32_t capacity,
333 UErrorCode *pErrorCode);
334
335/**
336 * Adds a pattern to the generator. If the pattern has the same skeleton as
337 * an existing pattern, and the override parameter is set, then the previous
338 * value is overriden. Otherwise, the previous value is retained. In either
339 * case, the conflicting status is set and previous vale is stored in
340 * conflicting pattern.
341 * <p>
342 * Note that single-field patterns (like "MMM") are automatically added, and
343 * don't need to be added explicitly!
344 *
345 * @param dtpg a pointer to UDateTimePatternGenerator.
346 * @param pattern input pattern, such as "dd/MMM"
347 * @param patternLength the length of pattern.
348 * @param override When existing values are to be overridden use true,
349 * otherwise use false.
350 * @param conflictingPattern Previous pattern with the same skeleton.
351 * @param capacity the capacity of conflictingPattern.
352 * @param pLength a pointer to the length of conflictingPattern.
353 * @param pErrorCode a pointer to the UErrorCode which must not indicate a
354 * failure before the function call.
355 * @return conflicting status. The value could be UDATPG_NO_CONFLICT,
356 * UDATPG_BASE_CONFLICT or UDATPG_CONFLICT.
357 * @stable ICU 3.8
358 */
359U_STABLE UDateTimePatternConflict U_EXPORT2
360udatpg_addPattern(UDateTimePatternGenerator *dtpg,
361 const UChar *pattern, int32_t patternLength,
362 UBool override,
363 UChar *conflictingPattern, int32_t capacity, int32_t *pLength,
364 UErrorCode *pErrorCode);
365
366/**
367 * An AppendItem format is a pattern used to append a field if there is no
368 * good match. For example, suppose that the input skeleton is "GyyyyMMMd",
369 * and there is no matching pattern internally, but there is a pattern
370 * matching "yyyyMMMd", say "d-MM-yyyy". Then that pattern is used, plus the
371 * G. The way these two are conjoined is by using the AppendItemFormat for G
372 * (era). So if that value is, say "{0}, {1}" then the final resulting
373 * pattern is "d-MM-yyyy, G".
374 * <p>
375 * There are actually three available variables: {0} is the pattern so far,
376 * {1} is the element we are adding, and {2} is the name of the element.
377 * <p>
378 * This reflects the way that the CLDR data is organized.
379 *
380 * @param dtpg a pointer to UDateTimePatternGenerator.
381 * @param field UDateTimePatternField, such as UDATPG_ERA_FIELD
382 * @param value pattern, such as "{0}, {1}"
383 * @param length the length of value.
384 * @stable ICU 3.8
385 */
386U_STABLE void U_EXPORT2
387udatpg_setAppendItemFormat(UDateTimePatternGenerator *dtpg,
388 UDateTimePatternField field,
389 const UChar *value, int32_t length);
390
391/**
392 * Getter corresponding to setAppendItemFormat. Values below 0 or at or
393 * above UDATPG_FIELD_COUNT are illegal arguments.
394 *
395 * @param dtpg A pointer to UDateTimePatternGenerator.
396 * @param field UDateTimePatternField, such as UDATPG_ERA_FIELD
397 * @param pLength A pointer that will receive the length of appendItemFormat.
398 * @return appendItemFormat for field.
399 * @stable ICU 3.8
400 */
401U_STABLE const UChar * U_EXPORT2
402udatpg_getAppendItemFormat(const UDateTimePatternGenerator *dtpg,
403 UDateTimePatternField field,
404 int32_t *pLength);
405
406/**
407 * Set the name of field, eg "era" in English for ERA. These are only
408 * used if the corresponding AppendItemFormat is used, and if it contains a
409 * {2} variable.
410 * <p>
411 * This reflects the way that the CLDR data is organized.
412 *
413 * @param dtpg a pointer to UDateTimePatternGenerator.
414 * @param field UDateTimePatternField
415 * @param value name for the field.
416 * @param length the length of value.
417 * @stable ICU 3.8
418 */
419U_STABLE void U_EXPORT2
420udatpg_setAppendItemName(UDateTimePatternGenerator *dtpg,
421 UDateTimePatternField field,
422 const UChar *value, int32_t length);
423
424/**
425 * Getter corresponding to setAppendItemNames. Values below 0 or at or above
426 * UDATPG_FIELD_COUNT are illegal arguments. Note: The more general function
427 * for getting date/time field display names is udatpg_getFieldDisplayName.
428 *
429 * @param dtpg a pointer to UDateTimePatternGenerator.
430 * @param field UDateTimePatternField, such as UDATPG_ERA_FIELD
431 * @param pLength A pointer that will receive the length of the name for field.
432 * @return name for field
433 * @see udatpg_getFieldDisplayName
434 * @stable ICU 3.8
435 */
436U_STABLE const UChar * U_EXPORT2
437udatpg_getAppendItemName(const UDateTimePatternGenerator *dtpg,
438 UDateTimePatternField field,
439 int32_t *pLength);
440
441/**
442 * The general interface to get a display name for a particular date/time field,
443 * in one of several possible display widths.
444 *
445 * @param dtpg
446 * A pointer to the UDateTimePatternGenerator object with the localized
447 * display names.
448 * @param field
449 * The desired UDateTimePatternField, such as UDATPG_ERA_FIELD.
450 * @param width
451 * The desired UDateTimePGDisplayWidth, such as UDATPG_ABBREVIATED.
452 * @param fieldName
453 * A pointer to a buffer to receive the NULL-terminated display name. If the name
454 * fits into fieldName but cannot be NULL-terminated (length == capacity) then
455 * the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the name doesn't
456 * fit into fieldName then the error code is set to U_BUFFER_OVERFLOW_ERROR.
457 * @param capacity
458 * The size of fieldName (in UChars).
459 * @param pErrorCode
460 * A pointer to a UErrorCode to receive any errors
461 * @return
462 * The full length of the name; if greater than capacity, fieldName contains a
463 * truncated result.
464 * @stable ICU 61
465 */
466U_STABLE int32_t U_EXPORT2
467udatpg_getFieldDisplayName(const UDateTimePatternGenerator *dtpg,
468 UDateTimePatternField field,
469 UDateTimePGDisplayWidth width,
470 UChar *fieldName, int32_t capacity,
471 UErrorCode *pErrorCode);
472
473/**
474 * The DateTimeFormat is a message format pattern used to compose date and
475 * time patterns. The default pattern in the root locale is "{1} {0}", where
476 * {1} will be replaced by the date pattern and {0} will be replaced by the
477 * time pattern; however, other locales may specify patterns such as
478 * "{1}, {0}" or "{1} 'at' {0}", etc.
479 * <p>
480 * This is used when the input skeleton contains both date and time fields,
481 * but there is not a close match among the added patterns. For example,
482 * suppose that this object was created by adding "dd-MMM" and "hh:mm", and
483 * its DateTimeFormat is the default "{1} {0}". Then if the input skeleton
484 * is "MMMdhmm", there is not an exact match, so the input skeleton is
485 * broken up into two components "MMMd" and "hmm". There are close matches
486 * for those two skeletons, so the result is put together with this pattern,
487 * resulting in "d-MMM h:mm".
488 *
489 * @param dtpg a pointer to UDateTimePatternGenerator.
490 * @param dtFormat
491 * message format pattern, here {1} will be replaced by the date
492 * pattern and {0} will be replaced by the time pattern.
493 * @param length the length of dtFormat.
494 * @stable ICU 3.8
495 */
496U_STABLE void U_EXPORT2
497udatpg_setDateTimeFormat(const UDateTimePatternGenerator *dtpg,
498 const UChar *dtFormat, int32_t length);
499
500/**
501 * Getter corresponding to setDateTimeFormat.
502 * @param dtpg a pointer to UDateTimePatternGenerator.
503 * @param pLength A pointer that will receive the length of the format
504 * @return dateTimeFormat.
505 * @stable ICU 3.8
506 */
507U_STABLE const UChar * U_EXPORT2
508udatpg_getDateTimeFormat(const UDateTimePatternGenerator *dtpg,
509 int32_t *pLength);
510
511/**
512 * The decimal value is used in formatting fractions of seconds. If the
513 * skeleton contains fractional seconds, then this is used with the
514 * fractional seconds. For example, suppose that the input pattern is
515 * "hhmmssSSSS", and the best matching pattern internally is "H:mm:ss", and
516 * the decimal string is ",". Then the resulting pattern is modified to be
517 * "H:mm:ss,SSSS"
518 *
519 * @param dtpg a pointer to UDateTimePatternGenerator.
520 * @param decimal
521 * @param length the length of decimal.
522 * @stable ICU 3.8
523 */
524U_STABLE void U_EXPORT2
525udatpg_setDecimal(UDateTimePatternGenerator *dtpg,
526 const UChar *decimal, int32_t length);
527
528/**
529 * Getter corresponding to setDecimal.
530 *
531 * @param dtpg a pointer to UDateTimePatternGenerator.
532 * @param pLength A pointer that will receive the length of the decimal string.
533 * @return corresponding to the decimal point.
534 * @stable ICU 3.8
535 */
536U_STABLE const UChar * U_EXPORT2
537udatpg_getDecimal(const UDateTimePatternGenerator *dtpg,
538 int32_t *pLength);
539
540/**
541 * Adjusts the field types (width and subtype) of a pattern to match what is
542 * in a skeleton. That is, if you supply a pattern like "d-M H:m", and a
543 * skeleton of "MMMMddhhmm", then the input pattern is adjusted to be
544 * "dd-MMMM hh:mm". This is used internally to get the best match for the
545 * input skeleton, but can also be used externally.
546 *
547 * Note that this function uses a non-const UDateTimePatternGenerator:
548 * It uses a stateful pattern parser which is set up for each generator object,
549 * rather than creating one for each function call.
550 * Consecutive calls to this function do not affect each other,
551 * but this function cannot be used concurrently on a single generator object.
552 *
553 * @param dtpg a pointer to UDateTimePatternGenerator.
554 * @param pattern Input pattern
555 * @param patternLength the length of input pattern.
556 * @param skeleton
557 * @param skeletonLength the length of input skeleton.
558 * @param dest pattern adjusted to match the skeleton fields widths and subtypes.
559 * @param destCapacity the capacity of dest.
560 * @param pErrorCode a pointer to the UErrorCode which must not indicate a
561 * failure before the function call.
562 * @return the length of dest.
563 * @stable ICU 3.8
564 */
565U_STABLE int32_t U_EXPORT2
566udatpg_replaceFieldTypes(UDateTimePatternGenerator *dtpg,
567 const UChar *pattern, int32_t patternLength,
568 const UChar *skeleton, int32_t skeletonLength,
569 UChar *dest, int32_t destCapacity,
570 UErrorCode *pErrorCode);
571
572/**
573 * Adjusts the field types (width and subtype) of a pattern to match what is
574 * in a skeleton. That is, if you supply a pattern like "d-M H:m", and a
575 * skeleton of "MMMMddhhmm", then the input pattern is adjusted to be
576 * "dd-MMMM hh:mm". This is used internally to get the best match for the
577 * input skeleton, but can also be used externally.
578 *
579 * Note that this function uses a non-const UDateTimePatternGenerator:
580 * It uses a stateful pattern parser which is set up for each generator object,
581 * rather than creating one for each function call.
582 * Consecutive calls to this function do not affect each other,
583 * but this function cannot be used concurrently on a single generator object.
584 *
585 * @param dtpg a pointer to UDateTimePatternGenerator.
586 * @param pattern Input pattern
587 * @param patternLength the length of input pattern.
588 * @param skeleton
589 * @param skeletonLength the length of input skeleton.
590 * @param options
591 * Options controlling whether the length of specified fields in the
592 * pattern are adjusted to match those in the skeleton (when this
593 * would not happen otherwise). For default behavior, use
594 * UDATPG_MATCH_NO_OPTIONS.
595 * @param dest pattern adjusted to match the skeleton fields widths and subtypes.
596 * @param destCapacity the capacity of dest.
597 * @param pErrorCode a pointer to the UErrorCode which must not indicate a
598 * failure before the function call.
599 * @return the length of dest.
600 * @stable ICU 4.4
601 */
602U_STABLE int32_t U_EXPORT2
603udatpg_replaceFieldTypesWithOptions(UDateTimePatternGenerator *dtpg,
604 const UChar *pattern, int32_t patternLength,
605 const UChar *skeleton, int32_t skeletonLength,
606 UDateTimePatternMatchOptions options,
607 UChar *dest, int32_t destCapacity,
608 UErrorCode *pErrorCode);
609
610/**
611 * Return a UEnumeration list of all the skeletons in canonical form.
612 * Call udatpg_getPatternForSkeleton() to get the corresponding pattern.
613 *
614 * @param dtpg a pointer to UDateTimePatternGenerator.
615 * @param pErrorCode a pointer to the UErrorCode which must not indicate a
616 * failure before the function call
617 * @return a UEnumeration list of all the skeletons
618 * The caller must close the object.
619 * @stable ICU 3.8
620 */
621U_STABLE UEnumeration * U_EXPORT2
622udatpg_openSkeletons(const UDateTimePatternGenerator *dtpg, UErrorCode *pErrorCode);
623
624/**
625 * Return a UEnumeration list of all the base skeletons in canonical form.
626 *
627 * @param dtpg a pointer to UDateTimePatternGenerator.
628 * @param pErrorCode a pointer to the UErrorCode which must not indicate a
629 * failure before the function call.
630 * @return a UEnumeration list of all the base skeletons
631 * The caller must close the object.
632 * @stable ICU 3.8
633 */
634U_STABLE UEnumeration * U_EXPORT2
635udatpg_openBaseSkeletons(const UDateTimePatternGenerator *dtpg, UErrorCode *pErrorCode);
636
637/**
638 * Get the pattern corresponding to a given skeleton.
639 *
640 * @param dtpg a pointer to UDateTimePatternGenerator.
641 * @param skeleton
642 * @param skeletonLength pointer to the length of skeleton.
643 * @param pLength pointer to the length of return pattern.
644 * @return pattern corresponding to a given skeleton.
645 * @stable ICU 3.8
646 */
647U_STABLE const UChar * U_EXPORT2
648udatpg_getPatternForSkeleton(const UDateTimePatternGenerator *dtpg,
649 const UChar *skeleton, int32_t skeletonLength,
650 int32_t *pLength);
651
652#endif
653