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#ifndef U_FORCE_HIDE_DEPRECATED_API
92 /**
93 * One more than the highest normal UDateTimePatternField value.
94 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
95 */
96 UDATPG_FIELD_COUNT
97#endif // U_FORCE_HIDE_DEPRECATED_API
98} UDateTimePatternField;
99
100/**
101 * Field display name width constants for udatpg_getFieldDisplayName().
102 * @stable ICU 61
103 */
104typedef enum UDateTimePGDisplayWidth {
105 /** @stable ICU 61 */
106 UDATPG_WIDE,
107 /** @stable ICU 61 */
108 UDATPG_ABBREVIATED,
109 /** @stable ICU 61 */
110 UDATPG_NARROW
111} UDateTimePGDisplayWidth;
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/**
444 * The general interface to get a display name for a particular date/time field,
445 * in one of several possible display widths.
446 *
447 * @param dtpg
448 * A pointer to the UDateTimePatternGenerator object with the localized
449 * display names.
450 * @param field
451 * The desired UDateTimePatternField, such as UDATPG_ERA_FIELD.
452 * @param width
453 * The desired UDateTimePGDisplayWidth, such as UDATPG_ABBREVIATED.
454 * @param fieldName
455 * A pointer to a buffer to receive the NULL-terminated display name. If the name
456 * fits into fieldName but cannot be NULL-terminated (length == capacity) then
457 * the error code is set to U_STRING_NOT_TERMINATED_WARNING. If the name doesn't
458 * fit into fieldName then the error code is set to U_BUFFER_OVERFLOW_ERROR.
459 * @param capacity
460 * The size of fieldName (in UChars).
461 * @param pErrorCode
462 * A pointer to a UErrorCode to receive any errors
463 * @return
464 * The full length of the name; if greater than capacity, fieldName contains a
465 * truncated result.
466 * @stable ICU 61
467 */
468U_STABLE int32_t U_EXPORT2
469udatpg_getFieldDisplayName(const UDateTimePatternGenerator *dtpg,
470 UDateTimePatternField field,
471 UDateTimePGDisplayWidth width,
472 UChar *fieldName, int32_t capacity,
473 UErrorCode *pErrorCode);
474
475/**
476 * The DateTimeFormat is a message format pattern used to compose date and
477 * time patterns. The default pattern in the root locale is "{1} {0}", where
478 * {1} will be replaced by the date pattern and {0} will be replaced by the
479 * time pattern; however, other locales may specify patterns such as
480 * "{1}, {0}" or "{1} 'at' {0}", etc.
481 * <p>
482 * This is used when the input skeleton contains both date and time fields,
483 * but there is not a close match among the added patterns. For example,
484 * suppose that this object was created by adding "dd-MMM" and "hh:mm", and
485 * its DateTimeFormat is the default "{1} {0}". Then if the input skeleton
486 * is "MMMdhmm", there is not an exact match, so the input skeleton is
487 * broken up into two components "MMMd" and "hmm". There are close matches
488 * for those two skeletons, so the result is put together with this pattern,
489 * resulting in "d-MMM h:mm".
490 *
491 * @param dtpg a pointer to UDateTimePatternGenerator.
492 * @param dtFormat
493 * message format pattern, here {1} will be replaced by the date
494 * pattern and {0} will be replaced by the time pattern.
495 * @param length the length of dtFormat.
496 * @stable ICU 3.8
497 */
498U_STABLE void U_EXPORT2
499udatpg_setDateTimeFormat(const UDateTimePatternGenerator *dtpg,
500 const UChar *dtFormat, int32_t length);
501
502/**
503 * Getter corresponding to setDateTimeFormat.
504 * @param dtpg a pointer to UDateTimePatternGenerator.
505 * @param pLength A pointer that will receive the length of the format
506 * @return dateTimeFormat.
507 * @stable ICU 3.8
508 */
509U_STABLE const UChar * U_EXPORT2
510udatpg_getDateTimeFormat(const UDateTimePatternGenerator *dtpg,
511 int32_t *pLength);
512
513/**
514 * The decimal value is used in formatting fractions of seconds. If the
515 * skeleton contains fractional seconds, then this is used with the
516 * fractional seconds. For example, suppose that the input pattern is
517 * "hhmmssSSSS", and the best matching pattern internally is "H:mm:ss", and
518 * the decimal string is ",". Then the resulting pattern is modified to be
519 * "H:mm:ss,SSSS"
520 *
521 * @param dtpg a pointer to UDateTimePatternGenerator.
522 * @param decimal
523 * @param length the length of decimal.
524 * @stable ICU 3.8
525 */
526U_STABLE void U_EXPORT2
527udatpg_setDecimal(UDateTimePatternGenerator *dtpg,
528 const UChar *decimal, int32_t length);
529
530/**
531 * Getter corresponding to setDecimal.
532 *
533 * @param dtpg a pointer to UDateTimePatternGenerator.
534 * @param pLength A pointer that will receive the length of the decimal string.
535 * @return corresponding to the decimal point.
536 * @stable ICU 3.8
537 */
538U_STABLE const UChar * U_EXPORT2
539udatpg_getDecimal(const UDateTimePatternGenerator *dtpg,
540 int32_t *pLength);
541
542/**
543 * Adjusts the field types (width and subtype) of a pattern to match what is
544 * in a skeleton. That is, if you supply a pattern like "d-M H:m", and a
545 * skeleton of "MMMMddhhmm", then the input pattern is adjusted to be
546 * "dd-MMMM hh:mm". This is used internally to get the best match for the
547 * input skeleton, but can also be used externally.
548 *
549 * Note that this function uses a non-const UDateTimePatternGenerator:
550 * It uses a stateful pattern parser which is set up for each generator object,
551 * rather than creating one for each function call.
552 * Consecutive calls to this function do not affect each other,
553 * but this function cannot be used concurrently on a single generator object.
554 *
555 * @param dtpg a pointer to UDateTimePatternGenerator.
556 * @param pattern Input pattern
557 * @param patternLength the length of input pattern.
558 * @param skeleton
559 * @param skeletonLength the length of input skeleton.
560 * @param dest pattern adjusted to match the skeleton fields widths and subtypes.
561 * @param destCapacity the capacity of dest.
562 * @param pErrorCode a pointer to the UErrorCode which must not indicate a
563 * failure before the function call.
564 * @return the length of dest.
565 * @stable ICU 3.8
566 */
567U_STABLE int32_t U_EXPORT2
568udatpg_replaceFieldTypes(UDateTimePatternGenerator *dtpg,
569 const UChar *pattern, int32_t patternLength,
570 const UChar *skeleton, int32_t skeletonLength,
571 UChar *dest, int32_t destCapacity,
572 UErrorCode *pErrorCode);
573
574/**
575 * Adjusts the field types (width and subtype) of a pattern to match what is
576 * in a skeleton. That is, if you supply a pattern like "d-M H:m", and a
577 * skeleton of "MMMMddhhmm", then the input pattern is adjusted to be
578 * "dd-MMMM hh:mm". This is used internally to get the best match for the
579 * input skeleton, but can also be used externally.
580 *
581 * Note that this function uses a non-const UDateTimePatternGenerator:
582 * It uses a stateful pattern parser which is set up for each generator object,
583 * rather than creating one for each function call.
584 * Consecutive calls to this function do not affect each other,
585 * but this function cannot be used concurrently on a single generator object.
586 *
587 * @param dtpg a pointer to UDateTimePatternGenerator.
588 * @param pattern Input pattern
589 * @param patternLength the length of input pattern.
590 * @param skeleton
591 * @param skeletonLength the length of input skeleton.
592 * @param options
593 * Options controlling whether the length of specified fields in the
594 * pattern are adjusted to match those in the skeleton (when this
595 * would not happen otherwise). For default behavior, use
596 * UDATPG_MATCH_NO_OPTIONS.
597 * @param dest pattern adjusted to match the skeleton fields widths and subtypes.
598 * @param destCapacity the capacity of dest.
599 * @param pErrorCode a pointer to the UErrorCode which must not indicate a
600 * failure before the function call.
601 * @return the length of dest.
602 * @stable ICU 4.4
603 */
604U_STABLE int32_t U_EXPORT2
605udatpg_replaceFieldTypesWithOptions(UDateTimePatternGenerator *dtpg,
606 const UChar *pattern, int32_t patternLength,
607 const UChar *skeleton, int32_t skeletonLength,
608 UDateTimePatternMatchOptions options,
609 UChar *dest, int32_t destCapacity,
610 UErrorCode *pErrorCode);
611
612/**
613 * Return a UEnumeration list of all the skeletons in canonical form.
614 * Call udatpg_getPatternForSkeleton() to get the corresponding pattern.
615 *
616 * @param dtpg a pointer to UDateTimePatternGenerator.
617 * @param pErrorCode a pointer to the UErrorCode which must not indicate a
618 * failure before the function call
619 * @return a UEnumeration list of all the skeletons
620 * The caller must close the object.
621 * @stable ICU 3.8
622 */
623U_STABLE UEnumeration * U_EXPORT2
624udatpg_openSkeletons(const UDateTimePatternGenerator *dtpg, UErrorCode *pErrorCode);
625
626/**
627 * Return a UEnumeration list of all the base skeletons in canonical form.
628 *
629 * @param dtpg a pointer to UDateTimePatternGenerator.
630 * @param pErrorCode a pointer to the UErrorCode which must not indicate a
631 * failure before the function call.
632 * @return a UEnumeration list of all the base skeletons
633 * The caller must close the object.
634 * @stable ICU 3.8
635 */
636U_STABLE UEnumeration * U_EXPORT2
637udatpg_openBaseSkeletons(const UDateTimePatternGenerator *dtpg, UErrorCode *pErrorCode);
638
639/**
640 * Get the pattern corresponding to a given skeleton.
641 *
642 * @param dtpg a pointer to UDateTimePatternGenerator.
643 * @param skeleton
644 * @param skeletonLength pointer to the length of skeleton.
645 * @param pLength pointer to the length of return pattern.
646 * @return pattern corresponding to a given skeleton.
647 * @stable ICU 3.8
648 */
649U_STABLE const UChar * U_EXPORT2
650udatpg_getPatternForSkeleton(const UDateTimePatternGenerator *dtpg,
651 const UChar *skeleton, int32_t skeletonLength,
652 int32_t *pLength);
653
654#endif
655