1// © 2016 and later: Unicode, Inc. and others.
2// License & terms of use: http://www.unicode.org/copyright.html
3/*
4*******************************************************************************
5*
6* Copyright (C) 2012-2016, International Business Machines
7* Corporation and others. All Rights Reserved.
8*
9*******************************************************************************
10* file name: listformatter.h
11* encoding: UTF-8
12* tab size: 8 (not used)
13* indentation:4
14*
15* created on: 20120426
16* created by: Umesh P. Nair
17*/
18
19#ifndef __LISTFORMATTER_H__
20#define __LISTFORMATTER_H__
21
22#include "unicode/utypes.h"
23
24#if U_SHOW_CPLUSPLUS_API
25
26#include "unicode/unistr.h"
27#include "unicode/locid.h"
28#include "unicode/formattedvalue.h"
29
30U_NAMESPACE_BEGIN
31
32class FieldPositionIterator;
33class FieldPositionHandler;
34class FormattedListData;
35class ListFormatter;
36
37/** @internal */
38class Hashtable;
39
40/** @internal */
41struct ListFormatInternal;
42
43/* The following can't be #ifndef U_HIDE_INTERNAL_API, needed for other .h file declarations */
44/**
45 * @internal
46 * \cond
47 */
48struct ListFormatData : public UMemory {
49 UnicodeString twoPattern;
50 UnicodeString startPattern;
51 UnicodeString middlePattern;
52 UnicodeString endPattern;
53
54 ListFormatData(const UnicodeString& two, const UnicodeString& start, const UnicodeString& middle, const UnicodeString& end) :
55 twoPattern(two), startPattern(start), middlePattern(middle), endPattern(end) {}
56};
57/** \endcond */
58
59
60/**
61 * \file
62 * \brief C++ API: API for formatting a list.
63 */
64
65
66#if !UCONFIG_NO_FORMATTING
67#ifndef U_HIDE_DRAFT_API
68/**
69 * An immutable class containing the result of a list formatting operation.
70 *
71 * Instances of this class are immutable and thread-safe.
72 *
73 * When calling nextPosition():
74 * The fields are returned from start to end. The special field category
75 * UFIELD_CATEGORY_LIST_SPAN is used to indicate which argument
76 * was inserted at the given position. The span category will
77 * always occur before the corresponding instance of UFIELD_CATEGORY_LIST
78 * in the nextPosition() iterator.
79 *
80 * Not intended for public subclassing.
81 *
82 * @draft ICU 64
83 */
84class U_I18N_API FormattedList : public UMemory, public FormattedValue {
85 public:
86 /**
87 * Default constructor; makes an empty FormattedList.
88 * @draft ICU 64
89 */
90 FormattedList() : fData(nullptr), fErrorCode(U_INVALID_STATE_ERROR) {}
91
92 /**
93 * Move constructor: Leaves the source FormattedList in an undefined state.
94 * @draft ICU 64
95 */
96 FormattedList(FormattedList&& src) U_NOEXCEPT;
97
98 /**
99 * Destruct an instance of FormattedList.
100 * @draft ICU 64
101 */
102 virtual ~FormattedList() U_OVERRIDE;
103
104 /** Copying not supported; use move constructor instead. */
105 FormattedList(const FormattedList&) = delete;
106
107 /** Copying not supported; use move assignment instead. */
108 FormattedList& operator=(const FormattedList&) = delete;
109
110 /**
111 * Move assignment: Leaves the source FormattedList in an undefined state.
112 * @draft ICU 64
113 */
114 FormattedList& operator=(FormattedList&& src) U_NOEXCEPT;
115
116 /** @copydoc FormattedValue::toString() */
117 UnicodeString toString(UErrorCode& status) const U_OVERRIDE;
118
119 /** @copydoc FormattedValue::toTempString() */
120 UnicodeString toTempString(UErrorCode& status) const U_OVERRIDE;
121
122 /** @copydoc FormattedValue::appendTo() */
123 Appendable &appendTo(Appendable& appendable, UErrorCode& status) const U_OVERRIDE;
124
125 /** @copydoc FormattedValue::nextPosition() */
126 UBool nextPosition(ConstrainedFieldPosition& cfpos, UErrorCode& status) const U_OVERRIDE;
127
128 private:
129 FormattedListData *fData;
130 UErrorCode fErrorCode;
131 explicit FormattedList(FormattedListData *results)
132 : fData(results), fErrorCode(U_ZERO_ERROR) {}
133 explicit FormattedList(UErrorCode errorCode)
134 : fData(nullptr), fErrorCode(errorCode) {}
135 friend class ListFormatter;
136};
137#endif /* U_HIDE_DRAFT_API */
138#endif // !UCONFIG_NO_FORMATTING
139
140
141/**
142 * An immutable class for formatting a list, using data from CLDR (or supplied
143 * separately).
144 *
145 * Example: Input data ["Alice", "Bob", "Charlie", "Delta"] will be formatted
146 * as "Alice, Bob, Charlie and Delta" in English.
147 *
148 * The ListFormatter class is not intended for public subclassing.
149 * @stable ICU 50
150 */
151class U_I18N_API ListFormatter : public UObject{
152
153 public:
154
155 /**
156 * Copy constructor.
157 * @stable ICU 52
158 */
159 ListFormatter(const ListFormatter&);
160
161 /**
162 * Assignment operator.
163 * @stable ICU 52
164 */
165 ListFormatter& operator=(const ListFormatter& other);
166
167 /**
168 * Creates a ListFormatter appropriate for the default locale.
169 *
170 * @param errorCode ICU error code, set if no data available for default locale.
171 * @return Pointer to a ListFormatter object for the default locale,
172 * created from internal data derived from CLDR data.
173 * @stable ICU 50
174 */
175 static ListFormatter* createInstance(UErrorCode& errorCode);
176
177 /**
178 * Creates a ListFormatter appropriate for a locale.
179 *
180 * @param locale The locale.
181 * @param errorCode ICU error code, set if no data available for the given locale.
182 * @return A ListFormatter object created from internal data derived from
183 * CLDR data.
184 * @stable ICU 50
185 */
186 static ListFormatter* createInstance(const Locale& locale, UErrorCode& errorCode);
187
188#ifndef U_HIDE_INTERNAL_API
189 /**
190 * Creates a ListFormatter appropriate for a locale and style.
191 *
192 * @param locale The locale.
193 * @param style the style, either "standard", "or", "unit", "unit-narrow", or "unit-short"
194 * @param errorCode ICU error code, set if no data available for the given locale.
195 * @return A ListFormatter object created from internal data derived from
196 * CLDR data.
197 * @internal
198 */
199 static ListFormatter* createInstance(const Locale& locale, const char* style, UErrorCode& errorCode);
200#endif /* U_HIDE_INTERNAL_API */
201
202 /**
203 * Destructor.
204 *
205 * @stable ICU 50
206 */
207 virtual ~ListFormatter();
208
209
210 /**
211 * Formats a list of strings.
212 *
213 * @param items An array of strings to be combined and formatted.
214 * @param n_items Length of the array items.
215 * @param appendTo The string to which the result should be appended to.
216 * @param errorCode ICU error code, set if there is an error.
217 * @return Formatted string combining the elements of items, appended to appendTo.
218 * @stable ICU 50
219 */
220 UnicodeString& format(const UnicodeString items[], int32_t n_items,
221 UnicodeString& appendTo, UErrorCode& errorCode) const;
222
223#ifndef U_HIDE_DRAFT_API
224 /**
225 * Format a list of strings.
226 *
227 * @param items An array of strings to be combined and formatted.
228 * @param n_items Length of the array items.
229 * @param appendTo The string to which the formatted result will be
230 * appended.
231 * @param posIter On return, can be used to iterate over positions of
232 * fields generated by this format call. Field values are
233 * defined in UListFormatterField. Can be NULL.
234 * @param errorCode ICU error code returned here.
235 * @return Formatted string combining the elements of items,
236 * appended to appendTo.
237 * @draft ICU 63
238 */
239 UnicodeString& format(const UnicodeString items[], int32_t n_items,
240 UnicodeString & appendTo, FieldPositionIterator* posIter,
241 UErrorCode& errorCode) const;
242#endif // U_HIDE_DRAFT_API
243
244#if !UCONFIG_NO_FORMATTING
245#ifndef U_HIDE_DRAFT_API
246 /**
247 * Formats a list of strings to a FormattedList, which exposes field
248 * position information. The FormattedList contains more information than
249 * a FieldPositionIterator.
250 *
251 * @param items An array of strings to be combined and formatted.
252 * @param n_items Length of the array items.
253 * @param errorCode ICU error code returned here.
254 * @return A FormattedList containing field information.
255 * @draft ICU 64
256 */
257 FormattedList formatStringsToValue(
258 const UnicodeString items[],
259 int32_t n_items,
260 UErrorCode& errorCode) const;
261#endif /* U_HIDE_DRAFT_API */
262#endif // !UCONFIG_NO_FORMATTING
263
264#ifndef U_HIDE_INTERNAL_API
265 /**
266 @internal for MeasureFormat
267 */
268 UnicodeString& format(
269 const UnicodeString items[],
270 int32_t n_items,
271 UnicodeString& appendTo,
272 int32_t index,
273 int32_t &offset,
274 UErrorCode& errorCode) const;
275 /**
276 * @internal constructor made public for testing.
277 */
278 ListFormatter(const ListFormatData &data, UErrorCode &errorCode);
279 /**
280 * @internal constructor made public for testing.
281 */
282 ListFormatter(const ListFormatInternal* listFormatterInternal);
283#endif /* U_HIDE_INTERNAL_API */
284
285 private:
286 static void initializeHash(UErrorCode& errorCode);
287 static const ListFormatInternal* getListFormatInternal(const Locale& locale, const char *style, UErrorCode& errorCode);
288 struct ListPatternsSink;
289 static ListFormatInternal* loadListFormatInternal(const Locale& locale, const char* style, UErrorCode& errorCode);
290
291 UnicodeString& format_(
292 const UnicodeString items[], int32_t n_items, UnicodeString& appendTo,
293 int32_t index, int32_t &offset, FieldPositionHandler* handler, UErrorCode& errorCode) const;
294
295 ListFormatter();
296
297 ListFormatInternal* owned;
298 const ListFormatInternal* data;
299};
300
301U_NAMESPACE_END
302
303#endif /* U_SHOW_CPLUSPLUS_API */
304
305#endif // __LISTFORMATTER_H__
306