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 
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