ulistformatter.h (11043B)
1 // © 2016 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 /* 4 ***************************************************************************************** 5 * Copyright (C) 2015-2016, International Business Machines 6 * Corporation and others. All Rights Reserved. 7 ***************************************************************************************** 8 */ 9 10 #ifndef ULISTFORMATTER_H 11 #define ULISTFORMATTER_H 12 13 #include "unicode/utypes.h" 14 15 #if !UCONFIG_NO_FORMATTING 16 17 #include "unicode/uformattedvalue.h" 18 19 #if U_SHOW_CPLUSPLUS_API 20 #include "unicode/localpointer.h" 21 #endif // U_SHOW_CPLUSPLUS_API 22 23 /** 24 * \file 25 * \brief C API: Format a list in a locale-appropriate way. 26 * 27 * A UListFormatter is used to format a list of items in a locale-appropriate way, 28 * using data from CLDR. 29 * Example: Input data ["Alice", "Bob", "Charlie", "Delta"] will be formatted 30 * as "Alice, Bob, Charlie, and Delta" in English. 31 */ 32 33 /** 34 * Opaque UListFormatter object for use in C 35 * @stable ICU 55 36 */ 37 struct UListFormatter; 38 typedef struct UListFormatter UListFormatter; /**< C typedef for struct UListFormatter. @stable ICU 55 */ 39 40 struct UFormattedList; 41 /** 42 * Opaque struct to contain the results of a UListFormatter operation. 43 * @stable ICU 64 44 */ 45 typedef struct UFormattedList UFormattedList; 46 47 /** 48 * FieldPosition and UFieldPosition selectors for format fields 49 * defined by ListFormatter. 50 * @stable ICU 63 51 */ 52 typedef enum UListFormatterField { 53 /** 54 * The literal text in the result which came from the resources. 55 * @stable ICU 63 56 */ 57 ULISTFMT_LITERAL_FIELD, 58 /** 59 * The element text in the result which came from the input strings. 60 * @stable ICU 63 61 */ 62 ULISTFMT_ELEMENT_FIELD 63 } UListFormatterField; 64 65 /** 66 * Type of meaning expressed by the list. 67 * 68 * @stable ICU 67 69 */ 70 typedef enum UListFormatterType { 71 /** 72 * Conjunction formatting, e.g. "Alice, Bob, Charlie, and Delta". 73 * 74 * @stable ICU 67 75 */ 76 ULISTFMT_TYPE_AND, 77 78 /** 79 * Disjunction (or alternative, or simply one of) formatting, e.g. 80 * "Alice, Bob, Charlie, or Delta". 81 * 82 * @stable ICU 67 83 */ 84 ULISTFMT_TYPE_OR, 85 86 /** 87 * Formatting of a list of values with units, e.g. "5 pounds, 12 ounces". 88 * 89 * @stable ICU 67 90 */ 91 ULISTFMT_TYPE_UNITS 92 } UListFormatterType; 93 94 /** 95 * Verbosity level of the list patterns. 96 * 97 * @stable ICU 67 98 */ 99 typedef enum UListFormatterWidth { 100 /** 101 * Use list formatting with full words (no abbreviations) when possible. 102 * 103 * @stable ICU 67 104 */ 105 ULISTFMT_WIDTH_WIDE, 106 107 /** 108 * Use list formatting of typical length. 109 * @stable ICU 67 110 */ 111 ULISTFMT_WIDTH_SHORT, 112 113 /** 114 * Use list formatting of the shortest possible length. 115 * @stable ICU 67 116 */ 117 ULISTFMT_WIDTH_NARROW, 118 } UListFormatterWidth; 119 120 /** 121 * Open a new UListFormatter object using the rules for a given locale. 122 * The object will be initialized with AND type and WIDE width. 123 * 124 * @param locale 125 * The locale whose rules should be used; may be NULL for 126 * default locale. 127 * @param status 128 * A pointer to a standard ICU UErrorCode (input/output parameter). 129 * Its input value must pass the U_SUCCESS() test, or else the 130 * function returns immediately. The caller should check its output 131 * value with U_FAILURE(), or use with function chaining (see User 132 * Guide for details). 133 * @return 134 * A pointer to a UListFormatter object for the specified locale, 135 * or NULL if an error occurred. 136 * @stable ICU 55 137 */ 138 U_CAPI UListFormatter* U_EXPORT2 139 ulistfmt_open(const char* locale, 140 UErrorCode* status); 141 142 /** 143 * Open a new UListFormatter object appropriate for the given locale, list type, 144 * and style. 145 * 146 * @param locale 147 * The locale whose rules should be used; may be NULL for 148 * default locale. 149 * @param type 150 * The type of list formatting to use. 151 * @param width 152 * The width of formatting to use. 153 * @param status 154 * A pointer to a standard ICU UErrorCode (input/output parameter). 155 * Its input value must pass the U_SUCCESS() test, or else the 156 * function returns immediately. The caller should check its output 157 * value with U_FAILURE(), or use with function chaining (see User 158 * Guide for details). 159 * @return 160 * A pointer to a UListFormatter object for the specified locale, 161 * or NULL if an error occurred. 162 * @stable ICU 67 163 */ 164 U_CAPI UListFormatter* U_EXPORT2 165 ulistfmt_openForType(const char* locale, UListFormatterType type, 166 UListFormatterWidth width, UErrorCode* status); 167 168 /** 169 * Close a UListFormatter object. Once closed it may no longer be used. 170 * @param listfmt 171 * The UListFormatter object to close. 172 * @stable ICU 55 173 */ 174 U_CAPI void U_EXPORT2 175 ulistfmt_close(UListFormatter *listfmt); 176 177 /** 178 * Creates an object to hold the result of a UListFormatter 179 * operation. The object can be used repeatedly; it is cleared whenever 180 * passed to a format function. 181 * 182 * @param ec Set if an error occurs. 183 * @return A pointer needing ownership. 184 * @stable ICU 64 185 */ 186 U_CAPI UFormattedList* U_EXPORT2 187 ulistfmt_openResult(UErrorCode* ec); 188 189 /** 190 * Returns a representation of a UFormattedList as a UFormattedValue, 191 * which can be subsequently passed to any API requiring that type. 192 * 193 * The returned object is owned by the UFormattedList and is valid 194 * only as long as the UFormattedList is present and unchanged in memory. 195 * 196 * You can think of this method as a cast between types. 197 * 198 * When calling ufmtval_nextPosition(): 199 * The fields are returned from start to end. The special field category 200 * UFIELD_CATEGORY_LIST_SPAN is used to indicate which argument 201 * was inserted at the given position. The span category will 202 * always occur before the corresponding instance of UFIELD_CATEGORY_LIST 203 * in the ufmtval_nextPosition() iterator. 204 * 205 * @param uresult The object containing the formatted string. 206 * @param ec Set if an error occurs. 207 * @return A UFormattedValue owned by the input object. 208 * @stable ICU 64 209 */ 210 U_CAPI const UFormattedValue* U_EXPORT2 211 ulistfmt_resultAsValue(const UFormattedList* uresult, UErrorCode* ec); 212 213 /** 214 * Releases the UFormattedList created by ulistfmt_openResult(). 215 * 216 * @param uresult The object to release. 217 * @stable ICU 64 218 */ 219 U_CAPI void U_EXPORT2 220 ulistfmt_closeResult(UFormattedList* uresult); 221 222 223 #if U_SHOW_CPLUSPLUS_API 224 225 U_NAMESPACE_BEGIN 226 227 /** 228 * \class LocalUListFormatterPointer 229 * "Smart pointer" class, closes a UListFormatter via ulistfmt_close(). 230 * For most methods see the LocalPointerBase base class. 231 * 232 * @see LocalPointerBase 233 * @see LocalPointer 234 * @stable ICU 55 235 */ 236 U_DEFINE_LOCAL_OPEN_POINTER(LocalUListFormatterPointer, UListFormatter, ulistfmt_close); 237 238 /** 239 * \class LocalUFormattedListPointer 240 * "Smart pointer" class, closes a UFormattedList via ulistfmt_closeResult(). 241 * For most methods see the LocalPointerBase base class. 242 * 243 * @see LocalPointerBase 244 * @see LocalPointer 245 * @stable ICU 64 246 */ 247 U_DEFINE_LOCAL_OPEN_POINTER(LocalUFormattedListPointer, UFormattedList, ulistfmt_closeResult); 248 249 U_NAMESPACE_END 250 251 #endif 252 253 /** 254 * Formats a list of strings using the conventions established for the 255 * UListFormatter object. 256 * @param listfmt 257 * The UListFormatter object specifying the list conventions. 258 * @param strings 259 * An array of pointers to UChar strings; the array length is 260 * specified by stringCount. Must be non-NULL if stringCount > 0. 261 * @param stringLengths 262 * An array of string lengths corresponding to the strings[] 263 * parameter; any individual length value may be negative to indicate 264 * that the corresponding strings[] entry is 0-terminated, or 265 * stringLengths itself may be NULL if all of the strings are 266 * 0-terminated. If non-NULL, the stringLengths array must have 267 * stringCount entries. 268 * @param stringCount 269 * the number of entries in strings[], and the number of entries 270 * in the stringLengths array if it is not NULL. Must be >= 0. 271 * @param result 272 * A pointer to a buffer to receive the formatted list. 273 * @param resultCapacity 274 * The maximum size of result. 275 * @param status 276 * A pointer to a standard ICU UErrorCode (input/output parameter). 277 * Its input value must pass the U_SUCCESS() test, or else the 278 * function returns immediately. The caller should check its output 279 * value with U_FAILURE(), or use with function chaining (see User 280 * Guide for details). 281 * @return 282 * The total buffer size needed; if greater than resultLength, the 283 * output was truncated. May be <=0 if unable to determine the 284 * total buffer size needed (e.g. for illegal arguments). 285 * @stable ICU 55 286 */ 287 U_CAPI int32_t U_EXPORT2 288 ulistfmt_format(const UListFormatter* listfmt, 289 const UChar* const strings[], 290 const int32_t * stringLengths, 291 int32_t stringCount, 292 UChar* result, 293 int32_t resultCapacity, 294 UErrorCode* status); 295 296 /** 297 * Formats a list of strings to a UFormattedList, which exposes more 298 * information than the string exported by ulistfmt_format(). 299 * 300 * @param listfmt 301 * The UListFormatter object specifying the list conventions. 302 * @param strings 303 * An array of pointers to UChar strings; the array length is 304 * specified by stringCount. Must be non-NULL if stringCount > 0. 305 * @param stringLengths 306 * An array of string lengths corresponding to the strings[] 307 * parameter; any individual length value may be negative to indicate 308 * that the corresponding strings[] entry is 0-terminated, or 309 * stringLengths itself may be NULL if all of the strings are 310 * 0-terminated. If non-NULL, the stringLengths array must have 311 * stringCount entries. 312 * @param stringCount 313 * the number of entries in strings[], and the number of entries 314 * in the stringLengths array if it is not NULL. Must be >= 0. 315 * @param uresult 316 * The object in which to store the result of the list formatting 317 * operation. See ulistfmt_openResult(). 318 * @param status 319 * Error code set if an error occurred during formatting. 320 * @stable ICU 64 321 */ 322 U_CAPI void U_EXPORT2 323 ulistfmt_formatStringsToResult( 324 const UListFormatter* listfmt, 325 const UChar* const strings[], 326 const int32_t * stringLengths, 327 int32_t stringCount, 328 UFormattedList* uresult, 329 UErrorCode* status); 330 331 #endif /* #if !UCONFIG_NO_FORMATTING */ 332 333 #endif