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