intl/icu/source/i18n/unicode/dtitvfmt.h@6474c204b198
intl/icu/source/i18n/unicode/dtitvfmt.h
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
1 /********************************************************************************
2 * Copyright (C) 2008-2013, International Business Machines Corporation and
3 * others. All Rights Reserved.
4 *******************************************************************************
5 *
6 * File DTITVFMT.H
7 *
8 *******************************************************************************
9 */
11 #ifndef __DTITVFMT_H__
12 #define __DTITVFMT_H__
15 #include "unicode/utypes.h"
17 /**
18 * \file
19 * \brief C++ API: Format and parse date interval in a language-independent manner.
20 */
22 #if !UCONFIG_NO_FORMATTING
24 #include "unicode/ucal.h"
25 #include "unicode/smpdtfmt.h"
26 #include "unicode/dtintrv.h"
27 #include "unicode/dtitvinf.h"
28 #include "unicode/dtptngen.h"
30 U_NAMESPACE_BEGIN
34 /**
35 * DateIntervalFormat is a class for formatting and parsing date
36 * intervals in a language-independent manner.
37 * Only formatting is supported, parsing is not supported.
38 *
39 * <P>
40 * Date interval means from one date to another date,
41 * for example, from "Jan 11, 2008" to "Jan 18, 2008".
42 * We introduced class DateInterval to represent it.
43 * DateInterval is a pair of UDate, which is
44 * the standard milliseconds since 24:00 GMT, Jan 1, 1970.
45 *
46 * <P>
47 * DateIntervalFormat formats a DateInterval into
48 * text as compactly as possible.
49 * For example, the date interval format from "Jan 11, 2008" to "Jan 18,. 2008"
50 * is "Jan 11-18, 2008" for English.
51 * And it parses text into DateInterval,
52 * although initially, parsing is not supported.
53 *
54 * <P>
55 * There is no structural information in date time patterns.
56 * For any punctuations and string literals inside a date time pattern,
57 * we do not know whether it is just a separator, or a prefix, or a suffix.
58 * Without such information, so, it is difficult to generate a sub-pattern
59 * (or super-pattern) by algorithm.
60 * So, formatting a DateInterval is pattern-driven. It is very
61 * similar to formatting in SimpleDateFormat.
62 * We introduce class DateIntervalInfo to save date interval
63 * patterns, similar to date time pattern in SimpleDateFormat.
64 *
65 * <P>
66 * Logically, the interval patterns are mappings
67 * from (skeleton, the_largest_different_calendar_field)
68 * to (date_interval_pattern).
69 *
70 * <P>
71 * A skeleton
72 * <ol>
73 * <li>
74 * only keeps the field pattern letter and ignores all other parts
75 * in a pattern, such as space, punctuations, and string literals.
76 * </li>
77 * <li>
78 * hides the order of fields.
79 * </li>
80 * <li>
81 * might hide a field's pattern letter length.
82 * </li>
83 * </ol>
84 *
85 * For those non-digit calendar fields, the pattern letter length is
86 * important, such as MMM, MMMM, and MMMMM; EEE and EEEE,
87 * and the field's pattern letter length is honored.
88 *
89 * For the digit calendar fields, such as M or MM, d or dd, yy or yyyy,
90 * the field pattern length is ignored and the best match, which is defined
91 * in date time patterns, will be returned without honor the field pattern
92 * letter length in skeleton.
93 *
94 * <P>
95 * The calendar fields we support for interval formatting are:
96 * year, month, date, day-of-week, am-pm, hour, hour-of-day, and minute.
97 * Those calendar fields can be defined in the following order:
98 * year > month > date > hour (in day) > minute
99 *
100 * The largest different calendar fields between 2 calendars is the
101 * first different calendar field in above order.
102 *
103 * For example: the largest different calendar fields between "Jan 10, 2007"
104 * and "Feb 20, 2008" is year.
105 *
106 * <P>
107 * For other calendar fields, the compact interval formatting is not
108 * supported. And the interval format will be fall back to fall-back
109 * patterns, which is mostly "{date0} - {date1}".
110 *
111 * <P>
112 * There is a set of pre-defined static skeleton strings.
113 * There are pre-defined interval patterns for those pre-defined skeletons
114 * in locales' resource files.
115 * For example, for a skeleton UDAT_YEAR_ABBR_MONTH_DAY, which is "yMMMd",
116 * in en_US, if the largest different calendar field between date1 and date2
117 * is "year", the date interval pattern is "MMM d, yyyy - MMM d, yyyy",
118 * such as "Jan 10, 2007 - Jan 10, 2008".
119 * If the largest different calendar field between date1 and date2 is "month",
120 * the date interval pattern is "MMM d - MMM d, yyyy",
121 * such as "Jan 10 - Feb 10, 2007".
122 * If the largest different calendar field between date1 and date2 is "day",
123 * the date interval pattern is "MMM d-d, yyyy", such as "Jan 10-20, 2007".
124 *
125 * For date skeleton, the interval patterns when year, or month, or date is
126 * different are defined in resource files.
127 * For time skeleton, the interval patterns when am/pm, or hour, or minute is
128 * different are defined in resource files.
129 *
130 * <P>
131 * If a skeleton is not found in a locale's DateIntervalInfo, which means
132 * the interval patterns for the skeleton is not defined in resource file,
133 * the interval pattern will falls back to the interval "fallback" pattern
134 * defined in resource file.
135 * If the interval "fallback" pattern is not defined, the default fall-back
136 * is "{date0} - {data1}".
137 *
138 * <P>
139 * For the combination of date and time,
140 * The rule to generate interval patterns are:
141 * <ol>
142 * <li>
143 * when the year, month, or day differs, falls back to fall-back
144 * interval pattern, which mostly is the concatenate the two original
145 * expressions with a separator between,
146 * For example, interval pattern from "Jan 10, 2007 10:10 am"
147 * to "Jan 11, 2007 10:10am" is
148 * "Jan 10, 2007 10:10 am - Jan 11, 2007 10:10am"
149 * </li>
150 * <li>
151 * otherwise, present the date followed by the range expression
152 * for the time.
153 * For example, interval pattern from "Jan 10, 2007 10:10 am"
154 * to "Jan 10, 2007 11:10am" is "Jan 10, 2007 10:10 am - 11:10am"
155 * </li>
156 * </ol>
157 *
158 *
159 * <P>
160 * If two dates are the same, the interval pattern is the single date pattern.
161 * For example, interval pattern from "Jan 10, 2007" to "Jan 10, 2007" is
162 * "Jan 10, 2007".
163 *
164 * Or if the presenting fields between 2 dates have the exact same values,
165 * the interval pattern is the single date pattern.
166 * For example, if user only requests year and month,
167 * the interval pattern from "Jan 10, 2007" to "Jan 20, 2007" is "Jan 2007".
168 *
169 * <P>
170 * DateIntervalFormat needs the following information for correct
171 * formatting: time zone, calendar type, pattern, date format symbols,
172 * and date interval patterns.
173 * It can be instantiated in 2 ways:
174 * <ol>
175 * <li>
176 * create an instance using default or given locale plus given skeleton.
177 * Users are encouraged to created date interval formatter this way and
178 * to use the pre-defined skeleton macros, such as
179 * UDAT_YEAR_NUM_MONTH, which consists the calendar fields and
180 * the format style.
181 * </li>
182 * <li>
183 * create an instance using default or given locale plus given skeleton
184 * plus a given DateIntervalInfo.
185 * This factory method is for powerful users who want to provide their own
186 * interval patterns.
187 * Locale provides the timezone, calendar, and format symbols information.
188 * Local plus skeleton provides full pattern information.
189 * DateIntervalInfo provides the date interval patterns.
190 * </li>
191 * </ol>
192 *
193 * <P>
194 * For the calendar field pattern letter, such as G, y, M, d, a, h, H, m, s etc.
195 * DateIntervalFormat uses the same syntax as that of
196 * DateTime format.
197 *
198 * <P>
199 * Code Sample: general usage
200 * <pre>
201 * \code
202 * // the date interval object which the DateIntervalFormat formats on
203 * // and parses into
204 * DateInterval* dtInterval = new DateInterval(1000*3600*24, 1000*3600*24*2);
205 * UErrorCode status = U_ZERO_ERROR;
206 * DateIntervalFormat* dtIntervalFmt = DateIntervalFormat::createInstance(
207 * UDAT_YEAR_MONTH_DAY,
208 * Locale("en", "GB", ""), status);
209 * UnicodeUnicodeString dateIntervalString;
210 * FieldPosition pos = 0;
211 * // formatting
212 * dtIntervalFmt->format(dtInterval, dateIntervalUnicodeString, pos, status);
213 * delete dtIntervalFmt;
214 * \endcode
215 * </pre>
216 */
218 class U_I18N_API DateIntervalFormat : public Format {
219 public:
221 /**
222 * Construct a DateIntervalFormat from skeleton and the default locale.
223 *
224 * This is a convenient override of
225 * createInstance(const UnicodeString& skeleton, const Locale& locale,
226 * UErrorCode&)
227 * with the value of locale as default locale.
228 *
229 * @param skeleton the skeleton on which interval format based.
230 * @param status output param set to success/failure code on exit
231 * @return a date time interval formatter which the caller owns.
232 * @stable ICU 4.0
233 */
234 static DateIntervalFormat* U_EXPORT2 createInstance(
235 const UnicodeString& skeleton,
236 UErrorCode& status);
238 /**
239 * Construct a DateIntervalFormat from skeleton and a given locale.
240 * <P>
241 * In this factory method,
242 * the date interval pattern information is load from resource files.
243 * Users are encouraged to created date interval formatter this way and
244 * to use the pre-defined skeleton macros.
245 *
246 * <P>
247 * There are pre-defined skeletons (defined in udate.h) having predefined
248 * interval patterns in resource files.
249 * Users are encouraged to use those macros.
250 * For example:
251 * DateIntervalFormat::createInstance(UDAT_MONTH_DAY, status)
252 *
253 * The given Locale provides the interval patterns.
254 * For example, for en_GB, if skeleton is UDAT_YEAR_ABBR_MONTH_WEEKDAY_DAY,
255 * which is "yMMMEEEd",
256 * the interval patterns defined in resource file to above skeleton are:
257 * "EEE, d MMM, yyyy - EEE, d MMM, yyyy" for year differs,
258 * "EEE, d MMM - EEE, d MMM, yyyy" for month differs,
259 * "EEE, d - EEE, d MMM, yyyy" for day differs,
260 * @param skeleton the skeleton on which the interval format is based.
261 * @param locale the given locale
262 * @param status output param set to success/failure code on exit
263 * @return a date time interval formatter which the caller owns.
264 * @stable ICU 4.0
265 * <p>
266 * <h4>Sample code</h4>
267 * \snippet samples/dtitvfmtsample/dtitvfmtsample.cpp dtitvfmtPreDefined1
268 * \snippet samples/dtitvfmtsample/dtitvfmtsample.cpp dtitvfmtPreDefined
269 * <p>
270 */
272 static DateIntervalFormat* U_EXPORT2 createInstance(
273 const UnicodeString& skeleton,
274 const Locale& locale,
275 UErrorCode& status);
277 /**
278 * Construct a DateIntervalFormat from skeleton
279 * DateIntervalInfo, and default locale.
280 *
281 * This is a convenient override of
282 * createInstance(const UnicodeString& skeleton, const Locale& locale,
283 * const DateIntervalInfo& dtitvinf, UErrorCode&)
284 * with the locale value as default locale.
285 *
286 * @param skeleton the skeleton on which interval format based.
287 * @param dtitvinf the DateIntervalInfo object.
288 * @param status output param set to success/failure code on exit
289 * @return a date time interval formatter which the caller owns.
290 * @stable ICU 4.0
291 */
292 static DateIntervalFormat* U_EXPORT2 createInstance(
293 const UnicodeString& skeleton,
294 const DateIntervalInfo& dtitvinf,
295 UErrorCode& status);
297 /**
298 * Construct a DateIntervalFormat from skeleton
299 * a DateIntervalInfo, and the given locale.
300 *
301 * <P>
302 * In this factory method, user provides its own date interval pattern
303 * information, instead of using those pre-defined data in resource file.
304 * This factory method is for powerful users who want to provide their own
305 * interval patterns.
306 * <P>
307 * There are pre-defined skeletons (defined in udate.h) having predefined
308 * interval patterns in resource files.
309 * Users are encouraged to use those macros.
310 * For example:
311 * DateIntervalFormat::createInstance(UDAT_MONTH_DAY, status)
312 *
313 * The DateIntervalInfo provides the interval patterns.
314 * and the DateIntervalInfo ownership remains to the caller.
315 *
316 * User are encouraged to set default interval pattern in DateIntervalInfo
317 * as well, if they want to set other interval patterns ( instead of
318 * reading the interval patterns from resource files).
319 * When the corresponding interval pattern for a largest calendar different
320 * field is not found ( if user not set it ), interval format fallback to
321 * the default interval pattern.
322 * If user does not provide default interval pattern, it fallback to
323 * "{date0} - {date1}"
324 *
325 * @param skeleton the skeleton on which interval format based.
326 * @param locale the given locale
327 * @param dtitvinf the DateIntervalInfo object.
328 * @param status output param set to success/failure code on exit
329 * @return a date time interval formatter which the caller owns.
330 * @stable ICU 4.0
331 * <p>
332 * <h4>Sample code</h4>
333 * \snippet samples/dtitvfmtsample/dtitvfmtsample.cpp dtitvfmtPreDefined1
334 * \snippet samples/dtitvfmtsample/dtitvfmtsample.cpp dtitvfmtCustomized
335 * <p>
336 */
337 static DateIntervalFormat* U_EXPORT2 createInstance(
338 const UnicodeString& skeleton,
339 const Locale& locale,
340 const DateIntervalInfo& dtitvinf,
341 UErrorCode& status);
343 /**
344 * Destructor.
345 * @stable ICU 4.0
346 */
347 virtual ~DateIntervalFormat();
349 /**
350 * Clone this Format object polymorphically. The caller owns the result and
351 * should delete it when done.
352 * @return A copy of the object.
353 * @stable ICU 4.0
354 */
355 virtual Format* clone(void) const;
357 /**
358 * Return true if the given Format objects are semantically equal. Objects
359 * of different subclasses are considered unequal.
360 * @param other the object to be compared with.
361 * @return true if the given Format objects are semantically equal.
362 * @stable ICU 4.0
363 */
364 virtual UBool operator==(const Format& other) const;
366 /**
367 * Return true if the given Format objects are not semantically equal.
368 * Objects of different subclasses are considered unequal.
369 * @param other the object to be compared with.
370 * @return true if the given Format objects are not semantically equal.
371 * @stable ICU 4.0
372 */
373 UBool operator!=(const Format& other) const;
376 using Format::format;
378 /**
379 * Format an object to produce a string. This method handles Formattable
380 * objects with a DateInterval type.
381 * If a the Formattable object type is not a DateInterval,
382 * then it returns a failing UErrorCode.
383 *
384 * @param obj The object to format.
385 * Must be a DateInterval.
386 * @param appendTo Output parameter to receive result.
387 * Result is appended to existing contents.
388 * @param fieldPosition On input: an alignment field, if desired.
389 * On output: the offsets of the alignment field.
390 * @param status Output param filled with success/failure status.
391 * @return Reference to 'appendTo' parameter.
392 * @stable ICU 4.0
393 */
394 virtual UnicodeString& format(const Formattable& obj,
395 UnicodeString& appendTo,
396 FieldPosition& fieldPosition,
397 UErrorCode& status) const ;
401 /**
402 * Format a DateInterval to produce a string.
403 *
404 * @param dtInterval DateInterval to be formatted.
405 * @param appendTo Output parameter to receive result.
406 * Result is appended to existing contents.
407 * @param fieldPosition On input: an alignment field, if desired.
408 * On output: the offsets of the alignment field.
409 * @param status Output param filled with success/failure status.
410 * @return Reference to 'appendTo' parameter.
411 * @stable ICU 4.0
412 */
413 UnicodeString& format(const DateInterval* dtInterval,
414 UnicodeString& appendTo,
415 FieldPosition& fieldPosition,
416 UErrorCode& status) const ;
419 /**
420 * Format 2 Calendars to produce a string.
421 *
422 * Note: "fromCalendar" and "toCalendar" are not const,
423 * since calendar is not const in SimpleDateFormat::format(Calendar&),
424 *
425 * @param fromCalendar calendar set to the from date in date interval
426 * to be formatted into date interval string
427 * @param toCalendar calendar set to the to date in date interval
428 * to be formatted into date interval string
429 * @param appendTo Output parameter to receive result.
430 * Result is appended to existing contents.
431 * @param fieldPosition On input: an alignment field, if desired.
432 * On output: the offsets of the alignment field.
433 * @param status Output param filled with success/failure status.
434 * Caller needs to make sure it is SUCCESS
435 * at the function entrance
436 * @return Reference to 'appendTo' parameter.
437 * @stable ICU 4.0
438 */
439 UnicodeString& format(Calendar& fromCalendar,
440 Calendar& toCalendar,
441 UnicodeString& appendTo,
442 FieldPosition& fieldPosition,
443 UErrorCode& status) const ;
445 /**
446 * Date interval parsing is not supported. Please do not use.
447 * <P>
448 * This method should handle parsing of
449 * date time interval strings into Formattable objects with
450 * DateInterval type, which is a pair of UDate.
451 * <P>
452 * Before calling, set parse_pos.index to the offset you want to start
453 * parsing at in the source. After calling, parse_pos.index is the end of
454 * the text you parsed. If error occurs, index is unchanged.
455 * <P>
456 * When parsing, leading whitespace is discarded (with a successful parse),
457 * while trailing whitespace is left as is.
458 * <P>
459 * See Format::parseObject() for more.
460 *
461 * @param source The string to be parsed into an object.
462 * @param result Formattable to be set to the parse result.
463 * If parse fails, return contents are undefined.
464 * @param parse_pos The position to start parsing at. Since no parsing
465 * is supported, upon return this param is unchanged.
466 * @return A newly created Formattable* object, or NULL
467 * on failure. The caller owns this and should
468 * delete it when done.
469 * @internal ICU 4.0
470 */
471 virtual void parseObject(const UnicodeString& source,
472 Formattable& result,
473 ParsePosition& parse_pos) const;
476 /**
477 * Gets the date time interval patterns.
478 * @return the date time interval patterns associated with
479 * this date interval formatter.
480 * @stable ICU 4.0
481 */
482 const DateIntervalInfo* getDateIntervalInfo(void) const;
485 /**
486 * Set the date time interval patterns.
487 * @param newIntervalPatterns the given interval patterns to copy.
488 * @param status output param set to success/failure code on exit
489 * @stable ICU 4.0
490 */
491 void setDateIntervalInfo(const DateIntervalInfo& newIntervalPatterns,
492 UErrorCode& status);
495 /**
496 * Gets the date formatter
497 * @return the date formatter associated with this date interval formatter.
498 * @stable ICU 4.0
499 */
500 const DateFormat* getDateFormat(void) const;
502 /**
503 * Returns a reference to the TimeZone used by this DateIntervalFormat's calendar.
504 * @return the time zone associated with the calendar of DateIntervalFormat.
505 * @stable ICU 4.8
506 */
507 virtual const TimeZone& getTimeZone(void) const;
509 /**
510 * Sets the time zone for the calendar used by this DateIntervalFormat object. The
511 * caller no longer owns the TimeZone object and should not delete it after this call.
512 * @param zoneToAdopt the TimeZone to be adopted.
513 * @stable ICU 4.8
514 */
515 virtual void adoptTimeZone(TimeZone* zoneToAdopt);
517 /**
518 * Sets the time zone for the calendar used by this DateIntervalFormat object.
519 * @param zone the new time zone.
520 * @stable ICU 4.8
521 */
522 virtual void setTimeZone(const TimeZone& zone);
524 /**
525 * Return the class ID for this class. This is useful only for comparing to
526 * a return value from getDynamicClassID(). For example:
527 * <pre>
528 * . Base* polymorphic_pointer = createPolymorphicObject();
529 * . if (polymorphic_pointer->getDynamicClassID() ==
530 * . erived::getStaticClassID()) ...
531 * </pre>
532 * @return The class ID for all objects of this class.
533 * @stable ICU 4.0
534 */
535 static UClassID U_EXPORT2 getStaticClassID(void);
537 /**
538 * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This
539 * method is to implement a simple version of RTTI, since not all C++
540 * compilers support genuine RTTI. Polymorphic operator==() and clone()
541 * methods call this method.
542 *
543 * @return The class ID for this object. All objects of a
544 * given class have the same class ID. Objects of
545 * other classes have different class IDs.
546 * @stable ICU 4.0
547 */
548 virtual UClassID getDynamicClassID(void) const;
550 protected:
552 /**
553 * Copy constructor.
554 * @stable ICU 4.0
555 */
556 DateIntervalFormat(const DateIntervalFormat&);
558 /**
559 * Assignment operator.
560 * @stable ICU 4.0
561 */
562 DateIntervalFormat& operator=(const DateIntervalFormat&);
564 private:
566 /*
567 * This is for ICU internal use only. Please do not use.
568 * Save the interval pattern information.
569 * Interval pattern consists of 2 single date patterns and the separator.
570 * For example, interval pattern "MMM d - MMM d, yyyy" consists
571 * a single date pattern "MMM d", another single date pattern "MMM d, yyyy",
572 * and a separator "-".
573 * The pattern is divided into 2 parts. For above example,
574 * the first part is "MMM d - ", and the second part is "MMM d, yyyy".
575 * Also, the first date appears in an interval pattern could be
576 * the earlier date or the later date.
577 * And such information is saved in the interval pattern as well.
578 */
579 struct PatternInfo {
580 UnicodeString firstPart;
581 UnicodeString secondPart;
582 /**
583 * Whether the first date in interval pattern is later date or not.
584 * Fallback format set the default ordering.
585 * And for a particular interval pattern, the order can be
586 * overriden by prefixing the interval pattern with "latestFirst:" or
587 * "earliestFirst:"
588 * For example, given 2 date, Jan 10, 2007 to Feb 10, 2007.
589 * if the fallback format is "{0} - {1}",
590 * and the pattern is "d MMM - d MMM yyyy", the interval format is
591 * "10 Jan - 10 Feb, 2007".
592 * If the pattern is "latestFirst:d MMM - d MMM yyyy",
593 * the interval format is "10 Feb - 10 Jan, 2007"
594 */
595 UBool laterDateFirst;
596 };
599 /**
600 * default constructor
601 * @internal ICU 4.0
602 */
603 DateIntervalFormat();
605 /**
606 * Construct a DateIntervalFormat from DateFormat,
607 * a DateIntervalInfo, and skeleton.
608 * DateFormat provides the timezone, calendar,
609 * full pattern, and date format symbols information.
610 * It should be a SimpleDateFormat object which
611 * has a pattern in it.
612 * the DateIntervalInfo provides the interval patterns.
613 *
614 * Note: the DateIntervalFormat takes ownership of both
615 * DateFormat and DateIntervalInfo objects.
616 * Caller should not delete them.
617 *
618 * @param locale the locale of this date interval formatter.
619 * @param dtItvInfo the DateIntervalInfo object to be adopted.
620 * @param skeleton the skeleton of the date formatter
621 * @param status output param set to success/failure code on exit
622 */
623 DateIntervalFormat(const Locale& locale, DateIntervalInfo* dtItvInfo,
624 const UnicodeString* skeleton, UErrorCode& status);
627 /**
628 * Construct a DateIntervalFormat from DateFormat
629 * and a DateIntervalInfo.
630 *
631 * It is a wrapper of the constructor.
632 *
633 * @param locale the locale of this date interval formatter.
634 * @param dtitvinf the DateIntervalInfo object to be adopted.
635 * @param skeleton the skeleton of this formatter.
636 * @param status Output param set to success/failure code.
637 * @return a date time interval formatter which the caller owns.
638 */
639 static DateIntervalFormat* U_EXPORT2 create(const Locale& locale,
640 DateIntervalInfo* dtitvinf,
641 const UnicodeString* skeleton,
642 UErrorCode& status);
644 /**
645 * Create a simple date/time formatter from skeleton, given locale,
646 * and date time pattern generator.
647 *
648 * @param skeleton the skeleton on which date format based.
649 * @param locale the given locale.
650 * @param dtpng the date time pattern generator.
651 * @param status Output param to be set to success/failure code.
652 * If it is failure, the returned date formatter will
653 * be NULL.
654 * @return a simple date formatter which the caller owns.
655 */
656 static SimpleDateFormat* U_EXPORT2 createSDFPatternInstance(
657 const UnicodeString& skeleton,
658 const Locale& locale,
659 DateTimePatternGenerator* dtpng,
660 UErrorCode& status);
663 /**
664 * Below are for generating interval patterns local to the formatter
665 */
668 /**
669 * Format 2 Calendars using fall-back interval pattern
670 *
671 * The full pattern used in this fall-back format is the
672 * full pattern of the date formatter.
673 *
674 * @param fromCalendar calendar set to the from date in date interval
675 * to be formatted into date interval string
676 * @param toCalendar calendar set to the to date in date interval
677 * to be formatted into date interval string
678 * @param appendTo Output parameter to receive result.
679 * Result is appended to existing contents.
680 * @param pos On input: an alignment field, if desired.
681 * On output: the offsets of the alignment field.
682 * @param status output param set to success/failure code on exit
683 * @return Reference to 'appendTo' parameter.
684 */
685 UnicodeString& fallbackFormat(Calendar& fromCalendar,
686 Calendar& toCalendar,
687 UnicodeString& appendTo,
688 FieldPosition& pos,
689 UErrorCode& status) const;
693 /**
694 * Initialize interval patterns locale to this formatter
695 *
696 * This code is a bit complicated since
697 * 1. the interval patterns saved in resource bundle files are interval
698 * patterns based on date or time only.
699 * It does not have interval patterns based on both date and time.
700 * Interval patterns on both date and time are algorithm generated.
701 *
702 * For example, it has interval patterns on skeleton "dMy" and "hm",
703 * but it does not have interval patterns on skeleton "dMyhm".
704 *
705 * The rule to generate interval patterns for both date and time skeleton are
706 * 1) when the year, month, or day differs, concatenate the two original
707 * expressions with a separator between,
708 * For example, interval pattern from "Jan 10, 2007 10:10 am"
709 * to "Jan 11, 2007 10:10am" is
710 * "Jan 10, 2007 10:10 am - Jan 11, 2007 10:10am"
711 *
712 * 2) otherwise, present the date followed by the range expression
713 * for the time.
714 * For example, interval pattern from "Jan 10, 2007 10:10 am"
715 * to "Jan 10, 2007 11:10am" is
716 * "Jan 10, 2007 10:10 am - 11:10am"
717 *
718 * 2. even a pattern does not request a certain calendar field,
719 * the interval pattern needs to include such field if such fields are
720 * different between 2 dates.
721 * For example, a pattern/skeleton is "hm", but the interval pattern
722 * includes year, month, and date when year, month, and date differs.
723 *
724 *
725 * @param status output param set to success/failure code on exit
726 */
727 void initializePattern(UErrorCode& status);
731 /**
732 * Set fall back interval pattern given a calendar field,
733 * a skeleton, and a date time pattern generator.
734 * @param field the largest different calendar field
735 * @param skeleton a skeleton
736 * @param status output param set to success/failure code on exit
737 */
738 void setFallbackPattern(UCalendarDateFields field,
739 const UnicodeString& skeleton,
740 UErrorCode& status);
744 /**
745 * get separated date and time skeleton from a combined skeleton.
746 *
747 * The difference between date skeleton and normalizedDateSkeleton are:
748 * 1. both 'y' and 'd' are appeared only once in normalizeDateSkeleton
749 * 2. 'E' and 'EE' are normalized into 'EEE'
750 * 3. 'MM' is normalized into 'M'
751 *
752 ** the difference between time skeleton and normalizedTimeSkeleton are:
753 * 1. both 'H' and 'h' are normalized as 'h' in normalized time skeleton,
754 * 2. 'a' is omitted in normalized time skeleton.
755 * 3. there is only one appearance for 'h', 'm','v', 'z' in normalized time
756 * skeleton
757 *
758 *
759 * @param skeleton given combined skeleton.
760 * @param date Output parameter for date only skeleton.
761 * @param normalizedDate Output parameter for normalized date only
762 *
763 * @param time Output parameter for time only skeleton.
764 * @param normalizedTime Output parameter for normalized time only
765 * skeleton.
766 *
767 */
768 static void U_EXPORT2 getDateTimeSkeleton(const UnicodeString& skeleton,
769 UnicodeString& date,
770 UnicodeString& normalizedDate,
771 UnicodeString& time,
772 UnicodeString& normalizedTime);
776 /**
777 * Generate date or time interval pattern from resource,
778 * and set them into the interval pattern locale to this formatter.
779 *
780 * It needs to handle the following:
781 * 1. need to adjust field width.
782 * For example, the interval patterns saved in DateIntervalInfo
783 * includes "dMMMy", but not "dMMMMy".
784 * Need to get interval patterns for dMMMMy from dMMMy.
785 * Another example, the interval patterns saved in DateIntervalInfo
786 * includes "hmv", but not "hmz".
787 * Need to get interval patterns for "hmz' from 'hmv'
788 *
789 * 2. there might be no pattern for 'y' differ for skeleton "Md",
790 * in order to get interval patterns for 'y' differ,
791 * need to look for it from skeleton 'yMd'
792 *
793 * @param dateSkeleton normalized date skeleton
794 * @param timeSkeleton normalized time skeleton
795 * @return whether the resource is found for the skeleton.
796 * TRUE if interval pattern found for the skeleton,
797 * FALSE otherwise.
798 */
799 UBool setSeparateDateTimePtn(const UnicodeString& dateSkeleton,
800 const UnicodeString& timeSkeleton);
805 /**
806 * Generate interval pattern from existing resource
807 *
808 * It not only save the interval patterns,
809 * but also return the extended skeleton and its best match skeleton.
810 *
811 * @param field largest different calendar field
812 * @param skeleton skeleton
813 * @param bestSkeleton the best match skeleton which has interval pattern
814 * defined in resource
815 * @param differenceInfo the difference between skeleton and best skeleton
816 * 0 means the best matched skeleton is the same as input skeleton
817 * 1 means the fields are the same, but field width are different
818 * 2 means the only difference between fields are v/z,
819 * -1 means there are other fields difference
820 *
821 * @param extendedSkeleton extended skeleton
822 * @param extendedBestSkeleton extended best match skeleton
823 * @return whether the interval pattern is found
824 * through extending skeleton or not.
825 * TRUE if interval pattern is found by
826 * extending skeleton, FALSE otherwise.
827 */
828 UBool setIntervalPattern(UCalendarDateFields field,
829 const UnicodeString* skeleton,
830 const UnicodeString* bestSkeleton,
831 int8_t differenceInfo,
832 UnicodeString* extendedSkeleton = NULL,
833 UnicodeString* extendedBestSkeleton = NULL);
835 /**
836 * Adjust field width in best match interval pattern to match
837 * the field width in input skeleton.
838 *
839 * TODO (xji) make a general solution
840 * The adjusting rule can be:
841 * 1. always adjust
842 * 2. never adjust
843 * 3. default adjust, which means adjust according to the following rules
844 * 3.1 always adjust string, such as MMM and MMMM
845 * 3.2 never adjust between string and numeric, such as MM and MMM
846 * 3.3 always adjust year
847 * 3.4 do not adjust 'd', 'h', or 'm' if h presents
848 * 3.5 do not adjust 'M' if it is numeric(?)
849 *
850 * Since date interval format is well-formed format,
851 * date and time skeletons are normalized previously,
852 * till this stage, the adjust here is only "adjust strings, such as MMM
853 * and MMMM, EEE and EEEE.
854 *
855 * @param inputSkeleton the input skeleton
856 * @param bestMatchSkeleton the best match skeleton
857 * @param bestMatchIntervalPattern the best match interval pattern
858 * @param differenceInfo the difference between 2 skeletons
859 * 1 means only field width differs
860 * 2 means v/z exchange
861 * @param adjustedIntervalPattern adjusted interval pattern
862 */
863 static void U_EXPORT2 adjustFieldWidth(
864 const UnicodeString& inputSkeleton,
865 const UnicodeString& bestMatchSkeleton,
866 const UnicodeString& bestMatchIntervalPattern,
867 int8_t differenceInfo,
868 UnicodeString& adjustedIntervalPattern);
870 /**
871 * Concat a single date pattern with a time interval pattern,
872 * set it into the intervalPatterns, while field is time field.
873 * This is used to handle time interval patterns on skeleton with
874 * both time and date. Present the date followed by
875 * the range expression for the time.
876 * @param format date and time format
877 * @param formatLen format string length
878 * @param datePattern date pattern
879 * @param field time calendar field: AM_PM, HOUR, MINUTE
880 * @param status output param set to success/failure code on exit
881 */
882 void concatSingleDate2TimeInterval(const UChar* format,
883 int32_t formatLen,
884 const UnicodeString& datePattern,
885 UCalendarDateFields field,
886 UErrorCode& status);
888 /**
889 * check whether a calendar field present in a skeleton.
890 * @param field calendar field need to check
891 * @param skeleton given skeleton on which to check the calendar field
892 * @return true if field present in a skeleton.
893 */
894 static UBool U_EXPORT2 fieldExistsInSkeleton(UCalendarDateFields field,
895 const UnicodeString& skeleton);
898 /**
899 * Split interval patterns into 2 part.
900 * @param intervalPattern interval pattern
901 * @return the index in interval pattern which split the pattern into 2 part
902 */
903 static int32_t U_EXPORT2 splitPatternInto2Part(const UnicodeString& intervalPattern);
906 /**
907 * Break interval patterns as 2 part and save them into pattern info.
908 * @param field calendar field
909 * @param intervalPattern interval pattern
910 */
911 void setIntervalPattern(UCalendarDateFields field,
912 const UnicodeString& intervalPattern);
915 /**
916 * Break interval patterns as 2 part and save them into pattern info.
917 * @param field calendar field
918 * @param intervalPattern interval pattern
919 * @param laterDateFirst whether later date appear first in interval pattern
920 */
921 void setIntervalPattern(UCalendarDateFields field,
922 const UnicodeString& intervalPattern,
923 UBool laterDateFirst);
926 /**
927 * Set pattern information.
928 *
929 * @param field calendar field
930 * @param firstPart the first part in interval pattern
931 * @param secondPart the second part in interval pattern
932 * @param laterDateFirst whether the first date in intervalPattern
933 * is earlier date or later date
934 */
935 void setPatternInfo(UCalendarDateFields field,
936 const UnicodeString* firstPart,
937 const UnicodeString* secondPart,
938 UBool laterDateFirst);
941 // from calendar field to pattern letter
942 static const UChar fgCalendarFieldToPatternLetter[];
945 /**
946 * The interval patterns for this locale.
947 */
948 DateIntervalInfo* fInfo;
950 /**
951 * The DateFormat object used to format single pattern
952 */
953 SimpleDateFormat* fDateFormat;
955 /**
956 * The 2 calendars with the from and to date.
957 * could re-use the calendar in fDateFormat,
958 * but keeping 2 calendars make it clear and clean.
959 */
960 Calendar* fFromCalendar;
961 Calendar* fToCalendar;
963 /**
964 * Date time pattern generator
965 */
966 DateTimePatternGenerator* fDtpng;
968 /**
969 * Following are interval information relavent (locale) to this formatter.
970 */
971 UnicodeString fSkeleton;
972 PatternInfo fIntervalPatterns[DateIntervalInfo::kIPI_MAX_INDEX];
973 };
975 inline UBool
976 DateIntervalFormat::operator!=(const Format& other) const {
977 return !operator==(other);
978 }
980 U_NAMESPACE_END
982 #endif /* #if !UCONFIG_NO_FORMATTING */
984 #endif // _DTITVFMT_H__
985 //eof
