icuSources/i18n/unicode/dtitvinf.h

   1 // © 2016 and later: Unicode, Inc. and others.
   2 // License & terms of use: http://www.unicode.org/copyright.html
   3 /*
   4  *******************************************************************************
   5  * Copyright (C) 2008-2016, International Business Machines Corporation and
   6  * others. All Rights Reserved.
   7  *******************************************************************************
   8  *
   9  * File DTITVINF.H
  10  *
  11  *******************************************************************************
  12  */
  13
  14 #ifndef __DTITVINF_H__
  15 #define __DTITVINF_H__
  16
  17 #include "unicode/utypes.h"
  18
  19 /**
  20  * \file
  21  * \brief C++ API: Date/Time interval patterns for formatting date/time interval
  22  */
  23
  24 #if !UCONFIG_NO_FORMATTING
  25
  26 #include "unicode/udat.h"
  27 #include "unicode/locid.h"
  28 #include "unicode/ucal.h"
  29 #include "unicode/dtptngen.h"
  30
  31 #if U_SHOW_CPLUSPLUS_API
  32 U_NAMESPACE_BEGIN
  33
  34 /**
  35  * DateIntervalInfo is a public class for encapsulating localizable
  36  * date time interval patterns. It is used by DateIntervalFormat.
  37  *
  38  * <P>
  39  * For most users, ordinary use of DateIntervalFormat does not need to create
  40  * DateIntervalInfo object directly.
  41  * DateIntervalFormat will take care of it when creating a date interval
  42  * formatter when user pass in skeleton and locale.
  43  *
  44  * <P>
  45  * For power users, who want to create their own date interval patterns,
  46  * or want to re-set date interval patterns, they could do so by
  47  * directly creating DateIntervalInfo and manupulating it.
  48  *
  49  * <P>
  50  * Logically, the interval patterns are mappings
  51  * from (skeleton, the_largest_different_calendar_field)
  52  * to (date_interval_pattern).
  53  *
  54  * <P>
  55  * A skeleton
  56  * <ol>
  57  * <li>
  58  * only keeps the field pattern letter and ignores all other parts
  59  * in a pattern, such as space, punctuations, and string literals.
  60  * <li>
  61  * hides the order of fields.
  62  * <li>
  63  * might hide a field's pattern letter length.
  64  *
  65  * For those non-digit calendar fields, the pattern letter length is
  66  * important, such as MMM, MMMM, and MMMMM; EEE and EEEE,
  67  * and the field's pattern letter length is honored.
  68  *
  69  * For the digit calendar fields,  such as M or MM, d or dd, yy or yyyy,
  70  * the field pattern length is ignored and the best match, which is defined
  71  * in date time patterns, will be returned without honor the field pattern
  72  * letter length in skeleton.
  73  * </ol>
  74  *
  75  * <P>
  76  * The calendar fields we support for interval formatting are:
  77  * year, month, date, day-of-week, am-pm, hour, hour-of-day, and minute.
  78  * Those calendar fields can be defined in the following order:
  79  * year >  month > date > am-pm > hour >  minute
  80  *
  81  * The largest different calendar fields between 2 calendars is the
  82  * first different calendar field in above order.
  83  *
  84  * For example: the largest different calendar fields between &quot;Jan 10, 2007&quot;
  85  * and &quot;Feb 20, 2008&quot; is year.
  86  *
  87  * <P>
  88  * There is a set of pre-defined static skeleton strings.
  89  * There are pre-defined interval patterns for those pre-defined skeletons
  90  * in locales' resource files.
  91  * For example, for a skeleton UDAT_YEAR_ABBR_MONTH_DAY, which is  &quot;yMMMd&quot;,
  92  * in  en_US, if the largest different calendar field between date1 and date2
  93  * is &quot;year&quot;, the date interval pattern  is &quot;MMM d, yyyy - MMM d, yyyy&quot;,
  94  * such as &quot;Jan 10, 2007 - Jan 10, 2008&quot;.
  95  * If the largest different calendar field between date1 and date2 is &quot;month&quot;,
  96  * the date interval pattern is &quot;MMM d - MMM d, yyyy&quot;,
  97  * such as &quot;Jan 10 - Feb 10, 2007&quot;.
  98  * If the largest different calendar field between date1 and date2 is &quot;day&quot;,
  99  * the date interval pattern is &quot;MMM d-d, yyyy&quot;, such as &quot;Jan 10-20, 2007&quot;.
 100  *
 101  * For date skeleton, the interval patterns when year, or month, or date is
 102  * different are defined in resource files.
 103  * For time skeleton, the interval patterns when am/pm, or hour, or minute is
 104  * different are defined in resource files.
 105  *
 106  *
 107  * <P>
 108  * There are 2 dates in interval pattern. For most locales, the first date
 109  * in an interval pattern is the earlier date. There might be a locale in which
 110  * the first date in an interval pattern is the later date.
 111  * We use fallback format for the default order for the locale.
 112  * For example, if the fallback format is &quot;{0} - {1}&quot;, it means
 113  * the first date in the interval pattern for this locale is earlier date.
 114  * If the fallback format is &quot;{1} - {0}&quot;, it means the first date is the
 115  * later date.
 116  * For a particular interval pattern, the default order can be overriden
 117  * by prefixing &quot;latestFirst:&quot; or &quot;earliestFirst:&quot; to the interval pattern.
 118  * For example, if the fallback format is &quot;{0}-{1}&quot;,
 119  * but for skeleton &quot;yMMMd&quot;, the interval pattern when day is different is
 120  * &quot;latestFirst:d-d MMM yy&quot;, it means by default, the first date in interval
 121  * pattern is the earlier date. But for skeleton &quot;yMMMd&quot;, when day is different,
 122  * the first date in &quot;d-d MMM yy&quot; is the later date.
 123  *
 124  * <P>
 125  * The recommended way to create a DateIntervalFormat object is to pass in
 126  * the locale.
 127  * By using a Locale parameter, the DateIntervalFormat object is
 128  * initialized with the pre-defined interval patterns for a given or
 129  * default locale.
 130  * <P>
 131  * Users can also create DateIntervalFormat object
 132  * by supplying their own interval patterns.
 133  * It provides flexibility for power users.
 134  *
 135  * <P>
 136  * After a DateIntervalInfo object is created, clients may modify
 137  * the interval patterns using setIntervalPattern function as so desired.
 138  * Currently, users can only set interval patterns when the following
 139  * calendar fields are different: ERA, YEAR, MONTH, DATE,  DAY_OF_MONTH,
 140  * DAY_OF_WEEK, AM_PM,  HOUR, HOUR_OF_DAY, and MINUTE.
 141  * Interval patterns when other calendar fields are different is not supported.
 142  * <P>
 143  * DateIntervalInfo objects are cloneable.
 144  * When clients obtain a DateIntervalInfo object,
 145  * they can feel free to modify it as necessary.
 146  * <P>
 147  * DateIntervalInfo are not expected to be subclassed.
 148  * Data for a calendar is loaded out of resource bundles.
 149  * Through ICU 4.4, date interval patterns are only supported in the Gregorian
 150  * calendar; non-Gregorian calendars are supported from ICU 4.4.1.
 151  * @stable ICU 4.0
 152 **/
 153
 154 class U_I18N_API DateIntervalInfo U_FINAL : public UObject {
 155 public:
 156     // Do not enclose the protected default constructor with #ifndef U_HIDE_INTERNAL_API
 157     // or else the compiler will create a public default constructor.
 158     /**
 159      * Default constructor.
 160      * It does not initialize any interval patterns except
 161      * that it initialize default fall-back pattern as "{0} - {1}",
 162      * which can be reset by setFallbackIntervalPattern().
 163      * It should be followed by setFallbackIntervalPattern() and
 164      * setIntervalPattern(),
 165      * and is recommended to be used only for power users who
 166      * wants to create their own interval patterns and use them to create
 167      * date interval formatter.
 168      * @param status   output param set to success/failure code on exit
 169      * @internal ICU 4.0
 170      */
 171     DateIntervalInfo(UErrorCode& status);
 172
 173
 174     /**
 175      * Construct DateIntervalInfo for the given locale,
 176      * @param locale  the interval patterns are loaded from the appropriate calendar
 177      *                data (specified calendar or default calendar) in this locale.
 178      * @param status  output param set to success/failure code on exit
 179      * @stable ICU 4.0
 180      */
 181     DateIntervalInfo(const Locale& locale, UErrorCode& status);
 182
 183
 184     /**
 185      * Copy constructor.
 186      * @stable ICU 4.0
 187      */
 188     DateIntervalInfo(const DateIntervalInfo&);
 189
 190     /**
 191      * Assignment operator
 192      * @stable ICU 4.0
 193      */
 194     DateIntervalInfo& operator=(const DateIntervalInfo&);
 195
 196     /**
 197      * Clone this object polymorphically.
 198      * The caller owns the result and should delete it when done.
 199      * @return   a copy of the object
 200      * @stable ICU 4.0
 201      */
 202     virtual DateIntervalInfo* clone(void) const;
 203
 204     /**
 205      * Destructor.
 206      * It is virtual to be safe, but it is not designed to be subclassed.
 207      * @stable ICU 4.0
 208      */
 209     virtual ~DateIntervalInfo();
 210
 211
 212     /**
 213      * Return true if another object is semantically equal to this one.
 214      *
 215      * @param other    the DateIntervalInfo object to be compared with.
 216      * @return         true if other is semantically equal to this.
 217      * @stable ICU 4.0
 218      */
 219     virtual UBool operator==(const DateIntervalInfo& other) const;
 220
 221     /**
 222      * Return true if another object is semantically unequal to this one.
 223      *
 224      * @param other    the DateIntervalInfo object to be compared with.
 225      * @return         true if other is semantically unequal to this.
 226      * @stable ICU 4.0
 227      */
 228     UBool operator!=(const DateIntervalInfo& other) const;
 229
 230
 231
 232     /**
 233      * Provides a way for client to build interval patterns.
 234      * User could construct DateIntervalInfo by providing a list of skeletons
 235      * and their patterns.
 236      * <P>
 237      * For example:
 238      * <pre>
 239      * UErrorCode status = U_ZERO_ERROR;
 240      * DateIntervalInfo dIntervalInfo = new DateIntervalInfo();
 241      * dIntervalInfo->setFallbackIntervalPattern("{0} ~ {1}");
 242      * dIntervalInfo->setIntervalPattern("yMd", UCAL_YEAR, "'from' yyyy-M-d 'to' yyyy-M-d", status);
 243      * dIntervalInfo->setIntervalPattern("yMMMd", UCAL_MONTH, "'from' yyyy MMM d 'to' MMM d", status);
 244      * dIntervalInfo->setIntervalPattern("yMMMd", UCAL_DAY, "yyyy MMM d-d", status, status);
 245      * </pre>
 246      *
 247      * Restriction:
 248      * Currently, users can only set interval patterns when the following
 249      * calendar fields are different: ERA, YEAR, MONTH, DATE,  DAY_OF_MONTH,
 250      * DAY_OF_WEEK, AM_PM,  HOUR, HOUR_OF_DAY, and MINUTE.
 251      * Interval patterns when other calendar fields are different are
 252      * not supported.
 253      *
 254      * @param skeleton         the skeleton on which interval pattern based
 255      * @param lrgDiffCalUnit   the largest different calendar unit.
 256      * @param intervalPattern  the interval pattern on the largest different
 257      *                         calendar unit.
 258      *                         For example, if lrgDiffCalUnit is
 259      *                         "year", the interval pattern for en_US when year
 260      *                         is different could be "'from' yyyy 'to' yyyy".
 261      * @param status           output param set to success/failure code on exit
 262      * @stable ICU 4.0
 263      */
 264     void setIntervalPattern(const UnicodeString& skeleton,
 265                             UCalendarDateFields lrgDiffCalUnit,
 266                             const UnicodeString& intervalPattern,
 267                             UErrorCode& status);
 268
 269     /**
 270      * Get the interval pattern given skeleton and
 271      * the largest different calendar field.
 272      * @param skeleton   the skeleton
 273      * @param field      the largest different calendar field
 274      * @param result     output param to receive the pattern
 275      * @param status     output param set to success/failure code on exit
 276      * @return a reference to 'result'
 277      * @stable ICU 4.0
 278      */
 279     UnicodeString& getIntervalPattern(const UnicodeString& skeleton,
 280                                       UCalendarDateFields field,
 281                                       UnicodeString& result,
 282                                       UErrorCode& status) const;
 283
 284     /**
 285      * Get the fallback interval pattern.
 286      * @param  result   output param to receive the pattern
 287      * @return a reference to 'result'
 288      * @stable ICU 4.0
 289      */
 290     UnicodeString& getFallbackIntervalPattern(UnicodeString& result) const;
 291
 292
 293     /**
 294      * Re-set the fallback interval pattern.
 295      *
 296      * In construction, default fallback pattern is set as "{0} - {1}".
 297      * And constructor taking locale as parameter will set the
 298      * fallback pattern as what defined in the locale resource file.
 299      *
 300      * This method provides a way for user to replace the fallback pattern.
 301      *
 302      * @param fallbackPattern  fall-back interval pattern.
 303      * @param status           output param set to success/failure code on exit
 304      * @stable ICU 4.0
 305      */
 306     void setFallbackIntervalPattern(const UnicodeString& fallbackPattern,
 307                                     UErrorCode& status);
 308
 309
 310     /** Get default order -- whether the first date in pattern is later date
 311                              or not.
 312      * return default date ordering in interval pattern. TRUE if the first date
 313      *        in pattern is later date, FALSE otherwise.
 314      * @stable ICU 4.0
 315      */
 316     UBool getDefaultOrder() const;
 317
 318
 319     /**
 320      * ICU "poor man's RTTI", returns a UClassID for the actual class.
 321      *
 322      * @stable ICU 4.0
 323      */
 324     virtual UClassID getDynamicClassID() const;
 325
 326     /**
 327      * ICU "poor man's RTTI", returns a UClassID for this class.
 328      *
 329      * @stable ICU 4.0
 330      */
 331     static UClassID U_EXPORT2 getStaticClassID();
 332
 333
 334 private:
 335     /**
 336      * DateIntervalFormat will need access to
 337      * getBestSkeleton(), parseSkeleton(), enum IntervalPatternIndex,
 338      * and calendarFieldToPatternIndex().
 339      *
 340      * Instead of making above public,
 341      * make DateIntervalFormat a friend of DateIntervalInfo.
 342      */
 343     friend class DateIntervalFormat;
 344
 345     /**
 346      * Internal struct used to load resource bundle data.
 347      */
 348     struct DateIntervalSink;
 349
 350     /**
 351      * Following is for saving the interval patterns.
 352      * We only support interval patterns on
 353      * ERA, YEAR, MONTH, DAY, AM_PM, HOUR, and MINUTE
 354      */
 355     enum IntervalPatternIndex
 356     {
 357         kIPI_ERA,
 358         kIPI_YEAR,
 359         kIPI_MONTH,
 360         kIPI_DATE,
 361         kIPI_AM_PM,
 362         kIPI_HOUR,
 363         kIPI_MINUTE,
 364         kIPI_SECOND,
 365         kIPI_MAX_INDEX
 366     };
 367 public:
 368 #ifndef U_HIDE_INTERNAL_API
 369     /**
 370      * Max index for stored interval patterns
 371      * @internal ICU 4.4
 372      */
 373      enum {
 374          kMaxIntervalPatternIndex = kIPI_MAX_INDEX
 375      };
 376 #endif  /* U_HIDE_INTERNAL_API */
 377 private:
 378
 379
 380     /**
 381      * Initialize the DateIntervalInfo from locale
 382      * @param locale   the given locale.
 383      * @param status   output param set to success/failure code on exit
 384      */
 385     void initializeData(const Locale& locale, UErrorCode& status);
 386
 387
 388     /* Set Interval pattern.
 389      *
 390      * It sets interval pattern into the hash map.
 391      *
 392      * @param skeleton         skeleton on which the interval pattern based
 393      * @param lrgDiffCalUnit   the largest different calendar unit.
 394      * @param intervalPattern  the interval pattern on the largest different
 395      *                         calendar unit.
 396      * @param status           output param set to success/failure code on exit
 397      */
 398     void setIntervalPatternInternally(const UnicodeString& skeleton,
 399                                       UCalendarDateFields lrgDiffCalUnit,
 400                                       const UnicodeString& intervalPattern,
 401                                       UErrorCode& status);
 402
 403
 404     /**given an input skeleton, get the best match skeleton
 405      * which has pre-defined interval pattern in resource file.
 406      * Also return the difference between the input skeleton
 407      * and the best match skeleton.
 408      *
 409      * TODO (xji): set field weight or
 410      *             isolate the funtionality in DateTimePatternGenerator
 411      * @param  skeleton               input skeleton
 412      * @param  bestMatchDistanceInfo  the difference between input skeleton
 413      *                                and best match skeleton.
 414      *         0, if there is exact match for input skeleton
 415      *         1, if there is only field width difference between
 416      *            the best match and the input skeleton
 417      *         2, the only field difference is 'v' and 'z'
 418      *        -1, if there is calendar field difference between
 419      *            the best match and the input skeleton
 420      * @return                        best match skeleton
 421      */
 422     const UnicodeString* getBestSkeleton(const UnicodeString& skeleton,
 423                                          int8_t& bestMatchDistanceInfo) const;
 424
 425
 426     /**
 427      * Parse skeleton, save each field's width.
 428      * It is used for looking for best match skeleton,
 429      * and adjust pattern field width.
 430      * @param skeleton            skeleton to be parsed
 431      * @param skeletonFieldWidth  parsed skeleton field width
 432      */
 433     static void U_EXPORT2 parseSkeleton(const UnicodeString& skeleton,
 434                                         int32_t* skeletonFieldWidth);
 435
 436
 437     /**
 438      * Check whether one field width is numeric while the other is string.
 439      *
 440      * TODO (xji): make it general
 441      *
 442      * @param fieldWidth          one field width
 443      * @param anotherFieldWidth   another field width
 444      * @param patternLetter       pattern letter char
 445      * @return true if one field width is numeric and the other is string,
 446      *         false otherwise.
 447      */
 448     static UBool U_EXPORT2 stringNumeric(int32_t fieldWidth,
 449                                          int32_t anotherFieldWidth,
 450                                          char patternLetter);
 451
 452
 453     /**
 454      * Convert calendar field to the interval pattern index in
 455      * hash table.
 456      *
 457      * Since we only support the following calendar fields:
 458      * ERA, YEAR, MONTH, DATE,  DAY_OF_MONTH, DAY_OF_WEEK,
 459      * AM_PM,  HOUR, HOUR_OF_DAY, and MINUTE,
 460      * We reserve only 4 interval patterns for a skeleton.
 461      *
 462      * @param field    calendar field
 463      * @param status   output param set to success/failure code on exit
 464      * @return  interval pattern index in hash table
 465      */
 466     static IntervalPatternIndex U_EXPORT2 calendarFieldToIntervalIndex(
 467                                                       UCalendarDateFields field,
 468                                                       UErrorCode& status);
 469
 470
 471     /**
 472      * delete hash table (of type fIntervalPatterns).
 473      *
 474      * @param hTable  hash table to be deleted
 475      */
 476     void deleteHash(Hashtable* hTable);
 477
 478
 479     /**
 480      * initialize hash table (of type fIntervalPatterns).
 481      *
 482      * @param status   output param set to success/failure code on exit
 483      * @return         hash table initialized
 484      */
 485     Hashtable* initHash(UErrorCode& status);
 486
 487
 488
 489     /**
 490      * copy hash table (of type fIntervalPatterns).
 491      *
 492      * @param source   the source to copy from
 493      * @param target   the target to copy to
 494      * @param status   output param set to success/failure code on exit
 495      */
 496     void copyHash(const Hashtable* source, Hashtable* target, UErrorCode& status);
 497
 498
 499     // data members
 500     // fallback interval pattern
 501     UnicodeString fFallbackIntervalPattern;
 502     // default order
 503     UBool fFirstDateInPtnIsLaterDate;
 504
 505     // HashMap<UnicodeString, UnicodeString[kIPI_MAX_INDEX]>
 506     // HashMap( skeleton, pattern[largest_different_field] )
 507     Hashtable* fIntervalPatterns;
 508
 509 };// end class DateIntervalInfo
 510
 511
 512 inline UBool
 513 DateIntervalInfo::operator!=(const DateIntervalInfo& other) const {
 514     return !operator==(other);
 515 }
 516
 517
 518 U_NAMESPACE_END
 519 #endif // U_SHOW_CPLUSPLUS_API
 520
 521 #endif
 522
 523 #endif
 524