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