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