icuSources/i18n/unicode/dtitvfmt.h

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