intl/icu/source/i18n/unicode/udatpg.h

Wed, 31 Dec 2014 07:22:50 +0100

author
Michael Schloh von Bennewitz <michael@schloh.com>
date
Wed, 31 Dec 2014 07:22:50 +0100
branch
TOR_BUG_3246
changeset 4
fc2d59ddac77
permissions
-rw-r--r--

Correct previous dual key logic pending first delivery installment.

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

mercurial