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