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 #ifndef U_HIDE_DRAFT_API 38 struct UFormattedList; 39 /** 40 * Opaque struct to contain the results of a UListFormatter operation. 41 * @draft ICU 64 42 */ 43 typedef struct UFormattedList UFormattedList; 44 #endif /* U_HIDE_DRAFT_API */ 45 46 #ifndef U_HIDE_DRAFT_API 47 /** 48 * FieldPosition and UFieldPosition selectors for format fields 49 * defined by ListFormatter. 50 * @draft ICU 63 51 */ 52 typedef enum UListFormatterField { 53 /** 54 * The literal text in the result which came from the resources. 55 * @draft ICU 63 56 */ 57 ULISTFMT_LITERAL_FIELD, 58 /** 59 * The element text in the result which came from the input strings. 60 * @draft ICU 63 61 */ 62 ULISTFMT_ELEMENT_FIELD 63 } UListFormatterField; 64 #endif /* U_HIDE_DRAFT_API */ 65 66 /** 67 * Open a new UListFormatter object using the rules for a given locale. 68 * @param locale 69 * The locale whose rules should be used; may be NULL for 70 * default locale. 71 * @param status 72 * A pointer to a standard ICU UErrorCode (input/output parameter). 73 * Its input value must pass the U_SUCCESS() test, or else the 74 * function returns immediately. The caller should check its output 75 * value with U_FAILURE(), or use with function chaining (see User 76 * Guide for details). 77 * @return 78 * A pointer to a UListFormatter object for the specified locale, 79 * or NULL if an error occurred. 80 * @stable ICU 55 81 */ 82 U_CAPI UListFormatter* U_EXPORT2 83 ulistfmt_open(const char* locale, 84 UErrorCode* status); 85 86 /** 87 * Close a UListFormatter object. Once closed it may no longer be used. 88 * @param listfmt 89 * The UListFormatter object to close. 90 * @stable ICU 55 91 */ 92 U_CAPI void U_EXPORT2 93 ulistfmt_close(UListFormatter *listfmt); 94 95 #ifndef U_HIDE_DRAFT_API 96 /** 97 * Creates an object to hold the result of a UListFormatter 98 * operation. The object can be used repeatedly; it is cleared whenever 99 * passed to a format function. 100 * 101 * @param ec Set if an error occurs. 102 * @return A pointer needing ownership. 103 * @draft ICU 64 104 */ 105 U_CAPI UFormattedList* U_EXPORT2 106 ulistfmt_openResult(UErrorCode* ec); 107 108 /** 109 * Returns a representation of a UFormattedList as a UFormattedValue, 110 * which can be subsequently passed to any API requiring that type. 111 * 112 * The returned object is owned by the UFormattedList and is valid 113 * only as long as the UFormattedList is present and unchanged in memory. 114 * 115 * You can think of this method as a cast between types. 116 * 117 * When calling ufmtval_nextPosition(): 118 * The fields are returned from start to end. The special field category 119 * UFIELD_CATEGORY_LIST_SPAN is used to indicate which argument 120 * was inserted at the given position. The span category will 121 * always occur before the corresponding instance of UFIELD_CATEGORY_LIST 122 * in the ufmtval_nextPosition() iterator. 123 * 124 * @param uresult The object containing the formatted string. 125 * @param ec Set if an error occurs. 126 * @return A UFormattedValue owned by the input object. 127 * @draft ICU 64 128 */ 129 U_CAPI const UFormattedValue* U_EXPORT2 130 ulistfmt_resultAsValue(const UFormattedList* uresult, UErrorCode* ec); 131 132 /** 133 * Releases the UFormattedList created by ulistfmt_openResult(). 134 * 135 * @param uresult The object to release. 136 * @draft ICU 64 137 */ 138 U_CAPI void U_EXPORT2 139 ulistfmt_closeResult(UFormattedList* uresult); 140 #endif /* U_HIDE_DRAFT_API */ 141 142 143 #if U_SHOW_CPLUSPLUS_API 144 145 U_NAMESPACE_BEGIN 146 147 /** 148 * \class LocalUListFormatterPointer 149 * "Smart pointer" class, closes a UListFormatter via ulistfmt_close(). 150 * For most methods see the LocalPointerBase base class. 151 * 152 * @see LocalPointerBase 153 * @see LocalPointer 154 * @stable ICU 55 155 */ 156 U_DEFINE_LOCAL_OPEN_POINTER(LocalUListFormatterPointer, UListFormatter, ulistfmt_close); 157 158 #ifndef U_HIDE_DRAFT_API 159 /** 160 * \class LocalUFormattedListPointer 161 * "Smart pointer" class, closes a UFormattedList via ulistfmt_closeResult(). 162 * For most methods see the LocalPointerBase base class. 163 * 164 * @see LocalPointerBase 165 * @see LocalPointer 166 * @draft ICU 64 167 */ 168 U_DEFINE_LOCAL_OPEN_POINTER(LocalUFormattedListPointer, UFormattedList, ulistfmt_closeResult); 169 #endif /* U_HIDE_DRAFT_API */ 170 171 U_NAMESPACE_END 172 173 #endif 174 175 /** 176 * Formats a list of strings using the conventions established for the 177 * UListFormatter object. 178 * @param listfmt 179 * The UListFormatter object specifying the list conventions. 180 * @param strings 181 * An array of pointers to UChar strings; the array length is 182 * specified by stringCount. Must be non-NULL if stringCount > 0. 183 * @param stringLengths 184 * An array of string lengths corresponding to the strings[] 185 * parameter; any individual length value may be negative to indicate 186 * that the corresponding strings[] entry is 0-terminated, or 187 * stringLengths itself may be NULL if all of the strings are 188 * 0-terminated. If non-NULL, the stringLengths array must have 189 * stringCount entries. 190 * @param stringCount 191 * the number of entries in strings[], and the number of entries 192 * in the stringLengths array if it is not NULL. Must be >= 0. 193 * @param result 194 * A pointer to a buffer to receive the formatted list. 195 * @param resultCapacity 196 * The maximum size of result. 197 * @param status 198 * A pointer to a standard ICU UErrorCode (input/output parameter). 199 * Its input value must pass the U_SUCCESS() test, or else the 200 * function returns immediately. The caller should check its output 201 * value with U_FAILURE(), or use with function chaining (see User 202 * Guide for details). 203 * @return 204 * The total buffer size needed; if greater than resultLength, the 205 * output was truncated. May be <=0 if unable to determine the 206 * total buffer size needed (e.g. for illegal arguments). 207 * @stable ICU 55 208 */ 209 U_CAPI int32_t U_EXPORT2 210 ulistfmt_format(const UListFormatter* listfmt, 211 const UChar* const strings[], 212 const int32_t * stringLengths, 213 int32_t stringCount, 214 UChar* result, 215 int32_t resultCapacity, 216 UErrorCode* status); 217 218 #ifndef U_HIDE_DRAFT_API 219 /** 220 * Formats a list of strings to a UFormattedList, which exposes more 221 * information than the string exported by ulistfmt_format(). 222 * 223 * @param listfmt 224 * The UListFormatter object specifying the list conventions. 225 * @param strings 226 * An array of pointers to UChar strings; the array length is 227 * specified by stringCount. Must be non-NULL if stringCount > 0. 228 * @param stringLengths 229 * An array of string lengths corresponding to the strings[] 230 * parameter; any individual length value may be negative to indicate 231 * that the corresponding strings[] entry is 0-terminated, or 232 * stringLengths itself may be NULL if all of the strings are 233 * 0-terminated. If non-NULL, the stringLengths array must have 234 * stringCount entries. 235 * @param stringCount 236 * the number of entries in strings[], and the number of entries 237 * in the stringLengths array if it is not NULL. Must be >= 0. 238 * @param uresult 239 * The object in which to store the result of the list formatting 240 * operation. See ulistfmt_openResult(). 241 * @param status 242 * Error code set if an error occurred during formatting. 243 * @draft ICU 64 244 */ 245 U_CAPI void U_EXPORT2 246 ulistfmt_formatStringsToResult( 247 const UListFormatter* listfmt, 248 const UChar* const strings[], 249 const int32_t * stringLengths, 250 int32_t stringCount, 251 UFormattedList* uresult, 252 UErrorCode* status); 253 #endif /* U_HIDE_DRAFT_API */ 254 255 #endif /* #if !UCONFIG_NO_FORMATTING */ 256 257 #endif 258