michael@0: /* michael@0: ******************************************************************************* michael@0: * Copyright (C) 2007-2013, International Business Machines Corporation and michael@0: * others. All Rights Reserved. michael@0: ******************************************************************************* michael@0: * michael@0: * File DTPTNGEN.H michael@0: * michael@0: ******************************************************************************* michael@0: */ michael@0: michael@0: #ifndef __DTPTNGEN_H__ michael@0: #define __DTPTNGEN_H__ michael@0: michael@0: #include "unicode/datefmt.h" michael@0: #include "unicode/locid.h" michael@0: #include "unicode/udat.h" michael@0: #include "unicode/udatpg.h" michael@0: michael@0: U_NAMESPACE_BEGIN michael@0: michael@0: /** michael@0: * \file michael@0: * \brief C++ API: Date/Time Pattern Generator michael@0: */ michael@0: michael@0: michael@0: class Hashtable; michael@0: class FormatParser; michael@0: class DateTimeMatcher; michael@0: class DistanceInfo; michael@0: class PatternMap; michael@0: class PtnSkeleton; michael@0: michael@0: /** michael@0: * This class provides flexible generation of date format patterns, like "yy-MM-dd". michael@0: * The user can build up the generator by adding successive patterns. Once that michael@0: * is done, a query can be made using a "skeleton", which is a pattern which just michael@0: * includes the desired fields and lengths. The generator will return the "best fit" michael@0: * pattern corresponding to that skeleton. michael@0: *

The main method people will use is getBestPattern(String skeleton), michael@0: * since normally this class is pre-built with data from a particular locale. michael@0: * However, generators can be built directly from other data as well. michael@0: *

Issue: may be useful to also have a function that returns the list of michael@0: * fields in a pattern, in order, since we have that internally. michael@0: * That would be useful for getting the UI order of field elements. michael@0: * @stable ICU 3.8 michael@0: **/ michael@0: class U_I18N_API DateTimePatternGenerator : public UObject { michael@0: public: michael@0: /** michael@0: * Construct a flexible generator according to default locale. michael@0: * @param status Output param set to success/failure code on exit, michael@0: * which must not indicate a failure before the function call. michael@0: * @stable ICU 3.8 michael@0: */ michael@0: static DateTimePatternGenerator* U_EXPORT2 createInstance(UErrorCode& status); michael@0: michael@0: /** michael@0: * Construct a flexible generator according to data for a given locale. michael@0: * @param uLocale michael@0: * @param status Output param set to success/failure code on exit, michael@0: * which must not indicate a failure before the function call. michael@0: * @stable ICU 3.8 michael@0: */ michael@0: static DateTimePatternGenerator* U_EXPORT2 createInstance(const Locale& uLocale, UErrorCode& status); michael@0: michael@0: /** michael@0: * Create an empty generator, to be constructed with addPattern(...) etc. michael@0: * @param status Output param set to success/failure code on exit, michael@0: * which must not indicate a failure before the function call. michael@0: * @stable ICU 3.8 michael@0: */ michael@0: static DateTimePatternGenerator* U_EXPORT2 createEmptyInstance(UErrorCode& status); michael@0: michael@0: /** michael@0: * Destructor. michael@0: * @stable ICU 3.8 michael@0: */ michael@0: virtual ~DateTimePatternGenerator(); michael@0: michael@0: /** michael@0: * Clone DateTimePatternGenerator object. Clients are responsible for michael@0: * deleting the DateTimePatternGenerator object cloned. michael@0: * @stable ICU 3.8 michael@0: */ michael@0: DateTimePatternGenerator* clone() const; michael@0: michael@0: /** michael@0: * Return true if another object is semantically equal to this one. michael@0: * michael@0: * @param other the DateTimePatternGenerator object to be compared with. michael@0: * @return true if other is semantically equal to this. michael@0: * @stable ICU 3.8 michael@0: */ michael@0: UBool operator==(const DateTimePatternGenerator& other) const; michael@0: michael@0: /** michael@0: * Return true if another object is semantically unequal to this one. michael@0: * michael@0: * @param other the DateTimePatternGenerator object to be compared with. michael@0: * @return true if other is semantically unequal to this. michael@0: * @stable ICU 3.8 michael@0: */ michael@0: UBool operator!=(const DateTimePatternGenerator& other) const; michael@0: michael@0: /** michael@0: * Utility to return a unique skeleton from a given pattern. For example, michael@0: * both "MMM-dd" and "dd/MMM" produce the skeleton "MMMdd". michael@0: * michael@0: * @param pattern Input pattern, such as "dd/MMM" michael@0: * @param status Output param set to success/failure code on exit, michael@0: * which must not indicate a failure before the function call. michael@0: * @return skeleton such as "MMMdd" michael@0: * @stable ICU 3.8 michael@0: */ michael@0: UnicodeString getSkeleton(const UnicodeString& pattern, UErrorCode& status); michael@0: michael@0: /** michael@0: * Utility to return a unique base skeleton from a given pattern. This is michael@0: * the same as the skeleton, except that differences in length are minimized michael@0: * so as to only preserve the difference between string and numeric form. So michael@0: * for example, both "MMM-dd" and "d/MMM" produce the skeleton "MMMd" michael@0: * (notice the single d). michael@0: * michael@0: * @param pattern Input pattern, such as "dd/MMM" michael@0: * @param status Output param set to success/failure code on exit, michael@0: * which must not indicate a failure before the function call. michael@0: * @return base skeleton, such as "Md" michael@0: * @stable ICU 3.8 michael@0: */ michael@0: UnicodeString getBaseSkeleton(const UnicodeString& pattern, UErrorCode& status); michael@0: michael@0: /** michael@0: * Adds a pattern to the generator. If the pattern has the same skeleton as michael@0: * an existing pattern, and the override parameter is set, then the previous michael@0: * value is overriden. Otherwise, the previous value is retained. In either michael@0: * case, the conflicting status is set and previous vale is stored in michael@0: * conflicting pattern. michael@0: *

michael@0: * Note that single-field patterns (like "MMM") are automatically added, and michael@0: * don't need to be added explicitly! michael@0: * michael@0: * @param pattern Input pattern, such as "dd/MMM" michael@0: * @param override When existing values are to be overridden use true, michael@0: * otherwise use false. michael@0: * @param conflictingPattern Previous pattern with the same skeleton. michael@0: * @param status Output param set to success/failure code on exit, michael@0: * which must not indicate a failure before the function call. michael@0: * @return conflicting status. The value could be UDATPG_NO_CONFLICT, michael@0: * UDATPG_BASE_CONFLICT or UDATPG_CONFLICT. michael@0: * @stable ICU 3.8 michael@0: *

michael@0: *

Sample code

michael@0: * \snippet samples/dtptngsample/dtptngsample.cpp getBestPatternExample1 michael@0: * \snippet samples/dtptngsample/dtptngsample.cpp addPatternExample michael@0: *

michael@0: */ michael@0: UDateTimePatternConflict addPattern(const UnicodeString& pattern, michael@0: UBool override, michael@0: UnicodeString& conflictingPattern, michael@0: UErrorCode& status); michael@0: michael@0: /** michael@0: * An AppendItem format is a pattern used to append a field if there is no michael@0: * good match. For example, suppose that the input skeleton is "GyyyyMMMd", michael@0: * and there is no matching pattern internally, but there is a pattern michael@0: * matching "yyyyMMMd", say "d-MM-yyyy". Then that pattern is used, plus the michael@0: * G. The way these two are conjoined is by using the AppendItemFormat for G michael@0: * (era). So if that value is, say "{0}, {1}" then the final resulting michael@0: * pattern is "d-MM-yyyy, G". michael@0: *

michael@0: * There are actually three available variables: {0} is the pattern so far, michael@0: * {1} is the element we are adding, and {2} is the name of the element. michael@0: *

michael@0: * This reflects the way that the CLDR data is organized. michael@0: * michael@0: * @param field such as UDATPG_ERA_FIELD. michael@0: * @param value pattern, such as "{0}, {1}" michael@0: * @stable ICU 3.8 michael@0: */ michael@0: void setAppendItemFormat(UDateTimePatternField field, const UnicodeString& value); michael@0: michael@0: /** michael@0: * Getter corresponding to setAppendItemFormat. Values below 0 or at or michael@0: * above UDATPG_FIELD_COUNT are illegal arguments. michael@0: * michael@0: * @param field such as UDATPG_ERA_FIELD. michael@0: * @return append pattern for field michael@0: * @stable ICU 3.8 michael@0: */ michael@0: const UnicodeString& getAppendItemFormat(UDateTimePatternField field) const; michael@0: michael@0: /** michael@0: * Sets the names of field, eg "era" in English for ERA. These are only michael@0: * used if the corresponding AppendItemFormat is used, and if it contains a michael@0: * {2} variable. michael@0: *

michael@0: * This reflects the way that the CLDR data is organized. michael@0: * michael@0: * @param field such as UDATPG_ERA_FIELD. michael@0: * @param value name of the field michael@0: * @stable ICU 3.8 michael@0: */ michael@0: void setAppendItemName(UDateTimePatternField field, const UnicodeString& value); michael@0: michael@0: /** michael@0: * Getter corresponding to setAppendItemNames. Values below 0 or at or above michael@0: * UDATPG_FIELD_COUNT are illegal arguments. michael@0: * michael@0: * @param field such as UDATPG_ERA_FIELD. michael@0: * @return name for field michael@0: * @stable ICU 3.8 michael@0: */ michael@0: const UnicodeString& getAppendItemName(UDateTimePatternField field) const; michael@0: michael@0: /** michael@0: * The date time format is a message format pattern used to compose date and michael@0: * time patterns. The default value is "{0} {1}", where {0} will be replaced michael@0: * by the date pattern and {1} will be replaced by the time pattern. michael@0: *

michael@0: * This is used when the input skeleton contains both date and time fields, michael@0: * but there is not a close match among the added patterns. For example, michael@0: * suppose that this object was created by adding "dd-MMM" and "hh:mm", and michael@0: * its datetimeFormat is the default "{0} {1}". Then if the input skeleton michael@0: * is "MMMdhmm", there is not an exact match, so the input skeleton is michael@0: * broken up into two components "MMMd" and "hmm". There are close matches michael@0: * for those two skeletons, so the result is put together with this pattern, michael@0: * resulting in "d-MMM h:mm". michael@0: * michael@0: * @param dateTimeFormat michael@0: * message format pattern, here {0} will be replaced by the date michael@0: * pattern and {1} will be replaced by the time pattern. michael@0: * @stable ICU 3.8 michael@0: */ michael@0: void setDateTimeFormat(const UnicodeString& dateTimeFormat); michael@0: michael@0: /** michael@0: * Getter corresponding to setDateTimeFormat. michael@0: * @return DateTimeFormat. michael@0: * @stable ICU 3.8 michael@0: */ michael@0: const UnicodeString& getDateTimeFormat() const; michael@0: michael@0: /** michael@0: * Return the best pattern matching the input skeleton. It is guaranteed to michael@0: * have all of the fields in the skeleton. michael@0: * michael@0: * @param skeleton michael@0: * The skeleton is a pattern containing only the variable fields. michael@0: * For example, "MMMdd" and "mmhh" are skeletons. michael@0: * @param status Output param set to success/failure code on exit, michael@0: * which must not indicate a failure before the function call. michael@0: * @return bestPattern michael@0: * The best pattern found from the given skeleton. michael@0: * @stable ICU 3.8 michael@0: *

michael@0: *

Sample code

michael@0: * \snippet samples/dtptngsample/dtptngsample.cpp getBestPatternExample1 michael@0: * \snippet samples/dtptngsample/dtptngsample.cpp getBestPatternExample michael@0: *

michael@0: */ michael@0: UnicodeString getBestPattern(const UnicodeString& skeleton, UErrorCode& status); michael@0: michael@0: michael@0: /** michael@0: * Return the best pattern matching the input skeleton. It is guaranteed to michael@0: * have all of the fields in the skeleton. michael@0: * michael@0: * @param skeleton michael@0: * The skeleton is a pattern containing only the variable fields. michael@0: * For example, "MMMdd" and "mmhh" are skeletons. michael@0: * @param options michael@0: * Options for forcing the length of specified fields in the michael@0: * returned pattern to match those in the skeleton (when this michael@0: * would not happen otherwise). For default behavior, use michael@0: * UDATPG_MATCH_NO_OPTIONS. michael@0: * @param status michael@0: * Output param set to success/failure code on exit, michael@0: * which must not indicate a failure before the function call. michael@0: * @return bestPattern michael@0: * The best pattern found from the given skeleton. michael@0: * @stable ICU 4.4 michael@0: */ michael@0: UnicodeString getBestPattern(const UnicodeString& skeleton, michael@0: UDateTimePatternMatchOptions options, michael@0: UErrorCode& status); michael@0: michael@0: michael@0: /** michael@0: * Adjusts the field types (width and subtype) of a pattern to match what is michael@0: * in a skeleton. That is, if you supply a pattern like "d-M H:m", and a michael@0: * skeleton of "MMMMddhhmm", then the input pattern is adjusted to be michael@0: * "dd-MMMM hh:mm". This is used internally to get the best match for the michael@0: * input skeleton, but can also be used externally. michael@0: * michael@0: * @param pattern Input pattern michael@0: * @param skeleton michael@0: * The skeleton is a pattern containing only the variable fields. michael@0: * For example, "MMMdd" and "mmhh" are skeletons. michael@0: * @param status Output param set to success/failure code on exit, michael@0: * which must not indicate a failure before the function call. michael@0: * @return pattern adjusted to match the skeleton fields widths and subtypes. michael@0: * @stable ICU 3.8 michael@0: *

michael@0: *

Sample code

michael@0: * \snippet samples/dtptngsample/dtptngsample.cpp getBestPatternExample1 michael@0: * \snippet samples/dtptngsample/dtptngsample.cpp replaceFieldTypesExample michael@0: *

michael@0: */ michael@0: UnicodeString replaceFieldTypes(const UnicodeString& pattern, michael@0: const UnicodeString& skeleton, michael@0: UErrorCode& status); michael@0: michael@0: /** michael@0: * Adjusts the field types (width and subtype) of a pattern to match what is michael@0: * in a skeleton. That is, if you supply a pattern like "d-M H:m", and a michael@0: * skeleton of "MMMMddhhmm", then the input pattern is adjusted to be michael@0: * "dd-MMMM hh:mm". This is used internally to get the best match for the michael@0: * input skeleton, but can also be used externally. michael@0: * michael@0: * @param pattern Input pattern michael@0: * @param skeleton michael@0: * The skeleton is a pattern containing only the variable fields. michael@0: * For example, "MMMdd" and "mmhh" are skeletons. michael@0: * @param options michael@0: * Options controlling whether the length of specified fields in the michael@0: * pattern are adjusted to match those in the skeleton (when this michael@0: * would not happen otherwise). For default behavior, use michael@0: * UDATPG_MATCH_NO_OPTIONS. michael@0: * @param status michael@0: * Output param set to success/failure code on exit, michael@0: * which must not indicate a failure before the function call. michael@0: * @return pattern adjusted to match the skeleton fields widths and subtypes. michael@0: * @stable ICU 4.4 michael@0: */ michael@0: UnicodeString replaceFieldTypes(const UnicodeString& pattern, michael@0: const UnicodeString& skeleton, michael@0: UDateTimePatternMatchOptions options, michael@0: UErrorCode& status); michael@0: michael@0: /** michael@0: * Return a list of all the skeletons (in canonical form) from this class. michael@0: * michael@0: * Call getPatternForSkeleton() to get the corresponding pattern. michael@0: * michael@0: * @param status Output param set to success/failure code on exit, michael@0: * which must not indicate a failure before the function call. michael@0: * @return StringEnumeration with the skeletons. michael@0: * The caller must delete the object. michael@0: * @stable ICU 3.8 michael@0: */ michael@0: StringEnumeration* getSkeletons(UErrorCode& status) const; michael@0: michael@0: /** michael@0: * Get the pattern corresponding to a given skeleton. michael@0: * @param skeleton michael@0: * @return pattern corresponding to a given skeleton. michael@0: * @stable ICU 3.8 michael@0: */ michael@0: const UnicodeString& getPatternForSkeleton(const UnicodeString& skeleton) const; michael@0: michael@0: /** michael@0: * Return a list of all the base skeletons (in canonical form) from this class. michael@0: * michael@0: * @param status Output param set to success/failure code on exit, michael@0: * which must not indicate a failure before the function call. michael@0: * @return a StringEnumeration with the base skeletons. michael@0: * The caller must delete the object. michael@0: * @stable ICU 3.8 michael@0: */ michael@0: StringEnumeration* getBaseSkeletons(UErrorCode& status) const; michael@0: michael@0: #ifndef U_HIDE_INTERNAL_API michael@0: /** michael@0: * Return a list of redundant patterns are those which if removed, make no michael@0: * difference in the resulting getBestPattern values. This method returns a michael@0: * list of them, to help check the consistency of the patterns used to build michael@0: * this generator. michael@0: * michael@0: * @param status Output param set to success/failure code on exit, michael@0: * which must not indicate a failure before the function call. michael@0: * @return a StringEnumeration with the redundant pattern. michael@0: * The caller must delete the object. michael@0: * @internal ICU 3.8 michael@0: */ michael@0: StringEnumeration* getRedundants(UErrorCode& status); michael@0: #endif /* U_HIDE_INTERNAL_API */ michael@0: michael@0: /** michael@0: * The decimal value is used in formatting fractions of seconds. If the michael@0: * skeleton contains fractional seconds, then this is used with the michael@0: * fractional seconds. For example, suppose that the input pattern is michael@0: * "hhmmssSSSS", and the best matching pattern internally is "H:mm:ss", and michael@0: * the decimal string is ",". Then the resulting pattern is modified to be michael@0: * "H:mm:ss,SSSS" michael@0: * michael@0: * @param decimal michael@0: * @stable ICU 3.8 michael@0: */ michael@0: void setDecimal(const UnicodeString& decimal); michael@0: michael@0: /** michael@0: * Getter corresponding to setDecimal. michael@0: * @return UnicodeString corresponding to the decimal point michael@0: * @stable ICU 3.8 michael@0: */ michael@0: const UnicodeString& getDecimal() const; michael@0: michael@0: /** michael@0: * ICU "poor man's RTTI", returns a UClassID for the actual class. michael@0: * michael@0: * @stable ICU 3.8 michael@0: */ michael@0: virtual UClassID getDynamicClassID() const; michael@0: michael@0: /** michael@0: * ICU "poor man's RTTI", returns a UClassID for this class. michael@0: * michael@0: * @stable ICU 3.8 michael@0: */ michael@0: static UClassID U_EXPORT2 getStaticClassID(void); michael@0: michael@0: private: michael@0: /** michael@0: * Constructor. michael@0: * @stable ICU 3.8 michael@0: */ michael@0: DateTimePatternGenerator(UErrorCode & status); michael@0: michael@0: /** michael@0: * Constructor. michael@0: * @stable ICU 3.8 michael@0: */ michael@0: DateTimePatternGenerator(const Locale& locale, UErrorCode & status); michael@0: michael@0: /** michael@0: * Copy constructor. michael@0: * @param other DateTimePatternGenerator to copy michael@0: * @stable ICU 3.8 michael@0: */ michael@0: DateTimePatternGenerator(const DateTimePatternGenerator& other); michael@0: michael@0: /** michael@0: * Default assignment operator. michael@0: * @param other DateTimePatternGenerator to copy michael@0: * @stable ICU 3.8 michael@0: */ michael@0: DateTimePatternGenerator& operator=(const DateTimePatternGenerator& other); michael@0: michael@0: Locale pLocale; // pattern locale michael@0: FormatParser *fp; michael@0: DateTimeMatcher* dtMatcher; michael@0: DistanceInfo *distanceInfo; michael@0: PatternMap *patternMap; michael@0: UnicodeString appendItemFormats[UDATPG_FIELD_COUNT]; michael@0: UnicodeString appendItemNames[UDATPG_FIELD_COUNT]; michael@0: UnicodeString dateTimeFormat; michael@0: UnicodeString decimal; michael@0: DateTimeMatcher *skipMatcher; michael@0: Hashtable *fAvailableFormatKeyHash; michael@0: UnicodeString hackPattern; michael@0: UnicodeString emptyString; michael@0: UChar fDefaultHourFormatChar; michael@0: michael@0: /* internal flags masks for adjustFieldTypes etc. */ michael@0: enum { michael@0: kDTPGNoFlags = 0, michael@0: kDTPGFixFractionalSeconds = 1, michael@0: kDTPGSkeletonUsesCapJ = 2 michael@0: }; michael@0: michael@0: void initData(const Locale &locale, UErrorCode &status); michael@0: void addCanonicalItems(); michael@0: void addICUPatterns(const Locale& locale, UErrorCode& status); michael@0: void hackTimes(const UnicodeString& hackPattern, UErrorCode& status); michael@0: void addCLDRData(const Locale& locale, UErrorCode& status); michael@0: UDateTimePatternConflict addPatternWithSkeleton(const UnicodeString& pattern, const UnicodeString * skeletonToUse, UBool override, UnicodeString& conflictingPattern, UErrorCode& status); michael@0: void initHashtable(UErrorCode& status); michael@0: void setDateTimeFromCalendar(const Locale& locale, UErrorCode& status); michael@0: void setDecimalSymbols(const Locale& locale, UErrorCode& status); michael@0: UDateTimePatternField getAppendFormatNumber(const char* field) const; michael@0: UDateTimePatternField getAppendNameNumber(const char* field) const; michael@0: void getAppendName(UDateTimePatternField field, UnicodeString& value); michael@0: int32_t getCanonicalIndex(const UnicodeString& field); michael@0: const UnicodeString* getBestRaw(DateTimeMatcher& source, int32_t includeMask, DistanceInfo* missingFields, const PtnSkeleton** specifiedSkeletonPtr = 0); michael@0: UnicodeString adjustFieldTypes(const UnicodeString& pattern, const PtnSkeleton* specifiedSkeleton, int32_t flags, UDateTimePatternMatchOptions options = UDATPG_MATCH_NO_OPTIONS); michael@0: UnicodeString getBestAppending(int32_t missingFields, int32_t flags, UDateTimePatternMatchOptions options = UDATPG_MATCH_NO_OPTIONS); michael@0: int32_t getTopBitNumber(int32_t foundMask); michael@0: void setAvailableFormat(const UnicodeString &key, UErrorCode& status); michael@0: UBool isAvailableFormatSet(const UnicodeString &key) const; michael@0: void copyHashtable(Hashtable *other, UErrorCode &status); michael@0: UBool isCanonicalItem(const UnicodeString& item) const; michael@0: } ;// end class DateTimePatternGenerator michael@0: michael@0: U_NAMESPACE_END michael@0: michael@0: #endif