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