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