1/*
2*******************************************************************************
3*
4*   Copyright (C) 2012-2013, 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#ifndef U_HIDE_DRAFT_API
23
24#include "unicode/unistr.h"
25#include "unicode/locid.h"
26
27U_NAMESPACE_BEGIN
28
29/** @internal */
30class Hashtable;
31
32#ifndef U_HIDE_INTERNAL_API
33/** @internal */
34struct ListFormatData : public UMemory {
35    UnicodeString twoPattern;
36    UnicodeString startPattern;
37    UnicodeString middlePattern;
38    UnicodeString endPattern;
39
40  ListFormatData(const UnicodeString& two, const UnicodeString& start, const UnicodeString& middle, const UnicodeString& end) :
41      twoPattern(two), startPattern(start), middlePattern(middle), endPattern(end) {}
42};
43#endif  /* U_HIDE_INTERNAL_API */
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 * @draft 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     * @draft 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     * @draft 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     * @draft 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     * @draft 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 constructor made public for testing.
137     */
138    ListFormatter(const ListFormatData* listFormatterData);
139#endif  /* U_HIDE_INTERNAL_API */
140
141  private:
142    static void initializeHash(UErrorCode& errorCode);
143    static const ListFormatData* getListFormatData(const Locale& locale, const char *style, UErrorCode& errorCode);
144
145    ListFormatter();
146    void addNewString(const UnicodeString& pattern, UnicodeString& originalString,
147                      const UnicodeString& newString, UErrorCode& errorCode) const;
148
149    const ListFormatData* data;
150};
151
152U_NAMESPACE_END
153
154#endif /* U_HIDE_DRAFT_API */
155#endif
156