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