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