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