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