1 // Copyright (C) 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
4 *******************************************************************************
5 * Copyright (C) 2007-2016, International Business Machines Corporation and
6 * others. All Rights Reserved.
7 *******************************************************************************
11 *******************************************************************************
14 #ifndef __DTPTNGEN_H__
15 #define __DTPTNGEN_H__
17 #include "unicode/datefmt.h"
18 #include "unicode/locid.h"
19 #include "unicode/udat.h"
20 #include "unicode/udatpg.h"
26 * \brief C++ API: Date/Time Pattern Generator
32 class DateTimeMatcher;
36 class SharedDateTimePatternGenerator;
39 * This class provides flexible generation of date format patterns, like "yy-MM-dd".
40 * The user can build up the generator by adding successive patterns. Once that
41 * is done, a query can be made using a "skeleton", which is a pattern which just
42 * includes the desired fields and lengths. The generator will return the "best fit"
43 * pattern corresponding to that skeleton.
44 * <p>The main method people will use is getBestPattern(String skeleton),
45 * since normally this class is pre-built with data from a particular locale.
46 * However, generators can be built directly from other data as well.
47 * <p><i>Issue: may be useful to also have a function that returns the list of
48 * fields in a pattern, in order, since we have that internally.
49 * That would be useful for getting the UI order of field elements.</i>
52 class U_I18N_API DateTimePatternGenerator : public UObject {
55 * Construct a flexible generator according to default locale.
56 * @param status Output param set to success/failure code on exit,
57 * which must not indicate a failure before the function call.
60 static DateTimePatternGenerator* U_EXPORT2 createInstance(UErrorCode& status);
63 * Construct a flexible generator according to data for a given locale.
65 * @param status Output param set to success/failure code on exit,
66 * which must not indicate a failure before the function call.
69 static DateTimePatternGenerator* U_EXPORT2 createInstance(const Locale& uLocale, UErrorCode& status);
71 #ifndef U_HIDE_INTERNAL_API
78 static DateTimePatternGenerator* U_EXPORT2 internalMakeInstance(const Locale& uLocale, UErrorCode& status);
80 #endif /* U_HIDE_INTERNAL_API */
83 * Create an empty generator, to be constructed with addPattern(...) etc.
84 * @param status Output param set to success/failure code on exit,
85 * which must not indicate a failure before the function call.
88 static DateTimePatternGenerator* U_EXPORT2 createEmptyInstance(UErrorCode& status);
94 virtual ~DateTimePatternGenerator();
97 * Clone DateTimePatternGenerator object. Clients are responsible for
98 * deleting the DateTimePatternGenerator object cloned.
101 DateTimePatternGenerator* clone() const;
104 * Return true if another object is semantically equal to this one.
106 * @param other the DateTimePatternGenerator object to be compared with.
107 * @return true if other is semantically equal to this.
110 UBool operator==(const DateTimePatternGenerator& other) const;
113 * Return true if another object is semantically unequal to this one.
115 * @param other the DateTimePatternGenerator object to be compared with.
116 * @return true if other is semantically unequal to this.
119 UBool operator!=(const DateTimePatternGenerator& other) const;
122 * Utility to return a unique skeleton from a given pattern. For example,
123 * both "MMM-dd" and "dd/MMM" produce the skeleton "MMMdd".
125 * @param pattern Input pattern, such as "dd/MMM"
126 * @param status Output param set to success/failure code on exit,
127 * which must not indicate a failure before the function call.
128 * @return skeleton such as "MMMdd"
131 static UnicodeString staticGetSkeleton(const UnicodeString& pattern, UErrorCode& status);
134 * Utility to return a unique skeleton from a given pattern. For example,
135 * both "MMM-dd" and "dd/MMM" produce the skeleton "MMMdd".
136 * getSkeleton() works exactly like staticGetSkeleton().
137 * Use staticGetSkeleton() instead of getSkeleton().
139 * @param pattern Input pattern, such as "dd/MMM"
140 * @param status Output param set to success/failure code on exit,
141 * which must not indicate a failure before the function call.
142 * @return skeleton such as "MMMdd"
145 UnicodeString getSkeleton(const UnicodeString& pattern, UErrorCode& status); /* {
146 The function is commented out because it is a stable API calling a draft API.
147 After staticGetSkeleton becomes stable, staticGetSkeleton can be used and
148 these comments and the definition of getSkeleton in dtptngen.cpp should be removed.
149 return staticGetSkeleton(pattern, status);
153 * Utility to return a unique base skeleton from a given pattern. This is
154 * the same as the skeleton, except that differences in length are minimized
155 * so as to only preserve the difference between string and numeric form. So
156 * for example, both "MMM-dd" and "d/MMM" produce the skeleton "MMMd"
157 * (notice the single d).
159 * @param pattern Input pattern, such as "dd/MMM"
160 * @param status Output param set to success/failure code on exit,
161 * which must not indicate a failure before the function call.
162 * @return base skeleton, such as "MMMd"
165 static UnicodeString staticGetBaseSkeleton(const UnicodeString& pattern, UErrorCode& status);
168 * Utility to return a unique base skeleton from a given pattern. This is
169 * the same as the skeleton, except that differences in length are minimized
170 * so as to only preserve the difference between string and numeric form. So
171 * for example, both "MMM-dd" and "d/MMM" produce the skeleton "MMMd"
172 * (notice the single d).
173 * getBaseSkeleton() works exactly like staticGetBaseSkeleton().
174 * Use staticGetBaseSkeleton() instead of getBaseSkeleton().
176 * @param pattern Input pattern, such as "dd/MMM"
177 * @param status Output param set to success/failure code on exit,
178 * which must not indicate a failure before the function call.
179 * @return base skeleton, such as "MMMd"
182 UnicodeString getBaseSkeleton(const UnicodeString& pattern, UErrorCode& status); /* {
183 The function is commented out because it is a stable API calling a draft API.
184 After staticGetBaseSkeleton becomes stable, staticGetBaseSkeleton can be used and
185 these comments and the definition of getBaseSkeleton in dtptngen.cpp should be removed.
186 return staticGetBaseSkeleton(pattern, status);
190 * Adds a pattern to the generator. If the pattern has the same skeleton as
191 * an existing pattern, and the override parameter is set, then the previous
192 * value is overriden. Otherwise, the previous value is retained. In either
193 * case, the conflicting status is set and previous vale is stored in
194 * conflicting pattern.
196 * Note that single-field patterns (like "MMM") are automatically added, and
197 * don't need to be added explicitly!
199 * @param pattern Input pattern, such as "dd/MMM"
200 * @param override When existing values are to be overridden use true,
201 * otherwise use false.
202 * @param conflictingPattern Previous pattern with the same skeleton.
203 * @param status Output param set to success/failure code on exit,
204 * which must not indicate a failure before the function call.
205 * @return conflicting status. The value could be UDATPG_NO_CONFLICT,
206 * UDATPG_BASE_CONFLICT or UDATPG_CONFLICT.
209 * <h4>Sample code</h4>
210 * \snippet samples/dtptngsample/dtptngsample.cpp getBestPatternExample1
211 * \snippet samples/dtptngsample/dtptngsample.cpp addPatternExample
214 UDateTimePatternConflict addPattern(const UnicodeString& pattern,
216 UnicodeString& conflictingPattern,
220 * An AppendItem format is a pattern used to append a field if there is no
221 * good match. For example, suppose that the input skeleton is "GyyyyMMMd",
222 * and there is no matching pattern internally, but there is a pattern
223 * matching "yyyyMMMd", say "d-MM-yyyy". Then that pattern is used, plus the
224 * G. The way these two are conjoined is by using the AppendItemFormat for G
225 * (era). So if that value is, say "{0}, {1}" then the final resulting
226 * pattern is "d-MM-yyyy, G".
228 * There are actually three available variables: {0} is the pattern so far,
229 * {1} is the element we are adding, and {2} is the name of the element.
231 * This reflects the way that the CLDR data is organized.
233 * @param field such as UDATPG_ERA_FIELD.
234 * @param value pattern, such as "{0}, {1}"
237 void setAppendItemFormat(UDateTimePatternField field, const UnicodeString& value);
240 * Getter corresponding to setAppendItemFormat. Values below 0 or at or
241 * above UDATPG_FIELD_COUNT are illegal arguments.
243 * @param field such as UDATPG_ERA_FIELD.
244 * @return append pattern for field
247 const UnicodeString& getAppendItemFormat(UDateTimePatternField field) const;
250 * Sets the names of field, eg "era" in English for ERA. These are only
251 * used if the corresponding AppendItemFormat is used, and if it contains a
254 * This reflects the way that the CLDR data is organized.
256 * @param field such as UDATPG_ERA_FIELD.
257 * @param value name of the field
260 void setAppendItemName(UDateTimePatternField field, const UnicodeString& value);
263 * Getter corresponding to setAppendItemNames. Values below 0 or at or above
264 * UDATPG_FIELD_COUNT are illegal arguments.
266 * @param field such as UDATPG_ERA_FIELD.
267 * @return name for field
270 const UnicodeString& getAppendItemName(UDateTimePatternField field) const;
273 * The DateTimeFormat is a message format pattern used to compose date and
274 * time patterns. The default pattern in the root locale is "{1} {0}", where
275 * {1} will be replaced by the date pattern and {0} will be replaced by the
276 * time pattern; however, other locales may specify patterns such as
277 * "{1}, {0}" or "{1} 'at' {0}", etc.
279 * This is used when the input skeleton contains both date and time fields,
280 * but there is not a close match among the added patterns. For example,
281 * suppose that this object was created by adding "dd-MMM" and "hh:mm", and
282 * its datetimeFormat is the default "{1} {0}". Then if the input skeleton
283 * is "MMMdhmm", there is not an exact match, so the input skeleton is
284 * broken up into two components "MMMd" and "hmm". There are close matches
285 * for those two skeletons, so the result is put together with this pattern,
286 * resulting in "d-MMM h:mm".
288 * @param dateTimeFormat
289 * message format pattern, here {1} will be replaced by the date
290 * pattern and {0} will be replaced by the time pattern.
293 void setDateTimeFormat(const UnicodeString& dateTimeFormat);
296 * Getter corresponding to setDateTimeFormat.
297 * @return DateTimeFormat.
300 const UnicodeString& getDateTimeFormat() const;
303 * Return the best pattern matching the input skeleton. It is guaranteed to
304 * have all of the fields in the skeleton.
307 * The skeleton is a pattern containing only the variable fields.
308 * For example, "MMMdd" and "mmhh" are skeletons.
309 * @param status Output param set to success/failure code on exit,
310 * which must not indicate a failure before the function call.
311 * @return bestPattern
312 * The best pattern found from the given skeleton.
315 * <h4>Sample code</h4>
316 * \snippet samples/dtptngsample/dtptngsample.cpp getBestPatternExample1
317 * \snippet samples/dtptngsample/dtptngsample.cpp getBestPatternExample
320 UnicodeString getBestPattern(const UnicodeString& skeleton, UErrorCode& status);
324 * Return the best pattern matching the input skeleton. It is guaranteed to
325 * have all of the fields in the skeleton.
328 * The skeleton is a pattern containing only the variable fields.
329 * For example, "MMMdd" and "mmhh" are skeletons.
331 * Options for forcing the length of specified fields in the
332 * returned pattern to match those in the skeleton (when this
333 * would not happen otherwise). For default behavior, use
334 * UDATPG_MATCH_NO_OPTIONS.
336 * Output param set to success/failure code on exit,
337 * which must not indicate a failure before the function call.
338 * @return bestPattern
339 * The best pattern found from the given skeleton.
342 UnicodeString getBestPattern(const UnicodeString& skeleton,
343 UDateTimePatternMatchOptions options,
348 * Adjusts the field types (width and subtype) of a pattern to match what is
349 * in a skeleton. That is, if you supply a pattern like "d-M H:m", and a
350 * skeleton of "MMMMddhhmm", then the input pattern is adjusted to be
351 * "dd-MMMM hh:mm". This is used internally to get the best match for the
352 * input skeleton, but can also be used externally.
354 * @param pattern Input pattern
356 * The skeleton is a pattern containing only the variable fields.
357 * For example, "MMMdd" and "mmhh" are skeletons.
358 * @param status Output param set to success/failure code on exit,
359 * which must not indicate a failure before the function call.
360 * @return pattern adjusted to match the skeleton fields widths and subtypes.
363 * <h4>Sample code</h4>
364 * \snippet samples/dtptngsample/dtptngsample.cpp getBestPatternExample1
365 * \snippet samples/dtptngsample/dtptngsample.cpp replaceFieldTypesExample
368 UnicodeString replaceFieldTypes(const UnicodeString& pattern,
369 const UnicodeString& skeleton,
373 * Adjusts the field types (width and subtype) of a pattern to match what is
374 * in a skeleton. That is, if you supply a pattern like "d-M H:m", and a
375 * skeleton of "MMMMddhhmm", then the input pattern is adjusted to be
376 * "dd-MMMM hh:mm". This is used internally to get the best match for the
377 * input skeleton, but can also be used externally.
379 * @param pattern Input pattern
381 * The skeleton is a pattern containing only the variable fields.
382 * For example, "MMMdd" and "mmhh" are skeletons.
384 * Options controlling whether the length of specified fields in the
385 * pattern are adjusted to match those in the skeleton (when this
386 * would not happen otherwise). For default behavior, use
387 * UDATPG_MATCH_NO_OPTIONS.
389 * Output param set to success/failure code on exit,
390 * which must not indicate a failure before the function call.
391 * @return pattern adjusted to match the skeleton fields widths and subtypes.
394 UnicodeString replaceFieldTypes(const UnicodeString& pattern,
395 const UnicodeString& skeleton,
396 UDateTimePatternMatchOptions options,
400 * Return a list of all the skeletons (in canonical form) from this class.
402 * Call getPatternForSkeleton() to get the corresponding pattern.
404 * @param status Output param set to success/failure code on exit,
405 * which must not indicate a failure before the function call.
406 * @return StringEnumeration with the skeletons.
407 * The caller must delete the object.
410 StringEnumeration* getSkeletons(UErrorCode& status) const;
413 * Get the pattern corresponding to a given skeleton.
415 * @return pattern corresponding to a given skeleton.
418 const UnicodeString& getPatternForSkeleton(const UnicodeString& skeleton) const;
421 * Return a list of all the base skeletons (in canonical form) from this class.
423 * @param status Output param set to success/failure code on exit,
424 * which must not indicate a failure before the function call.
425 * @return a StringEnumeration with the base skeletons.
426 * The caller must delete the object.
429 StringEnumeration* getBaseSkeletons(UErrorCode& status) const;
431 #ifndef U_HIDE_INTERNAL_API
433 * Return a list of redundant patterns are those which if removed, make no
434 * difference in the resulting getBestPattern values. This method returns a
435 * list of them, to help check the consistency of the patterns used to build
438 * @param status Output param set to success/failure code on exit,
439 * which must not indicate a failure before the function call.
440 * @return a StringEnumeration with the redundant pattern.
441 * The caller must delete the object.
444 StringEnumeration* getRedundants(UErrorCode& status);
445 #endif /* U_HIDE_INTERNAL_API */
448 * The decimal value is used in formatting fractions of seconds. If the
449 * skeleton contains fractional seconds, then this is used with the
450 * fractional seconds. For example, suppose that the input pattern is
451 * "hhmmssSSSS", and the best matching pattern internally is "H:mm:ss", and
452 * the decimal string is ",". Then the resulting pattern is modified to be
458 void setDecimal(const UnicodeString& decimal);
461 * Getter corresponding to setDecimal.
462 * @return UnicodeString corresponding to the decimal point
465 const UnicodeString& getDecimal() const;
468 * ICU "poor man's RTTI", returns a UClassID for the actual class.
472 virtual UClassID getDynamicClassID() const;
475 * ICU "poor man's RTTI", returns a UClassID for this class.
479 static UClassID U_EXPORT2 getStaticClassID(void);
486 DateTimePatternGenerator(UErrorCode & status);
492 DateTimePatternGenerator(const Locale& locale, UErrorCode & status);
496 * @param other DateTimePatternGenerator to copy
499 DateTimePatternGenerator(const DateTimePatternGenerator& other);
502 * Default assignment operator.
503 * @param other DateTimePatternGenerator to copy
506 DateTimePatternGenerator& operator=(const DateTimePatternGenerator& other);
508 Locale pLocale; // pattern locale
510 DateTimeMatcher* dtMatcher;
511 DistanceInfo *distanceInfo;
512 PatternMap *patternMap;
513 UnicodeString appendItemFormats[UDATPG_FIELD_COUNT];
514 UnicodeString appendItemNames[UDATPG_FIELD_COUNT];
515 UnicodeString dateTimeFormat;
516 UnicodeString decimal;
517 DateTimeMatcher *skipMatcher;
518 Hashtable *fAvailableFormatKeyHash;
519 UnicodeString emptyString;
520 UChar fDefaultHourFormatChar;
522 int32_t fAllowedHourFormats[7]; // Actually an array of AllowedHourFormat enum type, ending with UNKNOWN.
524 /* internal flags masks for adjustFieldTypes etc. */
527 kDTPGFixFractionalSeconds = 1,
528 kDTPGSkeletonUsesCapJ = 2,
529 kDTPGSkeletonUsesLowB = 3,
530 kDTPGSkeletonUsesCapB = 4
533 void initData(const Locale &locale, UErrorCode &status);
534 void addCanonicalItems(UErrorCode &status);
535 void addICUPatterns(const Locale& locale, UErrorCode& status);
536 void hackTimes(const UnicodeString& hackPattern, UErrorCode& status);
537 void getCalendarTypeToUse(const Locale& locale, CharString& destination, UErrorCode& err);
538 void consumeShortTimePattern(const UnicodeString& shortTimePattern, UErrorCode& status);
539 void addCLDRData(const Locale& locale, UErrorCode& status);
540 UDateTimePatternConflict addPatternWithSkeleton(const UnicodeString& pattern, const UnicodeString * skeletonToUse, UBool override, UnicodeString& conflictingPattern, UErrorCode& status);
541 void initHashtable(UErrorCode& status);
542 void setDateTimeFromCalendar(const Locale& locale, UErrorCode& status);
543 void setDecimalSymbols(const Locale& locale, UErrorCode& status);
544 UDateTimePatternField getAppendFormatNumber(const char* field) const;
545 UDateTimePatternField getAppendNameNumber(const char* field) const;
546 UnicodeString& getMutableAppendItemName(UDateTimePatternField field);
547 void getAppendName(UDateTimePatternField field, UnicodeString& value);
548 int32_t getCanonicalIndex(const UnicodeString& field);
549 const UnicodeString* getBestRaw(DateTimeMatcher& source, int32_t includeMask, DistanceInfo* missingFields, const PtnSkeleton** specifiedSkeletonPtr = 0);
550 UnicodeString adjustFieldTypes(const UnicodeString& pattern, const PtnSkeleton* specifiedSkeleton, int32_t flags, UDateTimePatternMatchOptions options = UDATPG_MATCH_NO_OPTIONS);
551 UnicodeString getBestAppending(int32_t missingFields, int32_t flags, UDateTimePatternMatchOptions options = UDATPG_MATCH_NO_OPTIONS);
552 int32_t getTopBitNumber(int32_t foundMask);
553 void setAvailableFormat(const UnicodeString &key, UErrorCode& status);
554 UBool isAvailableFormatSet(const UnicodeString &key) const;
555 void copyHashtable(Hashtable *other, UErrorCode &status);
556 UBool isCanonicalItem(const UnicodeString& item) const;
557 static void U_CALLCONV loadAllowedHourFormatsData(UErrorCode &status);
558 void getAllowedHourFormats(const Locale &locale, UErrorCode &status);
560 struct AppendItemFormatsSink;
561 struct AppendItemNamesSink;
562 struct AvailableFormatsSink;
563 } ;// end class DateTimePatternGenerator