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
25U_NAMESPACE_BEGIN
26
27/** @internal */
28class Hashtable;
29
30/** @internal */
31struct ListFormatInternal;
32
33/* The following can't be #ifndef U_HIDE_INTERNAL_API, needed for other .h file declarations */
34/** @internal */
35struct ListFormatData : public UMemory {
36    UnicodeString twoPattern;
37    UnicodeString startPattern;
38    UnicodeString middlePattern;
39    UnicodeString endPattern;
40
41  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 */
62class U_COMMON_API ListFormatter : public UObject{
63
64  public:
65
66    /**
67     * Copy constructor.
68     * @draft ICU 52
69     */
70    ListFormatter(const ListFormatter&);
71
72    /**
73     * Assignment operator.
74     * @draft 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
165U_NAMESPACE_END
166
167#endif
168