1 /* 2 ******************************************************************************* 3 * Copyright (C) 1996-2012, International Business Machines 4 * Corporation and others. All Rights Reserved. 5 ******************************************************************************* 6 */ 7 8 #ifndef UDAT_H 9 #define UDAT_H 10 11 #include "unicode/utypes.h" 12 13 #if !UCONFIG_NO_FORMATTING 14 15 #include "unicode/localpointer.h" 16 #include "unicode/ucal.h" 17 #include "unicode/unum.h" 18 #include "unicode/udisplaycontext.h" 19 /** 20 * \file 21 * \brief C API: DateFormat 22 * 23 * <h2> Date Format C API</h2> 24 * 25 * Date Format C API consists of functions that convert dates and 26 * times from their internal representations to textual form and back again in a 27 * language-independent manner. Converting from the internal representation (milliseconds 28 * since midnight, January 1, 1970) to text is known as "formatting," and converting 29 * from text to millis is known as "parsing." We currently define only one concrete 30 * structure UDateFormat, which can handle pretty much all normal 31 * date formatting and parsing actions. 32 * <P> 33 * Date Format helps you to format and parse dates for any locale. Your code can 34 * be completely independent of the locale conventions for months, days of the 35 * week, or even the calendar format: lunar vs. solar. 36 * <P> 37 * To format a date for the current Locale with default time and date style, 38 * use one of the static factory methods: 39 * <pre> 40 * \code 41 * UErrorCode status = U_ZERO_ERROR; 42 * UChar *myString; 43 * int32_t myStrlen = 0; 44 * UDateFormat* dfmt = udat_open(UDAT_DEFAULT, UDAT_DEFAULT, NULL, NULL, -1, NULL, -1, &status); 45 * myStrlen = udat_format(dfmt, myDate, NULL, myStrlen, NULL, &status); 46 * if (status==U_BUFFER_OVERFLOW_ERROR){ 47 * status=U_ZERO_ERROR; 48 * myString=(UChar*)malloc(sizeof(UChar) * (myStrlen+1) ); 49 * udat_format(dfmt, myDate, myString, myStrlen+1, NULL, &status); 50 * } 51 * \endcode 52 * </pre> 53 * If you are formatting multiple numbers, it is more efficient to get the 54 * format and use it multiple times so that the system doesn't have to fetch the 55 * information about the local language and country conventions multiple times. 56 * <pre> 57 * \code 58 * UErrorCode status = U_ZERO_ERROR; 59 * int32_t i, myStrlen = 0; 60 * UChar* myString; 61 * char buffer[1024]; 62 * UDate myDateArr[] = { 0.0, 100000000.0, 2000000000.0 }; // test values 63 * UDateFormat* df = udat_open(UDAT_DEFAULT, UDAT_DEFAULT, NULL, NULL, -1, NULL, 0, &status); 64 * for (i = 0; i < 3; i++) { 65 * myStrlen = udat_format(df, myDateArr[i], NULL, myStrlen, NULL, &status); 66 * if(status == U_BUFFER_OVERFLOW_ERROR){ 67 * status = U_ZERO_ERROR; 68 * myString = (UChar*)malloc(sizeof(UChar) * (myStrlen+1) ); 69 * udat_format(df, myDateArr[i], myString, myStrlen+1, NULL, &status); 70 * printf("%s\n", u_austrcpy(buffer, myString) ); 71 * free(myString); 72 * } 73 * } 74 * \endcode 75 * </pre> 76 * To get specific fields of a date, you can use UFieldPosition to 77 * get specific fields. 78 * <pre> 79 * \code 80 * UErrorCode status = U_ZERO_ERROR; 81 * UFieldPosition pos; 82 * UChar *myString; 83 * int32_t myStrlen = 0; 84 * char buffer[1024]; 85 * 86 * pos.field = 1; // Same as the DateFormat::EField enum 87 * UDateFormat* dfmt = udat_open(UDAT_DEFAULT, UDAT_DEFAULT, NULL, -1, NULL, 0, &status); 88 * myStrlen = udat_format(dfmt, myDate, NULL, myStrlen, &pos, &status); 89 * if (status==U_BUFFER_OVERFLOW_ERROR){ 90 * status=U_ZERO_ERROR; 91 * myString=(UChar*)malloc(sizeof(UChar) * (myStrlen+1) ); 92 * udat_format(dfmt, myDate, myString, myStrlen+1, &pos, &status); 93 * } 94 * printf("date format: %s\n", u_austrcpy(buffer, myString)); 95 * buffer[pos.endIndex] = 0; // NULL terminate the string. 96 * printf("UFieldPosition position equals %s\n", &buffer[pos.beginIndex]); 97 * \endcode 98 * </pre> 99 * To format a date for a different Locale, specify it in the call to 100 * udat_open() 101 * <pre> 102 * \code 103 * UDateFormat* df = udat_open(UDAT_SHORT, UDAT_SHORT, "fr_FR", NULL, -1, NULL, 0, &status); 104 * \endcode 105 * </pre> 106 * You can use a DateFormat API udat_parse() to parse. 107 * <pre> 108 * \code 109 * UErrorCode status = U_ZERO_ERROR; 110 * int32_t parsepos=0; 111 * UDate myDate = udat_parse(df, myString, u_strlen(myString), &parsepos, &status); 112 * \endcode 113 * </pre> 114 * You can pass in different options for the arguments for date and time style 115 * to control the length of the result; from SHORT to MEDIUM to LONG to FULL. 116 * The exact result depends on the locale, but generally: 117 * see UDateFormatStyle for more details 118 * <ul type=round> 119 * <li> UDAT_SHORT is completely numeric, such as 12/13/52 or 3:30pm 120 * <li> UDAT_MEDIUM is longer, such as Jan 12, 1952 121 * <li> UDAT_LONG is longer, such as January 12, 1952 or 3:30:32pm 122 * <li> UDAT_FULL is pretty completely specified, such as 123 * Tuesday, April 12, 1952 AD or 3:30:42pm PST. 124 * </ul> 125 * You can also set the time zone on the format if you wish. 126 * <P> 127 * You can also use forms of the parse and format methods with Parse Position and 128 * UFieldPosition to allow you to 129 * <ul type=round> 130 * <li> Progressively parse through pieces of a string. 131 * <li> Align any particular field, or find out where it is for selection 132 * on the screen. 133 * </ul> 134 */ 135 136 /** A date formatter. 137 * For usage in C programs. 138 * @stable ICU 2.6 139 */ 140 typedef void* UDateFormat; 141 142 /** The possible date/time format styles 143 * @stable ICU 2.6 144 */ 145 typedef enum UDateFormatStyle { 146 /** Full style */ 147 UDAT_FULL, 148 /** Long style */ 149 UDAT_LONG, 150 /** Medium style */ 151 UDAT_MEDIUM, 152 /** Short style */ 153 UDAT_SHORT, 154 /** Default style */ 155 UDAT_DEFAULT = UDAT_MEDIUM, 156 157 /** Bitfield for relative date */ 158 UDAT_RELATIVE = (1 << 7), 159 160 UDAT_FULL_RELATIVE = UDAT_FULL | UDAT_RELATIVE, 161 162 UDAT_LONG_RELATIVE = UDAT_LONG | UDAT_RELATIVE, 163 164 UDAT_MEDIUM_RELATIVE = UDAT_MEDIUM | UDAT_RELATIVE, 165 166 UDAT_SHORT_RELATIVE = UDAT_SHORT | UDAT_RELATIVE, 167 168 169 /** No style */ 170 UDAT_NONE = -1, 171 172 /** 173 * Use the pattern given in the parameter to udat_open 174 * @see udat_open 175 * @draft ICU 50 176 */ 177 UDAT_PATTERN = -2, 178 179 /** @internal alias to UDAT_PATTERN */ 180 UDAT_IGNORE = UDAT_PATTERN 181 } UDateFormatStyle; 182 183 // Skeletons for dates. 184 185 /** 186 * Constant for date skeleton with year. 187 * @stable ICU 4.0 188 */ 189 #define UDAT_YEAR "y" 190 /** 191 * Constant for date skeleton with quarter. 192 * @internal ICU 50 technology preview 193 */ 194 #define UDAT_QUARTER "QQQQ" 195 /** 196 * Constant for date skeleton with abbreviated quarter. 197 * @internal ICU 50 technology preview 198 */ 199 #define UDAT_ABBR_QUARTER "QQQ" 200 /** 201 * Constant for date skeleton with year and quarter. 202 * @stable ICU 4.0 203 */ 204 #define UDAT_YEAR_QUARTER "yQQQQ" 205 /** 206 * Constant for date skeleton with year and abbreviated quarter. 207 * @stable ICU 4.0 208 */ 209 #define UDAT_YEAR_ABBR_QUARTER "yQQQ" 210 /** 211 * Constant for date skeleton with month. 212 * @stable ICU 4.0 213 */ 214 #define UDAT_MONTH "MMMM" 215 /** 216 * Constant for date skeleton with abbreviated month. 217 * @stable ICU 4.0 218 */ 219 #define UDAT_ABBR_MONTH "MMM" 220 /** 221 * Constant for date skeleton with numeric month. 222 * @stable ICU 4.0 223 */ 224 #define UDAT_NUM_MONTH "M" 225 /** 226 * Constant for date skeleton with year and month. 227 * @stable ICU 4.0 228 */ 229 #define UDAT_YEAR_MONTH "yMMMM" 230 /** 231 * Constant for date skeleton with year and abbreviated month. 232 * @stable ICU 4.0 233 */ 234 #define UDAT_YEAR_ABBR_MONTH "yMMM" 235 /** 236 * Constant for date skeleton with year and numeric month. 237 * @stable ICU 4.0 238 */ 239 #define UDAT_YEAR_NUM_MONTH "yM" 240 /** 241 * Constant for date skeleton with day. 242 * @stable ICU 4.0 243 */ 244 #define UDAT_DAY "d" 245 /** 246 * Constant for date skeleton with year, month, and day. 247 * Used in combinations date + time, date + time + zone, or time + zone. 248 * @stable ICU 4.0 249 */ 250 #define UDAT_YEAR_MONTH_DAY "yMMMMd" 251 /** 252 * Constant for date skeleton with year, abbreviated month, and day. 253 * Used in combinations date + time, date + time + zone, or time + zone. 254 * @stable ICU 4.0 255 */ 256 #define UDAT_YEAR_ABBR_MONTH_DAY "yMMMd" 257 /** 258 * Constant for date skeleton with year, numeric month, and day. 259 * Used in combinations date + time, date + time + zone, or time + zone. 260 * @stable ICU 4.0 261 */ 262 #define UDAT_YEAR_NUM_MONTH_DAY "yMd" 263 /** 264 * Constant for date skeleton with weekday. 265 * @internal ICU 50 technology preview 266 */ 267 #define UDAT_WEEKDAY "EEEE" 268 /** 269 * Constant for date skeleton with abbreviated weekday. 270 * @internal ICU 50 technology preview 271 */ 272 #define UDAT_ABBR_WEEKDAY "E" 273 /** 274 * Constant for date skeleton with year, month, weekday, and day. 275 * Used in combinations date + time, date + time + zone, or time + zone. 276 * @stable ICU 4.0 277 */ 278 #define UDAT_YEAR_MONTH_WEEKDAY_DAY "yMMMMEEEEd" 279 /** 280 * Constant for date skeleton with year, abbreviated month, weekday, and day. 281 * Used in combinations date + time, date + time + zone, or time + zone. 282 * @stable ICU 4.0 283 */ 284 #define UDAT_YEAR_ABBR_MONTH_WEEKDAY_DAY "yMMMEd" 285 /** 286 * Constant for date skeleton with year, numeric month, weekday, and day. 287 * Used in combinations date + time, date + time + zone, or time + zone. 288 * @stable ICU 4.0 289 */ 290 #define UDAT_YEAR_NUM_MONTH_WEEKDAY_DAY "yMEd" 291 /** 292 * Constant for date skeleton with long month and day. 293 * Used in combinations date + time, date + time + zone, or time + zone. 294 * @stable ICU 4.0 295 */ 296 #define UDAT_MONTH_DAY "MMMMd" 297 /** 298 * Constant for date skeleton with abbreviated month and day. 299 * Used in combinations date + time, date + time + zone, or time + zone. 300 * @stable ICU 4.0 301 */ 302 #define UDAT_ABBR_MONTH_DAY "MMMd" 303 /** 304 * Constant for date skeleton with numeric month and day. 305 * Used in combinations date + time, date + time + zone, or time + zone. 306 * @stable ICU 4.0 307 */ 308 #define UDAT_NUM_MONTH_DAY "Md" 309 /** 310 * Constant for date skeleton with month, weekday, and day. 311 * Used in combinations date + time, date + time + zone, or time + zone. 312 * @stable ICU 4.0 313 */ 314 #define UDAT_MONTH_WEEKDAY_DAY "MMMMEEEEd" 315 /** 316 * Constant for date skeleton with abbreviated month, weekday, and day. 317 * Used in combinations date + time, date + time + zone, or time + zone. 318 * @stable ICU 4.0 319 */ 320 #define UDAT_ABBR_MONTH_WEEKDAY_DAY "MMMEd" 321 /** 322 * Constant for date skeleton with numeric month, weekday, and day. 323 * Used in combinations date + time, date + time + zone, or time + zone. 324 * @stable ICU 4.0 325 */ 326 #define UDAT_NUM_MONTH_WEEKDAY_DAY "MEd" 327 328 // Skeletons for times. 329 330 /** 331 * Constant for date skeleton with hour, with the locale's preferred hour format (12 or 24). 332 * @stable ICU 4.0 333 */ 334 #define UDAT_HOUR "j" 335 /** 336 * Constant for date skeleton with hour in 24-hour presentation. 337 * @internal ICU 50 technology preview 338 */ 339 #define UDAT_HOUR24 "H" 340 /** 341 * Constant for date skeleton with minute. 342 * @internal ICU 50 technology preview 343 */ 344 #define UDAT_MINUTE "m" 345 /** 346 * Constant for date skeleton with hour and minute, with the locale's preferred hour format (12 or 24). 347 * Used in combinations date + time, date + time + zone, or time + zone. 348 * @stable ICU 4.0 349 */ 350 #define UDAT_HOUR_MINUTE "jm" 351 /** 352 * Constant for date skeleton with hour and minute in 24-hour presentation. 353 * Used in combinations date + time, date + time + zone, or time + zone. 354 * @stable ICU 4.0 355 */ 356 #define UDAT_HOUR24_MINUTE "Hm" 357 /** 358 * Constant for date skeleton with second. 359 * @internal ICU 50 technology preview 360 */ 361 #define UDAT_SECOND "s" 362 /** 363 * Constant for date skeleton with hour, minute, and second, 364 * with the locale's preferred hour format (12 or 24). 365 * Used in combinations date + time, date + time + zone, or time + zone. 366 * @stable ICU 4.0 367 */ 368 #define UDAT_HOUR_MINUTE_SECOND "jms" 369 /** 370 * Constant for date skeleton with hour, minute, and second in 371 * 24-hour presentation. 372 * Used in combinations date + time, date + time + zone, or time + zone. 373 * @stable ICU 4.0 374 */ 375 #define UDAT_HOUR24_MINUTE_SECOND "Hms" 376 /** 377 * Constant for date skeleton with minute and second. 378 * Used in combinations date + time, date + time + zone, or time + zone. 379 * @stable ICU 4.0 380 */ 381 #define UDAT_MINUTE_SECOND "ms" 382 383 // Skeletons for time zones. 384 385 /** 386 * Constant for <i>generic location format</i>, such as Los Angeles Time; 387 * used in combinations date + time + zone, or time + zone. 388 * @see <a href="http://unicode.org/reports/tr35/#Date_Format_Patterns">LDML Date Format Patterns</a> 389 * @see <a href="http://unicode.org/reports/tr35/#Time_Zone_Fallback">LDML Time Zone Fallback</a> 390 * @internal ICU 50 technology preview 391 */ 392 #define UDAT_LOCATION_TZ "VVVV" 393 /** 394 * Constant for <i>generic non-location format</i>, such as Pacific Time; 395 * used in combinations date + time + zone, or time + zone. 396 * @see <a href="http://unicode.org/reports/tr35/#Date_Format_Patterns">LDML Date Format Patterns</a> 397 * @see <a href="http://unicode.org/reports/tr35/#Time_Zone_Fallback">LDML Time Zone Fallback</a> 398 * @internal ICU 50 technology preview 399 */ 400 #define UDAT_GENERIC_TZ "vvvv" 401 /** 402 * Constant for <i>generic non-location format</i>, abbreviated if possible, such as PT; 403 * used in combinations date + time + zone, or time + zone. 404 * @see <a href="http://unicode.org/reports/tr35/#Date_Format_Patterns">LDML Date Format Patterns</a> 405 * @see <a href="http://unicode.org/reports/tr35/#Time_Zone_Fallback">LDML Time Zone Fallback</a> 406 * @internal ICU 50 technology preview 407 */ 408 #define UDAT_ABBR_GENERIC_TZ "v" 409 /** 410 * Constant for <i>specific non-location format</i>, such as Pacific Daylight Time; 411 * used in combinations date + time + zone, or time + zone. 412 * @see <a href="http://unicode.org/reports/tr35/#Date_Format_Patterns">LDML Date Format Patterns</a> 413 * @see <a href="http://unicode.org/reports/tr35/#Time_Zone_Fallback">LDML Time Zone Fallback</a> 414 * @internal ICU 50 technology preview 415 */ 416 #define UDAT_SPECIFIC_TZ "zzzz" 417 /** 418 * Constant for <i>specific non-location format</i>, abbreviated if possible, such as PDT; 419 * used in combinations date + time + zone, or time + zone. 420 * @see <a href="http://unicode.org/reports/tr35/#Date_Format_Patterns">LDML Date Format Patterns</a> 421 * @see <a href="http://unicode.org/reports/tr35/#Time_Zone_Fallback">LDML Time Zone Fallback</a> 422 * @internal ICU 50 technology preview 423 */ 424 #define UDAT_ABBR_SPECIFIC_TZ "z" 425 /** 426 * Constant for <i>localized GMT/UTC format</i>, such as GMT+8:00 or HPG-8:00; 427 * used in combinations date + time + zone, or time + zone. 428 * @see <a href="http://unicode.org/reports/tr35/#Date_Format_Patterns">LDML Date Format Patterns</a> 429 * @see <a href="http://unicode.org/reports/tr35/#Time_Zone_Fallback">LDML Time Zone Fallback</a> 430 * @internal ICU 50 technology preview 431 */ 432 #define UDAT_ABBR_UTC_TZ "ZZZZ" 433 434 // deprecated skeleton constants 435 436 /** 437 * Constant for date skeleton with standalone month. 438 * @deprecated ICU 50 Use UDAT_MONTH instead. 439 */ 440 #define UDAT_STANDALONE_MONTH "LLLL" 441 /** 442 * Constant for date skeleton with standalone abbreviated month. 443 * @deprecated ICU 50 Use UDAT_ABBR_MONTH instead. 444 */ 445 #define UDAT_ABBR_STANDALONE_MONTH "LLL" 446 447 /** 448 * Constant for date skeleton with hour, minute, and generic timezone. 449 * @deprecated ICU 50 Use instead UDAT_HOUR_MINUTE UDAT_ABBR_GENERIC_TZ or some other timezone presentation. 450 */ 451 #define UDAT_HOUR_MINUTE_GENERIC_TZ "jmv" 452 /** 453 * Constant for date skeleton with hour, minute, and timezone. 454 * @deprecated ICU 50 Use instead UDAT_HOUR_MINUTE UDAT_ABBR_SPECIFIC_TZ or some other timezone presentation. 455 */ 456 #define UDAT_HOUR_MINUTE_TZ "jmz" 457 /** 458 * Constant for date skeleton with hour and generic timezone. 459 * @deprecated ICU 50 Use instead UDAT_HOUR UDAT_ABBR_GENERIC_TZ or some other timezone presentation. 460 */ 461 #define UDAT_HOUR_GENERIC_TZ "jv" 462 /** 463 * Constant for date skeleton with hour and timezone. 464 * @deprecated ICU 50 Use instead UDAT_HOUR UDAT_ABBR_SPECIFIC_TZ or some other timezone presentation. 465 */ 466 #define UDAT_HOUR_TZ "jz" 467 468 /** 469 * FieldPosition and UFieldPosition selectors for format fields 470 * defined by DateFormat and UDateFormat. 471 * @stable ICU 3.0 472 */ 473 typedef enum UDateFormatField { 474 /** 475 * FieldPosition and UFieldPosition selector for 'G' field alignment, 476 * corresponding to the UCAL_ERA field. 477 * @stable ICU 3.0 478 */ 479 UDAT_ERA_FIELD = 0, 480 481 /** 482 * FieldPosition and UFieldPosition selector for 'y' field alignment, 483 * corresponding to the UCAL_YEAR field. 484 * @stable ICU 3.0 485 */ 486 UDAT_YEAR_FIELD = 1, 487 488 /** 489 * FieldPosition and UFieldPosition selector for 'M' field alignment, 490 * corresponding to the UCAL_MONTH field. 491 * @stable ICU 3.0 492 */ 493 UDAT_MONTH_FIELD = 2, 494 495 /** 496 * FieldPosition and UFieldPosition selector for 'd' field alignment, 497 * corresponding to the UCAL_DATE field. 498 * @stable ICU 3.0 499 */ 500 UDAT_DATE_FIELD = 3, 501 502 /** 503 * FieldPosition and UFieldPosition selector for 'k' field alignment, 504 * corresponding to the UCAL_HOUR_OF_DAY field. 505 * UDAT_HOUR_OF_DAY1_FIELD is used for the one-based 24-hour clock. 506 * For example, 23:59 + 01:00 results in 24:59. 507 * @stable ICU 3.0 508 */ 509 UDAT_HOUR_OF_DAY1_FIELD = 4, 510 511 /** 512 * FieldPosition and UFieldPosition selector for 'H' field alignment, 513 * corresponding to the UCAL_HOUR_OF_DAY field. 514 * UDAT_HOUR_OF_DAY0_FIELD is used for the zero-based 24-hour clock. 515 * For example, 23:59 + 01:00 results in 00:59. 516 * @stable ICU 3.0 517 */ 518 UDAT_HOUR_OF_DAY0_FIELD = 5, 519 520 /** 521 * FieldPosition and UFieldPosition selector for 'm' field alignment, 522 * corresponding to the UCAL_MINUTE field. 523 * @stable ICU 3.0 524 */ 525 UDAT_MINUTE_FIELD = 6, 526 527 /** 528 * FieldPosition and UFieldPosition selector for 's' field alignment, 529 * corresponding to the UCAL_SECOND field. 530 * @stable ICU 3.0 531 */ 532 UDAT_SECOND_FIELD = 7, 533 534 /** 535 * FieldPosition and UFieldPosition selector for 'S' field alignment, 536 * corresponding to the UCAL_MILLISECOND field. 537 * 538 * Note: Time formats that use 'S' can display a maximum of three 539 * significant digits for fractional seconds, corresponding to millisecond 540 * resolution and a fractional seconds sub-pattern of SSS. If the 541 * sub-pattern is S or SS, the fractional seconds value will be truncated 542 * (not rounded) to the number of display places specified. If the 543 * fractional seconds sub-pattern is longer than SSS, the additional 544 * display places will be filled with zeros. 545 * @stable ICU 3.0 546 */ 547 UDAT_FRACTIONAL_SECOND_FIELD = 8, 548 549 /** 550 * FieldPosition and UFieldPosition selector for 'E' field alignment, 551 * corresponding to the UCAL_DAY_OF_WEEK field. 552 * @stable ICU 3.0 553 */ 554 UDAT_DAY_OF_WEEK_FIELD = 9, 555 556 /** 557 * FieldPosition and UFieldPosition selector for 'D' field alignment, 558 * corresponding to the UCAL_DAY_OF_YEAR field. 559 * @stable ICU 3.0 560 */ 561 UDAT_DAY_OF_YEAR_FIELD = 10, 562 563 /** 564 * FieldPosition and UFieldPosition selector for 'F' field alignment, 565 * corresponding to the UCAL_DAY_OF_WEEK_IN_MONTH field. 566 * @stable ICU 3.0 567 */ 568 UDAT_DAY_OF_WEEK_IN_MONTH_FIELD = 11, 569 570 /** 571 * FieldPosition and UFieldPosition selector for 'w' field alignment, 572 * corresponding to the UCAL_WEEK_OF_YEAR field. 573 * @stable ICU 3.0 574 */ 575 UDAT_WEEK_OF_YEAR_FIELD = 12, 576 577 /** 578 * FieldPosition and UFieldPosition selector for 'W' field alignment, 579 * corresponding to the UCAL_WEEK_OF_MONTH field. 580 * @stable ICU 3.0 581 */ 582 UDAT_WEEK_OF_MONTH_FIELD = 13, 583 584 /** 585 * FieldPosition and UFieldPosition selector for 'a' field alignment, 586 * corresponding to the UCAL_AM_PM field. 587 * @stable ICU 3.0 588 */ 589 UDAT_AM_PM_FIELD = 14, 590 591 /** 592 * FieldPosition and UFieldPosition selector for 'h' field alignment, 593 * corresponding to the UCAL_HOUR field. 594 * UDAT_HOUR1_FIELD is used for the one-based 12-hour clock. 595 * For example, 11:30 PM + 1 hour results in 12:30 AM. 596 * @stable ICU 3.0 597 */ 598 UDAT_HOUR1_FIELD = 15, 599 600 /** 601 * FieldPosition and UFieldPosition selector for 'K' field alignment, 602 * corresponding to the UCAL_HOUR field. 603 * UDAT_HOUR0_FIELD is used for the zero-based 12-hour clock. 604 * For example, 11:30 PM + 1 hour results in 00:30 AM. 605 * @stable ICU 3.0 606 */ 607 UDAT_HOUR0_FIELD = 16, 608 609 /** 610 * FieldPosition and UFieldPosition selector for 'z' field alignment, 611 * corresponding to the UCAL_ZONE_OFFSET and 612 * UCAL_DST_OFFSET fields. 613 * @stable ICU 3.0 614 */ 615 UDAT_TIMEZONE_FIELD = 17, 616 617 /** 618 * FieldPosition and UFieldPosition selector for 'Y' field alignment, 619 * corresponding to the UCAL_YEAR_WOY field. 620 * @stable ICU 3.0 621 */ 622 UDAT_YEAR_WOY_FIELD = 18, 623 624 /** 625 * FieldPosition and UFieldPosition selector for 'e' field alignment, 626 * corresponding to the UCAL_DOW_LOCAL field. 627 * @stable ICU 3.0 628 */ 629 UDAT_DOW_LOCAL_FIELD = 19, 630 631 /** 632 * FieldPosition and UFieldPosition selector for 'u' field alignment, 633 * corresponding to the UCAL_EXTENDED_YEAR field. 634 * @stable ICU 3.0 635 */ 636 UDAT_EXTENDED_YEAR_FIELD = 20, 637 638 /** 639 * FieldPosition and UFieldPosition selector for 'g' field alignment, 640 * corresponding to the UCAL_JULIAN_DAY field. 641 * @stable ICU 3.0 642 */ 643 UDAT_JULIAN_DAY_FIELD = 21, 644 645 /** 646 * FieldPosition and UFieldPosition selector for 'A' field alignment, 647 * corresponding to the UCAL_MILLISECONDS_IN_DAY field. 648 * @stable ICU 3.0 649 */ 650 UDAT_MILLISECONDS_IN_DAY_FIELD = 22, 651 652 /** 653 * FieldPosition and UFieldPosition selector for 'Z' field alignment, 654 * corresponding to the UCAL_ZONE_OFFSET and 655 * UCAL_DST_OFFSET fields. 656 * @stable ICU 3.0 657 */ 658 UDAT_TIMEZONE_RFC_FIELD = 23, 659 660 /** 661 * FieldPosition and UFieldPosition selector for 'v' field alignment, 662 * corresponding to the UCAL_ZONE_OFFSET field. 663 * @stable ICU 3.4 664 */ 665 UDAT_TIMEZONE_GENERIC_FIELD = 24, 666 /** 667 * FieldPosition selector for 'c' field alignment, 668 * corresponding to the {@link #UCAL_DOW_LOCAL} field. 669 * This displays the stand alone day name, if available. 670 * @stable ICU 3.4 671 */ 672 UDAT_STANDALONE_DAY_FIELD = 25, 673 674 /** 675 * FieldPosition selector for 'L' field alignment, 676 * corresponding to the {@link #UCAL_MONTH} field. 677 * This displays the stand alone month name, if available. 678 * @stable ICU 3.4 679 */ 680 UDAT_STANDALONE_MONTH_FIELD = 26, 681 682 /** 683 * FieldPosition selector for "Q" field alignment, 684 * corresponding to quarters. This is implemented 685 * using the {@link #UCAL_MONTH} field. This 686 * displays the quarter. 687 * @stable ICU 3.6 688 */ 689 UDAT_QUARTER_FIELD = 27, 690 691 /** 692 * FieldPosition selector for the "q" field alignment, 693 * corresponding to stand-alone quarters. This is 694 * implemented using the {@link #UCAL_MONTH} field. 695 * This displays the stand-alone quarter. 696 * @stable ICU 3.6 697 */ 698 UDAT_STANDALONE_QUARTER_FIELD = 28, 699 700 /** 701 * FieldPosition and UFieldPosition selector for 'V' field alignment, 702 * corresponding to the UCAL_ZONE_OFFSET field. 703 * @stable ICU 3.8 704 */ 705 UDAT_TIMEZONE_SPECIAL_FIELD = 29, 706 707 /** 708 * FieldPosition selector for "U" field alignment, 709 * corresponding to cyclic year names. This is implemented 710 * using the {@link #UCAL_YEAR} field. This displays 711 * the cyclic year name, if available. 712 * @draft ICU 49 713 */ 714 UDAT_YEAR_NAME_FIELD = 30, 715 716 /** 717 * Number of FieldPosition and UFieldPosition selectors for 718 * DateFormat and UDateFormat. 719 * Valid selectors range from 0 to UDAT_FIELD_COUNT-1. 720 * This value is subject to change if new fields are defined 721 * in the future. 722 * @stable ICU 3.0 723 */ 724 UDAT_FIELD_COUNT = 31 725 726 } UDateFormatField; 727 728 729 /** 730 * Maps from a UDateFormatField to the corresponding UCalendarDateFields. 731 * Note: since the mapping is many-to-one, there is no inverse mapping. 732 * @param field the UDateFormatField. 733 * @return the UCalendarDateField. This will be UCAL_FIELD_COUNT in case 734 * of error (e.g., the input field is UDAT_FIELD_COUNT). 735 * @stable ICU 4.4 736 */ 737 U_STABLE UCalendarDateFields U_EXPORT2 738 udat_toCalendarDateField(UDateFormatField field); 739 740 741 /** 742 * Open a new UDateFormat for formatting and parsing dates and times. 743 * A UDateFormat may be used to format dates in calls to {@link #udat_format }, 744 * and to parse dates in calls to {@link #udat_parse }. 745 * @param timeStyle The style used to format times; one of UDAT_FULL, UDAT_LONG, 746 * UDAT_MEDIUM, UDAT_SHORT, UDAT_DEFAULT, or UDAT_NONE (relative time styles 747 * are not currently supported). 748 * When the pattern parameter is used, pass in UDAT_PATTERN for both timeStyle and dateStyle. 749 * @param dateStyle The style used to format dates; one of UDAT_FULL, UDAT_LONG, 750 * UDAT_MEDIUM, UDAT_SHORT, UDAT_DEFAULT, UDAT_FULL_RELATIVE, UDAT_LONG_RELATIVE, 751 * UDAT_MEDIUM_RELATIVE, UDAT_SHORT_RELATIVE, or UDAT_NONE. 752 * When the pattern parameter is used, pass in UDAT_PATTERN for both timeStyle and dateStyle. 753 * As currently implemented, 754 * relative date formatting only affects a limited range of calendar days before or 755 * after the current date, based on the CLDR <field type="day">/<relative> data: For 756 * example, in English, "Yesterday", "Today", and "Tomorrow". Outside of this range, 757 * dates are formatted using the corresponding non-relative style. 758 * @param locale The locale specifying the formatting conventions 759 * @param tzID A timezone ID specifying the timezone to use. If 0, use 760 * the default timezone. 761 * @param tzIDLength The length of tzID, or -1 if null-terminated. 762 * @param pattern A pattern specifying the format to use. 763 * @param patternLength The number of characters in the pattern, or -1 if null-terminated. 764 * @param status A pointer to an UErrorCode to receive any errors 765 * @return A pointer to a UDateFormat to use for formatting dates and times, or 0 if 766 * an error occurred. 767 * @stable ICU 2.0 768 */ 769 U_STABLE UDateFormat* U_EXPORT2 770 udat_open(UDateFormatStyle timeStyle, 771 UDateFormatStyle dateStyle, 772 const char *locale, 773 const UChar *tzID, 774 int32_t tzIDLength, 775 const UChar *pattern, 776 int32_t patternLength, 777 UErrorCode *status); 778 779 780 /** 781 * Close a UDateFormat. 782 * Once closed, a UDateFormat may no longer be used. 783 * @param format The formatter to close. 784 * @stable ICU 2.0 785 */ 786 U_STABLE void U_EXPORT2 787 udat_close(UDateFormat* format); 788 789 #if U_SHOW_CPLUSPLUS_API 790 791 U_NAMESPACE_BEGIN 792 793 /** 794 * \class LocalUDateFormatPointer 795 * "Smart pointer" class, closes a UDateFormat via udat_close(). 796 * For most methods see the LocalPointerBase base class. 797 * 798 * @see LocalPointerBase 799 * @see LocalPointer 800 * @stable ICU 4.4 801 */ 802 U_DEFINE_LOCAL_OPEN_POINTER(LocalUDateFormatPointer, UDateFormat, udat_close); 803 804 U_NAMESPACE_END 805 806 #endif 807 808 /** 809 * Open a copy of a UDateFormat. 810 * This function performs a deep copy. 811 * @param fmt The format to copy 812 * @param status A pointer to an UErrorCode to receive any errors. 813 * @return A pointer to a UDateFormat identical to fmt. 814 * @stable ICU 2.0 815 */ 816 U_STABLE UDateFormat* U_EXPORT2 817 udat_clone(const UDateFormat *fmt, 818 UErrorCode *status); 819 820 /** 821 * Format a date using an UDateFormat. 822 * The date will be formatted using the conventions specified in {@link #udat_open } 823 * @param format The formatter to use 824 * @param dateToFormat The date to format 825 * @param result A pointer to a buffer to receive the formatted number. 826 * @param resultLength The maximum size of result. 827 * @param position A pointer to a UFieldPosition. On input, position->field 828 * is read. On output, position->beginIndex and position->endIndex indicate 829 * the beginning and ending indices of field number position->field, if such 830 * a field exists. This parameter may be NULL, in which case no field 831 * position data is returned. 832 * @param status A pointer to an UErrorCode to receive any errors 833 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 834 * @see udat_parse 835 * @see UFieldPosition 836 * @stable ICU 2.0 837 */ 838 U_STABLE int32_t U_EXPORT2 839 udat_format( const UDateFormat* format, 840 UDate dateToFormat, 841 UChar* result, 842 int32_t resultLength, 843 UFieldPosition* position, 844 UErrorCode* status); 845 846 /** 847 * Parse a string into an date/time using a UDateFormat. 848 * The date will be parsed using the conventions specified in {@link #udat_open }. 849 * <P> 850 * Note that the normal date formats associated with some calendars - such 851 * as the Chinese lunar calendar - do not specify enough fields to enable 852 * dates to be parsed unambiguously. In the case of the Chinese lunar 853 * calendar, while the year within the current 60-year cycle is specified, 854 * the number of such cycles since the start date of the calendar (in the 855 * UCAL_ERA field of the UCalendar object) is not normally part of the format, 856 * and parsing may assume the wrong era. For cases such as this it is 857 * recommended that clients parse using udat_parseCalendar with the UCalendar 858 * passed in set to the current date, or to a date within the era/cycle that 859 * should be assumed if absent in the format. 860 * 861 * @param format The formatter to use. 862 * @param text The text to parse. 863 * @param textLength The length of text, or -1 if null-terminated. 864 * @param parsePos If not 0, on input a pointer to an integer specifying the offset at which 865 * to begin parsing. If not 0, on output the offset at which parsing ended. 866 * @param status A pointer to an UErrorCode to receive any errors 867 * @return The value of the parsed date/time 868 * @see udat_format 869 * @stable ICU 2.0 870 */ 871 U_STABLE UDate U_EXPORT2 872 udat_parse(const UDateFormat* format, 873 const UChar* text, 874 int32_t textLength, 875 int32_t *parsePos, 876 UErrorCode *status); 877 878 /** 879 * Parse a string into an date/time using a UDateFormat. 880 * The date will be parsed using the conventions specified in {@link #udat_open }. 881 * @param format The formatter to use. 882 * @param calendar A calendar set on input to the date and time to be used for 883 * missing values in the date/time string being parsed, and set 884 * on output to the parsed date/time. When the calendar type is 885 * different from the internal calendar held by the UDateFormat 886 * instance, the internal calendar will be cloned to a work 887 * calendar set to the same milliseconds and time zone as this 888 * calendar parameter, field values will be parsed based on the 889 * work calendar, then the result (milliseconds and time zone) 890 * will be set in this calendar. 891 * @param text The text to parse. 892 * @param textLength The length of text, or -1 if null-terminated. 893 * @param parsePos If not 0, on input a pointer to an integer specifying the offset at which 894 * to begin parsing. If not 0, on output the offset at which parsing ended. 895 * @param status A pointer to an UErrorCode to receive any errors 896 * @see udat_format 897 * @stable ICU 2.0 898 */ 899 U_STABLE void U_EXPORT2 900 udat_parseCalendar(const UDateFormat* format, 901 UCalendar* calendar, 902 const UChar* text, 903 int32_t textLength, 904 int32_t *parsePos, 905 UErrorCode *status); 906 907 /** 908 * Determine if an UDateFormat will perform lenient parsing. 909 * With lenient parsing, the parser may use heuristics to interpret inputs that do not 910 * precisely match the pattern. With strict parsing, inputs must match the pattern. 911 * @param fmt The formatter to query 912 * @return TRUE if fmt is set to perform lenient parsing, FALSE otherwise. 913 * @see udat_setLenient 914 * @stable ICU 2.0 915 */ 916 U_STABLE UBool U_EXPORT2 917 udat_isLenient(const UDateFormat* fmt); 918 919 /** 920 * Specify whether an UDateFormat will perform lenient parsing. 921 * With lenient parsing, the parser may use heuristics to interpret inputs that do not 922 * precisely match the pattern. With strict parsing, inputs must match the pattern. 923 * @param fmt The formatter to set 924 * @param isLenient TRUE if fmt should perform lenient parsing, FALSE otherwise. 925 * @see dat_isLenient 926 * @stable ICU 2.0 927 */ 928 U_STABLE void U_EXPORT2 929 udat_setLenient( UDateFormat* fmt, 930 UBool isLenient); 931 932 /** 933 * Get the UCalendar associated with an UDateFormat. 934 * A UDateFormat uses a UCalendar to convert a raw value to, for example, 935 * the day of the week. 936 * @param fmt The formatter to query. 937 * @return A pointer to the UCalendar used by fmt. 938 * @see udat_setCalendar 939 * @stable ICU 2.0 940 */ 941 U_STABLE const UCalendar* U_EXPORT2 942 udat_getCalendar(const UDateFormat* fmt); 943 944 /** 945 * Set the UCalendar associated with an UDateFormat. 946 * A UDateFormat uses a UCalendar to convert a raw value to, for example, 947 * the day of the week. 948 * @param fmt The formatter to set. 949 * @param calendarToSet A pointer to an UCalendar to be used by fmt. 950 * @see udat_setCalendar 951 * @stable ICU 2.0 952 */ 953 U_STABLE void U_EXPORT2 954 udat_setCalendar( UDateFormat* fmt, 955 const UCalendar* calendarToSet); 956 957 /** 958 * Get the UNumberFormat associated with an UDateFormat. 959 * A UDateFormat uses a UNumberFormat to format numbers within a date, 960 * for example the day number. 961 * @param fmt The formatter to query. 962 * @return A pointer to the UNumberFormat used by fmt to format numbers. 963 * @see udat_setNumberFormat 964 * @stable ICU 2.0 965 */ 966 U_STABLE const UNumberFormat* U_EXPORT2 967 udat_getNumberFormat(const UDateFormat* fmt); 968 969 /** 970 * Set the UNumberFormat associated with an UDateFormat. 971 * A UDateFormat uses a UNumberFormat to format numbers within a date, 972 * for example the day number. 973 * @param fmt The formatter to set. 974 * @param numberFormatToSet A pointer to the UNumberFormat to be used by fmt to format numbers. 975 * @see udat_getNumberFormat 976 * @stable ICU 2.0 977 */ 978 U_STABLE void U_EXPORT2 979 udat_setNumberFormat( UDateFormat* fmt, 980 const UNumberFormat* numberFormatToSet); 981 982 /** 983 * Get a locale for which date/time formatting patterns are available. 984 * A UDateFormat in a locale returned by this function will perform the correct 985 * formatting and parsing for the locale. 986 * @param localeIndex The index of the desired locale. 987 * @return A locale for which date/time formatting patterns are available, or 0 if none. 988 * @see udat_countAvailable 989 * @stable ICU 2.0 990 */ 991 U_STABLE const char* U_EXPORT2 992 udat_getAvailable(int32_t localeIndex); 993 994 /** 995 * Determine how many locales have date/time formatting patterns available. 996 * This function is most useful as determining the loop ending condition for 997 * calls to {@link #udat_getAvailable }. 998 * @return The number of locales for which date/time formatting patterns are available. 999 * @see udat_getAvailable 1000 * @stable ICU 2.0 1001 */ 1002 U_STABLE int32_t U_EXPORT2 1003 udat_countAvailable(void); 1004 1005 /** 1006 * Get the year relative to which all 2-digit years are interpreted. 1007 * For example, if the 2-digit start year is 2100, the year 99 will be 1008 * interpreted as 2199. 1009 * @param fmt The formatter to query. 1010 * @param status A pointer to an UErrorCode to receive any errors 1011 * @return The year relative to which all 2-digit years are interpreted. 1012 * @see udat_Set2DigitYearStart 1013 * @stable ICU 2.0 1014 */ 1015 U_STABLE UDate U_EXPORT2 1016 udat_get2DigitYearStart( const UDateFormat *fmt, 1017 UErrorCode *status); 1018 1019 /** 1020 * Set the year relative to which all 2-digit years will be interpreted. 1021 * For example, if the 2-digit start year is 2100, the year 99 will be 1022 * interpreted as 2199. 1023 * @param fmt The formatter to set. 1024 * @param d The year relative to which all 2-digit years will be interpreted. 1025 * @param status A pointer to an UErrorCode to receive any errors 1026 * @see udat_Set2DigitYearStart 1027 * @stable ICU 2.0 1028 */ 1029 U_STABLE void U_EXPORT2 1030 udat_set2DigitYearStart( UDateFormat *fmt, 1031 UDate d, 1032 UErrorCode *status); 1033 1034 /** 1035 * Extract the pattern from a UDateFormat. 1036 * The pattern will follow the pattern syntax rules. 1037 * @param fmt The formatter to query. 1038 * @param localized TRUE if the pattern should be localized, FALSE otherwise. 1039 * @param result A pointer to a buffer to receive the pattern. 1040 * @param resultLength The maximum size of result. 1041 * @param status A pointer to an UErrorCode to receive any errors 1042 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 1043 * @see udat_applyPattern 1044 * @stable ICU 2.0 1045 */ 1046 U_STABLE int32_t U_EXPORT2 1047 udat_toPattern( const UDateFormat *fmt, 1048 UBool localized, 1049 UChar *result, 1050 int32_t resultLength, 1051 UErrorCode *status); 1052 1053 /** 1054 * Set the pattern used by an UDateFormat. 1055 * The pattern should follow the pattern syntax rules. 1056 * @param format The formatter to set. 1057 * @param localized TRUE if the pattern is localized, FALSE otherwise. 1058 * @param pattern The new pattern 1059 * @param patternLength The length of pattern, or -1 if null-terminated. 1060 * @see udat_toPattern 1061 * @stable ICU 2.0 1062 */ 1063 U_STABLE void U_EXPORT2 1064 udat_applyPattern( UDateFormat *format, 1065 UBool localized, 1066 const UChar *pattern, 1067 int32_t patternLength); 1068 1069 /** 1070 * The possible types of date format symbols 1071 * @stable ICU 2.6 1072 */ 1073 typedef enum UDateFormatSymbolType { 1074 /** The era names, for example AD */ 1075 UDAT_ERAS, 1076 /** The month names, for example February */ 1077 UDAT_MONTHS, 1078 /** The short month names, for example Feb. */ 1079 UDAT_SHORT_MONTHS, 1080 /** The weekday names, for example Monday */ 1081 UDAT_WEEKDAYS, 1082 /** The short weekday names, for example Mon. */ 1083 UDAT_SHORT_WEEKDAYS, 1084 /** The AM/PM names, for example AM */ 1085 UDAT_AM_PMS, 1086 /** The localized characters */ 1087 UDAT_LOCALIZED_CHARS, 1088 /** The long era names, for example Anno Domini */ 1089 UDAT_ERA_NAMES, 1090 /** The narrow month names, for example F */ 1091 UDAT_NARROW_MONTHS, 1092 /** The narrow weekday names, for example N */ 1093 UDAT_NARROW_WEEKDAYS, 1094 /** Standalone context versions of months */ 1095 UDAT_STANDALONE_MONTHS, 1096 UDAT_STANDALONE_SHORT_MONTHS, 1097 UDAT_STANDALONE_NARROW_MONTHS, 1098 /** Standalone context versions of weekdays */ 1099 UDAT_STANDALONE_WEEKDAYS, 1100 UDAT_STANDALONE_SHORT_WEEKDAYS, 1101 UDAT_STANDALONE_NARROW_WEEKDAYS, 1102 /** The quarters, for example 1st Quarter */ 1103 UDAT_QUARTERS, 1104 /** The short quarter names, for example Q1 */ 1105 UDAT_SHORT_QUARTERS, 1106 /** Standalone context versions of quarters */ 1107 UDAT_STANDALONE_QUARTERS, 1108 UDAT_STANDALONE_SHORT_QUARTERS 1109 1110 } UDateFormatSymbolType; 1111 1112 struct UDateFormatSymbols; 1113 /** Date format symbols. 1114 * For usage in C programs. 1115 * @stable ICU 2.6 1116 */ 1117 typedef struct UDateFormatSymbols UDateFormatSymbols; 1118 1119 /** 1120 * Get the symbols associated with an UDateFormat. 1121 * The symbols are what a UDateFormat uses to represent locale-specific data, 1122 * for example month or day names. 1123 * @param fmt The formatter to query. 1124 * @param type The type of symbols to get. One of UDAT_ERAS, UDAT_MONTHS, UDAT_SHORT_MONTHS, 1125 * UDAT_WEEKDAYS, UDAT_SHORT_WEEKDAYS, UDAT_AM_PMS, or UDAT_LOCALIZED_CHARS 1126 * @param symbolIndex The desired symbol of type type. 1127 * @param result A pointer to a buffer to receive the pattern. 1128 * @param resultLength The maximum size of result. 1129 * @param status A pointer to an UErrorCode to receive any errors 1130 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 1131 * @see udat_countSymbols 1132 * @see udat_setSymbols 1133 * @stable ICU 2.0 1134 */ 1135 U_STABLE int32_t U_EXPORT2 1136 udat_getSymbols(const UDateFormat *fmt, 1137 UDateFormatSymbolType type, 1138 int32_t symbolIndex, 1139 UChar *result, 1140 int32_t resultLength, 1141 UErrorCode *status); 1142 1143 /** 1144 * Count the number of particular symbols for an UDateFormat. 1145 * This function is most useful as for detemining the loop termination condition 1146 * for calls to {@link #udat_getSymbols }. 1147 * @param fmt The formatter to query. 1148 * @param type The type of symbols to count. One of UDAT_ERAS, UDAT_MONTHS, UDAT_SHORT_MONTHS, 1149 * UDAT_WEEKDAYS, UDAT_SHORT_WEEKDAYS, UDAT_AM_PMS, or UDAT_LOCALIZED_CHARS 1150 * @return The number of symbols of type type. 1151 * @see udat_getSymbols 1152 * @see udat_setSymbols 1153 * @stable ICU 2.0 1154 */ 1155 U_STABLE int32_t U_EXPORT2 1156 udat_countSymbols( const UDateFormat *fmt, 1157 UDateFormatSymbolType type); 1158 1159 /** 1160 * Set the symbols associated with an UDateFormat. 1161 * The symbols are what a UDateFormat uses to represent locale-specific data, 1162 * for example month or day names. 1163 * @param format The formatter to set 1164 * @param type The type of symbols to set. One of UDAT_ERAS, UDAT_MONTHS, UDAT_SHORT_MONTHS, 1165 * UDAT_WEEKDAYS, UDAT_SHORT_WEEKDAYS, UDAT_AM_PMS, or UDAT_LOCALIZED_CHARS 1166 * @param symbolIndex The index of the symbol to set of type type. 1167 * @param value The new value 1168 * @param valueLength The length of value, or -1 if null-terminated 1169 * @param status A pointer to an UErrorCode to receive any errors 1170 * @see udat_getSymbols 1171 * @see udat_countSymbols 1172 * @stable ICU 2.0 1173 */ 1174 U_STABLE void U_EXPORT2 1175 udat_setSymbols( UDateFormat *format, 1176 UDateFormatSymbolType type, 1177 int32_t symbolIndex, 1178 UChar *value, 1179 int32_t valueLength, 1180 UErrorCode *status); 1181 1182 /** 1183 * Get the locale for this date format object. 1184 * You can choose between valid and actual locale. 1185 * @param fmt The formatter to get the locale from 1186 * @param type type of the locale we're looking for (valid or actual) 1187 * @param status error code for the operation 1188 * @return the locale name 1189 * @stable ICU 2.8 1190 */ 1191 U_STABLE const char* U_EXPORT2 1192 udat_getLocaleByType(const UDateFormat *fmt, 1193 ULocDataLocaleType type, 1194 UErrorCode* status); 1195 1196 #ifndef U_HIDE_INTERNAL_API 1197 /** 1198 * Set a particular UDisplayContext value in the formatter, such as 1199 * UDISPCTX_CAPITALIZATION_FOR_STANDALONE. 1200 * @param fmt The formatter for which to set a UDisplayContext value. 1201 * @param value The UDisplayContext value to set. 1202 * @param status A pointer to an UErrorCode to receive any errors 1203 * @internal ICU 50 technology preview 1204 */ 1205 U_INTERNAL void U_EXPORT2 1206 udat_setContext(UDateFormat* fmt, UDisplayContext value, UErrorCode* status); 1207 1208 /** 1209 * Get the formatter's UDisplayContext value for the specified UDisplayContextType, 1210 * such as UDISPCTX_TYPE_CAPITALIZATION. 1211 * @param fmt The formatter to query. 1212 * @param type The UDisplayContextType whose value to return 1213 * @param status A pointer to an UErrorCode to receive any errors 1214 * @return The UDisplayContextValue for the specified type. 1215 * @internal ICU 50 technology preview 1216 */ 1217 U_INTERNAL UDisplayContext U_EXPORT2 1218 udat_getContext(UDateFormat* fmt, UDisplayContextType type, UErrorCode* status); 1219 1220 #endif /* U_HIDE_INTERNAL_API */ 1221 1222 #ifndef U_HIDE_INTERNAL_API 1223 /** 1224 * Extract the date pattern from a UDateFormat set for relative date formatting. 1225 * The pattern will follow the pattern syntax rules. 1226 * @param fmt The formatter to query. 1227 * @param result A pointer to a buffer to receive the pattern. 1228 * @param resultLength The maximum size of result. 1229 * @param status A pointer to a UErrorCode to receive any errors 1230 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 1231 * @see udat_applyPatternRelative 1232 * @internal ICU 4.2 technology preview 1233 */ 1234 U_INTERNAL int32_t U_EXPORT2 1235 udat_toPatternRelativeDate(const UDateFormat *fmt, 1236 UChar *result, 1237 int32_t resultLength, 1238 UErrorCode *status); 1239 1240 /** 1241 * Extract the time pattern from a UDateFormat set for relative date formatting. 1242 * The pattern will follow the pattern syntax rules. 1243 * @param fmt The formatter to query. 1244 * @param result A pointer to a buffer to receive the pattern. 1245 * @param resultLength The maximum size of result. 1246 * @param status A pointer to a UErrorCode to receive any errors 1247 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 1248 * @see udat_applyPatternRelative 1249 * @internal ICU 4.2 technology preview 1250 */ 1251 U_INTERNAL int32_t U_EXPORT2 1252 udat_toPatternRelativeTime(const UDateFormat *fmt, 1253 UChar *result, 1254 int32_t resultLength, 1255 UErrorCode *status); 1256 1257 /** 1258 * Set the date & time patterns used by a UDateFormat set for relative date formatting. 1259 * The patterns should follow the pattern syntax rules. 1260 * @param format The formatter to set. 1261 * @param datePattern The new date pattern 1262 * @param datePatternLength The length of datePattern, or -1 if null-terminated. 1263 * @param timePattern The new time pattern 1264 * @param timePatternLength The length of timePattern, or -1 if null-terminated. 1265 * @param status A pointer to a UErrorCode to receive any errors 1266 * @see udat_toPatternRelativeDate, udat_toPatternRelativeTime 1267 * @internal ICU 4.2 technology preview 1268 */ 1269 U_INTERNAL void U_EXPORT2 1270 udat_applyPatternRelative(UDateFormat *format, 1271 const UChar *datePattern, 1272 int32_t datePatternLength, 1273 const UChar *timePattern, 1274 int32_t timePatternLength, 1275 UErrorCode *status); 1276 #endif /* U_HIDE_INTERNAL_API */ 1277 1278 /** 1279 * @internal 1280 * @see udat_open 1281 */ 1282 typedef UDateFormat* (U_EXPORT2 *UDateFormatOpener) (UDateFormatStyle timeStyle, 1283 UDateFormatStyle dateStyle, 1284 const char *locale, 1285 const UChar *tzID, 1286 int32_t tzIDLength, 1287 const UChar *pattern, 1288 int32_t patternLength, 1289 UErrorCode *status); 1290 1291 /** 1292 * Register a provider factory 1293 * @internal ICU 49 1294 */ 1295 U_INTERNAL void U_EXPORT2 1296 udat_registerOpener(UDateFormatOpener opener, UErrorCode *status); 1297 1298 /** 1299 * Un-Register a provider factory 1300 * @internal ICU 49 1301 */ 1302 U_INTERNAL UDateFormatOpener U_EXPORT2 1303 udat_unregisterOpener(UDateFormatOpener opener, UErrorCode *status); 1304 1305 1306 #endif /* #if !UCONFIG_NO_FORMATTING */ 1307 1308 #endif 1309