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