1/*
2*******************************************************************************
3*
4*   Copyright (C) 2012, 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/unistr.h"
21#include "unicode/locid.h"
22
23
24U_NAMESPACE_BEGIN
25
26/** @internal */
27class Hashtable;
28
29/** @internal */
30struct ListFormatData : public UMemory {
31    UnicodeString twoPattern;
32    UnicodeString startPattern;
33    UnicodeString middlePattern;
34    UnicodeString endPattern;
35
36  ListFormatData(const UnicodeString& two, const UnicodeString& start, const UnicodeString& middle, const UnicodeString& end) :
37      twoPattern(two), startPattern(start), middlePattern(middle), endPattern(end) {}
38};
39
40
41/**
42 * \file
43 * \brief C++ API: API for formatting a list.
44 */
45
46
47/**
48 * An immutable class for formatting a list, using data from CLDR (or supplied
49 * separately).
50 *
51 * Example: Input data ["Alice", "Bob", "Charlie", "Delta"] will be formatted
52 * as "Alice, Bob, Charlie and Delta" in English.
53 *
54 * The ListFormatter class is not intended for public subclassing.
55 */
56class U_COMMON_API ListFormatter : public UObject{
57
58  public:
59    /**
60     * Creates a ListFormatter appropriate for the default locale.
61     *
62     * @param errorCode ICU error code, set if no data available for default locale.
63     * @return Pointer to a ListFormatter object for the default locale,
64     *     created from internal data derived from CLDR data.
65     * @draft ICU 50
66     */
67    static ListFormatter* createInstance(UErrorCode& errorCode);
68
69    /**
70     * Creates a ListFormatter appropriate for a locale.
71     *
72     * @param locale The locale.
73     * @param errorCode ICU error code, set if no data available for the given locale.
74     * @return A ListFormatter object created from internal data derived from
75     *     CLDR data.
76     * @draft ICU 50
77     */
78    static ListFormatter* createInstance(const Locale& locale, UErrorCode& errorCode);
79
80
81    /**
82     * Destructor.
83     *
84     * @draft ICU 50
85     */
86    virtual ~ListFormatter();
87
88
89    /**
90     * Formats a list of strings.
91     *
92     * @param items An array of strings to be combined and formatted.
93     * @param n_items Length of the array items.
94     * @param appendTo The string to which the result should be appended to.
95     * @param errorCode ICU error code, set if there is an error.
96     * @return Formatted string combining the elements of items, appended to appendTo.
97     * @draft ICU 50
98     */
99    UnicodeString& format(const UnicodeString items[], int32_t n_items,
100        UnicodeString& appendTo, UErrorCode& errorCode) const;
101
102    /**
103     * Gets the fallback locale for a given locale.
104     * TODO: Consider moving this to the Locale class.
105     * @param in The input locale.
106     * @param out The output locale after fallback.
107     * @internal For testing.
108     */
109    static void getFallbackLocale(const Locale& in, Locale& out, UErrorCode& errorCode);
110
111    /**
112     * @internal constructor made public for testing.
113     */
114    ListFormatter(const ListFormatData& listFormatterData);
115
116  private:
117    static void initializeHash(UErrorCode& errorCode);
118    static void addDataToHash(const char* locale, const char* two, const char* start, const char* middle, const char* end, UErrorCode& errorCode);
119    static const ListFormatData* getListFormatData(const Locale& locale, UErrorCode& errorCode);
120
121    ListFormatter();
122    ListFormatter(const ListFormatter&);
123
124    ListFormatter& operator = (const ListFormatter&);
125    void addNewString(const UnicodeString& pattern, UnicodeString& originalString,
126                      const UnicodeString& newString, UErrorCode& errorCode) const;
127    virtual UClassID getDynamicClassID() const;
128
129    const ListFormatData& data;
130};
131
132U_NAMESPACE_END
133
134#endif
135