icuSources/i18n/unicode/dtitvfmt.h

   1 /********************************************************************************
   2 * Copyright (C) 2008-2012, 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
  31 U_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  &quot;yMMMd&quot;,
 117  * in  en_US, if the largest different calendar field between date1 and date2
 118  * is &quot;year&quot;, the date interval pattern  is &quot;MMM d, yyyy - MMM d, yyyy&quot;,
 119  * such as &quot;Jan 10, 2007 - Jan 10, 2008&quot;.
 120  * If the largest different calendar field between date1 and date2 is &quot;month&quot;,
 121  * the date interval pattern is &quot;MMM d - MMM d, yyyy&quot;,
 122  * such as &quot;Jan 10 - Feb 10, 2007&quot;.
 123  * If the largest different calendar field between date1 and date2 is &quot;day&quot;,
 124  * the date interval pattern is &quot;MMM d-d, yyyy&quot;, such as &quot;Jan 10-20, 2007&quot;.
 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
 219 class U_I18N_API DateIntervalFormat : public Format {
 220 public:
 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      */
 267
 268     static DateIntervalFormat* U_EXPORT2 createInstance(
 269                                                const UnicodeString& skeleton,
 270                                                const Locale& locale,
 271                                                UErrorCode& status);
 272
 273     /**
 274      * Construct a DateIntervalFormat from skeleton
 275      *  DateIntervalInfo, and default locale.
 276      *
 277      * This is a convenient override of
 278      * createInstance(const UnicodeString& skeleton, const Locale& locale,
 279      *                const DateIntervalInfo& dtitvinf, UErrorCode&)
 280      * with the locale value as default locale.
 281      *
 282      * @param skeleton  the skeleton on which interval format based.
 283      * @param dtitvinf  the DateIntervalInfo object.
 284      * @param status    output param set to success/failure code on exit
 285      * @return          a date time interval formatter which the caller owns.
 286      * @stable ICU 4.0
 287      */
 288     static DateIntervalFormat* U_EXPORT2 createInstance(
 289                                               const UnicodeString& skeleton,
 290                                               const DateIntervalInfo& dtitvinf,
 291                                               UErrorCode& status);
 292
 293     /**
 294      * Construct a DateIntervalFormat from skeleton
 295      * a DateIntervalInfo, and the given locale.
 296      *
 297      * <P>
 298      * In this factory method, user provides its own date interval pattern
 299      * information, instead of using those pre-defined data in resource file.
 300      * This factory method is for powerful users who want to provide their own
 301      * interval patterns.
 302      * <P>
 303      * There are pre-defined skeletons (defined in udate.h) having predefined
 304      * interval patterns in resource files.
 305      * Users are encouraged to use those macros.
 306      * For example:
 307      * DateIntervalFormat::createInstance(UDAT_MONTH_DAY, status)
 308      *
 309      * The DateIntervalInfo provides the interval patterns.
 310      * and the DateIntervalInfo ownership remains to the caller.
 311      *
 312      * User are encouraged to set default interval pattern in DateIntervalInfo
 313      * as well, if they want to set other interval patterns ( instead of
 314      * reading the interval patterns from resource files).
 315      * When the corresponding interval pattern for a largest calendar different
 316      * field is not found ( if user not set it ), interval format fallback to
 317      * the default interval pattern.
 318      * If user does not provide default interval pattern, it fallback to
 319      * "{date0} - {date1}"
 320      *
 321      * @param skeleton  the skeleton on which interval format based.
 322      * @param locale    the given locale
 323      * @param dtitvinf  the DateIntervalInfo object.
 324      * @param status    output param set to success/failure code on exit
 325      * @return          a date time interval formatter which the caller owns.
 326      * @stable ICU 4.0
 327      */
 328     static DateIntervalFormat* U_EXPORT2 createInstance(
 329                                               const UnicodeString& skeleton,
 330                                               const Locale& locale,
 331                                               const DateIntervalInfo& dtitvinf,
 332                                               UErrorCode& status);
 333
 334     /**
 335      * Destructor.
 336      * @stable ICU 4.0
 337      */
 338     virtual ~DateIntervalFormat();
 339
 340     /**
 341      * Clone this Format object polymorphically. The caller owns the result and
 342      * should delete it when done.
 343      * @return    A copy of the object.
 344      * @stable ICU 4.0
 345      */
 346     virtual Format* clone(void) const;
 347
 348     /**
 349      * Return true if the given Format objects are semantically equal. Objects
 350      * of different subclasses are considered unequal.
 351      * @param other    the object to be compared with.
 352      * @return         true if the given Format objects are semantically equal.
 353      * @stable ICU 4.0
 354      */
 355     virtual UBool operator==(const Format& other) const;
 356
 357     /**
 358      * Return true if the given Format objects are not semantically equal.
 359      * Objects of different subclasses are considered unequal.
 360      * @param other the object to be compared with.
 361      * @return      true if the given Format objects are not semantically equal.
 362      * @stable ICU 4.0
 363      */
 364     UBool operator!=(const Format& other) const;
 365
 366
 367     using Format::format;
 368
 369     /**
 370      * Format an object to produce a string. This method handles Formattable
 371      * objects with a DateInterval type.
 372      * If a the Formattable object type is not a DateInterval,
 373      * then it returns a failing UErrorCode.
 374      *
 375      * @param obj               The object to format.
 376      *                          Must be a DateInterval.
 377      * @param appendTo          Output parameter to receive result.
 378      *                          Result is appended to existing contents.
 379      * @param fieldPosition     On input: an alignment field, if desired.
 380      *                          On output: the offsets of the alignment field.
 381      * @param status            Output param filled with success/failure status.
 382      * @return                  Reference to 'appendTo' parameter.
 383      * @stable ICU 4.0
 384      */
 385     virtual UnicodeString& format(const Formattable& obj,
 386                                   UnicodeString& appendTo,
 387                                   FieldPosition& fieldPosition,
 388                                   UErrorCode& status) const ;
 389
 390
 391
 392     /**
 393      * Format a DateInterval to produce a string.
 394      *
 395      * @param dtInterval        DateInterval to be formatted.
 396      * @param appendTo          Output parameter to receive result.
 397      *                          Result is appended to existing contents.
 398      * @param fieldPosition     On input: an alignment field, if desired.
 399      *                          On output: the offsets of the alignment field.
 400      * @param status            Output param filled with success/failure status.
 401      * @return                  Reference to 'appendTo' parameter.
 402      * @stable ICU 4.0
 403      */
 404     UnicodeString& format(const DateInterval* dtInterval,
 405                           UnicodeString& appendTo,
 406                           FieldPosition& fieldPosition,
 407                           UErrorCode& status) const ;
 408
 409
 410     /**
 411      * Format 2 Calendars to produce a string.
 412      *
 413      * Note: "fromCalendar" and "toCalendar" are not const,
 414      * since calendar is not const in  SimpleDateFormat::format(Calendar&),
 415      *
 416      * @param fromCalendar      calendar set to the from date in date interval
 417      *                          to be formatted into date interval string
 418      * @param toCalendar        calendar set to the to date in date interval
 419      *                          to be formatted into date interval string
 420      * @param appendTo          Output parameter to receive result.
 421      *                          Result is appended to existing contents.
 422      * @param fieldPosition     On input: an alignment field, if desired.
 423      *                          On output: the offsets of the alignment field.
 424      * @param status            Output param filled with success/failure status.
 425      *                          Caller needs to make sure it is SUCCESS
 426      *                          at the function entrance
 427      * @return                  Reference to 'appendTo' parameter.
 428      * @stable ICU 4.0
 429      */
 430     UnicodeString& format(Calendar& fromCalendar,
 431                           Calendar& toCalendar,
 432                           UnicodeString& appendTo,
 433                           FieldPosition& fieldPosition,
 434                           UErrorCode& status) const ;
 435
 436     /**
 437      * Date interval parsing is not supported. Please do not use.
 438      * <P>
 439      * This method should handle parsing of
 440      * date time interval strings into Formattable objects with
 441      * DateInterval type, which is a pair of UDate.
 442      * <P>
 443      * Before calling, set parse_pos.index to the offset you want to start
 444      * parsing at in the source. After calling, parse_pos.index is the end of
 445      * the text you parsed. If error occurs, index is unchanged.
 446      * <P>
 447      * When parsing, leading whitespace is discarded (with a successful parse),
 448      * while trailing whitespace is left as is.
 449      * <P>
 450      * See Format::parseObject() for more.
 451      *
 452      * @param source    The string to be parsed into an object.
 453      * @param result    Formattable to be set to the parse result.
 454      *                  If parse fails, return contents are undefined.
 455      * @param parse_pos The position to start parsing at. Since no parsing
 456      *                  is supported, upon return this param is unchanged.
 457      * @return          A newly created Formattable* object, or NULL
 458      *                  on failure.  The caller owns this and should
 459      *                  delete it when done.
 460      * @internal ICU 4.0
 461      */
 462     virtual void parseObject(const UnicodeString& source,
 463                              Formattable& result,
 464                              ParsePosition& parse_pos) const;
 465
 466
 467     /**
 468      * Gets the date time interval patterns.
 469      * @return the date time interval patterns associated with
 470      * this date interval formatter.
 471      * @stable ICU 4.0
 472      */
 473     const DateIntervalInfo* getDateIntervalInfo(void) const;
 474
 475
 476     /**
 477      * Set the date time interval patterns.
 478      * @param newIntervalPatterns   the given interval patterns to copy.
 479      * @param status          output param set to success/failure code on exit
 480      * @stable ICU 4.0
 481      */
 482     void setDateIntervalInfo(const DateIntervalInfo& newIntervalPatterns,
 483                              UErrorCode& status);
 484
 485
 486     /**
 487      * Gets the date formatter
 488      * @return the date formatter associated with this date interval formatter.
 489      * @stable ICU 4.0
 490      */
 491     const DateFormat* getDateFormat(void) const;
 492
 493     /**
 494      * Returns a reference to the TimeZone used by this DateIntervalFormat's calendar.
 495      * @return the time zone associated with the calendar of DateIntervalFormat.
 496      * @stable ICU 4.8
 497      */
 498     virtual const TimeZone& getTimeZone(void) const;
 499
 500     /**
 501      * Sets the time zone for the calendar used by this DateIntervalFormat object. The
 502      * caller no longer owns the TimeZone object and should not delete it after this call.
 503      * @param zoneToAdopt the TimeZone to be adopted.
 504      * @stable ICU 4.8
 505      */
 506     virtual void adoptTimeZone(TimeZone* zoneToAdopt);
 507
 508     /**
 509      * Sets the time zone for the calendar used by this DateIntervalFormat object.
 510      * @param zone the new time zone.
 511      * @stable ICU 4.8
 512      */
 513     virtual void setTimeZone(const TimeZone& zone);
 514
 515     /**
 516      * Change attributes for the DateIntervalFormat object.
 517      * @param attr
 518      *            The attribute to change.
 519      * @param value
 520      *            The new value for the attribute.
 521      * @param status
 522      *            A UErrorCode to receive any errors.
 523      * @internal
 524      */
 525     virtual void setAttribute(UDateIntervalFormatAttribute attr,
 526                               UDateIntervalFormatAttributeValue value,
 527                               UErrorCode &status);
 528
 529     /**
 530      * Return the class ID for this class. This is useful only for comparing to
 531      * a return value from getDynamicClassID(). For example:
 532      * <pre>
 533      * .   Base* polymorphic_pointer = createPolymorphicObject();
 534      * .   if (polymorphic_pointer->getDynamicClassID() ==
 535      * .       erived::getStaticClassID()) ...
 536      * </pre>
 537      * @return          The class ID for all objects of this class.
 538      * @stable ICU 4.0
 539      */
 540     static UClassID U_EXPORT2 getStaticClassID(void);
 541
 542     /**
 543      * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This
 544      * method is to implement a simple version of RTTI, since not all C++
 545      * compilers support genuine RTTI. Polymorphic operator==() and clone()
 546      * methods call this method.
 547      *
 548      * @return          The class ID for this object. All objects of a
 549      *                  given class have the same class ID.  Objects of
 550      *                  other classes have different class IDs.
 551      * @stable ICU 4.0
 552      */
 553     virtual UClassID getDynamicClassID(void) const;
 554
 555 protected:
 556
 557     /**
 558      * Copy constructor.
 559      * @stable ICU 4.0
 560      */
 561     DateIntervalFormat(const DateIntervalFormat&);
 562
 563     /**
 564      * Assignment operator.
 565      * @stable ICU 4.0
 566      */
 567     DateIntervalFormat& operator=(const DateIntervalFormat&);
 568
 569 private:
 570
 571     /*
 572      * This is for ICU internal use only. Please do not use.
 573      * Save the interval pattern information.
 574      * Interval pattern consists of 2 single date patterns and the separator.
 575      * For example, interval pattern "MMM d - MMM d, yyyy" consists
 576      * a single date pattern "MMM d", another single date pattern "MMM d, yyyy",
 577      * and a separator "-".
 578      * The pattern is divided into 2 parts. For above example,
 579      * the first part is "MMM d - ", and the second part is "MMM d, yyyy".
 580      * Also, the first date appears in an interval pattern could be
 581      * the earlier date or the later date.
 582      * And such information is saved in the interval pattern as well.
 583      * @internal ICU 4.0
 584      */
 585     struct PatternInfo {
 586         UnicodeString firstPart;
 587         UnicodeString secondPart;
 588         /**
 589          * Whether the first date in interval pattern is later date or not.
 590          * Fallback format set the default ordering.
 591          * And for a particular interval pattern, the order can be
 592          * overriden by prefixing the interval pattern with "latestFirst:" or
 593          * "earliestFirst:"
 594          * For example, given 2 date, Jan 10, 2007 to Feb 10, 2007.
 595          * if the fallback format is "{0} - {1}",
 596          * and the pattern is "d MMM - d MMM yyyy", the interval format is
 597          * "10 Jan - 10 Feb, 2007".
 598          * If the pattern is "latestFirst:d MMM - d MMM yyyy",
 599          * the interval format is "10 Feb - 10 Jan, 2007"
 600          */
 601         UBool         laterDateFirst;
 602     };
 603
 604
 605     /**
 606      * default constructor
 607      * @internal ICU 4.0
 608      */
 609     DateIntervalFormat();
 610
 611     /**
 612      * Construct a DateIntervalFormat from DateFormat,
 613      * a DateIntervalInfo, and skeleton.
 614      * DateFormat provides the timezone, calendar,
 615      * full pattern, and date format symbols information.
 616      * It should be a SimpleDateFormat object which
 617      * has a pattern in it.
 618      * the DateIntervalInfo provides the interval patterns.
 619      *
 620      * Note: the DateIntervalFormat takes ownership of both
 621      * DateFormat and DateIntervalInfo objects.
 622      * Caller should not delete them.
 623      *
 624      * @param locale    the locale of this date interval formatter.
 625      * @param dtItvInfo the DateIntervalInfo object to be adopted.
 626      * @param skeleton  the skeleton of the date formatter
 627      * @param status    output param set to success/failure code on exit
 628      * @internal ICU 4.0
 629      */
 630     DateIntervalFormat(const Locale& locale, DateIntervalInfo* dtItvInfo,
 631                        const UnicodeString* skeleton, UErrorCode& status);
 632
 633
 634     /**
 635      * Construct a DateIntervalFormat from DateFormat
 636      * and a DateIntervalInfo.
 637      *
 638      * It is a wrapper of the constructor.
 639      *
 640      * @param locale    the locale of this date interval formatter.
 641      * @param dtitvinf  the DateIntervalInfo object to be adopted.
 642      * @param skeleton  the skeleton of this formatter.
 643      * @param status    Output param set to success/failure code.
 644      * @return          a date time interval formatter which the caller owns.
 645      * @internal ICU 4.0
 646      */
 647     static DateIntervalFormat* U_EXPORT2 create(const Locale& locale,
 648                                                 DateIntervalInfo* dtitvinf,
 649                                                 const UnicodeString* skeleton,
 650                                                 UErrorCode& status);
 651
 652     /**
 653      * Create a simple date/time formatter from skeleton, given locale,
 654      * and date time pattern generator.
 655      *
 656      * @param skeleton  the skeleton on which date format based.
 657      * @param locale    the given locale.
 658      * @param dtpng     the date time pattern generator.
 659      * @param status    Output param to be set to success/failure code.
 660      *                  If it is failure, the returned date formatter will
 661      *                  be NULL.
 662      * @return          a simple date formatter which the caller owns.
 663      * @internal ICU 4.0
 664      */
 665     static SimpleDateFormat* U_EXPORT2 createSDFPatternInstance(
 666                                         const UnicodeString& skeleton,
 667                                         const Locale& locale,
 668                                         DateTimePatternGenerator* dtpng,
 669                                         UErrorCode& status);
 670
 671
 672     /**
 673      *  Below are for generating interval patterns local to the formatter
 674      */
 675
 676
 677     /**
 678      * Format 2 Calendars using fall-back interval pattern
 679      *
 680      * The full pattern used in this fall-back format is the
 681      * full pattern of the date formatter.
 682      *
 683      * @param fromCalendar      calendar set to the from date in date interval
 684      *                          to be formatted into date interval string
 685      * @param toCalendar        calendar set to the to date in date interval
 686      *                          to be formatted into date interval string
 687      * @param appendTo          Output parameter to receive result.
 688      *                          Result is appended to existing contents.
 689      * @param pos               On input: an alignment field, if desired.
 690      *                          On output: the offsets of the alignment field.
 691      * @param status            output param set to success/failure code on exit
 692      * @return                  Reference to 'appendTo' parameter.
 693      * @internal ICU 4.0
 694      */
 695     UnicodeString& fallbackFormat(Calendar& fromCalendar,
 696                                   Calendar& toCalendar,
 697                                   UnicodeString& appendTo,
 698                                   FieldPosition& pos,
 699                                   UErrorCode& status) const;
 700
 701
 702
 703     /**
 704      * Initialize interval patterns locale to this formatter
 705      *
 706      * This code is a bit complicated since
 707      * 1. the interval patterns saved in resource bundle files are interval
 708      *    patterns based on date or time only.
 709      *    It does not have interval patterns based on both date and time.
 710      *    Interval patterns on both date and time are algorithm generated.
 711      *
 712      *    For example, it has interval patterns on skeleton "dMy" and "hm",
 713      *    but it does not have interval patterns on skeleton "dMyhm".
 714      *
 715      *    The rule to generate interval patterns for both date and time skeleton are
 716      *    1) when the year, month, or day differs, concatenate the two original
 717      *    expressions with a separator between,
 718      *    For example, interval pattern from "Jan 10, 2007 10:10 am"
 719      *    to "Jan 11, 2007 10:10am" is
 720      *    "Jan 10, 2007 10:10 am - Jan 11, 2007 10:10am"
 721      *
 722      *    2) otherwise, present the date followed by the range expression
 723      *    for the time.
 724      *    For example, interval pattern from "Jan 10, 2007 10:10 am"
 725      *    to "Jan 10, 2007 11:10am" is
 726      *    "Jan 10, 2007 10:10 am - 11:10am"
 727      *
 728      * 2. even a pattern does not request a certain calendar field,
 729      *    the interval pattern needs to include such field if such fields are
 730      *    different between 2 dates.
 731      *    For example, a pattern/skeleton is "hm", but the interval pattern
 732      *    includes year, month, and date when year, month, and date differs.
 733      *
 734      *
 735      * @param status    output param set to success/failure code on exit
 736      * @internal ICU 4.0
 737      */
 738     void initializePattern(UErrorCode& status);
 739
 740
 741
 742     /**
 743      * Set fall back interval pattern given a calendar field,
 744      * a skeleton, and a date time pattern generator.
 745      * @param field      the largest different calendar field
 746      * @param skeleton   a skeleton
 747      * @param status     output param set to success/failure code on exit
 748      * @internal ICU 4.0
 749      */
 750     void setFallbackPattern(UCalendarDateFields field,
 751                             const UnicodeString& skeleton,
 752                             UErrorCode& status);
 753
 754
 755
 756     /**
 757      * get separated date and time skeleton from a combined skeleton.
 758      *
 759      * The difference between date skeleton and normalizedDateSkeleton are:
 760      * 1. both 'y' and 'd' are appeared only once in normalizeDateSkeleton
 761      * 2. 'E' and 'EE' are normalized into 'EEE'
 762      * 3. 'MM' is normalized into 'M'
 763      *
 764      ** the difference between time skeleton and normalizedTimeSkeleton are:
 765      * 1. both 'H' and 'h' are normalized as 'h' in normalized time skeleton,
 766      * 2. 'a' is omitted in normalized time skeleton.
 767      * 3. there is only one appearance for 'h', 'm','v', 'z' in normalized time
 768      *    skeleton
 769      *
 770      *
 771      *  @param skeleton               given combined skeleton.
 772      *  @param date                   Output parameter for date only skeleton.
 773      *  @param normalizedDate         Output parameter for normalized date only
 774      *
 775      *  @param time                   Output parameter for time only skeleton.
 776      *  @param normalizedTime         Output parameter for normalized time only
 777      *                                skeleton.
 778      *
 779      * @internal ICU 4.0
 780      */
 781     static void  U_EXPORT2 getDateTimeSkeleton(const UnicodeString& skeleton,
 782                                     UnicodeString& date,
 783                                     UnicodeString& normalizedDate,
 784                                     UnicodeString& time,
 785                                     UnicodeString& normalizedTime);
 786
 787
 788
 789     /**
 790      * Generate date or time interval pattern from resource,
 791      * and set them into the interval pattern locale to this formatter.
 792      *
 793      * It needs to handle the following:
 794      * 1. need to adjust field width.
 795      *    For example, the interval patterns saved in DateIntervalInfo
 796      *    includes "dMMMy", but not "dMMMMy".
 797      *    Need to get interval patterns for dMMMMy from dMMMy.
 798      *    Another example, the interval patterns saved in DateIntervalInfo
 799      *    includes "hmv", but not "hmz".
 800      *    Need to get interval patterns for "hmz' from 'hmv'
 801      *
 802      * 2. there might be no pattern for 'y' differ for skeleton "Md",
 803      *    in order to get interval patterns for 'y' differ,
 804      *    need to look for it from skeleton 'yMd'
 805      *
 806      * @param dateSkeleton   normalized date skeleton
 807      * @param timeSkeleton   normalized time skeleton
 808      * @return               whether the resource is found for the skeleton.
 809      *                       TRUE if interval pattern found for the skeleton,
 810      *                       FALSE otherwise.
 811      * @internal ICU 4.0
 812      */
 813     UBool setSeparateDateTimePtn(const UnicodeString& dateSkeleton,
 814                                  const UnicodeString& timeSkeleton);
 815
 816
 817
 818
 819     /**
 820      * Generate interval pattern from existing resource
 821      *
 822      * It not only save the interval patterns,
 823      * but also return the extended skeleton and its best match skeleton.
 824      *
 825      * @param field           largest different calendar field
 826      * @param skeleton        skeleton
 827      * @param bestSkeleton    the best match skeleton which has interval pattern
 828      *                        defined in resource
 829      * @param differenceInfo  the difference between skeleton and best skeleton
 830      *         0 means the best matched skeleton is the same as input skeleton
 831      *         1 means the fields are the same, but field width are different
 832      *         2 means the only difference between fields are v/z,
 833      *        -1 means there are other fields difference
 834      *
 835      * @param extendedSkeleton      extended skeleton
 836      * @param extendedBestSkeleton  extended best match skeleton
 837      * @return                      whether the interval pattern is found
 838      *                              through extending skeleton or not.
 839      *                              TRUE if interval pattern is found by
 840      *                              extending skeleton, FALSE otherwise.
 841      * @internal ICU 4.0
 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      * @internal ICU 4.0
 878      */
 879     static void U_EXPORT2 adjustFieldWidth(
 880                             const UnicodeString& inputSkeleton,
 881                             const UnicodeString& bestMatchSkeleton,
 882                             const UnicodeString& bestMatchIntervalPattern,
 883                             int8_t differenceInfo,
 884                             UnicodeString& adjustedIntervalPattern);
 885
 886     /**
 887      * Concat a single date pattern with a time interval pattern,
 888      * set it into the intervalPatterns, while field is time field.
 889      * This is used to handle time interval patterns on skeleton with
 890      * both time and date. Present the date followed by
 891      * the range expression for the time.
 892      * @param format         date and time format
 893      * @param formatLen      format string length
 894      * @param datePattern    date pattern
 895      * @param field          time calendar field: AM_PM, HOUR, MINUTE
 896      * @param status         output param set to success/failure code on exit
 897      * @internal ICU 4.0
 898      */
 899     void concatSingleDate2TimeInterval(const UChar* format,
 900                                        int32_t formatLen,
 901                                        const UnicodeString& datePattern,
 902                                        UCalendarDateFields field,
 903                                        UErrorCode& status);
 904
 905     /**
 906      * check whether a calendar field present in a skeleton.
 907      * @param field      calendar field need to check
 908      * @param skeleton   given skeleton on which to check the calendar field
 909      * @return           true if field present in a skeleton.
 910      * @internal ICU 4.0
 911      */
 912     static UBool U_EXPORT2 fieldExistsInSkeleton(UCalendarDateFields field,
 913                                                  const UnicodeString& skeleton);
 914
 915
 916     /**
 917      * Split interval patterns into 2 part.
 918      * @param intervalPattern  interval pattern
 919      * @return the index in interval pattern which split the pattern into 2 part
 920      * @internal ICU 4.0
 921      */
 922     static int32_t  U_EXPORT2 splitPatternInto2Part(const UnicodeString& intervalPattern);
 923
 924
 925     /**
 926      * Break interval patterns as 2 part and save them into pattern info.
 927      * @param field            calendar field
 928      * @param intervalPattern  interval pattern
 929      * @internal ICU 4.0
 930      */
 931     void setIntervalPattern(UCalendarDateFields field,
 932                             const UnicodeString& intervalPattern);
 933
 934
 935     /**
 936      * Break interval patterns as 2 part and save them into pattern info.
 937      * @param field            calendar field
 938      * @param intervalPattern  interval pattern
 939      * @param laterDateFirst   whether later date appear first in interval pattern
 940      * @internal ICU 4.0
 941      */
 942     void setIntervalPattern(UCalendarDateFields field,
 943                             const UnicodeString& intervalPattern,
 944                             UBool laterDateFirst);
 945
 946
 947     /**
 948      * Set pattern information.
 949      *
 950      * @param field            calendar field
 951      * @param firstPart        the first part in interval pattern
 952      * @param secondPart       the second part in interval pattern
 953      * @param laterDateFirst   whether the first date in intervalPattern
 954      *                         is earlier date or later date
 955      * @internal ICU 4.0
 956      */
 957     void setPatternInfo(UCalendarDateFields field,
 958                         const UnicodeString* firstPart,
 959                         const UnicodeString* secondPart,
 960                         UBool laterDateFirst);
 961
 962
 963     // from calendar field to pattern letter
 964     static const UChar fgCalendarFieldToPatternLetter[];
 965
 966
 967     /**
 968      * The interval patterns for this locale.
 969      */
 970     DateIntervalInfo*     fInfo;
 971
 972     /**
 973      * The DateFormat object used to format single pattern
 974      */
 975     SimpleDateFormat*     fDateFormat;
 976
 977     /**
 978      * The 2 calendars with the from and to date.
 979      * could re-use the calendar in fDateFormat,
 980      * but keeping 2 calendars make it clear and clean.
 981      */
 982     Calendar* fFromCalendar;
 983     Calendar* fToCalendar;
 984
 985     /**
 986      * Date time pattern generator
 987      */
 988     DateTimePatternGenerator* fDtpng;
 989
 990     /**
 991      * Following are interval information relevant (locale) to this formatter.
 992      */
 993     UnicodeString fSkeleton;
 994     PatternInfo fIntervalPatterns[DateIntervalInfo::kIPI_MAX_INDEX];
 995
 996     /**
 997      * Atttributes
 998      */
 999     int32_t fMinimizeType;
1000 };
1001
1002 inline UBool
1003 DateIntervalFormat::operator!=(const Format& other) const  {
1004     return !operator==(other);
1005 }
1006
1007 U_NAMESPACE_END
1008
1009 #endif /* #if !UCONFIG_NO_FORMATTING */
1010
1011 #endif // _DTITVFMT_H__
1012 //eof