Line data Source code
1 : // © 2016 and later: Unicode, Inc. and others.
2 : // License & terms of use: http://www.unicode.org/copyright.html
3 : /*
4 : *******************************************************************************
5 : * Copyright (C) 2008-2016, International Business Machines Corporation and
6 : * others. All Rights Reserved.
7 : *******************************************************************************
8 : *
9 : * File DTITVINF.H
10 : *
11 : *******************************************************************************
12 : */
13 :
14 : #ifndef __DTITVINF_H__
15 : #define __DTITVINF_H__
16 :
17 : #include "unicode/utypes.h"
18 :
19 : /**
20 : * \file
21 : * \brief C++ API: Date/Time interval patterns for formatting date/time interval
22 : */
23 :
24 : #if !UCONFIG_NO_FORMATTING
25 :
26 : #include "unicode/udat.h"
27 : #include "unicode/locid.h"
28 : #include "unicode/ucal.h"
29 : #include "unicode/dtptngen.h"
30 :
31 : U_NAMESPACE_BEGIN
32 :
33 : /**
34 : * DateIntervalInfo is a public class for encapsulating localizable
35 : * date time interval patterns. It is used by DateIntervalFormat.
36 : *
37 : * <P>
38 : * For most users, ordinary use of DateIntervalFormat does not need to create
39 : * DateIntervalInfo object directly.
40 : * DateIntervalFormat will take care of it when creating a date interval
41 : * formatter when user pass in skeleton and locale.
42 : *
43 : * <P>
44 : * For power users, who want to create their own date interval patterns,
45 : * or want to re-set date interval patterns, they could do so by
46 : * directly creating DateIntervalInfo and manupulating it.
47 : *
48 : * <P>
49 : * Logically, the interval patterns are mappings
50 : * from (skeleton, the_largest_different_calendar_field)
51 : * to (date_interval_pattern).
52 : *
53 : * <P>
54 : * A skeleton
55 : * <ol>
56 : * <li>
57 : * only keeps the field pattern letter and ignores all other parts
58 : * in a pattern, such as space, punctuations, and string literals.
59 : * <li>
60 : * hides the order of fields.
61 : * <li>
62 : * might hide a field's pattern letter length.
63 : *
64 : * For those non-digit calendar fields, the pattern letter length is
65 : * important, such as MMM, MMMM, and MMMMM; EEE and EEEE,
66 : * and the field's pattern letter length is honored.
67 : *
68 : * For the digit calendar fields, such as M or MM, d or dd, yy or yyyy,
69 : * the field pattern length is ignored and the best match, which is defined
70 : * in date time patterns, will be returned without honor the field pattern
71 : * letter length in skeleton.
72 : * </ol>
73 : *
74 : * <P>
75 : * The calendar fields we support for interval formatting are:
76 : * year, month, date, day-of-week, am-pm, hour, hour-of-day, and minute.
77 : * Those calendar fields can be defined in the following order:
78 : * year > month > date > am-pm > hour > minute
79 : *
80 : * The largest different calendar fields between 2 calendars is the
81 : * first different calendar field in above order.
82 : *
83 : * For example: the largest different calendar fields between "Jan 10, 2007"
84 : * and "Feb 20, 2008" is year.
85 : *
86 : * <P>
87 : * There is a set of pre-defined static skeleton strings.
88 : * There are pre-defined interval patterns for those pre-defined skeletons
89 : * in locales' resource files.
90 : * For example, for a skeleton UDAT_YEAR_ABBR_MONTH_DAY, which is "yMMMd",
91 : * in en_US, if the largest different calendar field between date1 and date2
92 : * is "year", the date interval pattern is "MMM d, yyyy - MMM d, yyyy",
93 : * such as "Jan 10, 2007 - Jan 10, 2008".
94 : * If the largest different calendar field between date1 and date2 is "month",
95 : * the date interval pattern is "MMM d - MMM d, yyyy",
96 : * such as "Jan 10 - Feb 10, 2007".
97 : * If the largest different calendar field between date1 and date2 is "day",
98 : * the date interval pattern is "MMM d-d, yyyy", such as "Jan 10-20, 2007".
99 : *
100 : * For date skeleton, the interval patterns when year, or month, or date is
101 : * different are defined in resource files.
102 : * For time skeleton, the interval patterns when am/pm, or hour, or minute is
103 : * different are defined in resource files.
104 : *
105 : *
106 : * <P>
107 : * There are 2 dates in interval pattern. For most locales, the first date
108 : * in an interval pattern is the earlier date. There might be a locale in which
109 : * the first date in an interval pattern is the later date.
110 : * We use fallback format for the default order for the locale.
111 : * For example, if the fallback format is "{0} - {1}", it means
112 : * the first date in the interval pattern for this locale is earlier date.
113 : * If the fallback format is "{1} - {0}", it means the first date is the
114 : * later date.
115 : * For a particular interval pattern, the default order can be overriden
116 : * by prefixing "latestFirst:" or "earliestFirst:" to the interval pattern.
117 : * For example, if the fallback format is "{0}-{1}",
118 : * but for skeleton "yMMMd", the interval pattern when day is different is
119 : * "latestFirst:d-d MMM yy", it means by default, the first date in interval
120 : * pattern is the earlier date. But for skeleton "yMMMd", when day is different,
121 : * the first date in "d-d MMM yy" is the later date.
122 : *
123 : * <P>
124 : * The recommended way to create a DateIntervalFormat object is to pass in
125 : * the locale.
126 : * By using a Locale parameter, the DateIntervalFormat object is
127 : * initialized with the pre-defined interval patterns for a given or
128 : * default locale.
129 : * <P>
130 : * Users can also create DateIntervalFormat object
131 : * by supplying their own interval patterns.
132 : * It provides flexibility for power users.
133 : *
134 : * <P>
135 : * After a DateIntervalInfo object is created, clients may modify
136 : * the interval patterns using setIntervalPattern function as so desired.
137 : * Currently, users can only set interval patterns when the following
138 : * calendar fields are different: ERA, YEAR, MONTH, DATE, DAY_OF_MONTH,
139 : * DAY_OF_WEEK, AM_PM, HOUR, HOUR_OF_DAY, and MINUTE.
140 : * Interval patterns when other calendar fields are different is not supported.
141 : * <P>
142 : * DateIntervalInfo objects are cloneable.
143 : * When clients obtain a DateIntervalInfo object,
144 : * they can feel free to modify it as necessary.
145 : * <P>
146 : * DateIntervalInfo are not expected to be subclassed.
147 : * Data for a calendar is loaded out of resource bundles.
148 : * Through ICU 4.4, date interval patterns are only supported in the Gregorian
149 : * calendar; non-Gregorian calendars are supported from ICU 4.4.1.
150 : * @stable ICU 4.0
151 : **/
152 :
153 : class U_I18N_API DateIntervalInfo U_FINAL : public UObject {
154 : public:
155 : // Do not enclose the protected default constructor with #ifndef U_HIDE_INTERNAL_API
156 : // or else the compiler will create a public default constructor.
157 : /**
158 : * Default constructor.
159 : * It does not initialize any interval patterns except
160 : * that it initialize default fall-back pattern as "{0} - {1}",
161 : * which can be reset by setFallbackIntervalPattern().
162 : * It should be followed by setFallbackIntervalPattern() and
163 : * setIntervalPattern(),
164 : * and is recommended to be used only for power users who
165 : * wants to create their own interval patterns and use them to create
166 : * date interval formatter.
167 : * @param status output param set to success/failure code on exit
168 : * @internal ICU 4.0
169 : */
170 : DateIntervalInfo(UErrorCode& status);
171 :
172 :
173 : /**
174 : * Construct DateIntervalInfo for the given locale,
175 : * @param locale the interval patterns are loaded from the appropriate calendar
176 : * data (specified calendar or default calendar) in this locale.
177 : * @param status output param set to success/failure code on exit
178 : * @stable ICU 4.0
179 : */
180 : DateIntervalInfo(const Locale& locale, UErrorCode& status);
181 :
182 :
183 : /**
184 : * Copy constructor.
185 : * @stable ICU 4.0
186 : */
187 : DateIntervalInfo(const DateIntervalInfo&);
188 :
189 : /**
190 : * Assignment operator
191 : * @stable ICU 4.0
192 : */
193 : DateIntervalInfo& operator=(const DateIntervalInfo&);
194 :
195 : /**
196 : * Clone this object polymorphically.
197 : * The caller owns the result and should delete it when done.
198 : * @return a copy of the object
199 : * @stable ICU 4.0
200 : */
201 : virtual DateIntervalInfo* clone(void) const;
202 :
203 : /**
204 : * Destructor.
205 : * It is virtual to be safe, but it is not designed to be subclassed.
206 : * @stable ICU 4.0
207 : */
208 : virtual ~DateIntervalInfo();
209 :
210 :
211 : /**
212 : * Return true if another object is semantically equal to this one.
213 : *
214 : * @param other the DateIntervalInfo object to be compared with.
215 : * @return true if other is semantically equal to this.
216 : * @stable ICU 4.0
217 : */
218 : virtual UBool operator==(const DateIntervalInfo& other) const;
219 :
220 : /**
221 : * Return true if another object is semantically unequal to this one.
222 : *
223 : * @param other the DateIntervalInfo object to be compared with.
224 : * @return true if other is semantically unequal to this.
225 : * @stable ICU 4.0
226 : */
227 : UBool operator!=(const DateIntervalInfo& other) const;
228 :
229 :
230 :
231 : /**
232 : * Provides a way for client to build interval patterns.
233 : * User could construct DateIntervalInfo by providing a list of skeletons
234 : * and their patterns.
235 : * <P>
236 : * For example:
237 : * <pre>
238 : * UErrorCode status = U_ZERO_ERROR;
239 : * DateIntervalInfo dIntervalInfo = new DateIntervalInfo();
240 : * dIntervalInfo->setFallbackIntervalPattern("{0} ~ {1}");
241 : * dIntervalInfo->setIntervalPattern("yMd", UCAL_YEAR, "'from' yyyy-M-d 'to' yyyy-M-d", status);
242 : * dIntervalInfo->setIntervalPattern("yMMMd", UCAL_MONTH, "'from' yyyy MMM d 'to' MMM d", status);
243 : * dIntervalInfo->setIntervalPattern("yMMMd", UCAL_DAY, "yyyy MMM d-d", status, status);
244 : * </pre>
245 : *
246 : * Restriction:
247 : * Currently, users can only set interval patterns when the following
248 : * calendar fields are different: ERA, YEAR, MONTH, DATE, DAY_OF_MONTH,
249 : * DAY_OF_WEEK, AM_PM, HOUR, HOUR_OF_DAY, and MINUTE.
250 : * Interval patterns when other calendar fields are different are
251 : * not supported.
252 : *
253 : * @param skeleton the skeleton on which interval pattern based
254 : * @param lrgDiffCalUnit the largest different calendar unit.
255 : * @param intervalPattern the interval pattern on the largest different
256 : * calendar unit.
257 : * For example, if lrgDiffCalUnit is
258 : * "year", the interval pattern for en_US when year
259 : * is different could be "'from' yyyy 'to' yyyy".
260 : * @param status output param set to success/failure code on exit
261 : * @stable ICU 4.0
262 : */
263 : void setIntervalPattern(const UnicodeString& skeleton,
264 : UCalendarDateFields lrgDiffCalUnit,
265 : const UnicodeString& intervalPattern,
266 : UErrorCode& status);
267 :
268 : /**
269 : * Get the interval pattern given skeleton and
270 : * the largest different calendar field.
271 : * @param skeleton the skeleton
272 : * @param field the largest different calendar field
273 : * @param result output param to receive the pattern
274 : * @param status output param set to success/failure code on exit
275 : * @return a reference to 'result'
276 : * @stable ICU 4.0
277 : */
278 : UnicodeString& getIntervalPattern(const UnicodeString& skeleton,
279 : UCalendarDateFields field,
280 : UnicodeString& result,
281 : UErrorCode& status) const;
282 :
283 : /**
284 : * Get the fallback interval pattern.
285 : * @param result output param to receive the pattern
286 : * @return a reference to 'result'
287 : * @stable ICU 4.0
288 : */
289 : UnicodeString& getFallbackIntervalPattern(UnicodeString& result) const;
290 :
291 :
292 : /**
293 : * Re-set the fallback interval pattern.
294 : *
295 : * In construction, default fallback pattern is set as "{0} - {1}".
296 : * And constructor taking locale as parameter will set the
297 : * fallback pattern as what defined in the locale resource file.
298 : *
299 : * This method provides a way for user to replace the fallback pattern.
300 : *
301 : * @param fallbackPattern fall-back interval pattern.
302 : * @param status output param set to success/failure code on exit
303 : * @stable ICU 4.0
304 : */
305 : void setFallbackIntervalPattern(const UnicodeString& fallbackPattern,
306 : UErrorCode& status);
307 :
308 :
309 : /** Get default order -- whether the first date in pattern is later date
310 : or not.
311 : * return default date ordering in interval pattern. TRUE if the first date
312 : * in pattern is later date, FALSE otherwise.
313 : * @stable ICU 4.0
314 : */
315 : UBool getDefaultOrder() const;
316 :
317 :
318 : /**
319 : * ICU "poor man's RTTI", returns a UClassID for the actual class.
320 : *
321 : * @stable ICU 4.0
322 : */
323 : virtual UClassID getDynamicClassID() const;
324 :
325 : /**
326 : * ICU "poor man's RTTI", returns a UClassID for this class.
327 : *
328 : * @stable ICU 4.0
329 : */
330 : static UClassID U_EXPORT2 getStaticClassID();
331 :
332 :
333 : private:
334 : /**
335 : * DateIntervalFormat will need access to
336 : * getBestSkeleton(), parseSkeleton(), enum IntervalPatternIndex,
337 : * and calendarFieldToPatternIndex().
338 : *
339 : * Instead of making above public,
340 : * make DateIntervalFormat a friend of DateIntervalInfo.
341 : */
342 : friend class DateIntervalFormat;
343 :
344 : /**
345 : * Internal struct used to load resource bundle data.
346 : */
347 : struct DateIntervalSink;
348 :
349 : /**
350 : * Following is for saving the interval patterns.
351 : * We only support interval patterns on
352 : * ERA, YEAR, MONTH, DAY, AM_PM, HOUR, and MINUTE
353 : */
354 : enum IntervalPatternIndex
355 : {
356 : kIPI_ERA,
357 : kIPI_YEAR,
358 : kIPI_MONTH,
359 : kIPI_DATE,
360 : kIPI_AM_PM,
361 : kIPI_HOUR,
362 : kIPI_MINUTE,
363 : kIPI_SECOND,
364 : kIPI_MAX_INDEX
365 : };
366 : public:
367 : #ifndef U_HIDE_INTERNAL_API
368 : /**
369 : * Max index for stored interval patterns
370 : * @internal ICU 4.4
371 : */
372 : enum {
373 : kMaxIntervalPatternIndex = kIPI_MAX_INDEX
374 : };
375 : #endif /* U_HIDE_INTERNAL_API */
376 : private:
377 :
378 :
379 : /**
380 : * Initialize the DateIntervalInfo from locale
381 : * @param locale the given locale.
382 : * @param status output param set to success/failure code on exit
383 : */
384 : void initializeData(const Locale& locale, UErrorCode& status);
385 :
386 :
387 : /* Set Interval pattern.
388 : *
389 : * It sets interval pattern into the hash map.
390 : *
391 : * @param skeleton skeleton on which the interval pattern based
392 : * @param lrgDiffCalUnit the largest different calendar unit.
393 : * @param intervalPattern the interval pattern on the largest different
394 : * calendar unit.
395 : * @param status output param set to success/failure code on exit
396 : */
397 : void setIntervalPatternInternally(const UnicodeString& skeleton,
398 : UCalendarDateFields lrgDiffCalUnit,
399 : const UnicodeString& intervalPattern,
400 : UErrorCode& status);
401 :
402 :
403 : /**given an input skeleton, get the best match skeleton
404 : * which has pre-defined interval pattern in resource file.
405 : * Also return the difference between the input skeleton
406 : * and the best match skeleton.
407 : *
408 : * TODO (xji): set field weight or
409 : * isolate the funtionality in DateTimePatternGenerator
410 : * @param skeleton input skeleton
411 : * @param bestMatchDistanceInfo the difference between input skeleton
412 : * and best match skeleton.
413 : * 0, if there is exact match for input skeleton
414 : * 1, if there is only field width difference between
415 : * the best match and the input skeleton
416 : * 2, the only field difference is 'v' and 'z'
417 : * -1, if there is calendar field difference between
418 : * the best match and the input skeleton
419 : * @return best match skeleton
420 : */
421 : const UnicodeString* getBestSkeleton(const UnicodeString& skeleton,
422 : int8_t& bestMatchDistanceInfo) const;
423 :
424 :
425 : /**
426 : * Parse skeleton, save each field's width.
427 : * It is used for looking for best match skeleton,
428 : * and adjust pattern field width.
429 : * @param skeleton skeleton to be parsed
430 : * @param skeletonFieldWidth parsed skeleton field width
431 : */
432 : static void U_EXPORT2 parseSkeleton(const UnicodeString& skeleton,
433 : int32_t* skeletonFieldWidth);
434 :
435 :
436 : /**
437 : * Check whether one field width is numeric while the other is string.
438 : *
439 : * TODO (xji): make it general
440 : *
441 : * @param fieldWidth one field width
442 : * @param anotherFieldWidth another field width
443 : * @param patternLetter pattern letter char
444 : * @return true if one field width is numeric and the other is string,
445 : * false otherwise.
446 : */
447 : static UBool U_EXPORT2 stringNumeric(int32_t fieldWidth,
448 : int32_t anotherFieldWidth,
449 : char patternLetter);
450 :
451 :
452 : /**
453 : * Convert calendar field to the interval pattern index in
454 : * hash table.
455 : *
456 : * Since we only support the following calendar fields:
457 : * ERA, YEAR, MONTH, DATE, DAY_OF_MONTH, DAY_OF_WEEK,
458 : * AM_PM, HOUR, HOUR_OF_DAY, and MINUTE,
459 : * We reserve only 4 interval patterns for a skeleton.
460 : *
461 : * @param field calendar field
462 : * @param status output param set to success/failure code on exit
463 : * @return interval pattern index in hash table
464 : */
465 : static IntervalPatternIndex U_EXPORT2 calendarFieldToIntervalIndex(
466 : UCalendarDateFields field,
467 : UErrorCode& status);
468 :
469 :
470 : /**
471 : * delete hash table (of type fIntervalPatterns).
472 : *
473 : * @param hTable hash table to be deleted
474 : */
475 : void deleteHash(Hashtable* hTable);
476 :
477 :
478 : /**
479 : * initialize hash table (of type fIntervalPatterns).
480 : *
481 : * @param status output param set to success/failure code on exit
482 : * @return hash table initialized
483 : */
484 : Hashtable* initHash(UErrorCode& status);
485 :
486 :
487 :
488 : /**
489 : * copy hash table (of type fIntervalPatterns).
490 : *
491 : * @param source the source to copy from
492 : * @param target the target to copy to
493 : * @param status output param set to success/failure code on exit
494 : */
495 : void copyHash(const Hashtable* source, Hashtable* target, UErrorCode& status);
496 :
497 :
498 : // data members
499 : // fallback interval pattern
500 : UnicodeString fFallbackIntervalPattern;
501 : // default order
502 : UBool fFirstDateInPtnIsLaterDate;
503 :
504 : // HashMap<UnicodeString, UnicodeString[kIPI_MAX_INDEX]>
505 : // HashMap( skeleton, pattern[largest_different_field] )
506 : Hashtable* fIntervalPatterns;
507 :
508 : };// end class DateIntervalInfo
509 :
510 :
511 : inline UBool
512 0 : DateIntervalInfo::operator!=(const DateIntervalInfo& other) const {
513 0 : return !operator==(other);
514 : }
515 :
516 :
517 : U_NAMESPACE_END
518 :
519 : #endif
520 :
521 : #endif
522 :
|
