1 /*
2 ******************************************************************************
3 * Copyright (C) 2010-2014, International Business Machines Corporation and
4 * others. All Rights Reserved.
5 ******************************************************************************
6 */
7
8 #ifndef LOCDSPNM_H
9 #define LOCDSPNM_H
10
11 #include "unicode/utypes.h"
12
13 /**
14 * \file
15 * \brief C++ API: Provides display names of Locale and its components.
16 */
17
18 #if !UCONFIG_NO_FORMATTING
19
20 #include "unicode/locid.h"
21 #include "unicode/uscript.h"
22 #include "unicode/uldnames.h"
23 #include "unicode/udisplaycontext.h"
24
25 U_NAMESPACE_BEGIN
26
27 /**
28 * Returns display names of Locales and components of Locales. For
29 * more information on language, script, region, variant, key, and
30 * values, see Locale.
31 * @stable ICU 4.4
32 */
33 class U_I18N_API LocaleDisplayNames : public UObject {
34 public:
35 /**
36 * Destructor.
37 * @stable ICU 4.4
38 */
39 virtual ~LocaleDisplayNames();
40
41 /**
42 * Convenience overload of
43 * {@link #createInstance(const Locale& locale, UDialectHandling dialectHandling)}
44 * that specifies STANDARD dialect handling.
45 * @param locale the display locale
46 * @return a LocaleDisplayNames instance
47 * @stable ICU 4.4
48 */
49 static LocaleDisplayNames* U_EXPORT2 createInstance(const Locale& locale);
50
51 /**
52 * Returns an instance of LocaleDisplayNames that returns names
53 * formatted for the provided locale, using the provided
54 * dialectHandling.
55 *
56 * @param locale the display locale
57 * @param dialectHandling how to select names for locales
58 * @return a LocaleDisplayNames instance
59 * @stable ICU 4.4
60 */
61 static LocaleDisplayNames* U_EXPORT2 createInstance(const Locale& locale,
62 UDialectHandling dialectHandling);
63
64 /**
65 * Returns an instance of LocaleDisplayNames that returns names formatted
66 * for the provided locale, using the provided UDisplayContext settings.
67 *
68 * @param locale the display locale
69 * @param contexts List of one or more context settings (e.g. for dialect
70 * handling, capitalization, etc.
71 * @param length Number of items in the contexts list
72 * @return a LocaleDisplayNames instance
73 * @stable ICU 51
74 */
75 static LocaleDisplayNames* U_EXPORT2 createInstance(const Locale& locale,
76 UDisplayContext *contexts, int32_t length);
77
78 // getters for state
79 /**
80 * Returns the locale used to determine the display names. This is
81 * not necessarily the same locale passed to {@link #createInstance}.
82 * @return the display locale
83 * @stable ICU 4.4
84 */
85 virtual const Locale& getLocale() const = 0;
86
87 /**
88 * Returns the dialect handling used in the display names.
89 * @return the dialect handling enum
90 * @stable ICU 4.4
91 */
92 virtual UDialectHandling getDialectHandling() const = 0;
93
94 /**
95 * Returns the UDisplayContext value for the specified UDisplayContextType.
96 * @param type the UDisplayContextType whose value to return
97 * @return the UDisplayContext for the specified type.
98 * @stable ICU 51
99 */
100 virtual UDisplayContext getContext(UDisplayContextType type) const = 0;
101
102 // names for entire locales
103 /**
104 * Returns the display name of the provided locale.
105 * @param locale the locale whose display name to return
106 * @param result receives the locale's display name
107 * @return the display name of the provided locale
108 * @stable ICU 4.4
109 */
110 virtual UnicodeString& localeDisplayName(const Locale& locale,
111 UnicodeString& result) const = 0;
112
113 /**
114 * Returns the display name of the provided locale id.
115 * @param localeId the id of the locale whose display name to return
116 * @param result receives the locale's display name
117 * @return the display name of the provided locale
118 * @stable ICU 4.4
119 */
120 virtual UnicodeString& localeDisplayName(const char* localeId,
121 UnicodeString& result) const = 0;
122
123 // names for components of a locale id
124 /**
125 * Returns the display name of the provided language code.
126 * @param lang the language code
127 * @param result receives the language code's display name
128 * @return the display name of the provided language code
129 * @stable ICU 4.4
130 */
131 virtual UnicodeString& languageDisplayName(const char* lang,
132 UnicodeString& result) const = 0;
133
134 /**
135 * Returns the display name of the provided script code.
136 * @param script the script code
137 * @param result receives the script code's display name
138 * @return the display name of the provided script code
139 * @stable ICU 4.4
140 */
141 virtual UnicodeString& scriptDisplayName(const char* script,
142 UnicodeString& result) const = 0;
143
144 /**
145 * Returns the display name of the provided script code.
146 * @param scriptCode the script code number
147 * @param result receives the script code's display name
148 * @return the display name of the provided script code
149 * @stable ICU 4.4
150 */
151 virtual UnicodeString& scriptDisplayName(UScriptCode scriptCode,
152 UnicodeString& result) const = 0;
153
154 /**
155 * Returns the display name of the provided region code.
156 * @param region the region code
157 * @param result receives the region code's display name
158 * @return the display name of the provided region code
159 * @stable ICU 4.4
160 */
161 virtual UnicodeString& regionDisplayName(const char* region,
162 UnicodeString& result) const = 0;
163
164 /**
165 * Returns the display name of the provided variant.
166 * @param variant the variant string
167 * @param result receives the variant's display name
168 * @return the display name of the provided variant
169 * @stable ICU 4.4
170 */
171 virtual UnicodeString& variantDisplayName(const char* variant,
172 UnicodeString& result) const = 0;
173
174 /**
175 * Returns the display name of the provided locale key.
176 * @param key the locale key name
177 * @param result receives the locale key's display name
178 * @return the display name of the provided locale key
179 * @stable ICU 4.4
180 */
181 virtual UnicodeString& keyDisplayName(const char* key,
182 UnicodeString& result) const = 0;
183
184 /**
185 * Returns the display name of the provided value (used with the provided key).
186 * @param key the locale key name
187 * @param value the locale key's value
188 * @param result receives the value's display name
189 * @return the display name of the provided value
190 * @stable ICU 4.4
191 */
192 virtual UnicodeString& keyValueDisplayName(const char* key, const char* value,
193 UnicodeString& result) const = 0;
194 };
195
createInstance(const Locale & locale)196 inline LocaleDisplayNames* LocaleDisplayNames::createInstance(const Locale& locale) {
197 return LocaleDisplayNames::createInstance(locale, ULDN_STANDARD_NAMES);
198 }
199
200 U_NAMESPACE_END
201
202 #endif
203
204 #endif
205