annotate modules/javafx.web/src/main/native/Source/ThirdParty/icu/source/i18n/unicode/udateintervalformat.h @ 11038:20a8447c71c6

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