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