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
