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 */ 44typedef 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 */ 52typedef 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 */ 93typedef 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 */ 112U_DRAFT UDateTimePatternGenerator * U_EXPORT2 113udatpg_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 */ 122U_DRAFT UDateTimePatternGenerator * U_EXPORT2 123udatpg_openEmpty(UErrorCode *pErrorCode); 124 125/** 126 * Close a generator. 127 * @param dtpg a pointer to UDateTimePatternGenerator. 128 * @stable ICU 3.8 129 */ 130U_DRAFT void U_EXPORT2 131udatpg_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 */ 141U_DRAFT UDateTimePatternGenerator * U_EXPORT2 142udatpg_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 */ 167U_DRAFT int32_t U_EXPORT2 168udatpg_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 */ 193U_DRAFT int32_t U_EXPORT2 194udatpg_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 */ 222U_DRAFT int32_t U_EXPORT2 223udatpg_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 */ 252U_DRAFT UDateTimePatternConflict U_EXPORT2 253udatpg_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 */ 279U_DRAFT void U_EXPORT2 280udatpg_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 */ 294U_DRAFT const UChar * U_EXPORT2 295udatpg_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 */ 312U_DRAFT void U_EXPORT2 313udatpg_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 */ 327U_DRAFT const UChar * U_EXPORT2 328udatpg_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 */ 353U_DRAFT void U_EXPORT2 354udatpg_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 */ 364U_DRAFT const UChar * U_EXPORT2 365udatpg_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 */ 381U_DRAFT void U_EXPORT2 382udatpg_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 */ 393U_DRAFT const UChar * U_EXPORT2 394udatpg_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 */ 422U_DRAFT int32_t U_EXPORT2 423udatpg_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 */ 440U_DRAFT UEnumeration * U_EXPORT2 441udatpg_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 */ 453U_DRAFT UEnumeration * U_EXPORT2 454udatpg_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 */ 466U_DRAFT const UChar * U_EXPORT2 467udatpg_getPatternForSkeleton(const UDateTimePatternGenerator *dtpg, 468 const UChar *skeleton, int32_t skeletonLength, 469 int32_t *pLength); 470 471#endif 472