2 *******************************************************************************
3 * Copyright (C) 2007-2011, International Business Machines Corporation and
4 * others. All Rights Reserved.
5 *******************************************************************************
9 *******************************************************************************
12 #ifndef __DTPTNGEN_H__
13 #define __DTPTNGEN_H__
15 #include "unicode/datefmt.h"
16 #include "unicode/locid.h"
17 #include "unicode/udat.h"
18 #include "unicode/udatpg.h"
24 * \brief C++ API: Date/Time Pattern Generator
30 class DateTimeMatcher
;
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>
49 class U_I18N_API DateTimePatternGenerator
: public UObject
{
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.
57 static DateTimePatternGenerator
* U_EXPORT2
createInstance(UErrorCode
& status
);
60 * Construct a flexible generator according to data for a given locale.
62 * @param status Output param set to success/failure code on exit,
63 * which must not indicate a failure before the function call.
66 static DateTimePatternGenerator
* U_EXPORT2
createInstance(const Locale
& uLocale
, UErrorCode
& status
);
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.
74 static DateTimePatternGenerator
* U_EXPORT2
createEmptyInstance(UErrorCode
& status
);
80 virtual ~DateTimePatternGenerator();
83 * Clone DateTimePatternGenerator object. Clients are responsible for
84 * deleting the DateTimePatternGenerator object cloned.
87 DateTimePatternGenerator
* clone() const;
90 * Return true if another object is semantically equal to this one.
92 * @param other the DateTimePatternGenerator object to be compared with.
93 * @return true if other is semantically equal to this.
96 UBool
operator==(const DateTimePatternGenerator
& other
) const;
99 * Return true if another object is semantically unequal to this one.
101 * @param other the DateTimePatternGenerator object to be compared with.
102 * @return true if other is semantically unequal to this.
105 UBool
operator!=(const DateTimePatternGenerator
& other
) const;
108 * Utility to return a unique skeleton from a given pattern. For example,
109 * both "MMM-dd" and "dd/MMM" produce the skeleton "MMMdd".
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"
117 UnicodeString
getSkeleton(const UnicodeString
& pattern
, UErrorCode
& status
);
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).
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"
132 UnicodeString
getBaseSkeleton(const UnicodeString
& pattern
, UErrorCode
& status
);
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.
141 * Note that single-field patterns (like "MMM") are automatically added, and
142 * don't need to be added explicitly!
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.
154 UDateTimePatternConflict
addPattern(const UnicodeString
& pattern
,
156 UnicodeString
& conflictingPattern
,
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".
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.
171 * This reflects the way that the CLDR data is organized.
173 * @param field such as UDATPG_ERA_FIELD.
174 * @param value pattern, such as "{0}, {1}"
177 void setAppendItemFormat(UDateTimePatternField field
, const UnicodeString
& value
);
180 * Getter corresponding to setAppendItemFormat. Values below 0 or at or
181 * above UDATPG_FIELD_COUNT are illegal arguments.
183 * @param field such as UDATPG_ERA_FIELD.
184 * @return append pattern for field
187 const UnicodeString
& getAppendItemFormat(UDateTimePatternField field
) const;
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
194 * This reflects the way that the CLDR data is organized.
196 * @param field such as UDATPG_ERA_FIELD.
197 * @param value name of the field
200 void setAppendItemName(UDateTimePatternField field
, const UnicodeString
& value
);
203 * Getter corresponding to setAppendItemNames. Values below 0 or at or above
204 * UDATPG_FIELD_COUNT are illegal arguments.
206 * @param field such as UDATPG_ERA_FIELD.
207 * @return name for field
210 const UnicodeString
& getAppendItemName(UDateTimePatternField field
) const;
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.
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".
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.
231 void setDateTimeFormat(const UnicodeString
& dateTimeFormat
);
234 * Getter corresponding to setDateTimeFormat.
235 * @return DateTimeFormat.
238 const UnicodeString
& getDateTimeFormat() const;
241 * Return the best pattern matching the input skeleton. It is guaranteed to
242 * have all of the fields in the 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.
253 UnicodeString
getBestPattern(const UnicodeString
& skeleton
, UErrorCode
& status
);
257 * Return the best pattern matching the input skeleton. It is guaranteed to
258 * have all of the fields in the skeleton.
261 * The skeleton is a pattern containing only the variable fields.
262 * For example, "MMMdd" and "mmhh" are skeletons.
264 * Options for forcing the length of specified fields in the
265 * returned pattern to match those in the skeleton (when this
266 * would not happen otherwise). For default behavior, use
267 * UDATPG_MATCH_NO_OPTIONS.
269 * Output param set to success/failure code on exit,
270 * which must not indicate a failure before the function call.
271 * @return bestPattern
272 * The best pattern found from the given skeleton.
275 UnicodeString
getBestPattern(const UnicodeString
& skeleton
,
276 UDateTimePatternMatchOptions options
,
281 * Adjusts the field types (width and subtype) of a pattern to match what is
282 * in a skeleton. That is, if you supply a pattern like "d-M H:m", and a
283 * skeleton of "MMMMddhhmm", then the input pattern is adjusted to be
284 * "dd-MMMM hh:mm". This is used internally to get the best match for the
285 * input skeleton, but can also be used externally.
287 * @param pattern Input pattern
289 * The skeleton is a pattern containing only the variable fields.
290 * For example, "MMMdd" and "mmhh" are skeletons.
291 * @param status Output param set to success/failure code on exit,
292 * which must not indicate a failure before the function call.
293 * @return pattern adjusted to match the skeleton fields widths and subtypes.
296 UnicodeString
replaceFieldTypes(const UnicodeString
& pattern
,
297 const UnicodeString
& skeleton
,
301 * Adjusts the field types (width and subtype) of a pattern to match what is
302 * in a skeleton. That is, if you supply a pattern like "d-M H:m", and a
303 * skeleton of "MMMMddhhmm", then the input pattern is adjusted to be
304 * "dd-MMMM hh:mm". This is used internally to get the best match for the
305 * input skeleton, but can also be used externally.
307 * @param pattern Input pattern
309 * The skeleton is a pattern containing only the variable fields.
310 * For example, "MMMdd" and "mmhh" are skeletons.
312 * Options controlling whether the length of specified fields in the
313 * pattern are adjusted to match those in the skeleton (when this
314 * would not happen otherwise). For default behavior, use
315 * UDATPG_MATCH_NO_OPTIONS.
317 * Output param set to success/failure code on exit,
318 * which must not indicate a failure before the function call.
319 * @return pattern adjusted to match the skeleton fields widths and subtypes.
322 UnicodeString
replaceFieldTypes(const UnicodeString
& pattern
,
323 const UnicodeString
& skeleton
,
324 UDateTimePatternMatchOptions options
,
328 * Return a list of all the skeletons (in canonical form) from this class.
330 * Call getPatternForSkeleton() to get the corresponding pattern.
332 * @param status Output param set to success/failure code on exit,
333 * which must not indicate a failure before the function call.
334 * @return StringEnumeration with the skeletons.
335 * The caller must delete the object.
338 StringEnumeration
* getSkeletons(UErrorCode
& status
) const;
341 * Get the pattern corresponding to a given skeleton.
343 * @return pattern corresponding to a given skeleton.
346 const UnicodeString
& getPatternForSkeleton(const UnicodeString
& skeleton
) const;
349 * Return a list of all the base skeletons (in canonical form) from this class.
351 * @param status Output param set to success/failure code on exit,
352 * which must not indicate a failure before the function call.
353 * @return a StringEnumeration with the base skeletons.
354 * The caller must delete the object.
357 StringEnumeration
* getBaseSkeletons(UErrorCode
& status
) const;
359 #ifndef U_HIDE_INTERNAL_API
361 * Return a list of redundant patterns are those which if removed, make no
362 * difference in the resulting getBestPattern values. This method returns a
363 * list of them, to help check the consistency of the patterns used to build
366 * @param status Output param set to success/failure code on exit,
367 * which must not indicate a failure before the function call.
368 * @return a StringEnumeration with the redundant pattern.
369 * The caller must delete the object.
372 StringEnumeration
* getRedundants(UErrorCode
& status
);
373 #endif /* U_HIDE_INTERNAL_API */
376 * The decimal value is used in formatting fractions of seconds. If the
377 * skeleton contains fractional seconds, then this is used with the
378 * fractional seconds. For example, suppose that the input pattern is
379 * "hhmmssSSSS", and the best matching pattern internally is "H:mm:ss", and
380 * the decimal string is ",". Then the resulting pattern is modified to be
386 void setDecimal(const UnicodeString
& decimal
);
389 * Getter corresponding to setDecimal.
390 * @return UnicodeString corresponding to the decimal point
393 const UnicodeString
& getDecimal() const;
396 * ICU "poor man's RTTI", returns a UClassID for the actual class.
400 virtual UClassID
getDynamicClassID() const;
403 * ICU "poor man's RTTI", returns a UClassID for this class.
407 static UClassID U_EXPORT2
getStaticClassID(void);
414 DateTimePatternGenerator(UErrorCode
& status
);
420 DateTimePatternGenerator(const Locale
& locale
, UErrorCode
& status
);
424 * @param other DateTimePatternGenerator to copy
427 DateTimePatternGenerator(const DateTimePatternGenerator
& other
);
430 * Default assignment operator.
431 * @param other DateTimePatternGenerator to copy
434 DateTimePatternGenerator
& operator=(const DateTimePatternGenerator
& other
);
436 Locale pLocale
; // pattern locale
438 DateTimeMatcher
* dtMatcher
;
439 DistanceInfo
*distanceInfo
;
440 PatternMap
*patternMap
;
441 UnicodeString appendItemFormats
[UDATPG_FIELD_COUNT
];
442 UnicodeString appendItemNames
[UDATPG_FIELD_COUNT
];
443 UnicodeString dateTimeFormat
;
444 UnicodeString decimal
;
445 DateTimeMatcher
*skipMatcher
;
446 Hashtable
*fAvailableFormatKeyHash
;
447 UnicodeString hackPattern
;
448 UnicodeString emptyString
;
449 UChar fDefaultHourFormatChar
;
451 void initData(const Locale
&locale
, UErrorCode
&status
);
452 void addCanonicalItems();
453 void addICUPatterns(const Locale
& locale
, UErrorCode
& status
);
454 void hackTimes(const UnicodeString
& hackPattern
, UErrorCode
& status
);
455 void addCLDRData(const Locale
& locale
, UErrorCode
& status
);
456 UDateTimePatternConflict
addPatternWithSkeleton(const UnicodeString
& pattern
, const UnicodeString
* skeletonToUse
, UBool override
, UnicodeString
& conflictingPattern
, UErrorCode
& status
);
457 void initHashtable(UErrorCode
& status
);
458 void setDateTimeFromCalendar(const Locale
& locale
, UErrorCode
& status
);
459 void setDecimalSymbols(const Locale
& locale
, UErrorCode
& status
);
460 UDateTimePatternField
getAppendFormatNumber(const char* field
) const;
461 UDateTimePatternField
getAppendNameNumber(const char* field
) const;
462 void getAppendName(UDateTimePatternField field
, UnicodeString
& value
);
463 int32_t getCanonicalIndex(const UnicodeString
& field
);
464 const UnicodeString
* getBestRaw(DateTimeMatcher
& source
, int32_t includeMask
, DistanceInfo
* missingFields
, const PtnSkeleton
** specifiedSkeletonPtr
= 0);
465 UnicodeString
adjustFieldTypes(const UnicodeString
& pattern
, const PtnSkeleton
* specifiedSkeleton
, UBool fixFractionalSeconds
, UDateTimePatternMatchOptions options
= UDATPG_MATCH_NO_OPTIONS
);
466 UnicodeString
getBestAppending(int32_t missingFields
, UDateTimePatternMatchOptions options
= UDATPG_MATCH_NO_OPTIONS
);
467 int32_t getTopBitNumber(int32_t foundMask
);
468 void setAvailableFormat(const UnicodeString
&key
, UErrorCode
& status
);
469 UBool
isAvailableFormatSet(const UnicodeString
&key
) const;
470 void copyHashtable(Hashtable
*other
, UErrorCode
&status
);
471 UBool
isCanonicalItem(const UnicodeString
& item
) const;
472 } ;// end class DateTimePatternGenerator