icuSources/i18n/unicode/dtitvfmt.h

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