codekingpro/portable-devtools

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
30U_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 */
38class U_COMMON_API LocaleDisplayNames : public UObject {
39public:
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
201inline LocaleDisplayNames* LocaleDisplayNames::createInstance(const Locale& locale) {
202  return LocaleDisplayNames::createInstance(locale, ULDN_STANDARD_NAMES);
203}
204
205U_NAMESPACE_END
206
207#endif
208
209#endif /* U_SHOW_CPLUSPLUS_API */
210
211#endif
212