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