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