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 30 U_NAMESPACE_BEGIN 31 32 class FieldPositionIterator; 33 class FieldPositionHandler; 34 class FormattedListData; 35 class ListFormatter; 36 37 /** @internal */ 38 class Hashtable; 39 40 /** @internal */ 41 struct 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 */ 48 struct ListFormatData : public UMemory { 49 UnicodeString twoPattern; 50 UnicodeString startPattern; 51 UnicodeString middlePattern; 52 UnicodeString endPattern; 53 ListFormatDataListFormatData54 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 */ 84 class U_I18N_API FormattedList : public UMemory, public FormattedValue { 85 public: 86 /** 87 * Default constructor; makes an empty FormattedList. 88 * @draft ICU 64 89 */ FormattedList()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; FormattedList(FormattedListData * results)131 explicit FormattedList(FormattedListData *results) 132 : fData(results), fErrorCode(U_ZERO_ERROR) {} FormattedList(UErrorCode errorCode)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 */ 151 class 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 301 U_NAMESPACE_END 302 303 #endif /* U_SHOW_CPLUSPLUS_API */ 304 305 #endif // __LISTFORMATTER_H__ 306