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