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