Edit file File name : dtitvfmt.h Content :// © 2016 and later: Unicode, Inc. and others. // License & terms of use: http://www.unicode.org/copyright.html /******************************************************************************** * Copyright (C) 2008-2016, International Business Machines Corporation and * others. All Rights Reserved. ******************************************************************************* * * File DTITVFMT.H * ******************************************************************************* */ #ifndef __DTITVFMT_H__ #define __DTITVFMT_H__ #include "unicode/utypes.h" #if U_SHOW_CPLUSPLUS_API /** * \file * \brief C++ API: Format and parse date interval in a language-independent manner. */ #if !UCONFIG_NO_FORMATTING #include "unicode/ucal.h" #include "unicode/smpdtfmt.h" #include "unicode/dtintrv.h" #include "unicode/dtitvinf.h" #include "unicode/dtptngen.h" #include "unicode/formattedvalue.h" U_NAMESPACE_BEGIN class FormattedDateIntervalData; class DateIntervalFormat; #ifndef U_HIDE_DRAFT_API /** * An immutable class containing the result of a date interval formatting operation. * * Instances of this class are immutable and thread-safe. * * When calling nextPosition(): * The fields are returned from left to right. The special field category * UFIELD_CATEGORY_DATE_INTERVAL_SPAN is used to indicate which datetime * primitives came from which arguments: 0 means fromCalendar, and 1 means * toCalendar. The span category will always occur before the * corresponding fields in UFIELD_CATEGORY_DATE * in the nextPosition() iterator. * * Not intended for public subclassing. * * @draft ICU 64 */ class U_I18N_API FormattedDateInterval : public UMemory, public FormattedValue { public: /** * Default constructor; makes an empty FormattedDateInterval. * @draft ICU 64 */ FormattedDateInterval() : fData(nullptr), fErrorCode(U_INVALID_STATE_ERROR) {} /** * Move constructor: Leaves the source FormattedDateInterval in an undefined state. * @draft ICU 64 */ FormattedDateInterval(FormattedDateInterval&& src) U_NOEXCEPT; /** * Destruct an instance of FormattedDateInterval. * @draft ICU 64 */ virtual ~FormattedDateInterval() U_OVERRIDE; /** Copying not supported; use move constructor instead. */ FormattedDateInterval(const FormattedDateInterval&) = delete; /** Copying not supported; use move assignment instead. */ FormattedDateInterval& operator=(const FormattedDateInterval&) = delete; /** * Move assignment: Leaves the source FormattedDateInterval in an undefined state. * @draft ICU 64 */ FormattedDateInterval& operator=(FormattedDateInterval&& src) U_NOEXCEPT; /** @copydoc FormattedValue::toString() */ UnicodeString toString(UErrorCode& status) const U_OVERRIDE; /** @copydoc FormattedValue::toTempString() */ UnicodeString toTempString(UErrorCode& status) const U_OVERRIDE; /** @copydoc FormattedValue::appendTo() */ Appendable &appendTo(Appendable& appendable, UErrorCode& status) const U_OVERRIDE; /** @copydoc FormattedValue::nextPosition() */ UBool nextPosition(ConstrainedFieldPosition& cfpos, UErrorCode& status) const U_OVERRIDE; private: FormattedDateIntervalData *fData; UErrorCode fErrorCode; explicit FormattedDateInterval(FormattedDateIntervalData *results) : fData(results), fErrorCode(U_ZERO_ERROR) {} explicit FormattedDateInterval(UErrorCode errorCode) : fData(nullptr), fErrorCode(errorCode) {} friend class DateIntervalFormat; }; #endif /* U_HIDE_DRAFT_API */ /** * DateIntervalFormat is a class for formatting and parsing date * intervals in a language-independent manner. * Only formatting is supported, parsing is not supported. * * <P> * Date interval means from one date to another date, * for example, from "Jan 11, 2008" to "Jan 18, 2008". * We introduced class DateInterval to represent it. * DateInterval is a pair of UDate, which is * the standard milliseconds since 24:00 GMT, Jan 1, 1970. * * <P> * DateIntervalFormat formats a DateInterval into * text as compactly as possible. * For example, the date interval format from "Jan 11, 2008" to "Jan 18,. 2008" * is "Jan 11-18, 2008" for English. * And it parses text into DateInterval, * although initially, parsing is not supported. * * <P> * There is no structural information in date time patterns. * For any punctuations and string literals inside a date time pattern, * we do not know whether it is just a separator, or a prefix, or a suffix. * Without such information, so, it is difficult to generate a sub-pattern * (or super-pattern) by algorithm. * So, formatting a DateInterval is pattern-driven. It is very * similar to formatting in SimpleDateFormat. * We introduce class DateIntervalInfo to save date interval * patterns, similar to date time pattern in SimpleDateFormat. * * <P> * Logically, the interval patterns are mappings * from (skeleton, the_largest_different_calendar_field) * to (date_interval_pattern). * * <P> * A skeleton * <ol> * <li> * only keeps the field pattern letter and ignores all other parts * in a pattern, such as space, punctuations, and string literals. * </li> * <li> * hides the order of fields. * </li> * <li> * might hide a field's pattern letter length. * </li> * </ol> * * For those non-digit calendar fields, the pattern letter length is * important, such as MMM, MMMM, and MMMMM; EEE and EEEE, * and the field's pattern letter length is honored. * * For the digit calendar fields, such as M or MM, d or dd, yy or yyyy, * the field pattern length is ignored and the best match, which is defined * in date time patterns, will be returned without honor the field pattern * letter length in skeleton. * * <P> * The calendar fields we support for interval formatting are: * year, month, date, day-of-week, am-pm, hour, hour-of-day, minute, and second * (though we do not currently have specific intervalFormat date for skeletons * with seconds). * Those calendar fields can be defined in the following order: * year > month > date > hour (in day) > minute > second * * The largest different calendar fields between 2 calendars is the * first different calendar field in above order. * * For example: the largest different calendar fields between "Jan 10, 2007" * and "Feb 20, 2008" is year. * * <P> * For other calendar fields, the compact interval formatting is not * supported. And the interval format will be fall back to fall-back * patterns, which is mostly "{date0} - {date1}". * * <P> * There is a set of pre-defined static skeleton strings. * There are pre-defined interval patterns for those pre-defined skeletons * in locales' resource files. * For example, for a skeleton UDAT_YEAR_ABBR_MONTH_DAY, which is "yMMMd", * in en_US, if the largest different calendar field between date1 and date2 * is "year", the date interval pattern is "MMM d, yyyy - MMM d, yyyy", * such as "Jan 10, 2007 - Jan 10, 2008". * If the largest different calendar field between date1 and date2 is "month", * the date interval pattern is "MMM d - MMM d, yyyy", * such as "Jan 10 - Feb 10, 2007". * If the largest different calendar field between date1 and date2 is "day", * the date interval pattern is "MMM d-d, yyyy", such as "Jan 10-20, 2007". * * For date skeleton, the interval patterns when year, or month, or date is * different are defined in resource files. * For time skeleton, the interval patterns when am/pm, or hour, or minute is * different are defined in resource files. * * <P> * If a skeleton is not found in a locale's DateIntervalInfo, which means * the interval patterns for the skeleton is not defined in resource file, * the interval pattern will falls back to the interval "fallback" pattern * defined in resource file. * If the interval "fallback" pattern is not defined, the default fall-back * is "{date0} - {data1}". * * <P> * For the combination of date and time, * The rule to generate interval patterns are: * <ol> * <li> * when the year, month, or day differs, falls back to fall-back * interval pattern, which mostly is the concatenate the two original * expressions with a separator between, * For example, interval pattern from "Jan 10, 2007 10:10 am" * to "Jan 11, 2007 10:10am" is * "Jan 10, 2007 10:10 am - Jan 11, 2007 10:10am" * </li> * <li> * otherwise, present the date followed by the range expression * for the time. * For example, interval pattern from "Jan 10, 2007 10:10 am" * to "Jan 10, 2007 11:10am" is "Jan 10, 2007 10:10 am - 11:10am" * </li> * </ol> * * * <P> * If two dates are the same, the interval pattern is the single date pattern. * For example, interval pattern from "Jan 10, 2007" to "Jan 10, 2007" is * "Jan 10, 2007". * * Or if the presenting fields between 2 dates have the exact same values, * the interval pattern is the single date pattern. * For example, if user only requests year and month, * the interval pattern from "Jan 10, 2007" to "Jan 20, 2007" is "Jan 2007". * * <P> * DateIntervalFormat needs the following information for correct * formatting: time zone, calendar type, pattern, date format symbols, * and date interval patterns. * It can be instantiated in 2 ways: * <ol> * <li> * create an instance using default or given locale plus given skeleton. * Users are encouraged to created date interval formatter this way and * to use the pre-defined skeleton macros, such as * UDAT_YEAR_NUM_MONTH, which consists the calendar fields and * the format style. * </li> * <li> * create an instance using default or given locale plus given skeleton * plus a given DateIntervalInfo. * This factory method is for powerful users who want to provide their own * interval patterns. * Locale provides the timezone, calendar, and format symbols information. * Local plus skeleton provides full pattern information. * DateIntervalInfo provides the date interval patterns. * </li> * </ol> * * <P> * For the calendar field pattern letter, such as G, y, M, d, a, h, H, m, s etc. * DateIntervalFormat uses the same syntax as that of * DateTime format. * * <P> * Code Sample: general usage * <pre> * \code * // the date interval object which the DateIntervalFormat formats on * // and parses into * DateInterval* dtInterval = new DateInterval(1000*3600*24, 1000*3600*24*2); * UErrorCode status = U_ZERO_ERROR; * DateIntervalFormat* dtIntervalFmt = DateIntervalFormat::createInstance( * UDAT_YEAR_MONTH_DAY, * Locale("en", "GB", ""), status); * UnicodeUnicodeString dateIntervalString; * FieldPosition pos = 0; * // formatting * dtIntervalFmt->format(dtInterval, dateIntervalUnicodeString, pos, status); * delete dtIntervalFmt; * \endcode * </pre> */ class U_I18N_API DateIntervalFormat : public Format { public: /** * Construct a DateIntervalFormat from skeleton and the default locale. * * This is a convenient override of * createInstance(const UnicodeString& skeleton, const Locale& locale, * UErrorCode&) * with the value of locale as default locale. * * @param skeleton the skeleton on which interval format based. * @param status output param set to success/failure code on exit * @return a date time interval formatter which the caller owns. * @stable ICU 4.0 */ static DateIntervalFormat* U_EXPORT2 createInstance( const UnicodeString& skeleton, UErrorCode& status); /** * Construct a DateIntervalFormat from skeleton and a given locale. * <P> * In this factory method, * the date interval pattern information is load from resource files. * Users are encouraged to created date interval formatter this way and * to use the pre-defined skeleton macros. * * <P> * There are pre-defined skeletons (defined in udate.h) having predefined * interval patterns in resource files. * Users are encouraged to use those macros. * For example: * DateIntervalFormat::createInstance(UDAT_MONTH_DAY, status) * * The given Locale provides the interval patterns. * For example, for en_GB, if skeleton is UDAT_YEAR_ABBR_MONTH_WEEKDAY_DAY, * which is "yMMMEEEd", * the interval patterns defined in resource file to above skeleton are: * "EEE, d MMM, yyyy - EEE, d MMM, yyyy" for year differs, * "EEE, d MMM - EEE, d MMM, yyyy" for month differs, * "EEE, d - EEE, d MMM, yyyy" for day differs, * @param skeleton the skeleton on which the interval format is based. * @param locale the given locale * @param status output param set to success/failure code on exit * @return a date time interval formatter which the caller owns. * @stable ICU 4.0 * <p> * <h4>Sample code</h4> * \snippet samples/dtitvfmtsample/dtitvfmtsample.cpp dtitvfmtPreDefined1 * \snippet samples/dtitvfmtsample/dtitvfmtsample.cpp dtitvfmtPreDefined * <p> */ static DateIntervalFormat* U_EXPORT2 createInstance( const UnicodeString& skeleton, const Locale& locale, UErrorCode& status); /** * Construct a DateIntervalFormat from skeleton * DateIntervalInfo, and default locale. * * This is a convenient override of * createInstance(const UnicodeString& skeleton, const Locale& locale, * const DateIntervalInfo& dtitvinf, UErrorCode&) * with the locale value as default locale. * * @param skeleton the skeleton on which interval format based. * @param dtitvinf the DateIntervalInfo object. * @param status output param set to success/failure code on exit * @return a date time interval formatter which the caller owns. * @stable ICU 4.0 */ static DateIntervalFormat* U_EXPORT2 createInstance( const UnicodeString& skeleton, const DateIntervalInfo& dtitvinf, UErrorCode& status); /** * Construct a DateIntervalFormat from skeleton * a DateIntervalInfo, and the given locale. * * <P> * In this factory method, user provides its own date interval pattern * information, instead of using those pre-defined data in resource file. * This factory method is for powerful users who want to provide their own * interval patterns. * <P> * There are pre-defined skeletons (defined in udate.h) having predefined * interval patterns in resource files. * Users are encouraged to use those macros. * For example: * DateIntervalFormat::createInstance(UDAT_MONTH_DAY, status) * * The DateIntervalInfo provides the interval patterns. * and the DateIntervalInfo ownership remains to the caller. * * User are encouraged to set default interval pattern in DateIntervalInfo * as well, if they want to set other interval patterns ( instead of * reading the interval patterns from resource files). * When the corresponding interval pattern for a largest calendar different * field is not found ( if user not set it ), interval format fallback to * the default interval pattern. * If user does not provide default interval pattern, it fallback to * "{date0} - {date1}" * * @param skeleton the skeleton on which interval format based. * @param locale the given locale * @param dtitvinf the DateIntervalInfo object. * @param status output param set to success/failure code on exit * @return a date time interval formatter which the caller owns. * @stable ICU 4.0 * <p> * <h4>Sample code</h4> * \snippet samples/dtitvfmtsample/dtitvfmtsample.cpp dtitvfmtPreDefined1 * \snippet samples/dtitvfmtsample/dtitvfmtsample.cpp dtitvfmtCustomized * <p> */ static DateIntervalFormat* U_EXPORT2 createInstance( const UnicodeString& skeleton, const Locale& locale, const DateIntervalInfo& dtitvinf, UErrorCode& status); /** * Destructor. * @stable ICU 4.0 */ virtual ~DateIntervalFormat(); /** * Clone this Format object polymorphically. The caller owns the result and * should delete it when done. * @return A copy of the object. * @stable ICU 4.0 */ virtual DateIntervalFormat* clone() const; /** * Return true if the given Format objects are semantically equal. Objects * of different subclasses are considered unequal. * @param other the object to be compared with. * @return true if the given Format objects are semantically equal. * @stable ICU 4.0 */ virtual UBool operator==(const Format& other) const; /** * Return true if the given Format objects are not semantically equal. * Objects of different subclasses are considered unequal. * @param other the object to be compared with. * @return true if the given Format objects are not semantically equal. * @stable ICU 4.0 */ UBool operator!=(const Format& other) const; using Format::format; /** * Format an object to produce a string. This method handles Formattable * objects with a DateInterval type. * If a the Formattable object type is not a DateInterval, * then it returns a failing UErrorCode. * * @param obj The object to format. * Must be a DateInterval. * @param appendTo Output parameter to receive result. * Result is appended to existing contents. * @param fieldPosition On input: an alignment field, if desired. * On output: the offsets of the alignment field. * There may be multiple instances of a given field type * in an interval format; in this case the fieldPosition * offsets refer to the first instance. * @param status Output param filled with success/failure status. * @return Reference to 'appendTo' parameter. * @stable ICU 4.0 */ virtual UnicodeString& format(const Formattable& obj, UnicodeString& appendTo, FieldPosition& fieldPosition, UErrorCode& status) const ; /** * Format a DateInterval to produce a string. * * @param dtInterval DateInterval to be formatted. * @param appendTo Output parameter to receive result. * Result is appended to existing contents. * @param fieldPosition On input: an alignment field, if desired. * On output: the offsets of the alignment field. * There may be multiple instances of a given field type * in an interval format; in this case the fieldPosition * offsets refer to the first instance. * @param status Output param filled with success/failure status. * @return Reference to 'appendTo' parameter. * @stable ICU 4.0 */ UnicodeString& format(const DateInterval* dtInterval, UnicodeString& appendTo, FieldPosition& fieldPosition, UErrorCode& status) const ; #ifndef U_HIDE_DRAFT_API /** * Format a DateInterval to produce a FormattedDateInterval. * * The FormattedDateInterval exposes field information about the formatted string. * * @param dtInterval DateInterval to be formatted. * @param status Set if an error occurs. * @return A FormattedDateInterval containing the format result. * @draft ICU 64 */ FormattedDateInterval formatToValue( const DateInterval& dtInterval, UErrorCode& status) const; #endif /* U_HIDE_DRAFT_API */ /** * Format 2 Calendars to produce a string. * * Note: "fromCalendar" and "toCalendar" are not const, * since calendar is not const in SimpleDateFormat::format(Calendar&), * * @param fromCalendar calendar set to the from date in date interval * to be formatted into date interval string * @param toCalendar calendar set to the to date in date interval * to be formatted into date interval string * @param appendTo Output parameter to receive result. * Result is appended to existing contents. * @param fieldPosition On input: an alignment field, if desired. * On output: the offsets of the alignment field. * There may be multiple instances of a given field type * in an interval format; in this case the fieldPosition * offsets refer to the first instance. * @param status Output param filled with success/failure status. * Caller needs to make sure it is SUCCESS * at the function entrance * @return Reference to 'appendTo' parameter. * @stable ICU 4.0 */ UnicodeString& format(Calendar& fromCalendar, Calendar& toCalendar, UnicodeString& appendTo, FieldPosition& fieldPosition, UErrorCode& status) const ; #ifndef U_HIDE_DRAFT_API /** * Format 2 Calendars to produce a FormattedDateInterval. * * The FormattedDateInterval exposes field information about the formatted string. * * Note: "fromCalendar" and "toCalendar" are not const, * since calendar is not const in SimpleDateFormat::format(Calendar&), * * @param fromCalendar calendar set to the from date in date interval * to be formatted into date interval string * @param toCalendar calendar set to the to date in date interval * to be formatted into date interval string * @param status Set if an error occurs. * @return A FormattedDateInterval containing the format result. * @draft ICU 64 */ FormattedDateInterval formatToValue( Calendar& fromCalendar, Calendar& toCalendar, UErrorCode& status) const; #endif /* U_HIDE_DRAFT_API */ /** * Date interval parsing is not supported. Please do not use. * <P> * This method should handle parsing of * date time interval strings into Formattable objects with * DateInterval type, which is a pair of UDate. * <P> * Before calling, set parse_pos.index to the offset you want to start * parsing at in the source. After calling, parse_pos.index is the end of * the text you parsed. If error occurs, index is unchanged. * <P> * When parsing, leading whitespace is discarded (with a successful parse), * while trailing whitespace is left as is. * <P> * See Format::parseObject() for more. * * @param source The string to be parsed into an object. * @param result Formattable to be set to the parse result. * If parse fails, return contents are undefined. * @param parse_pos The position to start parsing at. Since no parsing * is supported, upon return this param is unchanged. * @return A newly created Formattable* object, or NULL * on failure. The caller owns this and should * delete it when done. * @internal ICU 4.0 */ virtual void parseObject(const UnicodeString& source, Formattable& result, ParsePosition& parse_pos) const; /** * Gets the date time interval patterns. * @return the date time interval patterns associated with * this date interval formatter. * @stable ICU 4.0 */ const DateIntervalInfo* getDateIntervalInfo(void) const; /** * Set the date time interval patterns. * @param newIntervalPatterns the given interval patterns to copy. * @param status output param set to success/failure code on exit * @stable ICU 4.0 */ void setDateIntervalInfo(const DateIntervalInfo& newIntervalPatterns, UErrorCode& status); /** * Gets the date formatter. The DateIntervalFormat instance continues to own * the returned DateFormatter object, and will use and possibly modify it * during format operations. In a multi-threaded environment, the returned * DateFormat can only be used if it is certain that no other threads are * concurrently using this DateIntervalFormatter, even for nominally const * functions. * * @return the date formatter associated with this date interval formatter. * @stable ICU 4.0 */ const DateFormat* getDateFormat(void) const; /** * Returns a reference to the TimeZone used by this DateIntervalFormat's calendar. * @return the time zone associated with the calendar of DateIntervalFormat. * @stable ICU 4.8 */ virtual const TimeZone& getTimeZone(void) const; /** * Sets the time zone for the calendar used by this DateIntervalFormat object. The * caller no longer owns the TimeZone object and should not delete it after this call. * @param zoneToAdopt the TimeZone to be adopted. * @stable ICU 4.8 */ virtual void adoptTimeZone(TimeZone* zoneToAdopt); /** * Sets the time zone for the calendar used by this DateIntervalFormat object. * @param zone the new time zone. * @stable ICU 4.8 */ virtual void setTimeZone(const TimeZone& zone); /** * Return the class ID for this class. This is useful only for comparing to * a return value from getDynamicClassID(). For example: * <pre> * . Base* polymorphic_pointer = createPolymorphicObject(); * . if (polymorphic_pointer->getDynamicClassID() == * . erived::getStaticClassID()) ... * </pre> * @return The class ID for all objects of this class. * @stable ICU 4.0 */ static UClassID U_EXPORT2 getStaticClassID(void); /** * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This * method is to implement a simple version of RTTI, since not all C++ * compilers support genuine RTTI. Polymorphic operator==() and clone() * methods call this method. * * @return The class ID for this object. All objects of a * given class have the same class ID. Objects of * other classes have different class IDs. * @stable ICU 4.0 */ virtual UClassID getDynamicClassID(void) const; protected: /** * Copy constructor. * @stable ICU 4.0 */ DateIntervalFormat(const DateIntervalFormat&); /** * Assignment operator. * @stable ICU 4.0 */ DateIntervalFormat& operator=(const DateIntervalFormat&); private: /* * This is for ICU internal use only. Please do not use. * Save the interval pattern information. * Interval pattern consists of 2 single date patterns and the separator. * For example, interval pattern "MMM d - MMM d, yyyy" consists * a single date pattern "MMM d", another single date pattern "MMM d, yyyy", * and a separator "-". * The pattern is divided into 2 parts. For above example, * the first part is "MMM d - ", and the second part is "MMM d, yyyy". * Also, the first date appears in an interval pattern could be * the earlier date or the later date. * And such information is saved in the interval pattern as well. */ struct PatternInfo { UnicodeString firstPart; UnicodeString secondPart; /** * Whether the first date in interval pattern is later date or not. * Fallback format set the default ordering. * And for a particular interval pattern, the order can be * overriden by prefixing the interval pattern with "latestFirst:" or * "earliestFirst:" * For example, given 2 date, Jan 10, 2007 to Feb 10, 2007. * if the fallback format is "{0} - {1}", * and the pattern is "d MMM - d MMM yyyy", the interval format is * "10 Jan - 10 Feb, 2007". * If the pattern is "latestFirst:d MMM - d MMM yyyy", * the interval format is "10 Feb - 10 Jan, 2007" */ UBool laterDateFirst; }; /** * default constructor * @internal (private) */ DateIntervalFormat(); /** * Construct a DateIntervalFormat from DateFormat, * a DateIntervalInfo, and skeleton. * DateFormat provides the timezone, calendar, * full pattern, and date format symbols information. * It should be a SimpleDateFormat object which * has a pattern in it. * the DateIntervalInfo provides the interval patterns. * * Note: the DateIntervalFormat takes ownership of both * DateFormat and DateIntervalInfo objects. * Caller should not delete them. * * @param locale the locale of this date interval formatter. * @param dtItvInfo the DateIntervalInfo object to be adopted. * @param skeleton the skeleton of the date formatter * @param status output param set to success/failure code on exit */ DateIntervalFormat(const Locale& locale, DateIntervalInfo* dtItvInfo, const UnicodeString* skeleton, UErrorCode& status); /** * Construct a DateIntervalFormat from DateFormat * and a DateIntervalInfo. * * It is a wrapper of the constructor. * * @param locale the locale of this date interval formatter. * @param dtitvinf the DateIntervalInfo object to be adopted. * @param skeleton the skeleton of this formatter. * @param status Output param set to success/failure code. * @return a date time interval formatter which the caller owns. */ static DateIntervalFormat* U_EXPORT2 create(const Locale& locale, DateIntervalInfo* dtitvinf, const UnicodeString* skeleton, UErrorCode& status); /** * Below are for generating interval patterns local to the formatter */ /** Like fallbackFormat, but only formats the range part of the fallback. */ void fallbackFormatRange( Calendar& fromCalendar, Calendar& toCalendar, UnicodeString& appendTo, int8_t& firstIndex, FieldPositionHandler& fphandler, UErrorCode& status) const; /** * Format 2 Calendars using fall-back interval pattern * * The full pattern used in this fall-back format is the * full pattern of the date formatter. * * gFormatterMutex must already be locked when calling this function. * * @param fromCalendar calendar set to the from date in date interval * to be formatted into date interval string * @param toCalendar calendar set to the to date in date interval * to be formatted into date interval string * @param fromToOnSameDay TRUE iff from and to dates are on the same day * (any difference is in ampm/hours or below) * @param appendTo Output parameter to receive result. * Result is appended to existing contents. * @param firstIndex See formatImpl for more information. * @param fphandler See formatImpl for more information. * @param status output param set to success/failure code on exit * @return Reference to 'appendTo' parameter. * @internal (private) */ UnicodeString& fallbackFormat(Calendar& fromCalendar, Calendar& toCalendar, UBool fromToOnSameDay, UnicodeString& appendTo, int8_t& firstIndex, FieldPositionHandler& fphandler, UErrorCode& status) const; /** * Initialize interval patterns locale to this formatter * * This code is a bit complicated since * 1. the interval patterns saved in resource bundle files are interval * patterns based on date or time only. * It does not have interval patterns based on both date and time. * Interval patterns on both date and time are algorithm generated. * * For example, it has interval patterns on skeleton "dMy" and "hm", * but it does not have interval patterns on skeleton "dMyhm". * * The rule to generate interval patterns for both date and time skeleton are * 1) when the year, month, or day differs, concatenate the two original * expressions with a separator between, * For example, interval pattern from "Jan 10, 2007 10:10 am" * to "Jan 11, 2007 10:10am" is * "Jan 10, 2007 10:10 am - Jan 11, 2007 10:10am" * * 2) otherwise, present the date followed by the range expression * for the time. * For example, interval pattern from "Jan 10, 2007 10:10 am" * to "Jan 10, 2007 11:10am" is * "Jan 10, 2007 10:10 am - 11:10am" * * 2. even a pattern does not request a certain calendar field, * the interval pattern needs to include such field if such fields are * different between 2 dates. * For example, a pattern/skeleton is "hm", but the interval pattern * includes year, month, and date when year, month, and date differs. * * * @param status output param set to success/failure code on exit */ void initializePattern(UErrorCode& status); /** * Set fall back interval pattern given a calendar field, * a skeleton, and a date time pattern generator. * @param field the largest different calendar field * @param skeleton a skeleton * @param status output param set to success/failure code on exit */ void setFallbackPattern(UCalendarDateFields field, const UnicodeString& skeleton, UErrorCode& status); /** * get separated date and time skeleton from a combined skeleton. * * The difference between date skeleton and normalizedDateSkeleton are: * 1. both 'y' and 'd' are appeared only once in normalizeDateSkeleton * 2. 'E' and 'EE' are normalized into 'EEE' * 3. 'MM' is normalized into 'M' * ** the difference between time skeleton and normalizedTimeSkeleton are: * 1. both 'H' and 'h' are normalized as 'h' in normalized time skeleton, * 2. 'a' is omitted in normalized time skeleton. * 3. there is only one appearance for 'h', 'm','v', 'z' in normalized time * skeleton * * * @param skeleton given combined skeleton. * @param date Output parameter for date only skeleton. * @param normalizedDate Output parameter for normalized date only * * @param time Output parameter for time only skeleton. * @param normalizedTime Output parameter for normalized time only * skeleton. * */ static void U_EXPORT2 getDateTimeSkeleton(const UnicodeString& skeleton, UnicodeString& date, UnicodeString& normalizedDate, UnicodeString& time, UnicodeString& normalizedTime); /** * Generate date or time interval pattern from resource, * and set them into the interval pattern locale to this formatter. * * It needs to handle the following: * 1. need to adjust field width. * For example, the interval patterns saved in DateIntervalInfo * includes "dMMMy", but not "dMMMMy". * Need to get interval patterns for dMMMMy from dMMMy. * Another example, the interval patterns saved in DateIntervalInfo * includes "hmv", but not "hmz". * Need to get interval patterns for "hmz' from 'hmv' * * 2. there might be no pattern for 'y' differ for skeleton "Md", * in order to get interval patterns for 'y' differ, * need to look for it from skeleton 'yMd' * * @param dateSkeleton normalized date skeleton * @param timeSkeleton normalized time skeleton * @return whether the resource is found for the skeleton. * TRUE if interval pattern found for the skeleton, * FALSE otherwise. */ UBool setSeparateDateTimePtn(const UnicodeString& dateSkeleton, const UnicodeString& timeSkeleton); /** * Generate interval pattern from existing resource * * It not only save the interval patterns, * but also return the extended skeleton and its best match skeleton. * * @param field largest different calendar field * @param skeleton skeleton * @param bestSkeleton the best match skeleton which has interval pattern * defined in resource * @param differenceInfo the difference between skeleton and best skeleton * 0 means the best matched skeleton is the same as input skeleton * 1 means the fields are the same, but field width are different * 2 means the only difference between fields are v/z, * -1 means there are other fields difference * * @param extendedSkeleton extended skeleton * @param extendedBestSkeleton extended best match skeleton * @return whether the interval pattern is found * through extending skeleton or not. * TRUE if interval pattern is found by * extending skeleton, FALSE otherwise. */ UBool setIntervalPattern(UCalendarDateFields field, const UnicodeString* skeleton, const UnicodeString* bestSkeleton, int8_t differenceInfo, UnicodeString* extendedSkeleton = NULL, UnicodeString* extendedBestSkeleton = NULL); /** * Adjust field width in best match interval pattern to match * the field width in input skeleton. * * TODO (xji) make a general solution * The adjusting rule can be: * 1. always adjust * 2. never adjust * 3. default adjust, which means adjust according to the following rules * 3.1 always adjust string, such as MMM and MMMM * 3.2 never adjust between string and numeric, such as MM and MMM * 3.3 always adjust year * 3.4 do not adjust 'd', 'h', or 'm' if h presents * 3.5 do not adjust 'M' if it is numeric(?) * * Since date interval format is well-formed format, * date and time skeletons are normalized previously, * till this stage, the adjust here is only "adjust strings, such as MMM * and MMMM, EEE and EEEE. * * @param inputSkeleton the input skeleton * @param bestMatchSkeleton the best match skeleton * @param bestMatchIntervalPattern the best match interval pattern * @param differenceInfo the difference between 2 skeletons * 1 means only field width differs * 2 means v/z exchange * @param adjustedIntervalPattern adjusted interval pattern */ static void U_EXPORT2 adjustFieldWidth( const UnicodeString& inputSkeleton, const UnicodeString& bestMatchSkeleton, const UnicodeString& bestMatchIntervalPattern, int8_t differenceInfo, UnicodeString& adjustedIntervalPattern); /** * Concat a single date pattern with a time interval pattern, * set it into the intervalPatterns, while field is time field. * This is used to handle time interval patterns on skeleton with * both time and date. Present the date followed by * the range expression for the time. * @param format date and time format * @param datePattern date pattern * @param field time calendar field: AM_PM, HOUR, MINUTE * @param status output param set to success/failure code on exit */ void concatSingleDate2TimeInterval(UnicodeString& format, const UnicodeString& datePattern, UCalendarDateFields field, UErrorCode& status); /** * check whether a calendar field present in a skeleton. * @param field calendar field need to check * @param skeleton given skeleton on which to check the calendar field * @return true if field present in a skeleton. */ static UBool U_EXPORT2 fieldExistsInSkeleton(UCalendarDateFields field, const UnicodeString& skeleton); /** * Split interval patterns into 2 part. * @param intervalPattern interval pattern * @return the index in interval pattern which split the pattern into 2 part */ static int32_t U_EXPORT2 splitPatternInto2Part(const UnicodeString& intervalPattern); /** * Break interval patterns as 2 part and save them into pattern info. * @param field calendar field * @param intervalPattern interval pattern */ void setIntervalPattern(UCalendarDateFields field, const UnicodeString& intervalPattern); /** * Break interval patterns as 2 part and save them into pattern info. * @param field calendar field * @param intervalPattern interval pattern * @param laterDateFirst whether later date appear first in interval pattern */ void setIntervalPattern(UCalendarDateFields field, const UnicodeString& intervalPattern, UBool laterDateFirst); /** * Set pattern information. * * @param field calendar field * @param firstPart the first part in interval pattern * @param secondPart the second part in interval pattern * @param laterDateFirst whether the first date in intervalPattern * is earlier date or later date */ void setPatternInfo(UCalendarDateFields field, const UnicodeString* firstPart, const UnicodeString* secondPart, UBool laterDateFirst); /** * Format 2 Calendars to produce a string. * Implementation of the similar public format function. * Must be called with gFormatterMutex already locked. * * Note: "fromCalendar" and "toCalendar" are not const, * since calendar is not const in SimpleDateFormat::format(Calendar&), * * @param fromCalendar calendar set to the from date in date interval * to be formatted into date interval string * @param toCalendar calendar set to the to date in date interval * to be formatted into date interval string * @param appendTo Output parameter to receive result. * Result is appended to existing contents. * @param firstIndex 0 if the first output date is fromCalendar; * 1 if it corresponds to toCalendar; * -1 if there is only one date printed. * @param fphandler Handler for field position information. * The fields will be from the UDateFormatField enum. * @param status Output param filled with success/failure status. * Caller needs to make sure it is SUCCESS * at the function entrance * @return Reference to 'appendTo' parameter. * @internal (private) */ UnicodeString& formatImpl(Calendar& fromCalendar, Calendar& toCalendar, UnicodeString& appendTo, int8_t& firstIndex, FieldPositionHandler& fphandler, UErrorCode& status) const ; /** Version of formatImpl for DateInterval. */ UnicodeString& formatIntervalImpl(const DateInterval& dtInterval, UnicodeString& appendTo, int8_t& firstIndex, FieldPositionHandler& fphandler, UErrorCode& status) const; // from calendar field to pattern letter static const char16_t fgCalendarFieldToPatternLetter[]; /** * The interval patterns for this locale. */ DateIntervalInfo* fInfo; /** * The DateFormat object used to format single pattern */ SimpleDateFormat* fDateFormat; /** * The 2 calendars with the from and to date. * could re-use the calendar in fDateFormat, * but keeping 2 calendars make it clear and clean. */ Calendar* fFromCalendar; Calendar* fToCalendar; Locale fLocale; /** * Following are interval information relevant (locale) to this formatter. */ UnicodeString fSkeleton; PatternInfo fIntervalPatterns[DateIntervalInfo::kIPI_MAX_INDEX]; /** * Patterns for fallback formatting. */ UnicodeString* fDatePattern; UnicodeString* fTimePattern; UnicodeString* fDateTimeFormat; }; inline UBool DateIntervalFormat::operator!=(const Format& other) const { return !operator==(other); } U_NAMESPACE_END #endif /* #if !UCONFIG_NO_FORMATTING */ #endif /* U_SHOW_CPLUSPLUS_API */ #endif // _DTITVFMT_H__ //eof Save