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 */ 83 struct UDateIntervalFormat; 84 typedef struct UDateIntervalFormat UDateIntervalFormat; /**< C typedef for struct UDateIntervalFormat. @stable ICU 4.8 */ 85 86 struct UFormattedDateInterval; 87 /** 88 * Opaque struct to contain the results of a UDateIntervalFormat operation. 89 * @stable ICU 64 90 */ 91 typedef 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 */ 117 U_STABLE UDateIntervalFormat* U_EXPORT2 118 udtitvfmt_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 */ 131 U_STABLE void U_EXPORT2 132 udtitvfmt_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 */ 143 U_CAPI UFormattedDateInterval* U_EXPORT2 144 udtitvfmt_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 */ 168 U_CAPI const UFormattedValue* U_EXPORT2 169 udtitvfmt_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 */ 177 U_CAPI void U_EXPORT2 178 udtitvfmt_closeResult(UFormattedDateInterval* uresult); 179 180 181 #if U_SHOW_CPLUSPLUS_API 182 183 U_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 */ 194 U_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 */ 205 U_DEFINE_LOCAL_OPEN_POINTER(LocalUFormattedDateIntervalPointer, UFormattedDateInterval, udtitvfmt_closeResult); 206 207 U_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 */ 241 U_STABLE int32_t U_EXPORT2 242 udtitvfmt_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 */ 268 U_DRAFT void U_EXPORT2 269 udtitvfmt_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 293 U_DRAFT void U_EXPORT2 294 udtitvfmt_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