1 /*
2 *******************************************************************************
3 *
4 *   Copyright (C) 2012-2014, International Business Machines
5 *   Corporation and others.  All Rights Reserved.
6 *
7 *******************************************************************************
8 *   file name:  listformatter.h
9 *   encoding:   US-ASCII
10 *   tab size:   8 (not used)
11 *   indentation:4
12 *
13 *   created on: 20120426
14 *   created by: Umesh P. Nair
15 */
16 
17 #ifndef __LISTFORMATTER_H__
18 #define __LISTFORMATTER_H__
19 
20 #include "unicode/utypes.h"
21 
22 #include "unicode/unistr.h"
23 #include "unicode/locid.h"
24 
25 U_NAMESPACE_BEGIN
26 
27 /** @internal */
28 class Hashtable;
29 
30 /** @internal */
31 struct ListFormatInternal;
32 
33 /* The following can't be #ifndef U_HIDE_INTERNAL_API, needed for other .h file declarations */
34 /** @internal */
35 struct ListFormatData : public UMemory {
36     UnicodeString twoPattern;
37     UnicodeString startPattern;
38     UnicodeString middlePattern;
39     UnicodeString endPattern;
40 
ListFormatDataListFormatData41   ListFormatData(const UnicodeString& two, const UnicodeString& start, const UnicodeString& middle, const UnicodeString& end) :
42       twoPattern(two), startPattern(start), middlePattern(middle), endPattern(end) {}
43 };
44 
45 
46 /**
47  * \file
48  * \brief C++ API: API for formatting a list.
49  */
50 
51 
52 /**
53  * An immutable class for formatting a list, using data from CLDR (or supplied
54  * separately).
55  *
56  * Example: Input data ["Alice", "Bob", "Charlie", "Delta"] will be formatted
57  * as "Alice, Bob, Charlie and Delta" in English.
58  *
59  * The ListFormatter class is not intended for public subclassing.
60  * @stable ICU 50
61  */
62 class U_COMMON_API ListFormatter : public UObject{
63 
64   public:
65 
66     /**
67      * Copy constructor.
68      * @stable ICU 52
69      */
70     ListFormatter(const ListFormatter&);
71 
72     /**
73      * Assignment operator.
74      * @stable ICU 52
75      */
76     ListFormatter& operator=(const ListFormatter& other);
77 
78     /**
79      * Creates a ListFormatter appropriate for the default locale.
80      *
81      * @param errorCode ICU error code, set if no data available for default locale.
82      * @return Pointer to a ListFormatter object for the default locale,
83      *     created from internal data derived from CLDR data.
84      * @stable ICU 50
85      */
86     static ListFormatter* createInstance(UErrorCode& errorCode);
87 
88     /**
89      * Creates a ListFormatter appropriate for a locale.
90      *
91      * @param locale The locale.
92      * @param errorCode ICU error code, set if no data available for the given locale.
93      * @return A ListFormatter object created from internal data derived from
94      *     CLDR data.
95      * @stable ICU 50
96      */
97     static ListFormatter* createInstance(const Locale& locale, UErrorCode& errorCode);
98 
99 #ifndef U_HIDE_INTERNAL_API
100     /**
101      * Creates a ListFormatter appropriate for a locale and style.
102      *
103      * @param locale The locale.
104      * @param style the style, either "standard", "duration", or "duration-short"
105      * @param errorCode ICU error code, set if no data available for the given locale.
106      * @return A ListFormatter object created from internal data derived from
107      *     CLDR data.
108      * @internal
109      */
110     static ListFormatter* createInstance(const Locale& locale, const char* style, UErrorCode& errorCode);
111 #endif  /* U_HIDE_INTERNAL_API */
112 
113     /**
114      * Destructor.
115      *
116      * @stable ICU 50
117      */
118     virtual ~ListFormatter();
119 
120 
121     /**
122      * Formats a list of strings.
123      *
124      * @param items An array of strings to be combined and formatted.
125      * @param n_items Length of the array items.
126      * @param appendTo The string to which the result should be appended to.
127      * @param errorCode ICU error code, set if there is an error.
128      * @return Formatted string combining the elements of items, appended to appendTo.
129      * @stable ICU 50
130      */
131     UnicodeString& format(const UnicodeString items[], int32_t n_items,
132         UnicodeString& appendTo, UErrorCode& errorCode) const;
133 
134 #ifndef U_HIDE_INTERNAL_API
135     /**
136       @internal for MeasureFormat
137     */
138     UnicodeString& format(
139             const UnicodeString items[],
140             int32_t n_items,
141             UnicodeString& appendTo,
142             int32_t index,
143             int32_t &offset,
144             UErrorCode& errorCode) const;
145     /**
146      * @internal constructor made public for testing.
147      */
148     ListFormatter(const ListFormatData &data);
149     /**
150      * @internal constructor made public for testing.
151      */
152     ListFormatter(const ListFormatInternal* listFormatterInternal);
153 #endif  /* U_HIDE_INTERNAL_API */
154 
155   private:
156     static void initializeHash(UErrorCode& errorCode);
157     static const ListFormatInternal* getListFormatInternal(const Locale& locale, const char *style, UErrorCode& errorCode);
158 
159     ListFormatter();
160 
161     ListFormatInternal* owned;
162     const ListFormatInternal* data;
163 };
164 
165 U_NAMESPACE_END
166 
167 #endif
168