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 */ 79 struct UDateIntervalFormat; 80 typedef 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 */ 106 U_STABLE UDateIntervalFormat* U_EXPORT2 107 udtitvfmt_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 */ 120 U_STABLE void U_EXPORT2 121 udtitvfmt_close(UDateIntervalFormat *formatter); 122 123 124 #if U_SHOW_CPLUSPLUS_API 125 126 U_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 */ 137 U_DEFINE_LOCAL_OPEN_POINTER(LocalUDateIntervalFormatPointer, UDateIntervalFormat, udtitvfmt_close); 138 139 U_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 */ 170 U_STABLE int32_t U_EXPORT2 171 udtitvfmt_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
