1 // © 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
3 /*
4 *****************************************************************************************
5 * Copyright (C) 2010-2012,2015 International Business Machines
6 * Corporation and others. All Rights Reserved.
7 *****************************************************************************************
8 */
9 
10 #ifndef UDATEINTERVALFORMAT_H
11 #define UDATEINTERVALFORMAT_H
12 
13 #include "unicode/utypes.h"
14 
15 #if !UCONFIG_NO_FORMATTING
16 
17 #include "unicode/ucal.h"
18 #include "unicode/umisc.h"
19 #include "unicode/uformattedvalue.h"
20 #include "unicode/udisplaycontext.h"
21 
22 #if U_SHOW_CPLUSPLUS_API
23 #include "unicode/localpointer.h"
24 #endif   // U_SHOW_CPLUSPLUS_API
25 
26 /**
27  * \file
28  * \brief C API: Format a date interval.
29  *
30  * A UDateIntervalFormat is used to format the range between two UDate values
31  * in a locale-sensitive way, using a skeleton that specifies the precision and
32  * completeness of the information to show. If the range smaller than the resolution
33  * specified by the skeleton, a single date format will be produced. If the range
34  * is larger than the format specified by the skeleton, a locale-specific fallback
35  * will be used to format the items missing from the skeleton.
36  *
37  * For example, if the range is 2010-03-04 07:56 - 2010-03-04 19:56 (12 hours)
38  * - The skeleton jm will produce
39  *   for en_US, "7:56 AM - 7:56 PM"
40  *   for en_GB, "7:56 - 19:56"
41  * - The skeleton MMMd will produce
42  *   for en_US, "Mar 4"
43  *   for en_GB, "4 Mar"
44  * If the range is 2010-03-04 07:56 - 2010-03-08 16:11 (4 days, 8 hours, 15 minutes)
45  * - The skeleton jm will produce
46  *   for en_US, "3/4/2010 7:56 AM - 3/8/2010 4:11 PM"
47  *   for en_GB, "4/3/2010 7:56 - 8/3/2010 16:11"
48  * - The skeleton MMMd will produce
49  *   for en_US, "Mar 4-8"
50  *   for en_GB, "4-8 Mar"
51  *
52  * Note:  the "-" characters in the above sample output will actually be
53  * Unicode 2013, EN_DASH, in all but the last example.
54  *
55  * Note, in ICU 4.4 the standard skeletons for which date interval format data
56  * is usually available are as follows; best results will be obtained by using
57  * skeletons from this set, or those formed by combining these standard skeletons
58  * (note that for these skeletons, the length of digit field such as d, y, or
59  * M vs MM is irrelevant (but for non-digit fields such as MMM vs MMMM it is
60  * relevant). Note that a skeleton involving h or H generally explicitly requests
61  * that time style (12- or 24-hour time respectively). For a skeleton that
62  * requests the locale's default time style (h or H), use 'j' instead of h or H.
63  *   h, H, hm, Hm,
64  *   hv, Hv, hmv, Hmv,
65  *   d,
66  *   M, MMM, MMMM,
67  *   Md, MMMd,
68  *   MEd, MMMEd,
69  *   y,
70  *   yM, yMMM, yMMMM,
71  *   yMd, yMMMd,
72  *   yMEd, yMMMEd
73  *
74  * Locales for which ICU 4.4 seems to have a reasonable amount of this data
75  * include:
76  *   af, am, ar, be, bg, bn, ca, cs, da, de (_AT), el, en (_AU,_CA,_GB,_IE,_IN...),
77  *   eo, es (_AR,_CL,_CO,...,_US) et, fa, fi, fo, fr (_BE,_CH,_CA), fur, gsw, he,
78  *   hr, hu, hy, is, it (_CH), ja, kk, km, ko, lt, lv, mk, ml, mt, nb, nl )_BE),
79  *   nn, pl, pt (_PT), rm, ro, ru (_UA), sk, sl, so, sq, sr, sr_Latn, sv, th, to,
80  *   tr, uk, ur, vi, zh (_SG), zh_Hant (_HK,_MO)
81  */
82 
83 /**
84  * Opaque UDateIntervalFormat object for use in C programs.
85  * @stable ICU 4.8
86  */
87 struct UDateIntervalFormat;
88 typedef struct UDateIntervalFormat UDateIntervalFormat;  /**< C typedef for struct UDateIntervalFormat. @stable ICU 4.8 */
89 
90 struct UFormattedDateInterval;
91 /**
92  * Opaque struct to contain the results of a UDateIntervalFormat operation.
93  * @stable ICU 64
94  */
95 typedef struct UFormattedDateInterval UFormattedDateInterval;
96 
97 /**
98  * Open a new UDateIntervalFormat object using the predefined rules for a
99  * given locale plus a specified skeleton.
100  * @param locale
101  *            The locale for whose rules should be used; may be NULL for
102  *            default locale.
103  * @param skeleton
104  *            A pattern containing only the fields desired for the interval
105  *            format, for example "Hm", "yMMMd", or "yMMMEdHm".
106  * @param skeletonLength
107  *            The length of skeleton; may be -1 if the skeleton is zero-terminated.
108  * @param tzID
109  *            A timezone ID specifying the timezone to use. If 0, use the default
110  *            timezone.
111  * @param tzIDLength
112  *            The length of tzID, or -1 if null-terminated. If 0, use the default
113  *            timezone.
114  * @param status
115  *            A pointer to a UErrorCode to receive any errors.
116  * @return
117  *            A pointer to a UDateIntervalFormat object for the specified locale,
118  *            or NULL if an error occurred.
119  * @stable ICU 4.8
120  */
121 U_CAPI UDateIntervalFormat* U_EXPORT2
122 udtitvfmt_open(const char*  locale,
123               const UChar* skeleton,
124               int32_t      skeletonLength,
125               const UChar* tzID,
126               int32_t      tzIDLength,
127               UErrorCode*  status);
128 
129 /**
130  * Close a UDateIntervalFormat object. Once closed it may no longer be used.
131  * @param formatter
132  *            The UDateIntervalFormat object to close.
133  * @stable ICU 4.8
134  */
135 U_CAPI void U_EXPORT2
136 udtitvfmt_close(UDateIntervalFormat *formatter);
137 
138 /**
139  * Creates an object to hold the result of a UDateIntervalFormat
140  * operation. The object can be used repeatedly; it is cleared whenever
141  * passed to a format function.
142  *
143  * @param ec Set if an error occurs.
144  * @return A pointer needing ownership.
145  * @stable ICU 64
146  */
147 U_CAPI UFormattedDateInterval* U_EXPORT2
148 udtitvfmt_openResult(UErrorCode* ec);
149 
150 /**
151  * Returns a representation of a UFormattedDateInterval as a UFormattedValue,
152  * which can be subsequently passed to any API requiring that type.
153  *
154  * The returned object is owned by the UFormattedDateInterval and is valid
155  * only as long as the UFormattedDateInterval is present and unchanged in memory.
156  *
157  * You can think of this method as a cast between types.
158  *
159  * When calling ufmtval_nextPosition():
160  * The fields are returned from left to right. The special field category
161  * UFIELD_CATEGORY_DATE_INTERVAL_SPAN is used to indicate which datetime
162  * primitives came from which arguments: 0 means fromCalendar, and 1 means
163  * toCalendar. The span category will always occur before the
164  * corresponding fields in UFIELD_CATEGORY_DATE
165  * in the ufmtval_nextPosition() iterator.
166  *
167  * @param uresult The object containing the formatted string.
168  * @param ec Set if an error occurs.
169  * @return A UFormattedValue owned by the input object.
170  * @stable ICU 64
171  */
172 U_CAPI const UFormattedValue* U_EXPORT2
173 udtitvfmt_resultAsValue(const UFormattedDateInterval* uresult, UErrorCode* ec);
174 
175 /**
176  * Releases the UFormattedDateInterval created by udtitvfmt_openResult().
177  *
178  * @param uresult The object to release.
179  * @stable ICU 64
180  */
181 U_CAPI void U_EXPORT2
182 udtitvfmt_closeResult(UFormattedDateInterval* uresult);
183 
184 
185 #if U_SHOW_CPLUSPLUS_API
186 
187 U_NAMESPACE_BEGIN
188 
189 /**
190  * \class LocalUDateIntervalFormatPointer
191  * "Smart pointer" class, closes a UDateIntervalFormat via udtitvfmt_close().
192  * For most methods see the LocalPointerBase base class.
193  *
194  * @see LocalPointerBase
195  * @see LocalPointer
196  * @stable ICU 4.8
197  */
198 U_DEFINE_LOCAL_OPEN_POINTER(LocalUDateIntervalFormatPointer, UDateIntervalFormat, udtitvfmt_close);
199 
200 /**
201  * \class LocalUFormattedDateIntervalPointer
202  * "Smart pointer" class, closes a UFormattedDateInterval via udtitvfmt_close().
203  * For most methods see the LocalPointerBase base class.
204  *
205  * @see LocalPointerBase
206  * @see LocalPointer
207  * @stable ICU 64
208  */
209 U_DEFINE_LOCAL_OPEN_POINTER(LocalUFormattedDateIntervalPointer, UFormattedDateInterval, udtitvfmt_closeResult);
210 
211 U_NAMESPACE_END
212 
213 #endif
214 
215 
216 /**
217  * Formats a date/time range using the conventions established for the
218  * UDateIntervalFormat object.
219  * @param formatter
220  *            The UDateIntervalFormat object specifying the format conventions.
221  * @param fromDate
222  *            The starting point of the range.
223  * @param toDate
224  *            The ending point of the range.
225  * @param result
226  *            A pointer to a buffer to receive the formatted range.
227  * @param resultCapacity
228  *            The maximum size of result.
229  * @param position
230  *            A pointer to a UFieldPosition. On input, position->field is read.
231  *            On output, position->beginIndex and position->endIndex indicate
232  *            the beginning and ending indices of field number position->field,
233  *            if such a field exists. This parameter may be NULL, in which case
234  *            no field position data is returned.
235  *            There may be multiple instances of a given field type in an
236  *            interval format; in this case the position indices refer to the
237  *            first instance.
238  * @param status
239  *            A pointer to a UErrorCode to receive any errors.
240  * @return
241  *            The total buffer size needed; if greater than resultLength, the
242  *            output was truncated.
243  * @stable ICU 4.8
244  */
245 U_CAPI int32_t U_EXPORT2
246 udtitvfmt_format(const UDateIntervalFormat* formatter,
247                 UDate           fromDate,
248                 UDate           toDate,
249                 UChar*          result,
250                 int32_t         resultCapacity,
251                 UFieldPosition* position,
252                 UErrorCode*     status);
253 
254 
255 #ifndef U_HIDE_DRAFT_API
256 /**
257  * Formats a date/time range using the conventions established for the
258  * UDateIntervalFormat object.
259  * @param formatter
260  *            The UDateIntervalFormat object specifying the format conventions.
261  * @param fromDate
262  *            The starting point of the range.
263  * @param toDate
264  *            The ending point of the range.
265  * @param result
266  *            The UFormattedDateInterval to contain the result of the
267  *            formatting operation.
268  * @param status
269  *            A pointer to a UErrorCode to receive any errors.
270  * @draft ICU 67
271  */
272 U_CAPI void U_EXPORT2
273 udtitvfmt_formatToResult(
274                 const UDateIntervalFormat* formatter,
275                 UDate           fromDate,
276                 UDate           toDate,
277                 UFormattedDateInterval* result,
278                 UErrorCode*     status);
279 
280 /**
281  * Formats a date/time range using the conventions established for the
282  * UDateIntervalFormat object.
283  * @param formatter
284  *            The UDateIntervalFormat object specifying the format conventions.
285  * @param fromCalendar
286  *            The starting point of the range.
287  * @param toCalendar
288  *            The ending point of the range.
289  * @param result
290  *            The UFormattedDateInterval to contain the result of the
291  *            formatting operation.
292  * @param status
293  *            A pointer to a UErrorCode to receive any errors.
294  * @draft ICU 67
295  */
296 
297 U_CAPI void U_EXPORT2
298 udtitvfmt_formatCalendarToResult(
299                 const UDateIntervalFormat* formatter,
300                 UCalendar*      fromCalendar,
301                 UCalendar*      toCalendar,
302                 UFormattedDateInterval* result,
303                 UErrorCode*     status);
304 #endif /* U_HIDE_DRAFT_API */
305 
306 #ifndef U_HIDE_DRAFT_API
307 /**
308  * Set a particular UDisplayContext value in the formatter, such as
309  * UDISPCTX_CAPITALIZATION_FOR_STANDALONE. This causes the formatted
310  * result to be capitalized appropriately for the context in which
311  * it is intended to be used, considering both the locale and the
312  * type of field at the beginning of the formatted result.
313  * @param formatter The formatter for which to set a UDisplayContext value.
314  * @param value The UDisplayContext value to set.
315  * @param status A pointer to an UErrorCode to receive any errors
316  * @draft ICU 68
317  */
318 U_CAPI void U_EXPORT2
319 udtitvfmt_setContext(UDateIntervalFormat* formatter, UDisplayContext value, UErrorCode* status);
320 
321 /**
322  * Get the formatter's UDisplayContext value for the specified UDisplayContextType,
323  * such as UDISPCTX_TYPE_CAPITALIZATION.
324  * @param formatter The formatter to query.
325  * @param type The UDisplayContextType whose value to return
326  * @param status A pointer to an UErrorCode to receive any errors
327  * @return The UDisplayContextValue for the specified type.
328  * @draft ICU 68
329  */
330 U_CAPI UDisplayContext U_EXPORT2
331 udtitvfmt_getContext(const UDateIntervalFormat* formatter, UDisplayContextType type, UErrorCode* status);
332 
333 #endif /* U_HIDE_DRAFT_API */
334 
335 #endif /* #if !UCONFIG_NO_FORMATTING */
336 
337 #endif
338