listformatter.h (8799B)
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 57 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 */ 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) noexcept; 99 100 /** 101 * Destruct an instance of FormattedList. 102 * @stable ICU 64 103 */ 104 virtual ~FormattedList() 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) noexcept; 117 118 /** @copydoc FormattedValue::toString() */ 119 UnicodeString toString(UErrorCode& status) const override; 120 121 /** @copydoc FormattedValue::toTempString() */ 122 UnicodeString toTempString(UErrorCode& status) const override; 123 124 /** @copydoc FormattedValue::appendTo() */ 125 Appendable &appendTo(Appendable& appendable, UErrorCode& status) const override; 126 127 /** @copydoc FormattedValue::nextPosition() */ 128 UBool nextPosition(ConstrainedFieldPosition& cfpos, UErrorCode& status) const override; 129 130 private: 131 FormattedListData *fData; 132 UErrorCode fErrorCode; 133 explicit FormattedList(FormattedListData *results) 134 : fData(results), fErrorCode(U_ZERO_ERROR) {} 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 /** 202 * Destructor. 203 * 204 * @stable ICU 50 205 */ 206 virtual ~ListFormatter(); 207 208 209 /** 210 * Formats a list of strings. 211 * 212 * @param items An array of strings to be combined and formatted. 213 * @param n_items Length of the array items. 214 * @param appendTo The string to which the result should be appended to. 215 * @param errorCode ICU error code, set if there is an error. 216 * @return Formatted string combining the elements of items, appended to appendTo. 217 * @stable ICU 50 218 */ 219 UnicodeString& format(const UnicodeString items[], int32_t n_items, 220 UnicodeString& appendTo, UErrorCode& errorCode) const; 221 222 /** 223 * Formats a list of strings to a FormattedList, which exposes field 224 * position information. The FormattedList contains more information than 225 * a FieldPositionIterator. 226 * 227 * @param items An array of strings to be combined and formatted. 228 * @param n_items Length of the array items. 229 * @param errorCode ICU error code returned here. 230 * @return A FormattedList containing field information. 231 * @stable ICU 64 232 */ 233 FormattedList formatStringsToValue( 234 const UnicodeString items[], 235 int32_t n_items, 236 UErrorCode& errorCode) const; 237 238 #ifndef U_HIDE_INTERNAL_API 239 /** 240 @internal for MeasureFormat 241 */ 242 UnicodeString& format( 243 const UnicodeString items[], 244 int32_t n_items, 245 UnicodeString& appendTo, 246 int32_t index, 247 int32_t &offset, 248 UErrorCode& errorCode) const; 249 /** 250 * @internal constructor made public for testing. 251 */ 252 ListFormatter(const ListFormatData &data, UErrorCode &errorCode); 253 /** 254 * @internal constructor made public for testing. 255 */ 256 ListFormatter(const ListFormatInternal* listFormatterInternal); 257 #endif /* U_HIDE_INTERNAL_API */ 258 259 private: 260 261 /** 262 * Creates a ListFormatter appropriate for a locale and style. 263 * 264 * @param locale The locale. 265 * @param style the style, either "standard", "or", "unit", "unit-narrow", or "unit-short" 266 */ 267 static ListFormatter* createInstance(const Locale& locale, const char* style, UErrorCode& errorCode); 268 269 static void initializeHash(UErrorCode& errorCode); 270 static const ListFormatInternal* getListFormatInternal(const Locale& locale, const char *style, UErrorCode& errorCode); 271 struct U_HIDDEN ListPatternsSink; 272 static ListFormatInternal* loadListFormatInternal(const Locale& locale, const char* style, UErrorCode& errorCode); 273 274 ListFormatter() = delete; 275 276 ListFormatInternal* owned; 277 const ListFormatInternal* data; 278 }; 279 280 U_NAMESPACE_END 281 282 #endif /* #if !UCONFIG_NO_FORMATTING */ 283 284 #endif /* U_SHOW_CPLUSPLUS_API */ 285 286 #endif // __LISTFORMATTER_H__