1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/i18n/unicode/udatpg.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,588 @@
1.4 +/*
1.5 +*******************************************************************************
1.6 +*
1.7 +* Copyright (C) 2007-2012, International Business Machines
1.8 +* Corporation and others. All Rights Reserved.
1.9 +*
1.10 +*******************************************************************************
1.11 +* file name: udatpg.h
1.12 +* encoding: US-ASCII
1.13 +* tab size: 8 (not used)
1.14 +* indentation:4
1.15 +*
1.16 +* created on: 2007jul30
1.17 +* created by: Markus W. Scherer
1.18 +*/
1.19 +
1.20 +#ifndef __UDATPG_H__
1.21 +#define __UDATPG_H__
1.22 +
1.23 +#include "unicode/utypes.h"
1.24 +#include "unicode/uenum.h"
1.25 +#include "unicode/localpointer.h"
1.26 +
1.27 +/**
1.28 + * \file
1.29 + * \brief C API: Wrapper for icu::DateTimePatternGenerator (unicode/dtptngen.h).
1.30 + *
1.31 + * UDateTimePatternGenerator provides flexible generation of date format patterns,
1.32 + * like "yy-MM-dd". The user can build up the generator by adding successive
1.33 + * patterns. Once that is done, a query can be made using a "skeleton", which is
1.34 + * a pattern which just includes the desired fields and lengths. The generator
1.35 + * will return the "best fit" pattern corresponding to that skeleton.
1.36 + * <p>The main method people will use is udatpg_getBestPattern, since normally
1.37 + * UDateTimePatternGenerator is pre-built with data from a particular locale.
1.38 + * However, generators can be built directly from other data as well.
1.39 + * <p><i>Issue: may be useful to also have a function that returns the list of
1.40 + * fields in a pattern, in order, since we have that internally.
1.41 + * That would be useful for getting the UI order of field elements.</i>
1.42 + */
1.43 +
1.44 +/**
1.45 + * Opaque type for a date/time pattern generator object.
1.46 + * @stable ICU 3.8
1.47 + */
1.48 +typedef void *UDateTimePatternGenerator;
1.49 +
1.50 +/**
1.51 + * Field number constants for udatpg_getAppendItemFormats() and similar functions.
1.52 + * These constants are separate from UDateFormatField despite semantic overlap
1.53 + * because some fields are merged for the date/time pattern generator.
1.54 + * @stable ICU 3.8
1.55 + */
1.56 +typedef enum UDateTimePatternField {
1.57 + /** @stable ICU 3.8 */
1.58 + UDATPG_ERA_FIELD,
1.59 + /** @stable ICU 3.8 */
1.60 + UDATPG_YEAR_FIELD,
1.61 + /** @stable ICU 3.8 */
1.62 + UDATPG_QUARTER_FIELD,
1.63 + /** @stable ICU 3.8 */
1.64 + UDATPG_MONTH_FIELD,
1.65 + /** @stable ICU 3.8 */
1.66 + UDATPG_WEEK_OF_YEAR_FIELD,
1.67 + /** @stable ICU 3.8 */
1.68 + UDATPG_WEEK_OF_MONTH_FIELD,
1.69 + /** @stable ICU 3.8 */
1.70 + UDATPG_WEEKDAY_FIELD,
1.71 + /** @stable ICU 3.8 */
1.72 + UDATPG_DAY_OF_YEAR_FIELD,
1.73 + /** @stable ICU 3.8 */
1.74 + UDATPG_DAY_OF_WEEK_IN_MONTH_FIELD,
1.75 + /** @stable ICU 3.8 */
1.76 + UDATPG_DAY_FIELD,
1.77 + /** @stable ICU 3.8 */
1.78 + UDATPG_DAYPERIOD_FIELD,
1.79 + /** @stable ICU 3.8 */
1.80 + UDATPG_HOUR_FIELD,
1.81 + /** @stable ICU 3.8 */
1.82 + UDATPG_MINUTE_FIELD,
1.83 + /** @stable ICU 3.8 */
1.84 + UDATPG_SECOND_FIELD,
1.85 + /** @stable ICU 3.8 */
1.86 + UDATPG_FRACTIONAL_SECOND_FIELD,
1.87 + /** @stable ICU 3.8 */
1.88 + UDATPG_ZONE_FIELD,
1.89 + /** @stable ICU 3.8 */
1.90 + UDATPG_FIELD_COUNT
1.91 +} UDateTimePatternField;
1.92 +
1.93 +/**
1.94 + * Masks to control forcing the length of specified fields in the returned
1.95 + * pattern to match those in the skeleton (when this would not happen
1.96 + * otherwise). These may be combined to force the length of multiple fields.
1.97 + * Used with udatpg_getBestPatternWithOptions, udatpg_replaceFieldTypesWithOptions.
1.98 + * @stable ICU 4.4
1.99 + */
1.100 +typedef enum UDateTimePatternMatchOptions {
1.101 + /** @stable ICU 4.4 */
1.102 + UDATPG_MATCH_NO_OPTIONS = 0,
1.103 + /** @stable ICU 4.4 */
1.104 + UDATPG_MATCH_HOUR_FIELD_LENGTH = 1 << UDATPG_HOUR_FIELD,
1.105 +#ifndef U_HIDE_INTERNAL_API
1.106 + /** @internal ICU 4.4 */
1.107 + UDATPG_MATCH_MINUTE_FIELD_LENGTH = 1 << UDATPG_MINUTE_FIELD,
1.108 + /** @internal ICU 4.4 */
1.109 + UDATPG_MATCH_SECOND_FIELD_LENGTH = 1 << UDATPG_SECOND_FIELD,
1.110 +#endif /* U_HIDE_INTERNAL_API */
1.111 + /** @stable ICU 4.4 */
1.112 + UDATPG_MATCH_ALL_FIELDS_LENGTH = (1 << UDATPG_FIELD_COUNT) - 1
1.113 +} UDateTimePatternMatchOptions;
1.114 +
1.115 +/**
1.116 + * Status return values from udatpg_addPattern().
1.117 + * @stable ICU 3.8
1.118 + */
1.119 +typedef enum UDateTimePatternConflict {
1.120 + /** @stable ICU 3.8 */
1.121 + UDATPG_NO_CONFLICT,
1.122 + /** @stable ICU 3.8 */
1.123 + UDATPG_BASE_CONFLICT,
1.124 + /** @stable ICU 3.8 */
1.125 + UDATPG_CONFLICT,
1.126 + /** @stable ICU 3.8 */
1.127 + UDATPG_CONFLICT_COUNT
1.128 +} UDateTimePatternConflict;
1.129 +
1.130 +/**
1.131 + * Open a generator according to a given locale.
1.132 + * @param locale
1.133 + * @param pErrorCode a pointer to the UErrorCode which must not indicate a
1.134 + * failure before the function call.
1.135 + * @return a pointer to UDateTimePatternGenerator.
1.136 + * @stable ICU 3.8
1.137 + */
1.138 +U_STABLE UDateTimePatternGenerator * U_EXPORT2
1.139 +udatpg_open(const char *locale, UErrorCode *pErrorCode);
1.140 +
1.141 +/**
1.142 + * Open an empty generator, to be constructed with udatpg_addPattern(...) etc.
1.143 + * @param pErrorCode a pointer to the UErrorCode which must not indicate a
1.144 + * failure before the function call.
1.145 + * @return a pointer to UDateTimePatternGenerator.
1.146 + * @stable ICU 3.8
1.147 + */
1.148 +U_STABLE UDateTimePatternGenerator * U_EXPORT2
1.149 +udatpg_openEmpty(UErrorCode *pErrorCode);
1.150 +
1.151 +/**
1.152 + * Close a generator.
1.153 + * @param dtpg a pointer to UDateTimePatternGenerator.
1.154 + * @stable ICU 3.8
1.155 + */
1.156 +U_STABLE void U_EXPORT2
1.157 +udatpg_close(UDateTimePatternGenerator *dtpg);
1.158 +
1.159 +#if U_SHOW_CPLUSPLUS_API
1.160 +
1.161 +U_NAMESPACE_BEGIN
1.162 +
1.163 +/**
1.164 + * \class LocalUDateTimePatternGeneratorPointer
1.165 + * "Smart pointer" class, closes a UDateTimePatternGenerator via udatpg_close().
1.166 + * For most methods see the LocalPointerBase base class.
1.167 + *
1.168 + * @see LocalPointerBase
1.169 + * @see LocalPointer
1.170 + * @stable ICU 4.4
1.171 + */
1.172 +U_DEFINE_LOCAL_OPEN_POINTER(LocalUDateTimePatternGeneratorPointer, UDateTimePatternGenerator, udatpg_close);
1.173 +
1.174 +U_NAMESPACE_END
1.175 +
1.176 +#endif
1.177 +
1.178 +/**
1.179 + * Create a copy pf a generator.
1.180 + * @param dtpg a pointer to UDateTimePatternGenerator to be copied.
1.181 + * @param pErrorCode a pointer to the UErrorCode which must not indicate a
1.182 + * failure before the function call.
1.183 + * @return a pointer to a new UDateTimePatternGenerator.
1.184 + * @stable ICU 3.8
1.185 + */
1.186 +U_STABLE UDateTimePatternGenerator * U_EXPORT2
1.187 +udatpg_clone(const UDateTimePatternGenerator *dtpg, UErrorCode *pErrorCode);
1.188 +
1.189 +/**
1.190 + * Get the best pattern matching the input skeleton. It is guaranteed to
1.191 + * have all of the fields in the skeleton.
1.192 + *
1.193 + * Note that this function uses a non-const UDateTimePatternGenerator:
1.194 + * It uses a stateful pattern parser which is set up for each generator object,
1.195 + * rather than creating one for each function call.
1.196 + * Consecutive calls to this function do not affect each other,
1.197 + * but this function cannot be used concurrently on a single generator object.
1.198 + *
1.199 + * @param dtpg a pointer to UDateTimePatternGenerator.
1.200 + * @param skeleton
1.201 + * The skeleton is a pattern containing only the variable fields.
1.202 + * For example, "MMMdd" and "mmhh" are skeletons.
1.203 + * @param length the length of skeleton
1.204 + * @param bestPattern
1.205 + * The best pattern found from the given skeleton.
1.206 + * @param capacity the capacity of bestPattern.
1.207 + * @param pErrorCode a pointer to the UErrorCode which must not indicate a
1.208 + * failure before the function call.
1.209 + * @return the length of bestPattern.
1.210 + * @stable ICU 3.8
1.211 + */
1.212 +U_STABLE int32_t U_EXPORT2
1.213 +udatpg_getBestPattern(UDateTimePatternGenerator *dtpg,
1.214 + const UChar *skeleton, int32_t length,
1.215 + UChar *bestPattern, int32_t capacity,
1.216 + UErrorCode *pErrorCode);
1.217 +
1.218 +/**
1.219 + * Get the best pattern matching the input skeleton. It is guaranteed to
1.220 + * have all of the fields in the skeleton.
1.221 + *
1.222 + * Note that this function uses a non-const UDateTimePatternGenerator:
1.223 + * It uses a stateful pattern parser which is set up for each generator object,
1.224 + * rather than creating one for each function call.
1.225 + * Consecutive calls to this function do not affect each other,
1.226 + * but this function cannot be used concurrently on a single generator object.
1.227 + *
1.228 + * @param dtpg a pointer to UDateTimePatternGenerator.
1.229 + * @param skeleton
1.230 + * The skeleton is a pattern containing only the variable fields.
1.231 + * For example, "MMMdd" and "mmhh" are skeletons.
1.232 + * @param length the length of skeleton
1.233 + * @param options
1.234 + * Options for forcing the length of specified fields in the
1.235 + * returned pattern to match those in the skeleton (when this
1.236 + * would not happen otherwise). For default behavior, use
1.237 + * UDATPG_MATCH_NO_OPTIONS.
1.238 + * @param bestPattern
1.239 + * The best pattern found from the given skeleton.
1.240 + * @param capacity
1.241 + * the capacity of bestPattern.
1.242 + * @param pErrorCode
1.243 + * a pointer to the UErrorCode which must not indicate a
1.244 + * failure before the function call.
1.245 + * @return the length of bestPattern.
1.246 + * @stable ICU 4.4
1.247 + */
1.248 +U_STABLE int32_t U_EXPORT2
1.249 +udatpg_getBestPatternWithOptions(UDateTimePatternGenerator *dtpg,
1.250 + const UChar *skeleton, int32_t length,
1.251 + UDateTimePatternMatchOptions options,
1.252 + UChar *bestPattern, int32_t capacity,
1.253 + UErrorCode *pErrorCode);
1.254 +
1.255 +/**
1.256 + * Get a unique skeleton from a given pattern. For example,
1.257 + * both "MMM-dd" and "dd/MMM" produce the skeleton "MMMdd".
1.258 + *
1.259 + * Note that this function uses a non-const UDateTimePatternGenerator:
1.260 + * It uses a stateful pattern parser which is set up for each generator object,
1.261 + * rather than creating one for each function call.
1.262 + * Consecutive calls to this function do not affect each other,
1.263 + * but this function cannot be used concurrently on a single generator object.
1.264 + *
1.265 + * @param dtpg a pointer to UDateTimePatternGenerator.
1.266 + * @param pattern input pattern, such as "dd/MMM".
1.267 + * @param length the length of pattern.
1.268 + * @param skeleton such as "MMMdd"
1.269 + * @param capacity the capacity of skeleton.
1.270 + * @param pErrorCode a pointer to the UErrorCode which must not indicate a
1.271 + * failure before the function call.
1.272 + * @return the length of skeleton.
1.273 + * @stable ICU 3.8
1.274 + */
1.275 +U_STABLE int32_t U_EXPORT2
1.276 +udatpg_getSkeleton(UDateTimePatternGenerator *dtpg,
1.277 + const UChar *pattern, int32_t length,
1.278 + UChar *skeleton, int32_t capacity,
1.279 + UErrorCode *pErrorCode);
1.280 +
1.281 +/**
1.282 + * Get a unique base skeleton from a given pattern. This is the same
1.283 + * as the skeleton, except that differences in length are minimized so
1.284 + * as to only preserve the difference between string and numeric form. So
1.285 + * for example, both "MMM-dd" and "d/MMM" produce the skeleton "MMMd"
1.286 + * (notice the single d).
1.287 + *
1.288 + * Note that this function uses a non-const UDateTimePatternGenerator:
1.289 + * It uses a stateful pattern parser which is set up for each generator object,
1.290 + * rather than creating one for each function call.
1.291 + * Consecutive calls to this function do not affect each other,
1.292 + * but this function cannot be used concurrently on a single generator object.
1.293 + *
1.294 + * @param dtpg a pointer to UDateTimePatternGenerator.
1.295 + * @param pattern input pattern, such as "dd/MMM".
1.296 + * @param length the length of pattern.
1.297 + * @param baseSkeleton such as "Md"
1.298 + * @param capacity the capacity of base skeleton.
1.299 + * @param pErrorCode a pointer to the UErrorCode which must not indicate a
1.300 + * failure before the function call.
1.301 + * @return the length of baseSkeleton.
1.302 + * @stable ICU 3.8
1.303 + */
1.304 +U_STABLE int32_t U_EXPORT2
1.305 +udatpg_getBaseSkeleton(UDateTimePatternGenerator *dtpg,
1.306 + const UChar *pattern, int32_t length,
1.307 + UChar *baseSkeleton, int32_t capacity,
1.308 + UErrorCode *pErrorCode);
1.309 +
1.310 +/**
1.311 + * Adds a pattern to the generator. If the pattern has the same skeleton as
1.312 + * an existing pattern, and the override parameter is set, then the previous
1.313 + * value is overriden. Otherwise, the previous value is retained. In either
1.314 + * case, the conflicting status is set and previous vale is stored in
1.315 + * conflicting pattern.
1.316 + * <p>
1.317 + * Note that single-field patterns (like "MMM") are automatically added, and
1.318 + * don't need to be added explicitly!
1.319 + *
1.320 + * @param dtpg a pointer to UDateTimePatternGenerator.
1.321 + * @param pattern input pattern, such as "dd/MMM"
1.322 + * @param patternLength the length of pattern.
1.323 + * @param override When existing values are to be overridden use true,
1.324 + * otherwise use false.
1.325 + * @param conflictingPattern Previous pattern with the same skeleton.
1.326 + * @param capacity the capacity of conflictingPattern.
1.327 + * @param pLength a pointer to the length of conflictingPattern.
1.328 + * @param pErrorCode a pointer to the UErrorCode which must not indicate a
1.329 + * failure before the function call.
1.330 + * @return conflicting status. The value could be UDATPG_NO_CONFLICT,
1.331 + * UDATPG_BASE_CONFLICT or UDATPG_CONFLICT.
1.332 + * @stable ICU 3.8
1.333 + */
1.334 +U_STABLE UDateTimePatternConflict U_EXPORT2
1.335 +udatpg_addPattern(UDateTimePatternGenerator *dtpg,
1.336 + const UChar *pattern, int32_t patternLength,
1.337 + UBool override,
1.338 + UChar *conflictingPattern, int32_t capacity, int32_t *pLength,
1.339 + UErrorCode *pErrorCode);
1.340 +
1.341 +/**
1.342 + * An AppendItem format is a pattern used to append a field if there is no
1.343 + * good match. For example, suppose that the input skeleton is "GyyyyMMMd",
1.344 + * and there is no matching pattern internally, but there is a pattern
1.345 + * matching "yyyyMMMd", say "d-MM-yyyy". Then that pattern is used, plus the
1.346 + * G. The way these two are conjoined is by using the AppendItemFormat for G
1.347 + * (era). So if that value is, say "{0}, {1}" then the final resulting
1.348 + * pattern is "d-MM-yyyy, G".
1.349 + * <p>
1.350 + * There are actually three available variables: {0} is the pattern so far,
1.351 + * {1} is the element we are adding, and {2} is the name of the element.
1.352 + * <p>
1.353 + * This reflects the way that the CLDR data is organized.
1.354 + *
1.355 + * @param dtpg a pointer to UDateTimePatternGenerator.
1.356 + * @param field UDateTimePatternField, such as UDATPG_ERA_FIELD
1.357 + * @param value pattern, such as "{0}, {1}"
1.358 + * @param length the length of value.
1.359 + * @stable ICU 3.8
1.360 + */
1.361 +U_STABLE void U_EXPORT2
1.362 +udatpg_setAppendItemFormat(UDateTimePatternGenerator *dtpg,
1.363 + UDateTimePatternField field,
1.364 + const UChar *value, int32_t length);
1.365 +
1.366 +/**
1.367 + * Getter corresponding to setAppendItemFormat. Values below 0 or at or
1.368 + * above UDATPG_FIELD_COUNT are illegal arguments.
1.369 + *
1.370 + * @param dtpg A pointer to UDateTimePatternGenerator.
1.371 + * @param field UDateTimePatternField, such as UDATPG_ERA_FIELD
1.372 + * @param pLength A pointer that will receive the length of appendItemFormat.
1.373 + * @return appendItemFormat for field.
1.374 + * @stable ICU 3.8
1.375 + */
1.376 +U_STABLE const UChar * U_EXPORT2
1.377 +udatpg_getAppendItemFormat(const UDateTimePatternGenerator *dtpg,
1.378 + UDateTimePatternField field,
1.379 + int32_t *pLength);
1.380 +
1.381 +/**
1.382 + * Set the name of field, eg "era" in English for ERA. These are only
1.383 + * used if the corresponding AppendItemFormat is used, and if it contains a
1.384 + * {2} variable.
1.385 + * <p>
1.386 + * This reflects the way that the CLDR data is organized.
1.387 + *
1.388 + * @param dtpg a pointer to UDateTimePatternGenerator.
1.389 + * @param field UDateTimePatternField
1.390 + * @param value name for the field.
1.391 + * @param length the length of value.
1.392 + * @stable ICU 3.8
1.393 + */
1.394 +U_STABLE void U_EXPORT2
1.395 +udatpg_setAppendItemName(UDateTimePatternGenerator *dtpg,
1.396 + UDateTimePatternField field,
1.397 + const UChar *value, int32_t length);
1.398 +
1.399 +/**
1.400 + * Getter corresponding to setAppendItemNames. Values below 0 or at or above
1.401 + * UDATPG_FIELD_COUNT are illegal arguments.
1.402 + *
1.403 + * @param dtpg a pointer to UDateTimePatternGenerator.
1.404 + * @param field UDateTimePatternField, such as UDATPG_ERA_FIELD
1.405 + * @param pLength A pointer that will receive the length of the name for field.
1.406 + * @return name for field
1.407 + * @stable ICU 3.8
1.408 + */
1.409 +U_STABLE const UChar * U_EXPORT2
1.410 +udatpg_getAppendItemName(const UDateTimePatternGenerator *dtpg,
1.411 + UDateTimePatternField field,
1.412 + int32_t *pLength);
1.413 +
1.414 +/**
1.415 + * The date time format is a message format pattern used to compose date and
1.416 + * time patterns. The default value is "{0} {1}", where {0} will be replaced
1.417 + * by the date pattern and {1} will be replaced by the time pattern.
1.418 + * <p>
1.419 + * This is used when the input skeleton contains both date and time fields,
1.420 + * but there is not a close match among the added patterns. For example,
1.421 + * suppose that this object was created by adding "dd-MMM" and "hh:mm", and
1.422 + * its datetimeFormat is the default "{0} {1}". Then if the input skeleton
1.423 + * is "MMMdhmm", there is not an exact match, so the input skeleton is
1.424 + * broken up into two components "MMMd" and "hmm". There are close matches
1.425 + * for those two skeletons, so the result is put together with this pattern,
1.426 + * resulting in "d-MMM h:mm".
1.427 + *
1.428 + * @param dtpg a pointer to UDateTimePatternGenerator.
1.429 + * @param dtFormat
1.430 + * message format pattern, here {0} will be replaced by the date
1.431 + * pattern and {1} will be replaced by the time pattern.
1.432 + * @param length the length of dtFormat.
1.433 + * @stable ICU 3.8
1.434 + */
1.435 +U_STABLE void U_EXPORT2
1.436 +udatpg_setDateTimeFormat(const UDateTimePatternGenerator *dtpg,
1.437 + const UChar *dtFormat, int32_t length);
1.438 +
1.439 +/**
1.440 + * Getter corresponding to setDateTimeFormat.
1.441 + * @param dtpg a pointer to UDateTimePatternGenerator.
1.442 + * @param pLength A pointer that will receive the length of the format
1.443 + * @return dateTimeFormat.
1.444 + * @stable ICU 3.8
1.445 + */
1.446 +U_STABLE const UChar * U_EXPORT2
1.447 +udatpg_getDateTimeFormat(const UDateTimePatternGenerator *dtpg,
1.448 + int32_t *pLength);
1.449 +
1.450 +/**
1.451 + * The decimal value is used in formatting fractions of seconds. If the
1.452 + * skeleton contains fractional seconds, then this is used with the
1.453 + * fractional seconds. For example, suppose that the input pattern is
1.454 + * "hhmmssSSSS", and the best matching pattern internally is "H:mm:ss", and
1.455 + * the decimal string is ",". Then the resulting pattern is modified to be
1.456 + * "H:mm:ss,SSSS"
1.457 + *
1.458 + * @param dtpg a pointer to UDateTimePatternGenerator.
1.459 + * @param decimal
1.460 + * @param length the length of decimal.
1.461 + * @stable ICU 3.8
1.462 + */
1.463 +U_STABLE void U_EXPORT2
1.464 +udatpg_setDecimal(UDateTimePatternGenerator *dtpg,
1.465 + const UChar *decimal, int32_t length);
1.466 +
1.467 +/**
1.468 + * Getter corresponding to setDecimal.
1.469 + *
1.470 + * @param dtpg a pointer to UDateTimePatternGenerator.
1.471 + * @param pLength A pointer that will receive the length of the decimal string.
1.472 + * @return corresponding to the decimal point.
1.473 + * @stable ICU 3.8
1.474 + */
1.475 +U_STABLE const UChar * U_EXPORT2
1.476 +udatpg_getDecimal(const UDateTimePatternGenerator *dtpg,
1.477 + int32_t *pLength);
1.478 +
1.479 +/**
1.480 + * Adjusts the field types (width and subtype) of a pattern to match what is
1.481 + * in a skeleton. That is, if you supply a pattern like "d-M H:m", and a
1.482 + * skeleton of "MMMMddhhmm", then the input pattern is adjusted to be
1.483 + * "dd-MMMM hh:mm". This is used internally to get the best match for the
1.484 + * input skeleton, but can also be used externally.
1.485 + *
1.486 + * Note that this function uses a non-const UDateTimePatternGenerator:
1.487 + * It uses a stateful pattern parser which is set up for each generator object,
1.488 + * rather than creating one for each function call.
1.489 + * Consecutive calls to this function do not affect each other,
1.490 + * but this function cannot be used concurrently on a single generator object.
1.491 + *
1.492 + * @param dtpg a pointer to UDateTimePatternGenerator.
1.493 + * @param pattern Input pattern
1.494 + * @param patternLength the length of input pattern.
1.495 + * @param skeleton
1.496 + * @param skeletonLength the length of input skeleton.
1.497 + * @param dest pattern adjusted to match the skeleton fields widths and subtypes.
1.498 + * @param destCapacity the capacity of dest.
1.499 + * @param pErrorCode a pointer to the UErrorCode which must not indicate a
1.500 + * failure before the function call.
1.501 + * @return the length of dest.
1.502 + * @stable ICU 3.8
1.503 + */
1.504 +U_STABLE int32_t U_EXPORT2
1.505 +udatpg_replaceFieldTypes(UDateTimePatternGenerator *dtpg,
1.506 + const UChar *pattern, int32_t patternLength,
1.507 + const UChar *skeleton, int32_t skeletonLength,
1.508 + UChar *dest, int32_t destCapacity,
1.509 + UErrorCode *pErrorCode);
1.510 +
1.511 +/**
1.512 + * Adjusts the field types (width and subtype) of a pattern to match what is
1.513 + * in a skeleton. That is, if you supply a pattern like "d-M H:m", and a
1.514 + * skeleton of "MMMMddhhmm", then the input pattern is adjusted to be
1.515 + * "dd-MMMM hh:mm". This is used internally to get the best match for the
1.516 + * input skeleton, but can also be used externally.
1.517 + *
1.518 + * Note that this function uses a non-const UDateTimePatternGenerator:
1.519 + * It uses a stateful pattern parser which is set up for each generator object,
1.520 + * rather than creating one for each function call.
1.521 + * Consecutive calls to this function do not affect each other,
1.522 + * but this function cannot be used concurrently on a single generator object.
1.523 + *
1.524 + * @param dtpg a pointer to UDateTimePatternGenerator.
1.525 + * @param pattern Input pattern
1.526 + * @param patternLength the length of input pattern.
1.527 + * @param skeleton
1.528 + * @param skeletonLength the length of input skeleton.
1.529 + * @param options
1.530 + * Options controlling whether the length of specified fields in the
1.531 + * pattern are adjusted to match those in the skeleton (when this
1.532 + * would not happen otherwise). For default behavior, use
1.533 + * UDATPG_MATCH_NO_OPTIONS.
1.534 + * @param dest pattern adjusted to match the skeleton fields widths and subtypes.
1.535 + * @param destCapacity the capacity of dest.
1.536 + * @param pErrorCode a pointer to the UErrorCode which must not indicate a
1.537 + * failure before the function call.
1.538 + * @return the length of dest.
1.539 + * @stable ICU 4.4
1.540 + */
1.541 +U_STABLE int32_t U_EXPORT2
1.542 +udatpg_replaceFieldTypesWithOptions(UDateTimePatternGenerator *dtpg,
1.543 + const UChar *pattern, int32_t patternLength,
1.544 + const UChar *skeleton, int32_t skeletonLength,
1.545 + UDateTimePatternMatchOptions options,
1.546 + UChar *dest, int32_t destCapacity,
1.547 + UErrorCode *pErrorCode);
1.548 +
1.549 +/**
1.550 + * Return a UEnumeration list of all the skeletons in canonical form.
1.551 + * Call udatpg_getPatternForSkeleton() to get the corresponding pattern.
1.552 + *
1.553 + * @param dtpg a pointer to UDateTimePatternGenerator.
1.554 + * @param pErrorCode a pointer to the UErrorCode which must not indicate a
1.555 + * failure before the function call
1.556 + * @return a UEnumeration list of all the skeletons
1.557 + * The caller must close the object.
1.558 + * @stable ICU 3.8
1.559 + */
1.560 +U_STABLE UEnumeration * U_EXPORT2
1.561 +udatpg_openSkeletons(const UDateTimePatternGenerator *dtpg, UErrorCode *pErrorCode);
1.562 +
1.563 +/**
1.564 + * Return a UEnumeration list of all the base skeletons in canonical form.
1.565 + *
1.566 + * @param dtpg a pointer to UDateTimePatternGenerator.
1.567 + * @param pErrorCode a pointer to the UErrorCode which must not indicate a
1.568 + * failure before the function call.
1.569 + * @return a UEnumeration list of all the base skeletons
1.570 + * The caller must close the object.
1.571 + * @stable ICU 3.8
1.572 + */
1.573 +U_STABLE UEnumeration * U_EXPORT2
1.574 +udatpg_openBaseSkeletons(const UDateTimePatternGenerator *dtpg, UErrorCode *pErrorCode);
1.575 +
1.576 +/**
1.577 + * Get the pattern corresponding to a given skeleton.
1.578 + *
1.579 + * @param dtpg a pointer to UDateTimePatternGenerator.
1.580 + * @param skeleton
1.581 + * @param skeletonLength pointer to the length of skeleton.
1.582 + * @param pLength pointer to the length of return pattern.
1.583 + * @return pattern corresponding to a given skeleton.
1.584 + * @stable ICU 3.8
1.585 + */
1.586 +U_STABLE const UChar * U_EXPORT2
1.587 +udatpg_getPatternForSkeleton(const UDateTimePatternGenerator *dtpg,
1.588 + const UChar *skeleton, int32_t skeletonLength,
1.589 + int32_t *pLength);
1.590 +
1.591 +#endif
