icuSources/i18n/unicode/dtitvfmt.h

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