1 /* 2 ******************************************************************************* 3 * Copyright (C) 1996-2007, 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/ucal.h" 16 #include "unicode/unum.h" 17 /** 18 * \file 19 * \brief C API: DateFormat 20 * 21 * <h2> Date Format C API</h2> 22 * 23 * Date Format C API consists of functions that convert dates and 24 * times from their internal representations to textual form and back again in a 25 * language-independent manner. Converting from the internal representation (milliseconds 26 * since midnight, January 1, 1970) to text is known as "formatting," and converting 27 * from text to millis is known as "parsing." We currently define only one concrete 28 * structure UDateFormat, which can handle pretty much all normal 29 * date formatting and parsing actions. 30 * <P> 31 * Date Format helps you to format and parse dates for any locale. Your code can 32 * be completely independent of the locale conventions for months, days of the 33 * week, or even the calendar format: lunar vs. solar. 34 * <P> 35 * To format a date for the current Locale with default time and date style, 36 * use one of the static factory methods: 37 * <pre> 38 * \code 39 * UErrorCode status = U_ZERO_ERROR; 40 * UChar *myString; 41 * int32_t myStrlen = 0; 42 * UDateFormat* dfmt = udat_open(UDAT_DEFAULT, UDAT_DEFAULT, NULL, NULL, -1, NULL, -1, &status); 43 * myStrlen = udat_format(dfmt, myDate, NULL, myStrlen, NULL, &status); 44 * if (status==U_BUFFER_OVERFLOW_ERROR){ 45 * status=U_ZERO_ERROR; 46 * myString=(UChar*)malloc(sizeof(UChar) * (myStrlen+1) ); 47 * udat_format(dfmt, myDate, myString, myStrlen+1, NULL, &status); 48 * } 49 * \endcode 50 * </pre> 51 * If you are formatting multiple numbers, it is more efficient to get the 52 * format and use it multiple times so that the system doesn't have to fetch the 53 * information about the local language and country conventions multiple times. 54 * <pre> 55 * \code 56 * UErrorCode status = U_ZERO_ERROR; 57 * int32_t i, myStrlen = 0; 58 * UChar* myString; 59 * char buffer[1024]; 60 * UDate myDateArr[] = { 0.0, 100000000.0, 2000000000.0 }; // test values 61 * UDateFormat* df = udat_open(UDAT_DEFAULT, UDAT_DEFAULT, NULL, NULL, -1, NULL, 0, &status); 62 * for (i = 0; i < 3; i++) { 63 * myStrlen = udat_format(df, myDateArr[i], NULL, myStrlen, NULL, &status); 64 * if(status == U_BUFFER_OVERFLOW_ERROR){ 65 * status = U_ZERO_ERROR; 66 * myString = (UChar*)malloc(sizeof(UChar) * (myStrlen+1) ); 67 * udat_format(df, myDateArr[i], myString, myStrlen+1, NULL, &status); 68 * printf("%s\n", u_austrcpy(buffer, myString) ); 69 * free(myString); 70 * } 71 * } 72 * \endcode 73 * </pre> 74 * To get specific fields of a date, you can use UFieldPosition to 75 * get specific fields. 76 * <pre> 77 * \code 78 * UErrorCode status = U_ZERO_ERROR; 79 * UFieldPosition pos; 80 * UChar *myString; 81 * int32_t myStrlen = 0; 82 * char buffer[1024]; 83 * 84 * pos.field = 1; // Same as the DateFormat::EField enum 85 * UDateFormat* dfmt = udat_open(UDAT_DEFAULT, UDAT_DEFAULT, NULL, -1, NULL, 0, &status); 86 * myStrlen = udat_format(dfmt, myDate, NULL, myStrlen, &pos, &status); 87 * if (status==U_BUFFER_OVERFLOW_ERROR){ 88 * status=U_ZERO_ERROR; 89 * myString=(UChar*)malloc(sizeof(UChar) * (myStrlen+1) ); 90 * udat_format(dfmt, myDate, myString, myStrlen+1, &pos, &status); 91 * } 92 * printf("date format: %s\n", u_austrcpy(buffer, myString)); 93 * buffer[pos.endIndex] = 0; // NULL terminate the string. 94 * printf("UFieldPosition position equals %s\n", &buffer[pos.beginIndex]); 95 * \endcode 96 * </pre> 97 * To format a date for a different Locale, specify it in the call to 98 * udat_open() 99 * <pre> 100 * \code 101 * UDateFormat* df = udat_open(UDAT_SHORT, UDAT_SHORT, "fr_FR", NULL, -1, NULL, 0, &status); 102 * \endcode 103 * </pre> 104 * You can use a DateFormat API udat_parse() to parse. 105 * <pre> 106 * \code 107 * UErrorCode status = U_ZERO_ERROR; 108 * int32_t parsepos=0; 109 * UDate myDate = udat_parse(df, myString, u_strlen(myString), &parsepos, &status); 110 * \endcode 111 * </pre> 112 * You can pass in different options for the arguments for date and time style 113 * to control the length of the result; from SHORT to MEDIUM to LONG to FULL. 114 * The exact result depends on the locale, but generally: 115 * see UDateFormatStyle for more details 116 * <ul type=round> 117 * <li> UDAT_SHORT is completely numeric, such as 12/13/52 or 3:30pm 118 * <li> UDAT_MEDIUM is longer, such as Jan 12, 1952 119 * <li> UDAT_LONG is longer, such as January 12, 1952 or 3:30:32pm 120 * <li> UDAT_FULL is pretty completely specified, such as 121 * Tuesday, April 12, 1952 AD or 3:30:42pm PST. 122 * </ul> 123 * You can also set the time zone on the format if you wish. 124 * <P> 125 * You can also use forms of the parse and format methods with Parse Position and 126 * UFieldPosition to allow you to 127 * <ul type=round> 128 * <li> Progressively parse through pieces of a string. 129 * <li> Align any particular field, or find out where it is for selection 130 * on the screen. 131 * </ul> 132 */ 133 134 /** A date formatter. 135 * For usage in C programs. 136 * @stable ICU 2.6 137 */ 138 typedef void* UDateFormat; 139 140 /** The possible date/time format styles 141 * @stable ICU 2.6 142 */ 143 typedef enum UDateFormatStyle { 144 /** Full style */ 145 UDAT_FULL, 146 /** Long style */ 147 UDAT_LONG, 148 /** Medium style */ 149 UDAT_MEDIUM, 150 /** Short style */ 151 UDAT_SHORT, 152 /** Default style */ 153 UDAT_DEFAULT = UDAT_MEDIUM, 154 155 /** Bitfield for relative date */ 156 UDAT_RELATIVE = (1 << 7), 157 158 UDAT_FULL_RELATIVE = UDAT_FULL | UDAT_RELATIVE, 159 160 UDAT_LONG_RELATIVE = UDAT_LONG | UDAT_RELATIVE, 161 162 UDAT_MEDIUM_RELATIVE = UDAT_MEDIUM | UDAT_RELATIVE, 163 164 UDAT_SHORT_RELATIVE = UDAT_SHORT | UDAT_RELATIVE, 165 166 167 /** No style */ 168 UDAT_NONE = -1, 169 /** for internal API use only */ 170 UDAT_IGNORE = -2 171 172 } UDateFormatStyle; 173 174 /** 175 * FieldPosition and UFieldPosition selectors for format fields 176 * defined by DateFormat and UDateFormat. 177 * @stable ICU 3.0 178 */ 179 typedef enum UDateFormatField { 180 /** 181 * FieldPosition and UFieldPosition selector for 'G' field alignment, 182 * corresponding to the UCAL_ERA field. 183 * @stable ICU 3.0 184 */ 185 UDAT_ERA_FIELD = 0, 186 187 /** 188 * FieldPosition and UFieldPosition selector for 'y' field alignment, 189 * corresponding to the UCAL_YEAR field. 190 * @stable ICU 3.0 191 */ 192 UDAT_YEAR_FIELD = 1, 193 194 /** 195 * FieldPosition and UFieldPosition selector for 'M' field alignment, 196 * corresponding to the UCAL_MONTH field. 197 * @stable ICU 3.0 198 */ 199 UDAT_MONTH_FIELD = 2, 200 201 /** 202 * FieldPosition and UFieldPosition selector for 'd' field alignment, 203 * corresponding to the UCAL_DATE field. 204 * @stable ICU 3.0 205 */ 206 UDAT_DATE_FIELD = 3, 207 208 /** 209 * FieldPosition and UFieldPosition selector for 'k' field alignment, 210 * corresponding to the UCAL_HOUR_OF_DAY field. 211 * UDAT_HOUR_OF_DAY1_FIELD is used for the one-based 24-hour clock. 212 * For example, 23:59 + 01:00 results in 24:59. 213 * @stable ICU 3.0 214 */ 215 UDAT_HOUR_OF_DAY1_FIELD = 4, 216 217 /** 218 * FieldPosition and UFieldPosition selector for 'H' field alignment, 219 * corresponding to the UCAL_HOUR_OF_DAY field. 220 * UDAT_HOUR_OF_DAY0_FIELD is used for the zero-based 24-hour clock. 221 * For example, 23:59 + 01:00 results in 00:59. 222 * @stable ICU 3.0 223 */ 224 UDAT_HOUR_OF_DAY0_FIELD = 5, 225 226 /** 227 * FieldPosition and UFieldPosition selector for 'm' field alignment, 228 * corresponding to the UCAL_MINUTE field. 229 * @stable ICU 3.0 230 */ 231 UDAT_MINUTE_FIELD = 6, 232 233 /** 234 * FieldPosition and UFieldPosition selector for 's' field alignment, 235 * corresponding to the UCAL_SECOND field. 236 * @stable ICU 3.0 237 */ 238 UDAT_SECOND_FIELD = 7, 239 240 /** 241 * FieldPosition and UFieldPosition selector for 'S' field alignment, 242 * corresponding to the UCAL_MILLISECOND field. 243 * @stable ICU 3.0 244 */ 245 UDAT_FRACTIONAL_SECOND_FIELD = 8, 246 247 /** 248 * FieldPosition and UFieldPosition selector for 'E' field alignment, 249 * corresponding to the UCAL_DAY_OF_WEEK field. 250 * @stable ICU 3.0 251 */ 252 UDAT_DAY_OF_WEEK_FIELD = 9, 253 254 /** 255 * FieldPosition and UFieldPosition selector for 'D' field alignment, 256 * corresponding to the UCAL_DAY_OF_YEAR field. 257 * @stable ICU 3.0 258 */ 259 UDAT_DAY_OF_YEAR_FIELD = 10, 260 261 /** 262 * FieldPosition and UFieldPosition selector for 'F' field alignment, 263 * corresponding to the UCAL_DAY_OF_WEEK_IN_MONTH field. 264 * @stable ICU 3.0 265 */ 266 UDAT_DAY_OF_WEEK_IN_MONTH_FIELD = 11, 267 268 /** 269 * FieldPosition and UFieldPosition selector for 'w' field alignment, 270 * corresponding to the UCAL_WEEK_OF_YEAR field. 271 * @stable ICU 3.0 272 */ 273 UDAT_WEEK_OF_YEAR_FIELD = 12, 274 275 /** 276 * FieldPosition and UFieldPosition selector for 'W' field alignment, 277 * corresponding to the UCAL_WEEK_OF_MONTH field. 278 * @stable ICU 3.0 279 */ 280 UDAT_WEEK_OF_MONTH_FIELD = 13, 281 282 /** 283 * FieldPosition and UFieldPosition selector for 'a' field alignment, 284 * corresponding to the UCAL_AM_PM field. 285 * @stable ICU 3.0 286 */ 287 UDAT_AM_PM_FIELD = 14, 288 289 /** 290 * FieldPosition and UFieldPosition selector for 'h' field alignment, 291 * corresponding to the UCAL_HOUR field. 292 * UDAT_HOUR1_FIELD is used for the one-based 12-hour clock. 293 * For example, 11:30 PM + 1 hour results in 12:30 AM. 294 * @stable ICU 3.0 295 */ 296 UDAT_HOUR1_FIELD = 15, 297 298 /** 299 * FieldPosition and UFieldPosition selector for 'K' field alignment, 300 * corresponding to the UCAL_HOUR field. 301 * UDAT_HOUR0_FIELD is used for the zero-based 12-hour clock. 302 * For example, 11:30 PM + 1 hour results in 00:30 AM. 303 * @stable ICU 3.0 304 */ 305 UDAT_HOUR0_FIELD = 16, 306 307 /** 308 * FieldPosition and UFieldPosition selector for 'z' field alignment, 309 * corresponding to the UCAL_ZONE_OFFSET and 310 * UCAL_DST_OFFSET fields. 311 * @stable ICU 3.0 312 */ 313 UDAT_TIMEZONE_FIELD = 17, 314 315 /** 316 * FieldPosition and UFieldPosition selector for 'Y' field alignment, 317 * corresponding to the UCAL_YEAR_WOY field. 318 * @stable ICU 3.0 319 */ 320 UDAT_YEAR_WOY_FIELD = 18, 321 322 /** 323 * FieldPosition and UFieldPosition selector for 'e' field alignment, 324 * corresponding to the UCAL_DOW_LOCAL field. 325 * @stable ICU 3.0 326 */ 327 UDAT_DOW_LOCAL_FIELD = 19, 328 329 /** 330 * FieldPosition and UFieldPosition selector for 'u' field alignment, 331 * corresponding to the UCAL_EXTENDED_YEAR field. 332 * @stable ICU 3.0 333 */ 334 UDAT_EXTENDED_YEAR_FIELD = 20, 335 336 /** 337 * FieldPosition and UFieldPosition selector for 'g' field alignment, 338 * corresponding to the UCAL_JULIAN_DAY field. 339 * @stable ICU 3.0 340 */ 341 UDAT_JULIAN_DAY_FIELD = 21, 342 343 /** 344 * FieldPosition and UFieldPosition selector for 'A' field alignment, 345 * corresponding to the UCAL_MILLISECONDS_IN_DAY field. 346 * @stable ICU 3.0 347 */ 348 UDAT_MILLISECONDS_IN_DAY_FIELD = 22, 349 350 /** 351 * FieldPosition and UFieldPosition selector for 'Z' field alignment, 352 * corresponding to the UCAL_ZONE_OFFSET and 353 * UCAL_DST_OFFSET fields. 354 * @stable ICU 3.0 355 */ 356 UDAT_TIMEZONE_RFC_FIELD = 23, 357 358 /** 359 * FieldPosition and UFieldPosition selector for 'v' field alignment, 360 * corresponding to the UCAL_ZONE_OFFSET field. 361 * @stable ICU 3.4 362 */ 363 UDAT_TIMEZONE_GENERIC_FIELD = 24, 364 /** 365 * FieldPosition selector for 'c' field alignment, 366 * corresponding to the {@link #UCAL_DAY} field. 367 * This displays the stand alone day name, if available. 368 * @stable ICU 3.4 369 */ 370 UDAT_STANDALONE_DAY_FIELD = 25, 371 372 /** 373 * FieldPosition selector for 'L' field alignment, 374 * corresponding to the {@link #UCAL_MONTH} field. 375 * This displays the stand alone month name, if available. 376 * @stable ICU 3.4 377 */ 378 UDAT_STANDALONE_MONTH_FIELD = 26, 379 380 /** 381 * FieldPosition selector for "Q" field alignment, 382 * corresponding to quarters. This is implemented 383 * using the {@link #UCAL_MONTH} field. This 384 * displays the quarter. 385 * @stable ICU 3.6 386 */ 387 UDAT_QUARTER_FIELD = 27, 388 389 /** 390 * FieldPosition selector for the "q" field alignment, 391 * corresponding to stand-alone quarters. This is 392 * implemented using the {@link #UCAL_MONTH} field. 393 * This displays the stand-alone quarter. 394 * @stable ICU 3.6 395 */ 396 UDAT_STANDALONE_QUARTER_FIELD = 28, 397 398 /** 399 * FieldPosition and UFieldPosition selector for 'V' field alignment, 400 * corresponding to the UCAL_ZONE_OFFSET field. 401 * @stable ICU 3.8 402 */ 403 UDAT_TIMEZONE_SPECIAL_FIELD = 29, 404 405 /** 406 * Number of FieldPosition and UFieldPosition selectors for 407 * DateFormat and UDateFormat. 408 * Valid selectors range from 0 to UDAT_FIELD_COUNT-1. 409 * This value is subject to change if new fields are defined 410 * in the future. 411 * @stable ICU 3.0 412 */ 413 UDAT_FIELD_COUNT = 30 414 415 } UDateFormatField; 416 417 /** 418 * Open a new UDateFormat for formatting and parsing dates and times. 419 * A UDateFormat may be used to format dates in calls to {@link #udat_format }, 420 * and to parse dates in calls to {@link #udat_parse }. 421 * @param timeStyle The style used to format times; one of UDAT_FULL, UDAT_LONG, 422 * UDAT_MEDIUM, UDAT_SHORT, or UDAT_DEFAULT 423 * @param dateStyle The style used to format dates; one of UDAT_FULL, UDAT_LONG, 424 * UDAT_MEDIUM, UDAT_SHORT, or UDAT_DEFAULT 425 * @param locale The locale specifying the formatting conventions 426 * @param tzID A timezone ID specifying the timezone to use. If 0, use 427 * the default timezone. 428 * @param tzIDLength The length of tzID, or -1 if null-terminated. 429 * @param pattern A pattern specifying the format to use. 430 * @param patternLength The number of characters in the pattern, or -1 if null-terminated. 431 * @param status A pointer to an UErrorCode to receive any errors 432 * @return A pointer to a UDateFormat to use for formatting dates and times, or 0 if 433 * an error occurred. 434 * @stable ICU 2.0 435 */ 436 U_STABLE UDateFormat* U_EXPORT2 437 udat_open(UDateFormatStyle timeStyle, 438 UDateFormatStyle dateStyle, 439 const char *locale, 440 const UChar *tzID, 441 int32_t tzIDLength, 442 const UChar *pattern, 443 int32_t patternLength, 444 UErrorCode *status); 445 446 447 /** 448 * Close a UDateFormat. 449 * Once closed, a UDateFormat may no longer be used. 450 * @param format The formatter to close. 451 * @stable ICU 2.0 452 */ 453 U_STABLE void U_EXPORT2 454 udat_close(UDateFormat* format); 455 456 /** 457 * Open a copy of a UDateFormat. 458 * This function performs a deep copy. 459 * @param fmt The format to copy 460 * @param status A pointer to an UErrorCode to receive any errors. 461 * @return A pointer to a UDateFormat identical to fmt. 462 * @stable ICU 2.0 463 */ 464 U_STABLE UDateFormat* U_EXPORT2 465 udat_clone(const UDateFormat *fmt, 466 UErrorCode *status); 467 468 /** 469 * Format a date using an UDateFormat. 470 * The date will be formatted using the conventions specified in {@link #udat_open } 471 * @param format The formatter to use 472 * @param dateToFormat The date to format 473 * @param result A pointer to a buffer to receive the formatted number. 474 * @param resultLength The maximum size of result. 475 * @param position A pointer to a UFieldPosition. On input, position->field 476 * is read. On output, position->beginIndex and position->endIndex indicate 477 * the beginning and ending indices of field number position->field, if such 478 * a field exists. This parameter may be NULL, in which case no field 479 * position data is returned. 480 * @param status A pointer to an UErrorCode to receive any errors 481 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 482 * @see udat_parse 483 * @see UFieldPosition 484 * @stable ICU 2.0 485 */ 486 U_STABLE int32_t U_EXPORT2 487 udat_format( const UDateFormat* format, 488 UDate dateToFormat, 489 UChar* result, 490 int32_t resultLength, 491 UFieldPosition* position, 492 UErrorCode* status); 493 494 /** 495 * Parse a string into an date/time using a UDateFormat. 496 * The date will be parsed using the conventions specified in {@link #udat_open } 497 * @param format The formatter to use. 498 * @param text The text to parse. 499 * @param textLength The length of text, or -1 if null-terminated. 500 * @param parsePos If not 0, on input a pointer to an integer specifying the offset at which 501 * to begin parsing. If not 0, on output the offset at which parsing ended. 502 * @param status A pointer to an UErrorCode to receive any errors 503 * @return The value of the parsed date/time 504 * @see udat_format 505 * @stable ICU 2.0 506 */ 507 U_STABLE UDate U_EXPORT2 508 udat_parse( const UDateFormat* format, 509 const UChar* text, 510 int32_t textLength, 511 int32_t *parsePos, 512 UErrorCode *status); 513 514 /** 515 * Parse a string into an date/time using a UDateFormat. 516 * The date will be parsed using the conventions specified in {@link #udat_open } 517 * @param format The formatter to use. 518 * @param calendar The calendar in which to store the parsed data. 519 * @param text The text to parse. 520 * @param textLength The length of text, or -1 if null-terminated. 521 * @param parsePos If not 0, on input a pointer to an integer specifying the offset at which 522 * to begin parsing. If not 0, on output the offset at which parsing ended. 523 * @param status A pointer to an UErrorCode to receive any errors 524 * @see udat_format 525 * @stable ICU 2.0 526 */ 527 U_STABLE void U_EXPORT2 528 udat_parseCalendar(const UDateFormat* format, 529 UCalendar* calendar, 530 const UChar* text, 531 int32_t textLength, 532 int32_t *parsePos, 533 UErrorCode *status); 534 535 /** 536 * Determine if an UDateFormat will perform lenient parsing. 537 * With lenient parsing, the parser may use heuristics to interpret inputs that do not 538 * precisely match the pattern. With strict parsing, inputs must match the pattern. 539 * @param fmt The formatter to query 540 * @return TRUE if fmt is set to perform lenient parsing, FALSE otherwise. 541 * @see udat_setLenient 542 * @stable ICU 2.0 543 */ 544 U_STABLE UBool U_EXPORT2 545 udat_isLenient(const UDateFormat* fmt); 546 547 /** 548 * Specify whether an UDateFormat will perform lenient parsing. 549 * With lenient parsing, the parser may use heuristics to interpret inputs that do not 550 * precisely match the pattern. With strict parsing, inputs must match the pattern. 551 * @param fmt The formatter to set 552 * @param isLenient TRUE if fmt should perform lenient parsing, FALSE otherwise. 553 * @see dat_isLenient 554 * @stable ICU 2.0 555 */ 556 U_STABLE void U_EXPORT2 557 udat_setLenient( UDateFormat* fmt, 558 UBool isLenient); 559 560 /** 561 * Get the UCalendar associated with an UDateFormat. 562 * A UDateFormat uses a UCalendar to convert a raw value to, for example, 563 * the day of the week. 564 * @param fmt The formatter to query. 565 * @return A pointer to the UCalendar used by fmt. 566 * @see udat_setCalendar 567 * @stable ICU 2.0 568 */ 569 U_STABLE const UCalendar* U_EXPORT2 570 udat_getCalendar(const UDateFormat* fmt); 571 572 /** 573 * Set the UCalendar associated with an UDateFormat. 574 * A UDateFormat uses a UCalendar to convert a raw value to, for example, 575 * the day of the week. 576 * @param fmt The formatter to set. 577 * @param calendarToSet A pointer to an UCalendar to be used by fmt. 578 * @see udat_setCalendar 579 * @stable ICU 2.0 580 */ 581 U_STABLE void U_EXPORT2 582 udat_setCalendar( UDateFormat* fmt, 583 const UCalendar* calendarToSet); 584 585 /** 586 * Get the UNumberFormat associated with an UDateFormat. 587 * A UDateFormat uses a UNumberFormat to format numbers within a date, 588 * for example the day number. 589 * @param fmt The formatter to query. 590 * @return A pointer to the UNumberFormat used by fmt to format numbers. 591 * @see udat_setNumberFormat 592 * @stable ICU 2.0 593 */ 594 U_STABLE const UNumberFormat* U_EXPORT2 595 udat_getNumberFormat(const UDateFormat* fmt); 596 597 /** 598 * Set the UNumberFormat associated with an UDateFormat. 599 * A UDateFormat uses a UNumberFormat to format numbers within a date, 600 * for example the day number. 601 * @param fmt The formatter to set. 602 * @param numberFormatToSet A pointer to the UNumberFormat to be used by fmt to format numbers. 603 * @see udat_getNumberFormat 604 * @stable ICU 2.0 605 */ 606 U_STABLE void U_EXPORT2 607 udat_setNumberFormat( UDateFormat* fmt, 608 const UNumberFormat* numberFormatToSet); 609 610 /** 611 * Get a locale for which date/time formatting patterns are available. 612 * A UDateFormat in a locale returned by this function will perform the correct 613 * formatting and parsing for the locale. 614 * @param index The index of the desired locale. 615 * @return A locale for which date/time formatting patterns are available, or 0 if none. 616 * @see udat_countAvailable 617 * @stable ICU 2.0 618 */ 619 U_STABLE const char* U_EXPORT2 620 udat_getAvailable(int32_t index); 621 622 /** 623 * Determine how many locales have date/time formatting patterns available. 624 * This function is most useful as determining the loop ending condition for 625 * calls to {@link #udat_getAvailable }. 626 * @return The number of locales for which date/time formatting patterns are available. 627 * @see udat_getAvailable 628 * @stable ICU 2.0 629 */ 630 U_STABLE int32_t U_EXPORT2 631 udat_countAvailable(void); 632 633 /** 634 * Get the year relative to which all 2-digit years are interpreted. 635 * For example, if the 2-digit start year is 2100, the year 99 will be 636 * interpreted as 2199. 637 * @param fmt The formatter to query. 638 * @param status A pointer to an UErrorCode to receive any errors 639 * @return The year relative to which all 2-digit years are interpreted. 640 * @see udat_Set2DigitYearStart 641 * @stable ICU 2.0 642 */ 643 U_STABLE UDate U_EXPORT2 644 udat_get2DigitYearStart( const UDateFormat *fmt, 645 UErrorCode *status); 646 647 /** 648 * Set the year relative to which all 2-digit years will be interpreted. 649 * For example, if the 2-digit start year is 2100, the year 99 will be 650 * interpreted as 2199. 651 * @param fmt The formatter to set. 652 * @param d The year relative to which all 2-digit years will be interpreted. 653 * @param status A pointer to an UErrorCode to receive any errors 654 * @see udat_Set2DigitYearStart 655 * @stable ICU 2.0 656 */ 657 U_STABLE void U_EXPORT2 658 udat_set2DigitYearStart( UDateFormat *fmt, 659 UDate d, 660 UErrorCode *status); 661 662 /** 663 * Extract the pattern from a UDateFormat. 664 * The pattern will follow the pattern syntax rules. 665 * @param fmt The formatter to query. 666 * @param localized TRUE if the pattern should be localized, FALSE otherwise. 667 * @param result A pointer to a buffer to receive the pattern. 668 * @param resultLength The maximum size of result. 669 * @param status A pointer to an UErrorCode to receive any errors 670 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 671 * @see udat_applyPattern 672 * @stable ICU 2.0 673 */ 674 U_STABLE int32_t U_EXPORT2 675 udat_toPattern( const UDateFormat *fmt, 676 UBool localized, 677 UChar *result, 678 int32_t resultLength, 679 UErrorCode *status); 680 681 /** 682 * Set the pattern used by an UDateFormat. 683 * The pattern should follow the pattern syntax rules. 684 * @param format The formatter to set. 685 * @param localized TRUE if the pattern is localized, FALSE otherwise. 686 * @param pattern The new pattern 687 * @param patternLength The length of pattern, or -1 if null-terminated. 688 * @see udat_toPattern 689 * @stable ICU 2.0 690 */ 691 U_STABLE void U_EXPORT2 692 udat_applyPattern( UDateFormat *format, 693 UBool localized, 694 const UChar *pattern, 695 int32_t patternLength); 696 697 /** 698 * The possible types of date format symbols 699 * @stable ICU 2.6 700 */ 701 typedef enum UDateFormatSymbolType { 702 /** The era names, for example AD */ 703 UDAT_ERAS, 704 /** The month names, for example February */ 705 UDAT_MONTHS, 706 /** The short month names, for example Feb. */ 707 UDAT_SHORT_MONTHS, 708 /** The weekday names, for example Monday */ 709 UDAT_WEEKDAYS, 710 /** The short weekday names, for example Mon. */ 711 UDAT_SHORT_WEEKDAYS, 712 /** The AM/PM names, for example AM */ 713 UDAT_AM_PMS, 714 /** The localized characters */ 715 UDAT_LOCALIZED_CHARS, 716 /** The long era names, for example Anno Domini */ 717 UDAT_ERA_NAMES, 718 /** The narrow month names, for example F */ 719 UDAT_NARROW_MONTHS, 720 /** The narrow weekday names, for example N */ 721 UDAT_NARROW_WEEKDAYS, 722 /** Standalone context versions of months */ 723 UDAT_STANDALONE_MONTHS, 724 UDAT_STANDALONE_SHORT_MONTHS, 725 UDAT_STANDALONE_NARROW_MONTHS, 726 /** Standalone context versions of weekdays */ 727 UDAT_STANDALONE_WEEKDAYS, 728 UDAT_STANDALONE_SHORT_WEEKDAYS, 729 UDAT_STANDALONE_NARROW_WEEKDAYS, 730 /** The quarters, for example 1st Quarter */ 731 UDAT_QUARTERS, 732 /** The short quarter names, for example Q1 */ 733 UDAT_SHORT_QUARTERS, 734 /** Standalone context versions of quarters */ 735 UDAT_STANDALONE_QUARTERS, 736 UDAT_STANDALONE_SHORT_QUARTERS 737 738 } UDateFormatSymbolType; 739 740 struct UDateFormatSymbols; 741 /** Date format symbols. 742 * For usage in C programs. 743 * @stable ICU 2.6 744 */ 745 typedef struct UDateFormatSymbols UDateFormatSymbols; 746 747 /** 748 * Get the symbols associated with an UDateFormat. 749 * The symbols are what a UDateFormat uses to represent locale-specific data, 750 * for example month or day names. 751 * @param fmt The formatter to query. 752 * @param type The type of symbols to get. One of UDAT_ERAS, UDAT_MONTHS, UDAT_SHORT_MONTHS, 753 * UDAT_WEEKDAYS, UDAT_SHORT_WEEKDAYS, UDAT_AM_PMS, or UDAT_LOCALIZED_CHARS 754 * @param index The desired symbol of type type. 755 * @param result A pointer to a buffer to receive the pattern. 756 * @param resultLength The maximum size of result. 757 * @param status A pointer to an UErrorCode to receive any errors 758 * @return The total buffer size needed; if greater than resultLength, the output was truncated. 759 * @see udat_countSymbols 760 * @see udat_setSymbols 761 * @stable ICU 2.0 762 */ 763 U_STABLE int32_t U_EXPORT2 764 udat_getSymbols(const UDateFormat *fmt, 765 UDateFormatSymbolType type, 766 int32_t index, 767 UChar *result, 768 int32_t resultLength, 769 UErrorCode *status); 770 771 /** 772 * Count the number of particular symbols for an UDateFormat. 773 * This function is most useful as for detemining the loop termination condition 774 * for calls to {@link #udat_getSymbols }. 775 * @param fmt The formatter to query. 776 * @param type The type of symbols to count. One of UDAT_ERAS, UDAT_MONTHS, UDAT_SHORT_MONTHS, 777 * UDAT_WEEKDAYS, UDAT_SHORT_WEEKDAYS, UDAT_AM_PMS, or UDAT_LOCALIZED_CHARS 778 * @return The number of symbols of type type. 779 * @see udat_getSymbols 780 * @see udat_setSymbols 781 * @stable ICU 2.0 782 */ 783 U_STABLE int32_t U_EXPORT2 784 udat_countSymbols( const UDateFormat *fmt, 785 UDateFormatSymbolType type); 786 787 /** 788 * Set the symbols associated with an UDateFormat. 789 * The symbols are what a UDateFormat uses to represent locale-specific data, 790 * for example month or day names. 791 * @param format The formatter to set 792 * @param type The type of symbols to set. One of UDAT_ERAS, UDAT_MONTHS, UDAT_SHORT_MONTHS, 793 * UDAT_WEEKDAYS, UDAT_SHORT_WEEKDAYS, UDAT_AM_PMS, or UDAT_LOCALIZED_CHARS 794 * @param index The index of the symbol to set of type type. 795 * @param value The new value 796 * @param valueLength The length of value, or -1 if null-terminated 797 * @param status A pointer to an UErrorCode to receive any errors 798 * @see udat_getSymbols 799 * @see udat_countSymbols 800 * @stable ICU 2.0 801 */ 802 U_STABLE void U_EXPORT2 803 udat_setSymbols( UDateFormat *format, 804 UDateFormatSymbolType type, 805 int32_t index, 806 UChar *value, 807 int32_t valueLength, 808 UErrorCode *status); 809 810 /** 811 * Get the locale for this date format object. 812 * You can choose between valid and actual locale. 813 * @param fmt The formatter to get the locale from 814 * @param type type of the locale we're looking for (valid or actual) 815 * @param status error code for the operation 816 * @return the locale name 817 * @stable ICU 2.8 818 */ 819 U_STABLE const char* U_EXPORT2 820 udat_getLocaleByType(const UDateFormat *fmt, 821 ULocDataLocaleType type, 822 UErrorCode* status); 823 824 #endif /* #if !UCONFIG_NO_FORMATTING */ 825 826 #endif 827