jpayne@69: // © 2016 and later: Unicode, Inc. and others. jpayne@69: // License & terms of use: http://www.unicode.org/copyright.html jpayne@69: /* jpayne@69: ******************************************************************************* jpayne@69: * Copyright (C) 2008-2016, International Business Machines Corporation and jpayne@69: * others. All Rights Reserved. jpayne@69: ******************************************************************************* jpayne@69: * jpayne@69: * File DTITVINF.H jpayne@69: * jpayne@69: ******************************************************************************* jpayne@69: */ jpayne@69: jpayne@69: #ifndef __DTITVINF_H__ jpayne@69: #define __DTITVINF_H__ jpayne@69: jpayne@69: #include "unicode/utypes.h" jpayne@69: jpayne@69: #if U_SHOW_CPLUSPLUS_API jpayne@69: jpayne@69: /** jpayne@69: * \file jpayne@69: * \brief C++ API: Date/Time interval patterns for formatting date/time interval jpayne@69: */ jpayne@69: jpayne@69: #if !UCONFIG_NO_FORMATTING jpayne@69: jpayne@69: #include "unicode/udat.h" jpayne@69: #include "unicode/locid.h" jpayne@69: #include "unicode/ucal.h" jpayne@69: #include "unicode/dtptngen.h" jpayne@69: jpayne@69: U_NAMESPACE_BEGIN jpayne@69: jpayne@69: /** jpayne@69: * DateIntervalInfo is a public class for encapsulating localizable jpayne@69: * date time interval patterns. It is used by DateIntervalFormat. jpayne@69: * jpayne@69: *

jpayne@69: * For most users, ordinary use of DateIntervalFormat does not need to create jpayne@69: * DateIntervalInfo object directly. jpayne@69: * DateIntervalFormat will take care of it when creating a date interval jpayne@69: * formatter when user pass in skeleton and locale. jpayne@69: * jpayne@69: *

jpayne@69: * For power users, who want to create their own date interval patterns, jpayne@69: * or want to re-set date interval patterns, they could do so by jpayne@69: * directly creating DateIntervalInfo and manupulating it. jpayne@69: * jpayne@69: *

jpayne@69: * Logically, the interval patterns are mappings jpayne@69: * from (skeleton, the_largest_different_calendar_field) jpayne@69: * to (date_interval_pattern). jpayne@69: * jpayne@69: *

jpayne@69: * A skeleton jpayne@69: *

    jpayne@69: *
  1. jpayne@69: * only keeps the field pattern letter and ignores all other parts jpayne@69: * in a pattern, such as space, punctuations, and string literals. jpayne@69: *
  2. jpayne@69: * hides the order of fields. jpayne@69: *
  3. jpayne@69: * might hide a field's pattern letter length. jpayne@69: * jpayne@69: * For those non-digit calendar fields, the pattern letter length is jpayne@69: * important, such as MMM, MMMM, and MMMMM; EEE and EEEE, jpayne@69: * and the field's pattern letter length is honored. jpayne@69: * jpayne@69: * For the digit calendar fields, such as M or MM, d or dd, yy or yyyy, jpayne@69: * the field pattern length is ignored and the best match, which is defined jpayne@69: * in date time patterns, will be returned without honor the field pattern jpayne@69: * letter length in skeleton. jpayne@69: *
jpayne@69: * jpayne@69: *

jpayne@69: * The calendar fields we support for interval formatting are: jpayne@69: * year, month, date, day-of-week, am-pm, hour, hour-of-day, and minute. jpayne@69: * Those calendar fields can be defined in the following order: jpayne@69: * year > month > date > am-pm > hour > minute jpayne@69: * jpayne@69: * The largest different calendar fields between 2 calendars is the jpayne@69: * first different calendar field in above order. jpayne@69: * jpayne@69: * For example: the largest different calendar fields between "Jan 10, 2007" jpayne@69: * and "Feb 20, 2008" is year. jpayne@69: * jpayne@69: *

jpayne@69: * There is a set of pre-defined static skeleton strings. jpayne@69: * There are pre-defined interval patterns for those pre-defined skeletons jpayne@69: * in locales' resource files. jpayne@69: * For example, for a skeleton UDAT_YEAR_ABBR_MONTH_DAY, which is "yMMMd", jpayne@69: * in en_US, if the largest different calendar field between date1 and date2 jpayne@69: * is "year", the date interval pattern is "MMM d, yyyy - MMM d, yyyy", jpayne@69: * such as "Jan 10, 2007 - Jan 10, 2008". jpayne@69: * If the largest different calendar field between date1 and date2 is "month", jpayne@69: * the date interval pattern is "MMM d - MMM d, yyyy", jpayne@69: * such as "Jan 10 - Feb 10, 2007". jpayne@69: * If the largest different calendar field between date1 and date2 is "day", jpayne@69: * the date interval pattern is "MMM d-d, yyyy", such as "Jan 10-20, 2007". jpayne@69: * jpayne@69: * For date skeleton, the interval patterns when year, or month, or date is jpayne@69: * different are defined in resource files. jpayne@69: * For time skeleton, the interval patterns when am/pm, or hour, or minute is jpayne@69: * different are defined in resource files. jpayne@69: * jpayne@69: * jpayne@69: *

jpayne@69: * There are 2 dates in interval pattern. For most locales, the first date jpayne@69: * in an interval pattern is the earlier date. There might be a locale in which jpayne@69: * the first date in an interval pattern is the later date. jpayne@69: * We use fallback format for the default order for the locale. jpayne@69: * For example, if the fallback format is "{0} - {1}", it means jpayne@69: * the first date in the interval pattern for this locale is earlier date. jpayne@69: * If the fallback format is "{1} - {0}", it means the first date is the jpayne@69: * later date. jpayne@69: * For a particular interval pattern, the default order can be overriden jpayne@69: * by prefixing "latestFirst:" or "earliestFirst:" to the interval pattern. jpayne@69: * For example, if the fallback format is "{0}-{1}", jpayne@69: * but for skeleton "yMMMd", the interval pattern when day is different is jpayne@69: * "latestFirst:d-d MMM yy", it means by default, the first date in interval jpayne@69: * pattern is the earlier date. But for skeleton "yMMMd", when day is different, jpayne@69: * the first date in "d-d MMM yy" is the later date. jpayne@69: * jpayne@69: *

jpayne@69: * The recommended way to create a DateIntervalFormat object is to pass in jpayne@69: * the locale. jpayne@69: * By using a Locale parameter, the DateIntervalFormat object is jpayne@69: * initialized with the pre-defined interval patterns for a given or jpayne@69: * default locale. jpayne@69: *

jpayne@69: * Users can also create DateIntervalFormat object jpayne@69: * by supplying their own interval patterns. jpayne@69: * It provides flexibility for power users. jpayne@69: * jpayne@69: *

jpayne@69: * After a DateIntervalInfo object is created, clients may modify jpayne@69: * the interval patterns using setIntervalPattern function as so desired. jpayne@69: * Currently, users can only set interval patterns when the following jpayne@69: * calendar fields are different: ERA, YEAR, MONTH, DATE, DAY_OF_MONTH, jpayne@69: * DAY_OF_WEEK, AM_PM, HOUR, HOUR_OF_DAY, MINUTE, SECOND, and MILLISECOND. jpayne@69: * Interval patterns when other calendar fields are different is not supported. jpayne@69: *

jpayne@69: * DateIntervalInfo objects are cloneable. jpayne@69: * When clients obtain a DateIntervalInfo object, jpayne@69: * they can feel free to modify it as necessary. jpayne@69: *

jpayne@69: * DateIntervalInfo are not expected to be subclassed. jpayne@69: * Data for a calendar is loaded out of resource bundles. jpayne@69: * Through ICU 4.4, date interval patterns are only supported in the Gregorian jpayne@69: * calendar; non-Gregorian calendars are supported from ICU 4.4.1. jpayne@69: * @stable ICU 4.0 jpayne@69: **/ jpayne@69: class U_I18N_API DateIntervalInfo U_FINAL : public UObject { jpayne@69: public: jpayne@69: /** jpayne@69: * Default constructor. jpayne@69: * It does not initialize any interval patterns except jpayne@69: * that it initialize default fall-back pattern as "{0} - {1}", jpayne@69: * which can be reset by setFallbackIntervalPattern(). jpayne@69: * It should be followed by setFallbackIntervalPattern() and jpayne@69: * setIntervalPattern(), jpayne@69: * and is recommended to be used only for power users who jpayne@69: * wants to create their own interval patterns and use them to create jpayne@69: * date interval formatter. jpayne@69: * @param status output param set to success/failure code on exit jpayne@69: * @internal ICU 4.0 jpayne@69: */ jpayne@69: DateIntervalInfo(UErrorCode& status); jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * Construct DateIntervalInfo for the given locale, jpayne@69: * @param locale the interval patterns are loaded from the appropriate calendar jpayne@69: * data (specified calendar or default calendar) in this locale. jpayne@69: * @param status output param set to success/failure code on exit jpayne@69: * @stable ICU 4.0 jpayne@69: */ jpayne@69: DateIntervalInfo(const Locale& locale, UErrorCode& status); jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * Copy constructor. jpayne@69: * @stable ICU 4.0 jpayne@69: */ jpayne@69: DateIntervalInfo(const DateIntervalInfo&); jpayne@69: jpayne@69: /** jpayne@69: * Assignment operator jpayne@69: * @stable ICU 4.0 jpayne@69: */ jpayne@69: DateIntervalInfo& operator=(const DateIntervalInfo&); jpayne@69: jpayne@69: /** jpayne@69: * Clone this object polymorphically. jpayne@69: * The caller owns the result and should delete it when done. jpayne@69: * @return a copy of the object jpayne@69: * @stable ICU 4.0 jpayne@69: */ jpayne@69: virtual DateIntervalInfo* clone() const; jpayne@69: jpayne@69: /** jpayne@69: * Destructor. jpayne@69: * It is virtual to be safe, but it is not designed to be subclassed. jpayne@69: * @stable ICU 4.0 jpayne@69: */ jpayne@69: virtual ~DateIntervalInfo(); jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * Return true if another object is semantically equal to this one. jpayne@69: * jpayne@69: * @param other the DateIntervalInfo object to be compared with. jpayne@69: * @return true if other is semantically equal to this. jpayne@69: * @stable ICU 4.0 jpayne@69: */ jpayne@69: virtual UBool operator==(const DateIntervalInfo& other) const; jpayne@69: jpayne@69: /** jpayne@69: * Return true if another object is semantically unequal to this one. jpayne@69: * jpayne@69: * @param other the DateIntervalInfo object to be compared with. jpayne@69: * @return true if other is semantically unequal to this. jpayne@69: * @stable ICU 4.0 jpayne@69: */ jpayne@69: UBool operator!=(const DateIntervalInfo& other) const; jpayne@69: jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * Provides a way for client to build interval patterns. jpayne@69: * User could construct DateIntervalInfo by providing a list of skeletons jpayne@69: * and their patterns. jpayne@69: *

jpayne@69: * For example: jpayne@69: * 

jpayne@69:      * UErrorCode status = U_ZERO_ERROR;
jpayne@69:      * DateIntervalInfo dIntervalInfo = new DateIntervalInfo();
jpayne@69:      * dIntervalInfo->setFallbackIntervalPattern("{0} ~ {1}");
jpayne@69:      * dIntervalInfo->setIntervalPattern("yMd", UCAL_YEAR, "'from' yyyy-M-d 'to' yyyy-M-d", status);
jpayne@69:      * dIntervalInfo->setIntervalPattern("yMMMd", UCAL_MONTH, "'from' yyyy MMM d 'to' MMM d", status);
jpayne@69:      * dIntervalInfo->setIntervalPattern("yMMMd", UCAL_DAY, "yyyy MMM d-d", status, status);
jpayne@69:      *
jpayne@69: * jpayne@69: * Restriction: jpayne@69: * Currently, users can only set interval patterns when the following jpayne@69: * calendar fields are different: ERA, YEAR, MONTH, DATE, DAY_OF_MONTH, jpayne@69: * DAY_OF_WEEK, AM_PM, HOUR, HOUR_OF_DAY, MINUTE, SECOND and MILLISECOND. jpayne@69: * Interval patterns when other calendar fields are different are jpayne@69: * not supported. jpayne@69: * jpayne@69: * @param skeleton the skeleton on which interval pattern based jpayne@69: * @param lrgDiffCalUnit the largest different calendar unit. jpayne@69: * @param intervalPattern the interval pattern on the largest different jpayne@69: * calendar unit. jpayne@69: * For example, if lrgDiffCalUnit is jpayne@69: * "year", the interval pattern for en_US when year jpayne@69: * is different could be "'from' yyyy 'to' yyyy". jpayne@69: * @param status output param set to success/failure code on exit jpayne@69: * @stable ICU 4.0 jpayne@69: */ jpayne@69: void setIntervalPattern(const UnicodeString& skeleton, jpayne@69: UCalendarDateFields lrgDiffCalUnit, jpayne@69: const UnicodeString& intervalPattern, jpayne@69: UErrorCode& status); jpayne@69: jpayne@69: /** jpayne@69: * Get the interval pattern given skeleton and jpayne@69: * the largest different calendar field. jpayne@69: * @param skeleton the skeleton jpayne@69: * @param field the largest different calendar field jpayne@69: * @param result output param to receive the pattern jpayne@69: * @param status output param set to success/failure code on exit jpayne@69: * @return a reference to 'result' jpayne@69: * @stable ICU 4.0 jpayne@69: */ jpayne@69: UnicodeString& getIntervalPattern(const UnicodeString& skeleton, jpayne@69: UCalendarDateFields field, jpayne@69: UnicodeString& result, jpayne@69: UErrorCode& status) const; jpayne@69: jpayne@69: /** jpayne@69: * Get the fallback interval pattern. jpayne@69: * @param result output param to receive the pattern jpayne@69: * @return a reference to 'result' jpayne@69: * @stable ICU 4.0 jpayne@69: */ jpayne@69: UnicodeString& getFallbackIntervalPattern(UnicodeString& result) const; jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * Re-set the fallback interval pattern. jpayne@69: * jpayne@69: * In construction, default fallback pattern is set as "{0} - {1}". jpayne@69: * And constructor taking locale as parameter will set the jpayne@69: * fallback pattern as what defined in the locale resource file. jpayne@69: * jpayne@69: * This method provides a way for user to replace the fallback pattern. jpayne@69: * jpayne@69: * @param fallbackPattern fall-back interval pattern. jpayne@69: * @param status output param set to success/failure code on exit jpayne@69: * @stable ICU 4.0 jpayne@69: */ jpayne@69: void setFallbackIntervalPattern(const UnicodeString& fallbackPattern, jpayne@69: UErrorCode& status); jpayne@69: jpayne@69: jpayne@69: /** Get default order -- whether the first date in pattern is later date jpayne@69: or not. jpayne@69: * return default date ordering in interval pattern. TRUE if the first date jpayne@69: * in pattern is later date, FALSE otherwise. jpayne@69: * @stable ICU 4.0 jpayne@69: */ jpayne@69: UBool getDefaultOrder() const; jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * ICU "poor man's RTTI", returns a UClassID for the actual class. jpayne@69: * jpayne@69: * @stable ICU 4.0 jpayne@69: */ jpayne@69: virtual UClassID getDynamicClassID() const; jpayne@69: jpayne@69: /** jpayne@69: * ICU "poor man's RTTI", returns a UClassID for this class. jpayne@69: * jpayne@69: * @stable ICU 4.0 jpayne@69: */ jpayne@69: static UClassID U_EXPORT2 getStaticClassID(); jpayne@69: jpayne@69: jpayne@69: private: jpayne@69: /** jpayne@69: * DateIntervalFormat will need access to jpayne@69: * getBestSkeleton(), parseSkeleton(), enum IntervalPatternIndex, jpayne@69: * and calendarFieldToPatternIndex(). jpayne@69: * jpayne@69: * Instead of making above public, jpayne@69: * make DateIntervalFormat a friend of DateIntervalInfo. jpayne@69: */ jpayne@69: friend class DateIntervalFormat; jpayne@69: jpayne@69: /** jpayne@69: * Internal struct used to load resource bundle data. jpayne@69: */ jpayne@69: struct DateIntervalSink; jpayne@69: jpayne@69: /** jpayne@69: * Following is for saving the interval patterns. jpayne@69: * We only support interval patterns on jpayne@69: * ERA, YEAR, MONTH, DAY, AM_PM, HOUR, MINUTE, SECOND and MILLISECOND. jpayne@69: */ jpayne@69: enum IntervalPatternIndex jpayne@69: { jpayne@69: kIPI_ERA, jpayne@69: kIPI_YEAR, jpayne@69: kIPI_MONTH, jpayne@69: kIPI_DATE, jpayne@69: kIPI_AM_PM, jpayne@69: kIPI_HOUR, jpayne@69: kIPI_MINUTE, jpayne@69: kIPI_SECOND, jpayne@69: kIPI_MILLISECOND, jpayne@69: kIPI_MAX_INDEX jpayne@69: }; jpayne@69: public: jpayne@69: #ifndef U_HIDE_INTERNAL_API jpayne@69: /** jpayne@69: * Max index for stored interval patterns jpayne@69: * @internal ICU 4.4 jpayne@69: */ jpayne@69: enum { jpayne@69: kMaxIntervalPatternIndex = kIPI_MAX_INDEX jpayne@69: }; jpayne@69: #endif /* U_HIDE_INTERNAL_API */ jpayne@69: private: jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * Initialize the DateIntervalInfo from locale jpayne@69: * @param locale the given locale. jpayne@69: * @param status output param set to success/failure code on exit jpayne@69: */ jpayne@69: void initializeData(const Locale& locale, UErrorCode& status); jpayne@69: jpayne@69: jpayne@69: /* Set Interval pattern. jpayne@69: * jpayne@69: * It sets interval pattern into the hash map. jpayne@69: * jpayne@69: * @param skeleton skeleton on which the interval pattern based jpayne@69: * @param lrgDiffCalUnit the largest different calendar unit. jpayne@69: * @param intervalPattern the interval pattern on the largest different jpayne@69: * calendar unit. jpayne@69: * @param status output param set to success/failure code on exit jpayne@69: */ jpayne@69: void setIntervalPatternInternally(const UnicodeString& skeleton, jpayne@69: UCalendarDateFields lrgDiffCalUnit, jpayne@69: const UnicodeString& intervalPattern, jpayne@69: UErrorCode& status); jpayne@69: jpayne@69: jpayne@69: /**given an input skeleton, get the best match skeleton jpayne@69: * which has pre-defined interval pattern in resource file. jpayne@69: * Also return the difference between the input skeleton jpayne@69: * and the best match skeleton. jpayne@69: * jpayne@69: * TODO (xji): set field weight or jpayne@69: * isolate the funtionality in DateTimePatternGenerator jpayne@69: * @param skeleton input skeleton jpayne@69: * @param bestMatchDistanceInfo the difference between input skeleton jpayne@69: * and best match skeleton. jpayne@69: * 0, if there is exact match for input skeleton jpayne@69: * 1, if there is only field width difference between jpayne@69: * the best match and the input skeleton jpayne@69: * 2, the only field difference is 'v' and 'z' jpayne@69: * -1, if there is calendar field difference between jpayne@69: * the best match and the input skeleton jpayne@69: * @return best match skeleton jpayne@69: */ jpayne@69: const UnicodeString* getBestSkeleton(const UnicodeString& skeleton, jpayne@69: int8_t& bestMatchDistanceInfo) const; jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * Parse skeleton, save each field's width. jpayne@69: * It is used for looking for best match skeleton, jpayne@69: * and adjust pattern field width. jpayne@69: * @param skeleton skeleton to be parsed jpayne@69: * @param skeletonFieldWidth parsed skeleton field width jpayne@69: */ jpayne@69: static void U_EXPORT2 parseSkeleton(const UnicodeString& skeleton, jpayne@69: int32_t* skeletonFieldWidth); jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * Check whether one field width is numeric while the other is string. jpayne@69: * jpayne@69: * TODO (xji): make it general jpayne@69: * jpayne@69: * @param fieldWidth one field width jpayne@69: * @param anotherFieldWidth another field width jpayne@69: * @param patternLetter pattern letter char jpayne@69: * @return true if one field width is numeric and the other is string, jpayne@69: * false otherwise. jpayne@69: */ jpayne@69: static UBool U_EXPORT2 stringNumeric(int32_t fieldWidth, jpayne@69: int32_t anotherFieldWidth, jpayne@69: char patternLetter); jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * Convert calendar field to the interval pattern index in jpayne@69: * hash table. jpayne@69: * jpayne@69: * Since we only support the following calendar fields: jpayne@69: * ERA, YEAR, MONTH, DATE, DAY_OF_MONTH, DAY_OF_WEEK, jpayne@69: * AM_PM, HOUR, HOUR_OF_DAY, MINUTE, SECOND, and MILLISECOND. jpayne@69: * We reserve only 4 interval patterns for a skeleton. jpayne@69: * jpayne@69: * @param field calendar field jpayne@69: * @param status output param set to success/failure code on exit jpayne@69: * @return interval pattern index in hash table jpayne@69: */ jpayne@69: static IntervalPatternIndex U_EXPORT2 calendarFieldToIntervalIndex( jpayne@69: UCalendarDateFields field, jpayne@69: UErrorCode& status); jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * delete hash table (of type fIntervalPatterns). jpayne@69: * jpayne@69: * @param hTable hash table to be deleted jpayne@69: */ jpayne@69: void deleteHash(Hashtable* hTable); jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * initialize hash table (of type fIntervalPatterns). jpayne@69: * jpayne@69: * @param status output param set to success/failure code on exit jpayne@69: * @return hash table initialized jpayne@69: */ jpayne@69: Hashtable* initHash(UErrorCode& status); jpayne@69: jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * copy hash table (of type fIntervalPatterns). jpayne@69: * jpayne@69: * @param source the source to copy from jpayne@69: * @param target the target to copy to jpayne@69: * @param status output param set to success/failure code on exit jpayne@69: */ jpayne@69: void copyHash(const Hashtable* source, Hashtable* target, UErrorCode& status); jpayne@69: jpayne@69: jpayne@69: // data members jpayne@69: // fallback interval pattern jpayne@69: UnicodeString fFallbackIntervalPattern; jpayne@69: // default order jpayne@69: UBool fFirstDateInPtnIsLaterDate; jpayne@69: jpayne@69: // HashMap jpayne@69: // HashMap( skeleton, pattern[largest_different_field] ) jpayne@69: Hashtable* fIntervalPatterns; jpayne@69: jpayne@69: };// end class DateIntervalInfo jpayne@69: jpayne@69: jpayne@69: inline UBool jpayne@69: DateIntervalInfo::operator!=(const DateIntervalInfo& other) const { jpayne@69: return !operator==(other); jpayne@69: } jpayne@69: jpayne@69: jpayne@69: U_NAMESPACE_END jpayne@69: jpayne@69: #endif jpayne@69: jpayne@69: #endif /* U_SHOW_CPLUSPLUS_API */ jpayne@69: jpayne@69: #endif jpayne@69: