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 #include "unicode/unistr.h" 25 #include "unicode/locid.h" 26 27 U_NAMESPACE_BEGIN 28 29 class FieldPositionIterator; 30 class FieldPositionHandler; 31 32 /** @internal */ 33 class Hashtable; 34 35 /** @internal */ 36 struct ListFormatInternal; 37 38 /* The following can't be #ifndef U_HIDE_INTERNAL_API, needed for other .h file declarations */ 39 /** 40 * @internal 41 * \cond 42 */ 43 struct ListFormatData : public UMemory { 44 UnicodeString twoPattern; 45 UnicodeString startPattern; 46 UnicodeString middlePattern; 47 UnicodeString endPattern; 48 49 ListFormatData(const UnicodeString& two, const UnicodeString& start, const UnicodeString& middle, const UnicodeString& end) : 50 twoPattern(two), startPattern(start), middlePattern(middle), endPattern(end) {} 51 }; 52 /** \endcond */ 53 54 55 /** 56 * \file 57 * \brief C++ API: API for formatting a list. 58 */ 59 60 61 /** 62 * An immutable class for formatting a list, using data from CLDR (or supplied 63 * separately). 64 * 65 * Example: Input data ["Alice", "Bob", "Charlie", "Delta"] will be formatted 66 * as "Alice, Bob, Charlie and Delta" in English. 67 * 68 * The ListFormatter class is not intended for public subclassing. 69 * @stable ICU 50 70 */ 71 class U_I18N_API ListFormatter : public UObject{ 72 73 public: 74 75 /** 76 * Copy constructor. 77 * @stable ICU 52 78 */ 79 ListFormatter(const ListFormatter&); 80 81 /** 82 * Assignment operator. 83 * @stable ICU 52 84 */ 85 ListFormatter& operator=(const ListFormatter& other); 86 87 /** 88 * Creates a ListFormatter appropriate for the default locale. 89 * 90 * @param errorCode ICU error code, set if no data available for default locale. 91 * @return Pointer to a ListFormatter object for the default locale, 92 * created from internal data derived from CLDR data. 93 * @stable ICU 50 94 */ 95 static ListFormatter* createInstance(UErrorCode& errorCode); 96 97 /** 98 * Creates a ListFormatter appropriate for a locale. 99 * 100 * @param locale The locale. 101 * @param errorCode ICU error code, set if no data available for the given locale. 102 * @return A ListFormatter object created from internal data derived from 103 * CLDR data. 104 * @stable ICU 50 105 */ 106 static ListFormatter* createInstance(const Locale& locale, UErrorCode& errorCode); 107 108 #ifndef U_HIDE_INTERNAL_API 109 /** 110 * Creates a ListFormatter appropriate for a locale and style. 111 * 112 * @param locale The locale. 113 * @param style the style, either "standard", "duration", or "duration-short" 114 * @param errorCode ICU error code, set if no data available for the given locale. 115 * @return A ListFormatter object created from internal data derived from 116 * CLDR data. 117 * @internal 118 */ 119 static ListFormatter* createInstance(const Locale& locale, const char* style, UErrorCode& errorCode); 120 #endif /* U_HIDE_INTERNAL_API */ 121 122 /** 123 * Destructor. 124 * 125 * @stable ICU 50 126 */ 127 virtual ~ListFormatter(); 128 129 130 /** 131 * Formats a list of strings. 132 * 133 * @param items An array of strings to be combined and formatted. 134 * @param n_items Length of the array items. 135 * @param appendTo The string to which the result should be appended to. 136 * @param errorCode ICU error code, set if there is an error. 137 * @return Formatted string combining the elements of items, appended to appendTo. 138 * @stable ICU 50 139 */ 140 UnicodeString& format(const UnicodeString items[], int32_t n_items, 141 UnicodeString& appendTo, UErrorCode& errorCode) const; 142 143 #ifndef U_HIDE_DRAFT_API 144 /** 145 * Format a list of strings. 146 * 147 * @param items An array of strings to be combined and formatted. 148 * @param n_items Length of the array items. 149 * @param appendTo The string to which the formatted result will be 150 * appended. 151 * @param posIter On return, can be used to iterate over positions of 152 * fields generated by this format call. Field values are 153 * defined in UListFormatterField. Can be NULL. 154 * @param errorCode ICU error code returned here. 155 * @return Formatted string combining the elements of items, 156 * appended to appendTo. 157 * @draft ICU 63 158 */ 159 UnicodeString& format(const UnicodeString items[], int32_t n_items, 160 UnicodeString & appendTo, FieldPositionIterator* posIter, 161 UErrorCode& errorCode) const; 162 #endif /* U_HIDE_DRAFT_API */ 163 164 #ifndef U_HIDE_INTERNAL_API 165 /** 166 @internal for MeasureFormat 167 */ 168 UnicodeString& format( 169 const UnicodeString items[], 170 int32_t n_items, 171 UnicodeString& appendTo, 172 int32_t index, 173 int32_t &offset, 174 UErrorCode& errorCode) const; 175 /** 176 * @internal constructor made public for testing. 177 */ 178 ListFormatter(const ListFormatData &data, UErrorCode &errorCode); 179 /** 180 * @internal constructor made public for testing. 181 */ 182 ListFormatter(const ListFormatInternal* listFormatterInternal); 183 #endif /* U_HIDE_INTERNAL_API */ 184 185 private: 186 static void initializeHash(UErrorCode& errorCode); 187 static const ListFormatInternal* getListFormatInternal(const Locale& locale, const char *style, UErrorCode& errorCode); 188 struct ListPatternsSink; 189 static ListFormatInternal* loadListFormatInternal(const Locale& locale, const char* style, UErrorCode& errorCode); 190 191 UnicodeString& format_( 192 const UnicodeString items[], int32_t n_items, UnicodeString& appendTo, 193 int32_t index, int32_t &offset, FieldPositionHandler* handler, UErrorCode& errorCode) const; 194 195 ListFormatter(); 196 197 ListFormatInternal* owned; 198 const ListFormatInternal* data; 199 }; 200 201 U_NAMESPACE_END 202 203 #endif 204
