The Tor Browser / file comparison
comparison: intl/icu/source/i18n/unicode/udateintervalformat.h
intl/icu/source/i18n/unicode/udateintervalformat.h
- changeset 0
- 6474c204b198
equal
deleted
inserted
replaced
| -1:000000000000 | 0:16e35e06785d |
|---|---|
| 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 |
