1/*
2*****************************************************************************************
3* Copyright (C) 2010-2012, International Business Machines
4* Corporation and others. All Rights Reserved.
5*****************************************************************************************
6*/
7
8#ifndef UDATEINTERVALFORMAT_H
9#define UDATEINTERVALFORMAT_H
10
11#include "unicode/utypes.h"
12
13#if !UCONFIG_NO_FORMATTING
14
15#include "unicode/umisc.h"
16#include "unicode/localpointer.h"
17
18/**
19 * \file
20 * \brief C API: Format a date interval.
21 *
22 * A UDateIntervalFormat is used to format the range between two UDate values
23 * in a locale-sensitive way, using a skeleton that specifies the precision and
24 * completeness of the information to show. If the range smaller than the resolution
25 * specified by the skeleton, a single date format will be produced. If the range
26 * is larger than the format specified by the skeleton, a locale-specific fallback
27 * will be used to format the items missing from the skeleton.
28 *
29 * For example, if the range is 2010-03-04 07:56 - 2010-03-04 19:56 (12 hours)
30 * - The skeleton jm will produce
31 *   for en_US, "7:56 AM - 7:56 PM"
32 *   for en_GB, "7:56 - 19:56"
33 * - The skeleton MMMd will produce
34 *   for en_US, "Mar 4"
35 *   for en_GB, "4 Mar"
36 * If the range is 2010-03-04 07:56 - 2010-03-08 16:11 (4 days, 8 hours, 15 minutes)
37 * - The skeleton jm will produce
38 *   for en_US, "3/4/2010 7:56 AM - 3/8/2010 4:11 PM"
39 *   for en_GB, "4/3/2010 7:56 - 8/3/2010 16:11"
40 * - The skeleton MMMd will produce
41 *   for en_US, "Mar 4-8"
42 *   for en_GB, "4-8 Mar"
43 *
44 * Note:  the "-" characters in the above sample output will actually be
45 * Unicode 2013, EN_DASH, in all but the last example.
46 *
47 * Note, in ICU 4.4 the standard skeletons for which date interval format data
48 * is usually available are as follows; best results will be obtained by using
49 * skeletons from this set, or those formed by combining these standard skeletons
50 * (note that for these skeletons, the length of digit field such as d, y, or
51 * M vs MM is irrelevant (but for non-digit fields such as MMM vs MMMM it is
52 * relevant). Note that a skeleton involving h or H generally explicitly requests
53 * that time style (12- or 24-hour time respectively). For a skeleton that
54 * requests the locale's default time style (h or H), use 'j' instead of h or H.
55 *   h, H, hm, Hm,
56 *   hv, Hv, hmv, Hmv,
57 *   d,
58 *   M, MMM, MMMM,
59 *   Md, MMMd,
60 *   MEd, MMMEd,
61 *   y,
62 *   yM, yMMM, yMMMM,
63 *   yMd, yMMMd,
64 *   yMEd, yMMMEd
65 *
66 * Locales for which ICU 4.4 seems to have a reasonable amount of this data
67 * include:
68 *   af, am, ar, be, bg, bn, ca, cs, da, de (_AT), el, en (_AU,_CA,_GB,_IE,_IN...),
69 *   eo, es (_AR,_CL,_CO,...,_US) et, fa, fi, fo, fr (_BE,_CH,_CA), fur, gsw, he,
70 *   hr, hu, hy, is, it (_CH), ja, kk, km, ko, lt, lv, mk, ml, mt, nb, nl )_BE),
71 *   nn, pl, pt (_PT), rm, ro, ru (_UA), sk, sl, so, sq, sr, sr_Latn, sv, th, to,
72 *   tr, uk, ur, vi, zh (_SG), zh_Hant (_HK,_MO)
73 */
74
75/**
76 * Opaque UDateIntervalFormat object for use in C programs.
77 * @stable ICU 4.8
78 */
79struct UDateIntervalFormat;
80typedef struct UDateIntervalFormat UDateIntervalFormat;  /**< C typedef for struct UDateIntervalFormat. @stable ICU 4.8 */
81
82/**
83 * Open a new UDateIntervalFormat object using the predefined rules for a
84 * given locale plus a specified skeleton.
85 * @param locale
86 *            The locale for whose rules should be used; may be NULL for
87 *            default locale.
88 * @param skeleton
89 *            A pattern containing only the fields desired for the interval
90 *            format, for example "Hm", "yMMMd", or "yMMMEdHm".
91 * @param skeletonLength
92 *            The length of skeleton; may be -1 if the skeleton is zero-terminated.
93 * @param tzID
94 *            A timezone ID specifying the timezone to use. If 0, use the default
95 *            timezone.
96 * @param tzIDLength
97 *            The length of tzID, or -1 if null-terminated. If 0, use the default
98 *            timezone.
99 * @param status
100 *            A pointer to a UErrorCode to receive any errors.
101 * @return
102 *            A pointer to a UDateIntervalFormat object for the specified locale,
103 *            or NULL if an error occurred.
104 * @stable ICU 4.8
105 */
106U_STABLE UDateIntervalFormat* U_EXPORT2
107udtitvfmt_open(const char*  locale,
108              const UChar* skeleton,
109              int32_t      skeletonLength,
110              const UChar* tzID,
111              int32_t      tzIDLength,
112              UErrorCode*  status);
113
114/**
115 * Close a UDateIntervalFormat object. Once closed it may no longer be used.
116 * @param formatter
117 *            The UDateIntervalFormat object to close.
118 * @stable ICU 4.8
119 */
120U_STABLE void U_EXPORT2
121udtitvfmt_close(UDateIntervalFormat *formatter);
122
123
124#if U_SHOW_CPLUSPLUS_API
125
126U_NAMESPACE_BEGIN
127
128/**
129 * \class LocalUDateIntervalFormatPointer
130 * "Smart pointer" class, closes a UDateIntervalFormat via udtitvfmt_close().
131 * For most methods see the LocalPointerBase base class.
132 *
133 * @see LocalPointerBase
134 * @see LocalPointer
135 * @stable ICU 4.8
136 */
137U_DEFINE_LOCAL_OPEN_POINTER(LocalUDateIntervalFormatPointer, UDateIntervalFormat, udtitvfmt_close);
138
139U_NAMESPACE_END
140
141#endif
142
143
144/**
145 * Formats a date/time range using the conventions established for the
146 * UDateIntervalFormat object.
147 * @param formatter
148 *            The UDateIntervalFormat object specifying the format conventions.
149 * @param fromDate
150 *            The starting point of the range.
151 * @param toDate
152 *            The ending point of the range.
153 * @param result
154 *            A pointer to a buffer to receive the formatted range.
155 * @param resultCapacity
156 *            The maximum size of result.
157 * @param position
158 *            A pointer to a UFieldPosition. On input, position->field is read.
159 *            On output, position->beginIndex and position->endIndex indicate
160 *            the beginning and ending indices of field number position->field,
161 *            if such a field exists. This parameter may be NULL, in which case
162 *            no field position data is returned.
163 * @param status
164 *            A pointer to a UErrorCode to receive any errors.
165 * @return
166 *            The total buffer size needed; if greater than resultLength, the
167 *            output was truncated.
168 * @stable ICU 4.8
169 */
170U_STABLE int32_t U_EXPORT2
171udtitvfmt_format(const UDateIntervalFormat* formatter,
172                UDate           fromDate,
173                UDate           toDate,
174                UChar*          result,
175                int32_t         resultCapacity,
176                UFieldPosition* position,
177                UErrorCode*     status);
178
179#endif /* #if !UCONFIG_NO_FORMATTING */
180
181#endif
182