codekingpro/portable-devtools

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