1/* 2******************************************************************************* 3* Copyright (C) 2007-2009, International Business Machines Corporation and 4* others. All Rights Reserved. 5******************************************************************************* 6* 7* File DTPTNGEN.H 8* 9******************************************************************************* 10*/ 11 12#ifndef __DTPTNGEN_H__ 13#define __DTPTNGEN_H__ 14 15#include "unicode/datefmt.h" 16#include "unicode/locid.h" 17#include "unicode/udat.h" 18#include "unicode/udatpg.h" 19 20U_NAMESPACE_BEGIN 21 22/** 23 * \file 24 * \brief C++ API: Date/Time Pattern Generator 25 */ 26 27 28class Hashtable; 29class FormatParser; 30class DateTimeMatcher; 31class DistanceInfo; 32class PatternMap; 33class PtnSkeleton; 34 35/** 36 * This class provides flexible generation of date format patterns, like "yy-MM-dd". 37 * The user can build up the generator by adding successive patterns. Once that 38 * is done, a query can be made using a "skeleton", which is a pattern which just 39 * includes the desired fields and lengths. The generator will return the "best fit" 40 * pattern corresponding to that skeleton. 41 * <p>The main method people will use is getBestPattern(String skeleton), 42 * since normally this class is pre-built with data from a particular locale. 43 * However, generators can be built directly from other data as well. 44 * <p><i>Issue: may be useful to also have a function that returns the list of 45 * fields in a pattern, in order, since we have that internally. 46 * That would be useful for getting the UI order of field elements.</i> 47 * @stable ICU 3.8 48**/ 49class U_I18N_API DateTimePatternGenerator : public UObject { 50public: 51 /** 52 * Construct a flexible generator according to default locale. 53 * @param status Output param set to success/failure code on exit, 54 * which must not indicate a failure before the function call. 55 * @stable ICU 3.8 56 */ 57 static DateTimePatternGenerator* U_EXPORT2 createInstance(UErrorCode& status); 58 59 /** 60 * Construct a flexible generator according to data for a given locale. 61 * @param uLocale 62 * @param status Output param set to success/failure code on exit, 63 * which must not indicate a failure before the function call. 64 * @stable ICU 3.8 65 */ 66 static DateTimePatternGenerator* U_EXPORT2 createInstance(const Locale& uLocale, UErrorCode& status); 67 68 /** 69 * Create an empty generator, to be constructed with addPattern(...) etc. 70 * @param status Output param set to success/failure code on exit, 71 * which must not indicate a failure before the function call. 72 * @stable ICU 3.8 73 */ 74 static DateTimePatternGenerator* U_EXPORT2 createEmptyInstance(UErrorCode& status); 75 76 /** 77 * Destructor. 78 * @stable ICU 3.8 79 */ 80 virtual ~DateTimePatternGenerator(); 81 82 /** 83 * Clone DateTimePatternGenerator object. Clients are responsible for 84 * deleting the DateTimePatternGenerator object cloned. 85 * @stable ICU 3.8 86 */ 87 DateTimePatternGenerator* clone() const; 88 89 /** 90 * Return true if another object is semantically equal to this one. 91 * 92 * @param other the DateTimePatternGenerator object to be compared with. 93 * @return true if other is semantically equal to this. 94 * @stable ICU 3.8 95 */ 96 UBool operator==(const DateTimePatternGenerator& other) const; 97 98 /** 99 * Return true if another object is semantically unequal to this one. 100 * 101 * @param other the DateTimePatternGenerator object to be compared with. 102 * @return true if other is semantically unequal to this. 103 * @stable ICU 3.8 104 */ 105 UBool operator!=(const DateTimePatternGenerator& other) const; 106 107 /** 108 * Utility to return a unique skeleton from a given pattern. For example, 109 * both "MMM-dd" and "dd/MMM" produce the skeleton "MMMdd". 110 * 111 * @param pattern Input pattern, such as "dd/MMM" 112 * @param status Output param set to success/failure code on exit, 113 * which must not indicate a failure before the function call. 114 * @return skeleton such as "MMMdd" 115 * @stable ICU 3.8 116 */ 117 UnicodeString getSkeleton(const UnicodeString& pattern, UErrorCode& status); 118 119 /** 120 * Utility to return a unique base skeleton from a given pattern. This is 121 * the same as the skeleton, except that differences in length are minimized 122 * so as to only preserve the difference between string and numeric form. So 123 * for example, both "MMM-dd" and "d/MMM" produce the skeleton "MMMd" 124 * (notice the single d). 125 * 126 * @param pattern Input pattern, such as "dd/MMM" 127 * @param status Output param set to success/failure code on exit, 128 * which must not indicate a failure before the function call. 129 * @return base skeleton, such as "Md" 130 * @stable ICU 3.8 131 */ 132 UnicodeString getBaseSkeleton(const UnicodeString& pattern, UErrorCode& status); 133 134 /** 135 * Adds a pattern to the generator. If the pattern has the same skeleton as 136 * an existing pattern, and the override parameter is set, then the previous 137 * value is overriden. Otherwise, the previous value is retained. In either 138 * case, the conflicting status is set and previous vale is stored in 139 * conflicting pattern. 140 * <p> 141 * Note that single-field patterns (like "MMM") are automatically added, and 142 * don't need to be added explicitly! 143 * 144 * @param pattern Input pattern, such as "dd/MMM" 145 * @param override When existing values are to be overridden use true, 146 * otherwise use false. 147 * @param conflictingPattern Previous pattern with the same skeleton. 148 * @param status Output param set to success/failure code on exit, 149 * which must not indicate a failure before the function call. 150 * @return conflicting status. The value could be UDATPG_NO_CONFLICT, 151 * UDATPG_BASE_CONFLICT or UDATPG_CONFLICT. 152 * @stable ICU 3.8 153 */ 154 UDateTimePatternConflict addPattern(const UnicodeString& pattern, 155 UBool override, 156 UnicodeString& conflictingPattern, 157 UErrorCode& status); 158 159 /** 160 * An AppendItem format is a pattern used to append a field if there is no 161 * good match. For example, suppose that the input skeleton is "GyyyyMMMd", 162 * and there is no matching pattern internally, but there is a pattern 163 * matching "yyyyMMMd", say "d-MM-yyyy". Then that pattern is used, plus the 164 * G. The way these two are conjoined is by using the AppendItemFormat for G 165 * (era). So if that value is, say "{0}, {1}" then the final resulting 166 * pattern is "d-MM-yyyy, G". 167 * <p> 168 * There are actually three available variables: {0} is the pattern so far, 169 * {1} is the element we are adding, and {2} is the name of the element. 170 * <p> 171 * This reflects the way that the CLDR data is organized. 172 * 173 * @param field such as UDATPG_ERA_FIELD. 174 * @param value pattern, such as "{0}, {1}" 175 * @stable ICU 3.8 176 */ 177 void setAppendItemFormat(UDateTimePatternField field, const UnicodeString& value); 178 179 /** 180 * Getter corresponding to setAppendItemFormat. Values below 0 or at or 181 * above UDATPG_FIELD_COUNT are illegal arguments. 182 * 183 * @param field such as UDATPG_ERA_FIELD. 184 * @return append pattern for field 185 * @stable ICU 3.8 186 */ 187 const UnicodeString& getAppendItemFormat(UDateTimePatternField field) const; 188 189 /** 190 * Sets the names of field, eg "era" in English for ERA. These are only 191 * used if the corresponding AppendItemFormat is used, and if it contains a 192 * {2} variable. 193 * <p> 194 * This reflects the way that the CLDR data is organized. 195 * 196 * @param field such as UDATPG_ERA_FIELD. 197 * @param value name of the field 198 * @stable ICU 3.8 199 */ 200 void setAppendItemName(UDateTimePatternField field, const UnicodeString& value); 201 202 /** 203 * Getter corresponding to setAppendItemNames. Values below 0 or at or above 204 * UDATPG_FIELD_COUNT are illegal arguments. 205 * 206 * @param field such as UDATPG_ERA_FIELD. 207 * @return name for field 208 * @stable ICU 3.8 209 */ 210 const UnicodeString& getAppendItemName(UDateTimePatternField field) const; 211 212 /** 213 * The date time format is a message format pattern used to compose date and 214 * time patterns. The default value is "{0} {1}", where {0} will be replaced 215 * by the date pattern and {1} will be replaced by the time pattern. 216 * <p> 217 * This is used when the input skeleton contains both date and time fields, 218 * but there is not a close match among the added patterns. For example, 219 * suppose that this object was created by adding "dd-MMM" and "hh:mm", and 220 * its datetimeFormat is the default "{0} {1}". Then if the input skeleton 221 * is "MMMdhmm", there is not an exact match, so the input skeleton is 222 * broken up into two components "MMMd" and "hmm". There are close matches 223 * for those two skeletons, so the result is put together with this pattern, 224 * resulting in "d-MMM h:mm". 225 * 226 * @param dateTimeFormat 227 * message format pattern, here {0} will be replaced by the date 228 * pattern and {1} will be replaced by the time pattern. 229 * @stable ICU 3.8 230 */ 231 void setDateTimeFormat(const UnicodeString& dateTimeFormat); 232 233 /** 234 * Getter corresponding to setDateTimeFormat. 235 * @return DateTimeFormat. 236 * @stable ICU 3.8 237 */ 238 const UnicodeString& getDateTimeFormat() const; 239 240 /** 241 * Return the best pattern matching the input skeleton. It is guaranteed to 242 * have all of the fields in the skeleton. 243 * 244 * @param skeleton 245 * The skeleton is a pattern containing only the variable fields. 246 * For example, "MMMdd" and "mmhh" are skeletons. 247 * @param status Output param set to success/failure code on exit, 248 * which must not indicate a failure before the function call. 249 * @return bestPattern 250 * The best pattern found from the given skeleton. 251 * @stable ICU 3.8 252 */ 253 UnicodeString getBestPattern(const UnicodeString& skeleton, UErrorCode& status); 254 255 256 /** 257 * Adjusts the field types (width and subtype) of a pattern to match what is 258 * in a skeleton. That is, if you supply a pattern like "d-M H:m", and a 259 * skeleton of "MMMMddhhmm", then the input pattern is adjusted to be 260 * "dd-MMMM hh:mm". This is used internally to get the best match for the 261 * input skeleton, but can also be used externally. 262 * 263 * @param pattern Input pattern 264 * @param skeleton 265 * The skeleton is a pattern containing only the variable fields. 266 * For example, "MMMdd" and "mmhh" are skeletons. 267 * @param status Output param set to success/failure code on exit, 268 * which must not indicate a failure before the function call. 269 * @return pattern adjusted to match the skeleton fields widths and subtypes. 270 * @stable ICU 3.8 271 */ 272 UnicodeString replaceFieldTypes(const UnicodeString& pattern, 273 const UnicodeString& skeleton, 274 UErrorCode& status); 275 276 /** 277 * Return a list of all the skeletons (in canonical form) from this class. 278 * 279 * Call getPatternForSkeleton() to get the corresponding pattern. 280 * 281 * @param status Output param set to success/failure code on exit, 282 * which must not indicate a failure before the function call. 283 * @return StringEnumeration with the skeletons. 284 * The caller must delete the object. 285 * @stable ICU 3.8 286 */ 287 StringEnumeration* getSkeletons(UErrorCode& status) const; 288 289 /** 290 * Get the pattern corresponding to a given skeleton. 291 * @param skeleton 292 * @return pattern corresponding to a given skeleton. 293 * @stable ICU 3.8 294 */ 295 const UnicodeString& getPatternForSkeleton(const UnicodeString& skeleton) const; 296 297 /** 298 * Return a list of all the base skeletons (in canonical form) from this class. 299 * 300 * @param status Output param set to success/failure code on exit, 301 * which must not indicate a failure before the function call. 302 * @return a StringEnumeration with the base skeletons. 303 * The caller must delete the object. 304 * @stable ICU 3.8 305 */ 306 StringEnumeration* getBaseSkeletons(UErrorCode& status) const; 307 308 /** 309 * Return a list of redundant patterns are those which if removed, make no 310 * difference in the resulting getBestPattern values. This method returns a 311 * list of them, to help check the consistency of the patterns used to build 312 * this generator. 313 * 314 * @param status Output param set to success/failure code on exit, 315 * which must not indicate a failure before the function call. 316 * @return a StringEnumeration with the redundant pattern. 317 * The caller must delete the object. 318 * @internal ICU 3.8 319 */ 320 StringEnumeration* getRedundants(UErrorCode& status); 321 322 /** 323 * The decimal value is used in formatting fractions of seconds. If the 324 * skeleton contains fractional seconds, then this is used with the 325 * fractional seconds. For example, suppose that the input pattern is 326 * "hhmmssSSSS", and the best matching pattern internally is "H:mm:ss", and 327 * the decimal string is ",". Then the resulting pattern is modified to be 328 * "H:mm:ss,SSSS" 329 * 330 * @param decimal 331 * @stable ICU 3.8 332 */ 333 void setDecimal(const UnicodeString& decimal); 334 335 /** 336 * Getter corresponding to setDecimal. 337 * @return UnicodeString corresponding to the decimal point 338 * @stable ICU 3.8 339 */ 340 const UnicodeString& getDecimal() const; 341 342 /** 343 * ICU "poor man's RTTI", returns a UClassID for the actual class. 344 * 345 * @stable ICU 3.8 346 */ 347 virtual UClassID getDynamicClassID() const; 348 349 /** 350 * ICU "poor man's RTTI", returns a UClassID for this class. 351 * 352 * @stable ICU 3.8 353 */ 354 static UClassID U_EXPORT2 getStaticClassID(void); 355 356private: 357 /** 358 * Constructor. 359 * @stable ICU 3.8 360 */ 361 DateTimePatternGenerator(UErrorCode & status); 362 363 /** 364 * Constructor. 365 * @stable ICU 3.8 366 */ 367 DateTimePatternGenerator(const Locale& locale, UErrorCode & status); 368 369 /** 370 * Copy constructor. 371 * @param other DateTimePatternGenerator to copy 372 * @stable ICU 3.8 373 */ 374 DateTimePatternGenerator(const DateTimePatternGenerator& other); 375 376 /** 377 * Default assignment operator. 378 * @param other DateTimePatternGenerator to copy 379 * @stable ICU 3.8 380 */ 381 DateTimePatternGenerator& operator=(const DateTimePatternGenerator& other); 382 383 Locale pLocale; // pattern locale 384 FormatParser *fp; 385 DateTimeMatcher* dtMatcher; 386 DistanceInfo *distanceInfo; 387 PatternMap *patternMap; 388 UnicodeString appendItemFormats[UDATPG_FIELD_COUNT]; 389 UnicodeString appendItemNames[UDATPG_FIELD_COUNT]; 390 UnicodeString dateTimeFormat; 391 UnicodeString decimal; 392 DateTimeMatcher *skipMatcher; 393 Hashtable *fAvailableFormatKeyHash; 394 UnicodeString hackPattern; 395 UnicodeString emptyString; 396 UChar fDefaultHourFormatChar; 397 398 void initData(const Locale &locale, UErrorCode &status); 399 void addCanonicalItems(); 400 void addICUPatterns(const Locale& locale, UErrorCode& status); 401 void hackTimes(const UnicodeString& hackPattern, UErrorCode& status); 402 void addCLDRData(const Locale& locale, UErrorCode& status); 403 UDateTimePatternConflict addPatternWithSkeleton(const UnicodeString& pattern, const UnicodeString * skeletonToUse, UBool override, UnicodeString& conflictingPattern, UErrorCode& status); 404 void initHashtable(UErrorCode& status); 405 void setDateTimeFromCalendar(const Locale& locale, UErrorCode& status); 406 void setDecimalSymbols(const Locale& locale, UErrorCode& status); 407 UDateTimePatternField getAppendFormatNumber(const char* field) const; 408 UDateTimePatternField getAppendNameNumber(const char* field) const; 409 void getAppendName(UDateTimePatternField field, UnicodeString& value); 410 int32_t getCanonicalIndex(const UnicodeString& field); 411 const UnicodeString* getBestRaw(DateTimeMatcher& source, int32_t includeMask, DistanceInfo* missingFields, const PtnSkeleton** specifiedSkeletonPtr = 0); 412 UnicodeString adjustFieldTypes(const UnicodeString& pattern, const PtnSkeleton* specifiedSkeleton, UBool fixFractionalSeconds); 413 UnicodeString getBestAppending(int32_t missingFields); 414 int32_t getTopBitNumber(int32_t foundMask); 415 void setAvailableFormat(const UnicodeString &key, UErrorCode& status); 416 UBool isAvailableFormatSet(const UnicodeString &key) const; 417 void copyHashtable(Hashtable *other, UErrorCode &status); 418 UBool isCanonicalItem(const UnicodeString& item) const; 419} ;// end class DateTimePatternGenerator 420 421U_NAMESPACE_END 422 423#endif 424