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 */ 82 struct UDateIntervalFormat; 83 typedef struct UDateIntervalFormat UDateIntervalFormat; /**< C typedef for struct UDateIntervalFormat. @stable ICU 4.8 */ 84 85 #ifndef U_HIDE_DRAFT_API 86 struct UFormattedDateInterval; 87 /** 88 * Opaque struct to contain the results of a UDateIntervalFormat operation. 89 * @draft ICU 64 90 */ 91 typedef 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 */ 118 U_STABLE UDateIntervalFormat* U_EXPORT2 119 udtitvfmt_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 */ 132 U_STABLE void U_EXPORT2 133 udtitvfmt_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 */ 146 U_CAPI UFormattedDateInterval* U_EXPORT2 147 udtitvfmt_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 */ 171 U_CAPI const UFormattedValue* U_EXPORT2 172 udtitvfmt_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 */ 180 U_CAPI void U_EXPORT2 181 udtitvfmt_closeResult(UFormattedDateInterval* uresult); 182 #endif /* U_HIDE_DRAFT_API */ 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 #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 */ 210 U_DEFINE_LOCAL_OPEN_POINTER(LocalUFormattedDateIntervalPointer, UFormattedDateInterval, udtitvfmt_closeResult); 211 #endif /* U_HIDE_DRAFT_API */ 212 213 U_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 */ 247 U_STABLE int32_t U_EXPORT2 248 udtitvfmt_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 */ 274 U_DRAFT void U_EXPORT2 275 udtitvfmt_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