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 */
34struct UListFormatter;
35typedef struct UListFormatter UListFormatter; /**< C typedef for struct UListFormatter. @stable ICU 55 */
36
37struct UFormattedList;
38/**
39 * Opaque struct to contain the results of a UListFormatter operation.
40 * @stable ICU 64
41 */
42typedef struct UFormattedList UFormattedList;
43
44/**
45 * FieldPosition and UFieldPosition selectors for format fields
46 * defined by ListFormatter.
47 * @stable ICU 63
48 */
49typedef 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 */
68typedef 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 */
97typedef 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 */
137U_CAPI UListFormatter* U_EXPORT2
138ulistfmt_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 */
164U_DRAFT UListFormatter* U_EXPORT2
165ulistfmt_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 */
175U_CAPI void U_EXPORT2
176ulistfmt_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 */
187U_CAPI UFormattedList* U_EXPORT2
188ulistfmt_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 */
211U_CAPI const UFormattedValue* U_EXPORT2
212ulistfmt_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 */
220U_CAPI void U_EXPORT2
221ulistfmt_closeResult(UFormattedList* uresult);
222
223
224#if U_SHOW_CPLUSPLUS_API
225
226U_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 */
237U_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 */
248U_DEFINE_LOCAL_OPEN_POINTER(LocalUFormattedListPointer, UFormattedList, ulistfmt_closeResult);
249
250U_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 */
288U_CAPI int32_t U_EXPORT2
289ulistfmt_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 */
323U_CAPI void U_EXPORT2
324ulistfmt_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