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
37#ifndef U_HIDE_DRAFT_API
38struct UFormattedList;
39/**
40 * Opaque struct to contain the results of a UListFormatter operation.
41 * @draft ICU 64
42 */
43typedef 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 */
52typedef 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 */
82U_CAPI UListFormatter* U_EXPORT2
83ulistfmt_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 */
92U_CAPI void U_EXPORT2
93ulistfmt_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 */
105U_CAPI UFormattedList* U_EXPORT2
106ulistfmt_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 */
129U_CAPI const UFormattedValue* U_EXPORT2
130ulistfmt_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 */
138U_CAPI void U_EXPORT2
139ulistfmt_closeResult(UFormattedList* uresult);
140#endif /* U_HIDE_DRAFT_API */
141
142
143#if U_SHOW_CPLUSPLUS_API
144
145U_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 */
156U_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 */
168U_DEFINE_LOCAL_OPEN_POINTER(LocalUFormattedListPointer, UFormattedList, ulistfmt_closeResult);
169#endif /* U_HIDE_DRAFT_API */
170
171U_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 */
209U_CAPI int32_t U_EXPORT2
210ulistfmt_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 */
245U_CAPI void U_EXPORT2
246ulistfmt_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