Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/udatpg.h @ 69:33d812a61356

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