Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/uldnames.h @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
rev   line source
jpayne@69 1 // © 2016 and later: Unicode, Inc. and others.
jpayne@69 2 // License & terms of use: http://www.unicode.org/copyright.html
jpayne@69 3 /*
jpayne@69 4 *******************************************************************************
jpayne@69 5 * Copyright (C) 2010-2016, International Business Machines Corporation and
jpayne@69 6 * others. All Rights Reserved.
jpayne@69 7 *******************************************************************************
jpayne@69 8 */
jpayne@69 9
jpayne@69 10 #ifndef __ULDNAMES_H__
jpayne@69 11 #define __ULDNAMES_H__
jpayne@69 12
jpayne@69 13 /**
jpayne@69 14 * \file
jpayne@69 15 * \brief C API: Provides display names of Locale ids and their components.
jpayne@69 16 */
jpayne@69 17
jpayne@69 18 #include "unicode/utypes.h"
jpayne@69 19 #include "unicode/localpointer.h"
jpayne@69 20 #include "unicode/uscript.h"
jpayne@69 21 #include "unicode/udisplaycontext.h"
jpayne@69 22
jpayne@69 23 /**
jpayne@69 24 * Enum used in LocaleDisplayNames::createInstance.
jpayne@69 25 * @stable ICU 4.4
jpayne@69 26 */
jpayne@69 27 typedef enum {
jpayne@69 28 /**
jpayne@69 29 * Use standard names when generating a locale name,
jpayne@69 30 * e.g. en_GB displays as 'English (United Kingdom)'.
jpayne@69 31 * @stable ICU 4.4
jpayne@69 32 */
jpayne@69 33 ULDN_STANDARD_NAMES = 0,
jpayne@69 34 /**
jpayne@69 35 * Use dialect names, when generating a locale name,
jpayne@69 36 * e.g. en_GB displays as 'British English'.
jpayne@69 37 * @stable ICU 4.4
jpayne@69 38 */
jpayne@69 39 ULDN_DIALECT_NAMES
jpayne@69 40 } UDialectHandling;
jpayne@69 41
jpayne@69 42 /**
jpayne@69 43 * Opaque C service object type for the locale display names API
jpayne@69 44 * @stable ICU 4.4
jpayne@69 45 */
jpayne@69 46 struct ULocaleDisplayNames;
jpayne@69 47
jpayne@69 48 /**
jpayne@69 49 * C typedef for struct ULocaleDisplayNames.
jpayne@69 50 * @stable ICU 4.4
jpayne@69 51 */
jpayne@69 52 typedef struct ULocaleDisplayNames ULocaleDisplayNames;
jpayne@69 53
jpayne@69 54 #if !UCONFIG_NO_FORMATTING
jpayne@69 55
jpayne@69 56 /**
jpayne@69 57 * Returns an instance of LocaleDisplayNames that returns names
jpayne@69 58 * formatted for the provided locale, using the provided
jpayne@69 59 * dialectHandling. The usual value for dialectHandling is
jpayne@69 60 * ULOC_STANDARD_NAMES.
jpayne@69 61 *
jpayne@69 62 * @param locale the display locale
jpayne@69 63 * @param dialectHandling how to select names for locales
jpayne@69 64 * @return a ULocaleDisplayNames instance
jpayne@69 65 * @param pErrorCode the status code
jpayne@69 66 * @stable ICU 4.4
jpayne@69 67 */
jpayne@69 68 U_STABLE ULocaleDisplayNames * U_EXPORT2
jpayne@69 69 uldn_open(const char * locale,
jpayne@69 70 UDialectHandling dialectHandling,
jpayne@69 71 UErrorCode *pErrorCode);
jpayne@69 72
jpayne@69 73 /**
jpayne@69 74 * Closes a ULocaleDisplayNames instance obtained from uldn_open().
jpayne@69 75 * @param ldn the ULocaleDisplayNames instance to be closed
jpayne@69 76 * @stable ICU 4.4
jpayne@69 77 */
jpayne@69 78 U_STABLE void U_EXPORT2
jpayne@69 79 uldn_close(ULocaleDisplayNames *ldn);
jpayne@69 80
jpayne@69 81 #if U_SHOW_CPLUSPLUS_API
jpayne@69 82
jpayne@69 83 U_NAMESPACE_BEGIN
jpayne@69 84
jpayne@69 85 /**
jpayne@69 86 * \class LocalULocaleDisplayNamesPointer
jpayne@69 87 * "Smart pointer" class, closes a ULocaleDisplayNames via uldn_close().
jpayne@69 88 * For most methods see the LocalPointerBase base class.
jpayne@69 89 *
jpayne@69 90 * @see LocalPointerBase
jpayne@69 91 * @see LocalPointer
jpayne@69 92 * @stable ICU 4.4
jpayne@69 93 */
jpayne@69 94 U_DEFINE_LOCAL_OPEN_POINTER(LocalULocaleDisplayNamesPointer, ULocaleDisplayNames, uldn_close);
jpayne@69 95
jpayne@69 96 U_NAMESPACE_END
jpayne@69 97
jpayne@69 98 #endif
jpayne@69 99
jpayne@69 100 /* getters for state */
jpayne@69 101
jpayne@69 102 /**
jpayne@69 103 * Returns the locale used to determine the display names. This is
jpayne@69 104 * not necessarily the same locale passed to {@link #uldn_open}.
jpayne@69 105 * @param ldn the LocaleDisplayNames instance
jpayne@69 106 * @return the display locale
jpayne@69 107 * @stable ICU 4.4
jpayne@69 108 */
jpayne@69 109 U_STABLE const char * U_EXPORT2
jpayne@69 110 uldn_getLocale(const ULocaleDisplayNames *ldn);
jpayne@69 111
jpayne@69 112 /**
jpayne@69 113 * Returns the dialect handling used in the display names.
jpayne@69 114 * @param ldn the LocaleDisplayNames instance
jpayne@69 115 * @return the dialect handling enum
jpayne@69 116 * @stable ICU 4.4
jpayne@69 117 */
jpayne@69 118 U_STABLE UDialectHandling U_EXPORT2
jpayne@69 119 uldn_getDialectHandling(const ULocaleDisplayNames *ldn);
jpayne@69 120
jpayne@69 121 /* names for entire locales */
jpayne@69 122
jpayne@69 123 /**
jpayne@69 124 * Returns the display name of the provided locale.
jpayne@69 125 * @param ldn the LocaleDisplayNames instance
jpayne@69 126 * @param locale the locale whose display name to return
jpayne@69 127 * @param result receives the display name
jpayne@69 128 * @param maxResultSize the size of the result buffer
jpayne@69 129 * @param pErrorCode the status code
jpayne@69 130 * @return the actual buffer size needed for the display name. If it's
jpayne@69 131 * greater than maxResultSize, the returned name will be truncated.
jpayne@69 132 * @stable ICU 4.4
jpayne@69 133 */
jpayne@69 134 U_STABLE int32_t U_EXPORT2
jpayne@69 135 uldn_localeDisplayName(const ULocaleDisplayNames *ldn,
jpayne@69 136 const char *locale,
jpayne@69 137 UChar *result,
jpayne@69 138 int32_t maxResultSize,
jpayne@69 139 UErrorCode *pErrorCode);
jpayne@69 140
jpayne@69 141 /* names for components of a locale */
jpayne@69 142
jpayne@69 143 /**
jpayne@69 144 * Returns the display name of the provided language code.
jpayne@69 145 * @param ldn the LocaleDisplayNames instance
jpayne@69 146 * @param lang the language code whose display name to return
jpayne@69 147 * @param result receives the display name
jpayne@69 148 * @param maxResultSize the size of the result buffer
jpayne@69 149 * @param pErrorCode the status code
jpayne@69 150 * @return the actual buffer size needed for the display name. If it's
jpayne@69 151 * greater than maxResultSize, the returned name will be truncated.
jpayne@69 152 * @stable ICU 4.4
jpayne@69 153 */
jpayne@69 154 U_STABLE int32_t U_EXPORT2
jpayne@69 155 uldn_languageDisplayName(const ULocaleDisplayNames *ldn,
jpayne@69 156 const char *lang,
jpayne@69 157 UChar *result,
jpayne@69 158 int32_t maxResultSize,
jpayne@69 159 UErrorCode *pErrorCode);
jpayne@69 160
jpayne@69 161 /**
jpayne@69 162 * Returns the display name of the provided script.
jpayne@69 163 * @param ldn the LocaleDisplayNames instance
jpayne@69 164 * @param script the script whose display name to return
jpayne@69 165 * @param result receives the display name
jpayne@69 166 * @param maxResultSize the size of the result buffer
jpayne@69 167 * @param pErrorCode the status code
jpayne@69 168 * @return the actual buffer size needed for the display name. If it's
jpayne@69 169 * greater than maxResultSize, the returned name will be truncated.
jpayne@69 170 * @stable ICU 4.4
jpayne@69 171 */
jpayne@69 172 U_STABLE int32_t U_EXPORT2
jpayne@69 173 uldn_scriptDisplayName(const ULocaleDisplayNames *ldn,
jpayne@69 174 const char *script,
jpayne@69 175 UChar *result,
jpayne@69 176 int32_t maxResultSize,
jpayne@69 177 UErrorCode *pErrorCode);
jpayne@69 178
jpayne@69 179 /**
jpayne@69 180 * Returns the display name of the provided script code.
jpayne@69 181 * @param ldn the LocaleDisplayNames instance
jpayne@69 182 * @param scriptCode the script code whose display name to return
jpayne@69 183 * @param result receives the display name
jpayne@69 184 * @param maxResultSize the size of the result buffer
jpayne@69 185 * @param pErrorCode the status code
jpayne@69 186 * @return the actual buffer size needed for the display name. If it's
jpayne@69 187 * greater than maxResultSize, the returned name will be truncated.
jpayne@69 188 * @stable ICU 4.4
jpayne@69 189 */
jpayne@69 190 U_STABLE int32_t U_EXPORT2
jpayne@69 191 uldn_scriptCodeDisplayName(const ULocaleDisplayNames *ldn,
jpayne@69 192 UScriptCode scriptCode,
jpayne@69 193 UChar *result,
jpayne@69 194 int32_t maxResultSize,
jpayne@69 195 UErrorCode *pErrorCode);
jpayne@69 196
jpayne@69 197 /**
jpayne@69 198 * Returns the display name of the provided region code.
jpayne@69 199 * @param ldn the LocaleDisplayNames instance
jpayne@69 200 * @param region the region code whose display name to return
jpayne@69 201 * @param result receives the display name
jpayne@69 202 * @param maxResultSize the size of the result buffer
jpayne@69 203 * @param pErrorCode the status code
jpayne@69 204 * @return the actual buffer size needed for the display name. If it's
jpayne@69 205 * greater than maxResultSize, the returned name will be truncated.
jpayne@69 206 * @stable ICU 4.4
jpayne@69 207 */
jpayne@69 208 U_STABLE int32_t U_EXPORT2
jpayne@69 209 uldn_regionDisplayName(const ULocaleDisplayNames *ldn,
jpayne@69 210 const char *region,
jpayne@69 211 UChar *result,
jpayne@69 212 int32_t maxResultSize,
jpayne@69 213 UErrorCode *pErrorCode);
jpayne@69 214
jpayne@69 215 /**
jpayne@69 216 * Returns the display name of the provided variant
jpayne@69 217 * @param ldn the LocaleDisplayNames instance
jpayne@69 218 * @param variant the variant whose display name to return
jpayne@69 219 * @param result receives the display name
jpayne@69 220 * @param maxResultSize the size of the result buffer
jpayne@69 221 * @param pErrorCode the status code
jpayne@69 222 * @return the actual buffer size needed for the display name. If it's
jpayne@69 223 * greater than maxResultSize, the returned name will be truncated.
jpayne@69 224 * @stable ICU 4.4
jpayne@69 225 */
jpayne@69 226 U_STABLE int32_t U_EXPORT2
jpayne@69 227 uldn_variantDisplayName(const ULocaleDisplayNames *ldn,
jpayne@69 228 const char *variant,
jpayne@69 229 UChar *result,
jpayne@69 230 int32_t maxResultSize,
jpayne@69 231 UErrorCode *pErrorCode);
jpayne@69 232
jpayne@69 233 /**
jpayne@69 234 * Returns the display name of the provided locale key
jpayne@69 235 * @param ldn the LocaleDisplayNames instance
jpayne@69 236 * @param key the locale key whose display name to return
jpayne@69 237 * @param result receives the display name
jpayne@69 238 * @param maxResultSize the size of the result buffer
jpayne@69 239 * @param pErrorCode the status code
jpayne@69 240 * @return the actual buffer size needed for the display name. If it's
jpayne@69 241 * greater than maxResultSize, the returned name will be truncated.
jpayne@69 242 * @stable ICU 4.4
jpayne@69 243 */
jpayne@69 244 U_STABLE int32_t U_EXPORT2
jpayne@69 245 uldn_keyDisplayName(const ULocaleDisplayNames *ldn,
jpayne@69 246 const char *key,
jpayne@69 247 UChar *result,
jpayne@69 248 int32_t maxResultSize,
jpayne@69 249 UErrorCode *pErrorCode);
jpayne@69 250
jpayne@69 251 /**
jpayne@69 252 * Returns the display name of the provided value (used with the provided key).
jpayne@69 253 * @param ldn the LocaleDisplayNames instance
jpayne@69 254 * @param key the locale key
jpayne@69 255 * @param value the locale key's value
jpayne@69 256 * @param result receives the display name
jpayne@69 257 * @param maxResultSize the size of the result buffer
jpayne@69 258 * @param pErrorCode the status code
jpayne@69 259 * @return the actual buffer size needed for the display name. If it's
jpayne@69 260 * greater than maxResultSize, the returned name will be truncated.
jpayne@69 261 * @stable ICU 4.4
jpayne@69 262 */
jpayne@69 263 U_STABLE int32_t U_EXPORT2
jpayne@69 264 uldn_keyValueDisplayName(const ULocaleDisplayNames *ldn,
jpayne@69 265 const char *key,
jpayne@69 266 const char *value,
jpayne@69 267 UChar *result,
jpayne@69 268 int32_t maxResultSize,
jpayne@69 269 UErrorCode *pErrorCode);
jpayne@69 270
jpayne@69 271 /**
jpayne@69 272 * Returns an instance of LocaleDisplayNames that returns names formatted
jpayne@69 273 * for the provided locale, using the provided UDisplayContext settings.
jpayne@69 274 *
jpayne@69 275 * @param locale The display locale
jpayne@69 276 * @param contexts List of one or more context settings (e.g. for dialect
jpayne@69 277 * handling, capitalization, etc.
jpayne@69 278 * @param length Number of items in the contexts list
jpayne@69 279 * @param pErrorCode Pointer to UErrorCode input/output status. If at entry this indicates
jpayne@69 280 * a failure status, the function will do nothing; otherwise this will be
jpayne@69 281 * updated with any new status from the function.
jpayne@69 282 * @return a ULocaleDisplayNames instance
jpayne@69 283 * @stable ICU 51
jpayne@69 284 */
jpayne@69 285 U_STABLE ULocaleDisplayNames * U_EXPORT2
jpayne@69 286 uldn_openForContext(const char * locale, UDisplayContext *contexts,
jpayne@69 287 int32_t length, UErrorCode *pErrorCode);
jpayne@69 288
jpayne@69 289 /**
jpayne@69 290 * Returns the UDisplayContext value for the specified UDisplayContextType.
jpayne@69 291 * @param ldn the ULocaleDisplayNames instance
jpayne@69 292 * @param type the UDisplayContextType whose value to return
jpayne@69 293 * @param pErrorCode Pointer to UErrorCode input/output status. If at entry this indicates
jpayne@69 294 * a failure status, the function will do nothing; otherwise this will be
jpayne@69 295 * updated with any new status from the function.
jpayne@69 296 * @return the UDisplayContextValue for the specified type.
jpayne@69 297 * @stable ICU 51
jpayne@69 298 */
jpayne@69 299 U_STABLE UDisplayContext U_EXPORT2
jpayne@69 300 uldn_getContext(const ULocaleDisplayNames *ldn, UDisplayContextType type,
jpayne@69 301 UErrorCode *pErrorCode);
jpayne@69 302
jpayne@69 303 #endif /* !UCONFIG_NO_FORMATTING */
jpayne@69 304 #endif /* __ULDNAMES_H__ */