Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/udateintervalformat.h @ 69:33d812a61356

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