icuSources/i18n/unicode/dtitvfmt.h

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