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 #if !UCONFIG_NO_FORMATTING 27 28 #include "unicode/unistr.h" 29 #include "unicode/locid.h" 30 #include "unicode/formattedvalue.h" 31 #include "unicode/ulistformatter.h" 32 33 U_NAMESPACE_BEGIN 34 35 class FieldPositionHandler; 36 class FormattedListData; 37 class ListFormatter; 38 39 /** @internal */ 40 class Hashtable; 41 42 /** @internal */ 43 struct ListFormatInternal; 44 45 /* The following can't be #ifndef U_HIDE_INTERNAL_API, needed for other .h file declarations */ 46 /** 47 * @internal 48 * \cond 49 */ 50 struct ListFormatData : public UMemory { 51 UnicodeString twoPattern; 52 UnicodeString startPattern; 53 UnicodeString middlePattern; 54 UnicodeString endPattern; 55 Locale locale; 56 ListFormatDataListFormatData57 ListFormatData(const UnicodeString& two, const UnicodeString& start, const UnicodeString& middle, const UnicodeString& end, 58 const Locale& loc) : 59 twoPattern(two), startPattern(start), middlePattern(middle), endPattern(end), locale(loc) {} 60 }; 61 /** \endcond */ 62 63 64 /** 65 * \file 66 * \brief C++ API: API for formatting a list. 67 */ 68 69 70 /** 71 * An immutable class containing the result of a list formatting operation. 72 * 73 * Instances of this class are immutable and thread-safe. 74 * 75 * When calling nextPosition(): 76 * The fields are returned from start to end. The special field category 77 * UFIELD_CATEGORY_LIST_SPAN is used to indicate which argument 78 * was inserted at the given position. The span category will 79 * always occur before the corresponding instance of UFIELD_CATEGORY_LIST 80 * in the nextPosition() iterator. 81 * 82 * Not intended for public subclassing. 83 * 84 * @stable ICU 64 85 */ 86 class U_I18N_API FormattedList : public UMemory, public FormattedValue { 87 public: 88 /** 89 * Default constructor; makes an empty FormattedList. 90 * @stable ICU 64 91 */ FormattedList()92 FormattedList() : fData(nullptr), fErrorCode(U_INVALID_STATE_ERROR) {} 93 94 /** 95 * Move constructor: Leaves the source FormattedList in an undefined state. 96 * @stable ICU 64 97 */ 98 FormattedList(FormattedList&& src) U_NOEXCEPT; 99 100 /** 101 * Destruct an instance of FormattedList. 102 * @stable ICU 64 103 */ 104 virtual ~FormattedList() U_OVERRIDE; 105 106 /** Copying not supported; use move constructor instead. */ 107 FormattedList(const FormattedList&) = delete; 108 109 /** Copying not supported; use move assignment instead. */ 110 FormattedList& operator=(const FormattedList&) = delete; 111 112 /** 113 * Move assignment: Leaves the source FormattedList in an undefined state. 114 * @stable ICU 64 115 */ 116 FormattedList& operator=(FormattedList&& src) U_NOEXCEPT; 117 118 /** @copydoc FormattedValue::toString() */ 119 UnicodeString toString(UErrorCode& status) const U_OVERRIDE; 120 121 /** @copydoc FormattedValue::toTempString() */ 122 UnicodeString toTempString(UErrorCode& status) const U_OVERRIDE; 123 124 /** @copydoc FormattedValue::appendTo() */ 125 Appendable &appendTo(Appendable& appendable, UErrorCode& status) const U_OVERRIDE; 126 127 /** @copydoc FormattedValue::nextPosition() */ 128 UBool nextPosition(ConstrainedFieldPosition& cfpos, UErrorCode& status) const U_OVERRIDE; 129 130 private: 131 FormattedListData *fData; 132 UErrorCode fErrorCode; FormattedList(FormattedListData * results)133 explicit FormattedList(FormattedListData *results) 134 : fData(results), fErrorCode(U_ZERO_ERROR) {} FormattedList(UErrorCode errorCode)135 explicit FormattedList(UErrorCode errorCode) 136 : fData(nullptr), fErrorCode(errorCode) {} 137 friend class ListFormatter; 138 }; 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 /** 189 * Creates a ListFormatter for the given locale, list type, and style. 190 * 191 * @param locale The locale. 192 * @param type The type of list formatting to use. 193 * @param width The width of formatting to use. 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 CLDR data. 196 * @stable ICU 67 197 */ 198 static ListFormatter* createInstance( 199 const Locale& locale, UListFormatterType type, UListFormatterWidth width, UErrorCode& errorCode); 200 201 #ifndef U_HIDE_INTERNAL_API 202 /** 203 * Creates a ListFormatter appropriate for a locale and style. 204 * 205 * TODO(ICU-20888): Remove this in ICU 68. 206 * 207 * @param locale The locale. 208 * @param style the style, either "standard", "or", "unit", "unit-narrow", or "unit-short" 209 * @param errorCode ICU error code, set if no data available for the given locale. 210 * @return A ListFormatter object created from internal data derived from 211 * CLDR data. 212 * @internal 213 */ 214 static ListFormatter* createInstance(const Locale& locale, const char* style, UErrorCode& errorCode); 215 #endif /* U_HIDE_INTERNAL_API */ 216 217 /** 218 * Destructor. 219 * 220 * @stable ICU 50 221 */ 222 virtual ~ListFormatter(); 223 224 225 /** 226 * Formats a list of strings. 227 * 228 * @param items An array of strings to be combined and formatted. 229 * @param n_items Length of the array items. 230 * @param appendTo The string to which the result should be appended to. 231 * @param errorCode ICU error code, set if there is an error. 232 * @return Formatted string combining the elements of items, appended to appendTo. 233 * @stable ICU 50 234 */ 235 UnicodeString& format(const UnicodeString items[], int32_t n_items, 236 UnicodeString& appendTo, UErrorCode& errorCode) const; 237 238 /** 239 * Formats a list of strings to a FormattedList, which exposes field 240 * position information. The FormattedList contains more information than 241 * a FieldPositionIterator. 242 * 243 * @param items An array of strings to be combined and formatted. 244 * @param n_items Length of the array items. 245 * @param errorCode ICU error code returned here. 246 * @return A FormattedList containing field information. 247 * @stable ICU 64 248 */ 249 FormattedList formatStringsToValue( 250 const UnicodeString items[], 251 int32_t n_items, 252 UErrorCode& errorCode) const; 253 254 #ifndef U_HIDE_INTERNAL_API 255 /** 256 @internal for MeasureFormat 257 */ 258 UnicodeString& format( 259 const UnicodeString items[], 260 int32_t n_items, 261 UnicodeString& appendTo, 262 int32_t index, 263 int32_t &offset, 264 UErrorCode& errorCode) const; 265 /** 266 * @internal constructor made public for testing. 267 */ 268 ListFormatter(const ListFormatData &data, UErrorCode &errorCode); 269 /** 270 * @internal constructor made public for testing. 271 */ 272 ListFormatter(const ListFormatInternal* listFormatterInternal); 273 #endif /* U_HIDE_INTERNAL_API */ 274 275 private: 276 static void initializeHash(UErrorCode& errorCode); 277 static const ListFormatInternal* getListFormatInternal(const Locale& locale, const char *style, UErrorCode& errorCode); 278 struct ListPatternsSink; 279 static ListFormatInternal* loadListFormatInternal(const Locale& locale, const char* style, UErrorCode& errorCode); 280 281 UnicodeString& format_( 282 const UnicodeString items[], int32_t n_items, UnicodeString& appendTo, 283 int32_t index, int32_t &offset, FieldPositionHandler* handler, UErrorCode& errorCode) const; 284 285 ListFormatter(); 286 287 ListFormatInternal* owned; 288 const ListFormatInternal* data; 289 }; 290 291 U_NAMESPACE_END 292 293 #endif /* #if !UCONFIG_NO_FORMATTING */ 294 295 #endif /* U_SHOW_CPLUSPLUS_API */ 296 297 #endif // __LISTFORMATTER_H__ 298