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