dtitvfmt.h revision c73f511526464f8e56c242df80552e9b0d94ae3d
1/******************************************************************************** 2* Copyright (C) 2008-2013, International Business Machines Corporation and 3* others. All Rights Reserved. 4******************************************************************************* 5* 6* File DTITVFMT.H 7* 8******************************************************************************* 9*/ 10 11#ifndef __DTITVFMT_H__ 12#define __DTITVFMT_H__ 13 14 15#include "unicode/utypes.h" 16 17/** 18 * \file 19 * \brief C++ API: Format and parse date interval in a language-independent manner. 20 */ 21 22#if !UCONFIG_NO_FORMATTING 23 24#include "unicode/ucal.h" 25#include "unicode/smpdtfmt.h" 26#include "unicode/dtintrv.h" 27#include "unicode/dtitvinf.h" 28#include "unicode/dtptngen.h" 29 30U_NAMESPACE_BEGIN 31 32 33 34/** 35 * DateIntervalFormat is a class for formatting and parsing date 36 * intervals in a language-independent manner. 37 * Only formatting is supported, parsing is not supported. 38 * 39 * <P> 40 * Date interval means from one date to another date, 41 * for example, from "Jan 11, 2008" to "Jan 18, 2008". 42 * We introduced class DateInterval to represent it. 43 * DateInterval is a pair of UDate, which is 44 * the standard milliseconds since 24:00 GMT, Jan 1, 1970. 45 * 46 * <P> 47 * DateIntervalFormat formats a DateInterval into 48 * text as compactly as possible. 49 * For example, the date interval format from "Jan 11, 2008" to "Jan 18,. 2008" 50 * is "Jan 11-18, 2008" for English. 51 * And it parses text into DateInterval, 52 * although initially, parsing is not supported. 53 * 54 * <P> 55 * There is no structural information in date time patterns. 56 * For any punctuations and string literals inside a date time pattern, 57 * we do not know whether it is just a separator, or a prefix, or a suffix. 58 * Without such information, so, it is difficult to generate a sub-pattern 59 * (or super-pattern) by algorithm. 60 * So, formatting a DateInterval is pattern-driven. It is very 61 * similar to formatting in SimpleDateFormat. 62 * We introduce class DateIntervalInfo to save date interval 63 * patterns, similar to date time pattern in SimpleDateFormat. 64 * 65 * <P> 66 * Logically, the interval patterns are mappings 67 * from (skeleton, the_largest_different_calendar_field) 68 * to (date_interval_pattern). 69 * 70 * <P> 71 * A skeleton 72 * <ol> 73 * <li> 74 * only keeps the field pattern letter and ignores all other parts 75 * in a pattern, such as space, punctuations, and string literals. 76 * </li> 77 * <li> 78 * hides the order of fields. 79 * </li> 80 * <li> 81 * might hide a field's pattern letter length. 82 * </li> 83 * </ol> 84 * 85 * For those non-digit calendar fields, the pattern letter length is 86 * important, such as MMM, MMMM, and MMMMM; EEE and EEEE, 87 * and the field's pattern letter length is honored. 88 * 89 * For the digit calendar fields, such as M or MM, d or dd, yy or yyyy, 90 * the field pattern length is ignored and the best match, which is defined 91 * in date time patterns, will be returned without honor the field pattern 92 * letter length in skeleton. 93 * 94 * <P> 95 * The calendar fields we support for interval formatting are: 96 * year, month, date, day-of-week, am-pm, hour, hour-of-day, and minute. 97 * Those calendar fields can be defined in the following order: 98 * year > month > date > hour (in day) > minute 99 * 100 * The largest different calendar fields between 2 calendars is the 101 * first different calendar field in above order. 102 * 103 * For example: the largest different calendar fields between "Jan 10, 2007" 104 * and "Feb 20, 2008" is year. 105 * 106 * <P> 107 * For other calendar fields, the compact interval formatting is not 108 * supported. And the interval format will be fall back to fall-back 109 * patterns, which is mostly "{date0} - {date1}". 110 * 111 * <P> 112 * There is a set of pre-defined static skeleton strings. 113 * There are pre-defined interval patterns for those pre-defined skeletons 114 * in locales' resource files. 115 * For example, for a skeleton UDAT_YEAR_ABBR_MONTH_DAY, which is "yMMMd", 116 * in en_US, if the largest different calendar field between date1 and date2 117 * is "year", the date interval pattern is "MMM d, yyyy - MMM d, yyyy", 118 * such as "Jan 10, 2007 - Jan 10, 2008". 119 * If the largest different calendar field between date1 and date2 is "month", 120 * the date interval pattern is "MMM d - MMM d, yyyy", 121 * such as "Jan 10 - Feb 10, 2007". 122 * If the largest different calendar field between date1 and date2 is "day", 123 * the date interval pattern is "MMM d-d, yyyy", such as "Jan 10-20, 2007". 124 * 125 * For date skeleton, the interval patterns when year, or month, or date is 126 * different are defined in resource files. 127 * For time skeleton, the interval patterns when am/pm, or hour, or minute is 128 * different are defined in resource files. 129 * 130 * <P> 131 * If a skeleton is not found in a locale's DateIntervalInfo, which means 132 * the interval patterns for the skeleton is not defined in resource file, 133 * the interval pattern will falls back to the interval "fallback" pattern 134 * defined in resource file. 135 * If the interval "fallback" pattern is not defined, the default fall-back 136 * is "{date0} - {data1}". 137 * 138 * <P> 139 * For the combination of date and time, 140 * The rule to generate interval patterns are: 141 * <ol> 142 * <li> 143 * when the year, month, or day differs, falls back to fall-back 144 * interval pattern, which mostly is the concatenate the two original 145 * expressions with a separator between, 146 * For example, interval pattern from "Jan 10, 2007 10:10 am" 147 * to "Jan 11, 2007 10:10am" is 148 * "Jan 10, 2007 10:10 am - Jan 11, 2007 10:10am" 149 * </li> 150 * <li> 151 * otherwise, present the date followed by the range expression 152 * for the time. 153 * For example, interval pattern from "Jan 10, 2007 10:10 am" 154 * to "Jan 10, 2007 11:10am" is "Jan 10, 2007 10:10 am - 11:10am" 155 * </li> 156 * </ol> 157 * 158 * 159 * <P> 160 * If two dates are the same, the interval pattern is the single date pattern. 161 * For example, interval pattern from "Jan 10, 2007" to "Jan 10, 2007" is 162 * "Jan 10, 2007". 163 * 164 * Or if the presenting fields between 2 dates have the exact same values, 165 * the interval pattern is the single date pattern. 166 * For example, if user only requests year and month, 167 * the interval pattern from "Jan 10, 2007" to "Jan 20, 2007" is "Jan 2007". 168 * 169 * <P> 170 * DateIntervalFormat needs the following information for correct 171 * formatting: time zone, calendar type, pattern, date format symbols, 172 * and date interval patterns. 173 * It can be instantiated in 2 ways: 174 * <ol> 175 * <li> 176 * create an instance using default or given locale plus given skeleton. 177 * Users are encouraged to created date interval formatter this way and 178 * to use the pre-defined skeleton macros, such as 179 * UDAT_YEAR_NUM_MONTH, which consists the calendar fields and 180 * the format style. 181 * </li> 182 * <li> 183 * create an instance using default or given locale plus given skeleton 184 * plus a given DateIntervalInfo. 185 * This factory method is for powerful users who want to provide their own 186 * interval patterns. 187 * Locale provides the timezone, calendar, and format symbols information. 188 * Local plus skeleton provides full pattern information. 189 * DateIntervalInfo provides the date interval patterns. 190 * </li> 191 * </ol> 192 * 193 * <P> 194 * For the calendar field pattern letter, such as G, y, M, d, a, h, H, m, s etc. 195 * DateIntervalFormat uses the same syntax as that of 196 * DateTime format. 197 * 198 * <P> 199 * Code Sample: general usage 200 * <pre> 201 * \code 202 * // the date interval object which the DateIntervalFormat formats on 203 * // and parses into 204 * DateInterval* dtInterval = new DateInterval(1000*3600*24, 1000*3600*24*2); 205 * UErrorCode status = U_ZERO_ERROR; 206 * DateIntervalFormat* dtIntervalFmt = DateIntervalFormat::createInstance( 207 * UDAT_YEAR_MONTH_DAY, 208 * Locale("en", "GB", ""), status); 209 * UnicodeUnicodeString dateIntervalString; 210 * FieldPosition pos = 0; 211 * // formatting 212 * dtIntervalFmt->format(dtInterval, dateIntervalUnicodeString, pos, status); 213 * delete dtIntervalFmt; 214 * \endcode 215 * </pre> 216 */ 217 218class U_I18N_API DateIntervalFormat : public Format { 219public: 220 221 /** 222 * Construct a DateIntervalFormat from skeleton and the default locale. 223 * 224 * This is a convenient override of 225 * createInstance(const UnicodeString& skeleton, const Locale& locale, 226 * UErrorCode&) 227 * with the value of locale as default locale. 228 * 229 * @param skeleton the skeleton on which interval format based. 230 * @param status output param set to success/failure code on exit 231 * @return a date time interval formatter which the caller owns. 232 * @stable ICU 4.0 233 */ 234 static DateIntervalFormat* U_EXPORT2 createInstance( 235 const UnicodeString& skeleton, 236 UErrorCode& status); 237 238 /** 239 * Construct a DateIntervalFormat from skeleton and a given locale. 240 * <P> 241 * In this factory method, 242 * the date interval pattern information is load from resource files. 243 * Users are encouraged to created date interval formatter this way and 244 * to use the pre-defined skeleton macros. 245 * 246 * <P> 247 * There are pre-defined skeletons (defined in udate.h) having predefined 248 * interval patterns in resource files. 249 * Users are encouraged to use those macros. 250 * For example: 251 * DateIntervalFormat::createInstance(UDAT_MONTH_DAY, status) 252 * 253 * The given Locale provides the interval patterns. 254 * For example, for en_GB, if skeleton is UDAT_YEAR_ABBR_MONTH_WEEKDAY_DAY, 255 * which is "yMMMEEEd", 256 * the interval patterns defined in resource file to above skeleton are: 257 * "EEE, d MMM, yyyy - EEE, d MMM, yyyy" for year differs, 258 * "EEE, d MMM - EEE, d MMM, yyyy" for month differs, 259 * "EEE, d - EEE, d MMM, yyyy" for day differs, 260 * @param skeleton the skeleton on which the interval format is based. 261 * @param locale the given locale 262 * @param status output param set to success/failure code on exit 263 * @return a date time interval formatter which the caller owns. 264 * @stable ICU 4.0 265 * <p> 266 * <h4>Sample code</h4> 267 * \snippet samples/dtitvfmtsample/dtitvfmtsample.cpp dtitvfmtPreDefined1 268 * \snippet samples/dtitvfmtsample/dtitvfmtsample.cpp dtitvfmtPreDefined 269 * <p> 270 */ 271 272 static DateIntervalFormat* U_EXPORT2 createInstance( 273 const UnicodeString& skeleton, 274 const Locale& locale, 275 UErrorCode& status); 276 277 /** 278 * Construct a DateIntervalFormat from skeleton 279 * DateIntervalInfo, and default locale. 280 * 281 * This is a convenient override of 282 * createInstance(const UnicodeString& skeleton, const Locale& locale, 283 * const DateIntervalInfo& dtitvinf, UErrorCode&) 284 * with the locale value as default locale. 285 * 286 * @param skeleton the skeleton on which interval format based. 287 * @param dtitvinf the DateIntervalInfo object. 288 * @param status output param set to success/failure code on exit 289 * @return a date time interval formatter which the caller owns. 290 * @stable ICU 4.0 291 */ 292 static DateIntervalFormat* U_EXPORT2 createInstance( 293 const UnicodeString& skeleton, 294 const DateIntervalInfo& dtitvinf, 295 UErrorCode& status); 296 297 /** 298 * Construct a DateIntervalFormat from skeleton 299 * a DateIntervalInfo, and the given locale. 300 * 301 * <P> 302 * In this factory method, user provides its own date interval pattern 303 * information, instead of using those pre-defined data in resource file. 304 * This factory method is for powerful users who want to provide their own 305 * interval patterns. 306 * <P> 307 * There are pre-defined skeletons (defined in udate.h) having predefined 308 * interval patterns in resource files. 309 * Users are encouraged to use those macros. 310 * For example: 311 * DateIntervalFormat::createInstance(UDAT_MONTH_DAY, status) 312 * 313 * The DateIntervalInfo provides the interval patterns. 314 * and the DateIntervalInfo ownership remains to the caller. 315 * 316 * User are encouraged to set default interval pattern in DateIntervalInfo 317 * as well, if they want to set other interval patterns ( instead of 318 * reading the interval patterns from resource files). 319 * When the corresponding interval pattern for a largest calendar different 320 * field is not found ( if user not set it ), interval format fallback to 321 * the default interval pattern. 322 * If user does not provide default interval pattern, it fallback to 323 * "{date0} - {date1}" 324 * 325 * @param skeleton the skeleton on which interval format based. 326 * @param locale the given locale 327 * @param dtitvinf the DateIntervalInfo object. 328 * @param status output param set to success/failure code on exit 329 * @return a date time interval formatter which the caller owns. 330 * @stable ICU 4.0 331 * <p> 332 * <h4>Sample code</h4> 333 * \snippet samples/dtitvfmtsample/dtitvfmtsample.cpp dtitvfmtPreDefined1 334 * \snippet samples/dtitvfmtsample/dtitvfmtsample.cpp dtitvfmtCustomized 335 * <p> 336 */ 337 static DateIntervalFormat* U_EXPORT2 createInstance( 338 const UnicodeString& skeleton, 339 const Locale& locale, 340 const DateIntervalInfo& dtitvinf, 341 UErrorCode& status); 342 343 /** 344 * Destructor. 345 * @stable ICU 4.0 346 */ 347 virtual ~DateIntervalFormat(); 348 349 /** 350 * Clone this Format object polymorphically. The caller owns the result and 351 * should delete it when done. 352 * @return A copy of the object. 353 * @stable ICU 4.0 354 */ 355 virtual Format* clone(void) const; 356 357 /** 358 * Return true if the given Format objects are semantically equal. Objects 359 * of different subclasses are considered unequal. 360 * @param other the object to be compared with. 361 * @return true if the given Format objects are semantically equal. 362 * @stable ICU 4.0 363 */ 364 virtual UBool operator==(const Format& other) const; 365 366 /** 367 * Return true if the given Format objects are not semantically equal. 368 * Objects of different subclasses are considered unequal. 369 * @param other the object to be compared with. 370 * @return true if the given Format objects are not semantically equal. 371 * @stable ICU 4.0 372 */ 373 UBool operator!=(const Format& other) const; 374 375 376 using Format::format; 377 378 /** 379 * Format an object to produce a string. This method handles Formattable 380 * objects with a DateInterval type. 381 * If a the Formattable object type is not a DateInterval, 382 * then it returns a failing UErrorCode. 383 * 384 * @param obj The object to format. 385 * Must be a DateInterval. 386 * @param appendTo Output parameter to receive result. 387 * Result is appended to existing contents. 388 * @param fieldPosition On input: an alignment field, if desired. 389 * On output: the offsets of the alignment field. 390 * @param status Output param filled with success/failure status. 391 * @return Reference to 'appendTo' parameter. 392 * @stable ICU 4.0 393 */ 394 virtual UnicodeString& format(const Formattable& obj, 395 UnicodeString& appendTo, 396 FieldPosition& fieldPosition, 397 UErrorCode& status) const ; 398 399 400 401 /** 402 * Format a DateInterval to produce a string. 403 * 404 * @param dtInterval DateInterval to be formatted. 405 * @param appendTo Output parameter to receive result. 406 * Result is appended to existing contents. 407 * @param fieldPosition On input: an alignment field, if desired. 408 * On output: the offsets of the alignment field. 409 * @param status Output param filled with success/failure status. 410 * @return Reference to 'appendTo' parameter. 411 * @stable ICU 4.0 412 */ 413 UnicodeString& format(const DateInterval* dtInterval, 414 UnicodeString& appendTo, 415 FieldPosition& fieldPosition, 416 UErrorCode& status) const ; 417 418 419 /** 420 * Format 2 Calendars to produce a string. 421 * 422 * Note: "fromCalendar" and "toCalendar" are not const, 423 * since calendar is not const in SimpleDateFormat::format(Calendar&), 424 * 425 * @param fromCalendar calendar set to the from date in date interval 426 * to be formatted into date interval string 427 * @param toCalendar calendar set to the to date in date interval 428 * to be formatted into date interval string 429 * @param appendTo Output parameter to receive result. 430 * Result is appended to existing contents. 431 * @param fieldPosition On input: an alignment field, if desired. 432 * On output: the offsets of the alignment field. 433 * @param status Output param filled with success/failure status. 434 * Caller needs to make sure it is SUCCESS 435 * at the function entrance 436 * @return Reference to 'appendTo' parameter. 437 * @stable ICU 4.0 438 */ 439 UnicodeString& format(Calendar& fromCalendar, 440 Calendar& toCalendar, 441 UnicodeString& appendTo, 442 FieldPosition& fieldPosition, 443 UErrorCode& status) const ; 444 445 /** 446 * Date interval parsing is not supported. Please do not use. 447 * <P> 448 * This method should handle parsing of 449 * date time interval strings into Formattable objects with 450 * DateInterval type, which is a pair of UDate. 451 * <P> 452 * Before calling, set parse_pos.index to the offset you want to start 453 * parsing at in the source. After calling, parse_pos.index is the end of 454 * the text you parsed. If error occurs, index is unchanged. 455 * <P> 456 * When parsing, leading whitespace is discarded (with a successful parse), 457 * while trailing whitespace is left as is. 458 * <P> 459 * See Format::parseObject() for more. 460 * 461 * @param source The string to be parsed into an object. 462 * @param result Formattable to be set to the parse result. 463 * If parse fails, return contents are undefined. 464 * @param parse_pos The position to start parsing at. Since no parsing 465 * is supported, upon return this param is unchanged. 466 * @return A newly created Formattable* object, or NULL 467 * on failure. The caller owns this and should 468 * delete it when done. 469 * @internal ICU 4.0 470 */ 471 virtual void parseObject(const UnicodeString& source, 472 Formattable& result, 473 ParsePosition& parse_pos) const; 474 475 476 /** 477 * Gets the date time interval patterns. 478 * @return the date time interval patterns associated with 479 * this date interval formatter. 480 * @stable ICU 4.0 481 */ 482 const DateIntervalInfo* getDateIntervalInfo(void) const; 483 484 485 /** 486 * Set the date time interval patterns. 487 * @param newIntervalPatterns the given interval patterns to copy. 488 * @param status output param set to success/failure code on exit 489 * @stable ICU 4.0 490 */ 491 void setDateIntervalInfo(const DateIntervalInfo& newIntervalPatterns, 492 UErrorCode& status); 493 494 495 /** 496 * Gets the date formatter 497 * @return the date formatter associated with this date interval formatter. 498 * @stable ICU 4.0 499 */ 500 const DateFormat* getDateFormat(void) const; 501 502 /** 503 * Returns a reference to the TimeZone used by this DateIntervalFormat's calendar. 504 * @return the time zone associated with the calendar of DateIntervalFormat. 505 * @stable ICU 4.8 506 */ 507 virtual const TimeZone& getTimeZone(void) const; 508 509 /** 510 * Sets the time zone for the calendar used by this DateIntervalFormat object. The 511 * caller no longer owns the TimeZone object and should not delete it after this call. 512 * @param zoneToAdopt the TimeZone to be adopted. 513 * @stable ICU 4.8 514 */ 515 virtual void adoptTimeZone(TimeZone* zoneToAdopt); 516 517 /** 518 * Sets the time zone for the calendar used by this DateIntervalFormat object. 519 * @param zone the new time zone. 520 * @stable ICU 4.8 521 */ 522 virtual void setTimeZone(const TimeZone& zone); 523 524 /** 525 * Return the class ID for this class. This is useful only for comparing to 526 * a return value from getDynamicClassID(). For example: 527 * <pre> 528 * . Base* polymorphic_pointer = createPolymorphicObject(); 529 * . if (polymorphic_pointer->getDynamicClassID() == 530 * . erived::getStaticClassID()) ... 531 * </pre> 532 * @return The class ID for all objects of this class. 533 * @stable ICU 4.0 534 */ 535 static UClassID U_EXPORT2 getStaticClassID(void); 536 537 /** 538 * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This 539 * method is to implement a simple version of RTTI, since not all C++ 540 * compilers support genuine RTTI. Polymorphic operator==() and clone() 541 * methods call this method. 542 * 543 * @return The class ID for this object. All objects of a 544 * given class have the same class ID. Objects of 545 * other classes have different class IDs. 546 * @stable ICU 4.0 547 */ 548 virtual UClassID getDynamicClassID(void) const; 549 550protected: 551 552 /** 553 * Copy constructor. 554 * @stable ICU 4.0 555 */ 556 DateIntervalFormat(const DateIntervalFormat&); 557 558 /** 559 * Assignment operator. 560 * @stable ICU 4.0 561 */ 562 DateIntervalFormat& operator=(const DateIntervalFormat&); 563 564private: 565 566 /* 567 * This is for ICU internal use only. Please do not use. 568 * Save the interval pattern information. 569 * Interval pattern consists of 2 single date patterns and the separator. 570 * For example, interval pattern "MMM d - MMM d, yyyy" consists 571 * a single date pattern "MMM d", another single date pattern "MMM d, yyyy", 572 * and a separator "-". 573 * The pattern is divided into 2 parts. For above example, 574 * the first part is "MMM d - ", and the second part is "MMM d, yyyy". 575 * Also, the first date appears in an interval pattern could be 576 * the earlier date or the later date. 577 * And such information is saved in the interval pattern as well. 578 */ 579 struct PatternInfo { 580 UnicodeString firstPart; 581 UnicodeString secondPart; 582 /** 583 * Whether the first date in interval pattern is later date or not. 584 * Fallback format set the default ordering. 585 * And for a particular interval pattern, the order can be 586 * overriden by prefixing the interval pattern with "latestFirst:" or 587 * "earliestFirst:" 588 * For example, given 2 date, Jan 10, 2007 to Feb 10, 2007. 589 * if the fallback format is "{0} - {1}", 590 * and the pattern is "d MMM - d MMM yyyy", the interval format is 591 * "10 Jan - 10 Feb, 2007". 592 * If the pattern is "latestFirst:d MMM - d MMM yyyy", 593 * the interval format is "10 Feb - 10 Jan, 2007" 594 */ 595 UBool laterDateFirst; 596 }; 597 598 599 /** 600 * default constructor 601 * @internal ICU 4.0 602 */ 603 DateIntervalFormat(); 604 605 /** 606 * Construct a DateIntervalFormat from DateFormat, 607 * a DateIntervalInfo, and skeleton. 608 * DateFormat provides the timezone, calendar, 609 * full pattern, and date format symbols information. 610 * It should be a SimpleDateFormat object which 611 * has a pattern in it. 612 * the DateIntervalInfo provides the interval patterns. 613 * 614 * Note: the DateIntervalFormat takes ownership of both 615 * DateFormat and DateIntervalInfo objects. 616 * Caller should not delete them. 617 * 618 * @param locale the locale of this date interval formatter. 619 * @param dtItvInfo the DateIntervalInfo object to be adopted. 620 * @param skeleton the skeleton of the date formatter 621 * @param status output param set to success/failure code on exit 622 */ 623 DateIntervalFormat(const Locale& locale, DateIntervalInfo* dtItvInfo, 624 const UnicodeString* skeleton, UErrorCode& status); 625 626 627 /** 628 * Construct a DateIntervalFormat from DateFormat 629 * and a DateIntervalInfo. 630 * 631 * It is a wrapper of the constructor. 632 * 633 * @param locale the locale of this date interval formatter. 634 * @param dtitvinf the DateIntervalInfo object to be adopted. 635 * @param skeleton the skeleton of this formatter. 636 * @param status Output param set to success/failure code. 637 * @return a date time interval formatter which the caller owns. 638 */ 639 static DateIntervalFormat* U_EXPORT2 create(const Locale& locale, 640 DateIntervalInfo* dtitvinf, 641 const UnicodeString* skeleton, 642 UErrorCode& status); 643 644 /** 645 * Create a simple date/time formatter from skeleton, given locale, 646 * and date time pattern generator. 647 * 648 * @param skeleton the skeleton on which date format based. 649 * @param locale the given locale. 650 * @param dtpng the date time pattern generator. 651 * @param status Output param to be set to success/failure code. 652 * If it is failure, the returned date formatter will 653 * be NULL. 654 * @return a simple date formatter which the caller owns. 655 */ 656 static SimpleDateFormat* U_EXPORT2 createSDFPatternInstance( 657 const UnicodeString& skeleton, 658 const Locale& locale, 659 DateTimePatternGenerator* dtpng, 660 UErrorCode& status); 661 662 663 /** 664 * Below are for generating interval patterns local to the formatter 665 */ 666 667 668 /** 669 * Format 2 Calendars using fall-back interval pattern 670 * 671 * The full pattern used in this fall-back format is the 672 * full pattern of the date formatter. 673 * 674 * @param fromCalendar calendar set to the from date in date interval 675 * to be formatted into date interval string 676 * @param toCalendar calendar set to the to date in date interval 677 * to be formatted into date interval string 678 * @param appendTo Output parameter to receive result. 679 * Result is appended to existing contents. 680 * @param pos On input: an alignment field, if desired. 681 * On output: the offsets of the alignment field. 682 * @param status output param set to success/failure code on exit 683 * @return Reference to 'appendTo' parameter. 684 */ 685 UnicodeString& fallbackFormat(Calendar& fromCalendar, 686 Calendar& toCalendar, 687 UnicodeString& appendTo, 688 FieldPosition& pos, 689 UErrorCode& status) const; 690 691 692 693 /** 694 * Initialize interval patterns locale to this formatter 695 * 696 * This code is a bit complicated since 697 * 1. the interval patterns saved in resource bundle files are interval 698 * patterns based on date or time only. 699 * It does not have interval patterns based on both date and time. 700 * Interval patterns on both date and time are algorithm generated. 701 * 702 * For example, it has interval patterns on skeleton "dMy" and "hm", 703 * but it does not have interval patterns on skeleton "dMyhm". 704 * 705 * The rule to generate interval patterns for both date and time skeleton are 706 * 1) when the year, month, or day differs, concatenate the two original 707 * expressions with a separator between, 708 * For example, interval pattern from "Jan 10, 2007 10:10 am" 709 * to "Jan 11, 2007 10:10am" is 710 * "Jan 10, 2007 10:10 am - Jan 11, 2007 10:10am" 711 * 712 * 2) otherwise, present the date followed by the range expression 713 * for the time. 714 * For example, interval pattern from "Jan 10, 2007 10:10 am" 715 * to "Jan 10, 2007 11:10am" is 716 * "Jan 10, 2007 10:10 am - 11:10am" 717 * 718 * 2. even a pattern does not request a certain calendar field, 719 * the interval pattern needs to include such field if such fields are 720 * different between 2 dates. 721 * For example, a pattern/skeleton is "hm", but the interval pattern 722 * includes year, month, and date when year, month, and date differs. 723 * 724 * 725 * @param status output param set to success/failure code on exit 726 */ 727 void initializePattern(UErrorCode& status); 728 729 730 731 /** 732 * Set fall back interval pattern given a calendar field, 733 * a skeleton, and a date time pattern generator. 734 * @param field the largest different calendar field 735 * @param skeleton a skeleton 736 * @param status output param set to success/failure code on exit 737 */ 738 void setFallbackPattern(UCalendarDateFields field, 739 const UnicodeString& skeleton, 740 UErrorCode& status); 741 742 743 744 /** 745 * get separated date and time skeleton from a combined skeleton. 746 * 747 * The difference between date skeleton and normalizedDateSkeleton are: 748 * 1. both 'y' and 'd' are appeared only once in normalizeDateSkeleton 749 * 2. 'E' and 'EE' are normalized into 'EEE' 750 * 3. 'MM' is normalized into 'M' 751 * 752 ** the difference between time skeleton and normalizedTimeSkeleton are: 753 * 1. both 'H' and 'h' are normalized as 'h' in normalized time skeleton, 754 * 2. 'a' is omitted in normalized time skeleton. 755 * 3. there is only one appearance for 'h', 'm','v', 'z' in normalized time 756 * skeleton 757 * 758 * 759 * @param skeleton given combined skeleton. 760 * @param date Output parameter for date only skeleton. 761 * @param normalizedDate Output parameter for normalized date only 762 * 763 * @param time Output parameter for time only skeleton. 764 * @param normalizedTime Output parameter for normalized time only 765 * skeleton. 766 * 767 */ 768 static void U_EXPORT2 getDateTimeSkeleton(const UnicodeString& skeleton, 769 UnicodeString& date, 770 UnicodeString& normalizedDate, 771 UnicodeString& time, 772 UnicodeString& normalizedTime); 773 774 775 776 /** 777 * Generate date or time interval pattern from resource, 778 * and set them into the interval pattern locale to this formatter. 779 * 780 * It needs to handle the following: 781 * 1. need to adjust field width. 782 * For example, the interval patterns saved in DateIntervalInfo 783 * includes "dMMMy", but not "dMMMMy". 784 * Need to get interval patterns for dMMMMy from dMMMy. 785 * Another example, the interval patterns saved in DateIntervalInfo 786 * includes "hmv", but not "hmz". 787 * Need to get interval patterns for "hmz' from 'hmv' 788 * 789 * 2. there might be no pattern for 'y' differ for skeleton "Md", 790 * in order to get interval patterns for 'y' differ, 791 * need to look for it from skeleton 'yMd' 792 * 793 * @param dateSkeleton normalized date skeleton 794 * @param timeSkeleton normalized time skeleton 795 * @return whether the resource is found for the skeleton. 796 * TRUE if interval pattern found for the skeleton, 797 * FALSE otherwise. 798 */ 799 UBool setSeparateDateTimePtn(const UnicodeString& dateSkeleton, 800 const UnicodeString& timeSkeleton); 801 802 803 804 805 /** 806 * Generate interval pattern from existing resource 807 * 808 * It not only save the interval patterns, 809 * but also return the extended skeleton and its best match skeleton. 810 * 811 * @param field largest different calendar field 812 * @param skeleton skeleton 813 * @param bestSkeleton the best match skeleton which has interval pattern 814 * defined in resource 815 * @param differenceInfo the difference between skeleton and best skeleton 816 * 0 means the best matched skeleton is the same as input skeleton 817 * 1 means the fields are the same, but field width are different 818 * 2 means the only difference between fields are v/z, 819 * -1 means there are other fields difference 820 * 821 * @param extendedSkeleton extended skeleton 822 * @param extendedBestSkeleton extended best match skeleton 823 * @return whether the interval pattern is found 824 * through extending skeleton or not. 825 * TRUE if interval pattern is found by 826 * extending skeleton, FALSE otherwise. 827 */ 828 UBool setIntervalPattern(UCalendarDateFields field, 829 const UnicodeString* skeleton, 830 const UnicodeString* bestSkeleton, 831 int8_t differenceInfo, 832 UnicodeString* extendedSkeleton = NULL, 833 UnicodeString* extendedBestSkeleton = NULL); 834 835 /** 836 * Adjust field width in best match interval pattern to match 837 * the field width in input skeleton. 838 * 839 * TODO (xji) make a general solution 840 * The adjusting rule can be: 841 * 1. always adjust 842 * 2. never adjust 843 * 3. default adjust, which means adjust according to the following rules 844 * 3.1 always adjust string, such as MMM and MMMM 845 * 3.2 never adjust between string and numeric, such as MM and MMM 846 * 3.3 always adjust year 847 * 3.4 do not adjust 'd', 'h', or 'm' if h presents 848 * 3.5 do not adjust 'M' if it is numeric(?) 849 * 850 * Since date interval format is well-formed format, 851 * date and time skeletons are normalized previously, 852 * till this stage, the adjust here is only "adjust strings, such as MMM 853 * and MMMM, EEE and EEEE. 854 * 855 * @param inputSkeleton the input skeleton 856 * @param bestMatchSkeleton the best match skeleton 857 * @param bestMatchIntervalPattern the best match interval pattern 858 * @param differenceInfo the difference between 2 skeletons 859 * 1 means only field width differs 860 * 2 means v/z exchange 861 * @param adjustedIntervalPattern adjusted interval pattern 862 */ 863 static void U_EXPORT2 adjustFieldWidth( 864 const UnicodeString& inputSkeleton, 865 const UnicodeString& bestMatchSkeleton, 866 const UnicodeString& bestMatchIntervalPattern, 867 int8_t differenceInfo, 868 UnicodeString& adjustedIntervalPattern); 869 870 /** 871 * Concat a single date pattern with a time interval pattern, 872 * set it into the intervalPatterns, while field is time field. 873 * This is used to handle time interval patterns on skeleton with 874 * both time and date. Present the date followed by 875 * the range expression for the time. 876 * @param format date and time format 877 * @param formatLen format string length 878 * @param datePattern date pattern 879 * @param field time calendar field: AM_PM, HOUR, MINUTE 880 * @param status output param set to success/failure code on exit 881 */ 882 void concatSingleDate2TimeInterval(const UChar* format, 883 int32_t formatLen, 884 const UnicodeString& datePattern, 885 UCalendarDateFields field, 886 UErrorCode& status); 887 888 /** 889 * check whether a calendar field present in a skeleton. 890 * @param field calendar field need to check 891 * @param skeleton given skeleton on which to check the calendar field 892 * @return true if field present in a skeleton. 893 */ 894 static UBool U_EXPORT2 fieldExistsInSkeleton(UCalendarDateFields field, 895 const UnicodeString& skeleton); 896 897 898 /** 899 * Split interval patterns into 2 part. 900 * @param intervalPattern interval pattern 901 * @return the index in interval pattern which split the pattern into 2 part 902 */ 903 static int32_t U_EXPORT2 splitPatternInto2Part(const UnicodeString& intervalPattern); 904 905 906 /** 907 * Break interval patterns as 2 part and save them into pattern info. 908 * @param field calendar field 909 * @param intervalPattern interval pattern 910 */ 911 void setIntervalPattern(UCalendarDateFields field, 912 const UnicodeString& intervalPattern); 913 914 915 /** 916 * Break interval patterns as 2 part and save them into pattern info. 917 * @param field calendar field 918 * @param intervalPattern interval pattern 919 * @param laterDateFirst whether later date appear first in interval pattern 920 */ 921 void setIntervalPattern(UCalendarDateFields field, 922 const UnicodeString& intervalPattern, 923 UBool laterDateFirst); 924 925 926 /** 927 * Set pattern information. 928 * 929 * @param field calendar field 930 * @param firstPart the first part in interval pattern 931 * @param secondPart the second part in interval pattern 932 * @param laterDateFirst whether the first date in intervalPattern 933 * is earlier date or later date 934 */ 935 void setPatternInfo(UCalendarDateFields field, 936 const UnicodeString* firstPart, 937 const UnicodeString* secondPart, 938 UBool laterDateFirst); 939 940 941 // from calendar field to pattern letter 942 static const UChar fgCalendarFieldToPatternLetter[]; 943 944 945 /** 946 * The interval patterns for this locale. 947 */ 948 DateIntervalInfo* fInfo; 949 950 /** 951 * The DateFormat object used to format single pattern 952 */ 953 SimpleDateFormat* fDateFormat; 954 955 /** 956 * The 2 calendars with the from and to date. 957 * could re-use the calendar in fDateFormat, 958 * but keeping 2 calendars make it clear and clean. 959 */ 960 Calendar* fFromCalendar; 961 Calendar* fToCalendar; 962 963 /** 964 * Date time pattern generator 965 */ 966 DateTimePatternGenerator* fDtpng; 967 968 /** 969 * Following are interval information relavent (locale) to this formatter. 970 */ 971 UnicodeString fSkeleton; 972 PatternInfo fIntervalPatterns[DateIntervalInfo::kIPI_MAX_INDEX]; 973}; 974 975inline UBool 976DateIntervalFormat::operator!=(const Format& other) const { 977 return !operator==(other); 978} 979 980U_NAMESPACE_END 981 982#endif /* #if !UCONFIG_NO_FORMATTING */ 983 984#endif // _DTITVFMT_H__ 985//eof 986