jpayne@69: // © 2016 and later: Unicode, Inc. and others. jpayne@69: // License & terms of use: http://www.unicode.org/copyright.html jpayne@69: /* jpayne@69: ******************************************************************************* jpayne@69: * Copyright (C) 2010-2016, International Business Machines Corporation and jpayne@69: * others. All Rights Reserved. jpayne@69: ******************************************************************************* jpayne@69: */ jpayne@69: jpayne@69: #ifndef __ULDNAMES_H__ jpayne@69: #define __ULDNAMES_H__ jpayne@69: jpayne@69: /** jpayne@69: * \file jpayne@69: * \brief C API: Provides display names of Locale ids and their components. jpayne@69: */ jpayne@69: jpayne@69: #include "unicode/utypes.h" jpayne@69: #include "unicode/localpointer.h" jpayne@69: #include "unicode/uscript.h" jpayne@69: #include "unicode/udisplaycontext.h" jpayne@69: jpayne@69: /** jpayne@69: * Enum used in LocaleDisplayNames::createInstance. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: typedef enum { jpayne@69: /** jpayne@69: * Use standard names when generating a locale name, jpayne@69: * e.g. en_GB displays as 'English (United Kingdom)'. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: ULDN_STANDARD_NAMES = 0, jpayne@69: /** jpayne@69: * Use dialect names, when generating a locale name, jpayne@69: * e.g. en_GB displays as 'British English'. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: ULDN_DIALECT_NAMES jpayne@69: } UDialectHandling; jpayne@69: jpayne@69: /** jpayne@69: * Opaque C service object type for the locale display names API jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: struct ULocaleDisplayNames; jpayne@69: jpayne@69: /** jpayne@69: * C typedef for struct ULocaleDisplayNames. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: typedef struct ULocaleDisplayNames ULocaleDisplayNames; jpayne@69: jpayne@69: #if !UCONFIG_NO_FORMATTING jpayne@69: jpayne@69: /** jpayne@69: * Returns an instance of LocaleDisplayNames that returns names jpayne@69: * formatted for the provided locale, using the provided jpayne@69: * dialectHandling. The usual value for dialectHandling is jpayne@69: * ULOC_STANDARD_NAMES. jpayne@69: * jpayne@69: * @param locale the display locale jpayne@69: * @param dialectHandling how to select names for locales jpayne@69: * @return a ULocaleDisplayNames instance jpayne@69: * @param pErrorCode the status code jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: U_STABLE ULocaleDisplayNames * U_EXPORT2 jpayne@69: uldn_open(const char * locale, jpayne@69: UDialectHandling dialectHandling, jpayne@69: UErrorCode *pErrorCode); jpayne@69: jpayne@69: /** jpayne@69: * Closes a ULocaleDisplayNames instance obtained from uldn_open(). jpayne@69: * @param ldn the ULocaleDisplayNames instance to be closed jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: uldn_close(ULocaleDisplayNames *ldn); jpayne@69: jpayne@69: #if U_SHOW_CPLUSPLUS_API jpayne@69: jpayne@69: U_NAMESPACE_BEGIN jpayne@69: jpayne@69: /** jpayne@69: * \class LocalULocaleDisplayNamesPointer jpayne@69: * "Smart pointer" class, closes a ULocaleDisplayNames via uldn_close(). jpayne@69: * For most methods see the LocalPointerBase base class. jpayne@69: * jpayne@69: * @see LocalPointerBase jpayne@69: * @see LocalPointer jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: U_DEFINE_LOCAL_OPEN_POINTER(LocalULocaleDisplayNamesPointer, ULocaleDisplayNames, uldn_close); jpayne@69: jpayne@69: U_NAMESPACE_END jpayne@69: jpayne@69: #endif jpayne@69: jpayne@69: /* getters for state */ jpayne@69: jpayne@69: /** jpayne@69: * Returns the locale used to determine the display names. This is jpayne@69: * not necessarily the same locale passed to {@link #uldn_open}. jpayne@69: * @param ldn the LocaleDisplayNames instance jpayne@69: * @return the display locale jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: U_STABLE const char * U_EXPORT2 jpayne@69: uldn_getLocale(const ULocaleDisplayNames *ldn); jpayne@69: jpayne@69: /** jpayne@69: * Returns the dialect handling used in the display names. jpayne@69: * @param ldn the LocaleDisplayNames instance jpayne@69: * @return the dialect handling enum jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: U_STABLE UDialectHandling U_EXPORT2 jpayne@69: uldn_getDialectHandling(const ULocaleDisplayNames *ldn); jpayne@69: jpayne@69: /* names for entire locales */ jpayne@69: jpayne@69: /** jpayne@69: * Returns the display name of the provided locale. jpayne@69: * @param ldn the LocaleDisplayNames instance jpayne@69: * @param locale the locale whose display name to return jpayne@69: * @param result receives the display name jpayne@69: * @param maxResultSize the size of the result buffer jpayne@69: * @param pErrorCode the status code jpayne@69: * @return the actual buffer size needed for the display name. If it's jpayne@69: * greater than maxResultSize, the returned name will be truncated. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: uldn_localeDisplayName(const ULocaleDisplayNames *ldn, jpayne@69: const char *locale, jpayne@69: UChar *result, jpayne@69: int32_t maxResultSize, jpayne@69: UErrorCode *pErrorCode); jpayne@69: jpayne@69: /* names for components of a locale */ jpayne@69: jpayne@69: /** jpayne@69: * Returns the display name of the provided language code. jpayne@69: * @param ldn the LocaleDisplayNames instance jpayne@69: * @param lang the language code whose display name to return jpayne@69: * @param result receives the display name jpayne@69: * @param maxResultSize the size of the result buffer jpayne@69: * @param pErrorCode the status code jpayne@69: * @return the actual buffer size needed for the display name. If it's jpayne@69: * greater than maxResultSize, the returned name will be truncated. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: uldn_languageDisplayName(const ULocaleDisplayNames *ldn, jpayne@69: const char *lang, jpayne@69: UChar *result, jpayne@69: int32_t maxResultSize, jpayne@69: UErrorCode *pErrorCode); jpayne@69: jpayne@69: /** jpayne@69: * Returns the display name of the provided script. jpayne@69: * @param ldn the LocaleDisplayNames instance jpayne@69: * @param script the script whose display name to return jpayne@69: * @param result receives the display name jpayne@69: * @param maxResultSize the size of the result buffer jpayne@69: * @param pErrorCode the status code jpayne@69: * @return the actual buffer size needed for the display name. If it's jpayne@69: * greater than maxResultSize, the returned name will be truncated. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: uldn_scriptDisplayName(const ULocaleDisplayNames *ldn, jpayne@69: const char *script, jpayne@69: UChar *result, jpayne@69: int32_t maxResultSize, jpayne@69: UErrorCode *pErrorCode); jpayne@69: jpayne@69: /** jpayne@69: * Returns the display name of the provided script code. jpayne@69: * @param ldn the LocaleDisplayNames instance jpayne@69: * @param scriptCode the script code whose display name to return jpayne@69: * @param result receives the display name jpayne@69: * @param maxResultSize the size of the result buffer jpayne@69: * @param pErrorCode the status code jpayne@69: * @return the actual buffer size needed for the display name. If it's jpayne@69: * greater than maxResultSize, the returned name will be truncated. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: uldn_scriptCodeDisplayName(const ULocaleDisplayNames *ldn, jpayne@69: UScriptCode scriptCode, jpayne@69: UChar *result, jpayne@69: int32_t maxResultSize, jpayne@69: UErrorCode *pErrorCode); jpayne@69: jpayne@69: /** jpayne@69: * Returns the display name of the provided region code. jpayne@69: * @param ldn the LocaleDisplayNames instance jpayne@69: * @param region the region code whose display name to return jpayne@69: * @param result receives the display name jpayne@69: * @param maxResultSize the size of the result buffer jpayne@69: * @param pErrorCode the status code jpayne@69: * @return the actual buffer size needed for the display name. If it's jpayne@69: * greater than maxResultSize, the returned name will be truncated. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: uldn_regionDisplayName(const ULocaleDisplayNames *ldn, jpayne@69: const char *region, jpayne@69: UChar *result, jpayne@69: int32_t maxResultSize, jpayne@69: UErrorCode *pErrorCode); jpayne@69: jpayne@69: /** jpayne@69: * Returns the display name of the provided variant jpayne@69: * @param ldn the LocaleDisplayNames instance jpayne@69: * @param variant the variant whose display name to return jpayne@69: * @param result receives the display name jpayne@69: * @param maxResultSize the size of the result buffer jpayne@69: * @param pErrorCode the status code jpayne@69: * @return the actual buffer size needed for the display name. If it's jpayne@69: * greater than maxResultSize, the returned name will be truncated. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: uldn_variantDisplayName(const ULocaleDisplayNames *ldn, jpayne@69: const char *variant, jpayne@69: UChar *result, jpayne@69: int32_t maxResultSize, jpayne@69: UErrorCode *pErrorCode); jpayne@69: jpayne@69: /** jpayne@69: * Returns the display name of the provided locale key jpayne@69: * @param ldn the LocaleDisplayNames instance jpayne@69: * @param key the locale key whose display name to return jpayne@69: * @param result receives the display name jpayne@69: * @param maxResultSize the size of the result buffer jpayne@69: * @param pErrorCode the status code jpayne@69: * @return the actual buffer size needed for the display name. If it's jpayne@69: * greater than maxResultSize, the returned name will be truncated. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: uldn_keyDisplayName(const ULocaleDisplayNames *ldn, jpayne@69: const char *key, jpayne@69: UChar *result, jpayne@69: int32_t maxResultSize, jpayne@69: UErrorCode *pErrorCode); jpayne@69: jpayne@69: /** jpayne@69: * Returns the display name of the provided value (used with the provided key). jpayne@69: * @param ldn the LocaleDisplayNames instance jpayne@69: * @param key the locale key jpayne@69: * @param value the locale key's value jpayne@69: * @param result receives the display name jpayne@69: * @param maxResultSize the size of the result buffer jpayne@69: * @param pErrorCode the status code jpayne@69: * @return the actual buffer size needed for the display name. If it's jpayne@69: * greater than maxResultSize, the returned name will be truncated. jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: uldn_keyValueDisplayName(const ULocaleDisplayNames *ldn, jpayne@69: const char *key, jpayne@69: const char *value, jpayne@69: UChar *result, jpayne@69: int32_t maxResultSize, jpayne@69: UErrorCode *pErrorCode); jpayne@69: jpayne@69: /** jpayne@69: * Returns an instance of LocaleDisplayNames that returns names formatted jpayne@69: * for the provided locale, using the provided UDisplayContext settings. jpayne@69: * jpayne@69: * @param locale The display locale jpayne@69: * @param contexts List of one or more context settings (e.g. for dialect jpayne@69: * handling, capitalization, etc. jpayne@69: * @param length Number of items in the contexts list jpayne@69: * @param pErrorCode Pointer to UErrorCode input/output status. If at entry this indicates jpayne@69: * a failure status, the function will do nothing; otherwise this will be jpayne@69: * updated with any new status from the function. jpayne@69: * @return a ULocaleDisplayNames instance jpayne@69: * @stable ICU 51 jpayne@69: */ jpayne@69: U_STABLE ULocaleDisplayNames * U_EXPORT2 jpayne@69: uldn_openForContext(const char * locale, UDisplayContext *contexts, jpayne@69: int32_t length, UErrorCode *pErrorCode); jpayne@69: jpayne@69: /** jpayne@69: * Returns the UDisplayContext value for the specified UDisplayContextType. jpayne@69: * @param ldn the ULocaleDisplayNames instance jpayne@69: * @param type the UDisplayContextType whose value to return jpayne@69: * @param pErrorCode Pointer to UErrorCode input/output status. If at entry this indicates jpayne@69: * a failure status, the function will do nothing; otherwise this will be jpayne@69: * updated with any new status from the function. jpayne@69: * @return the UDisplayContextValue for the specified type. jpayne@69: * @stable ICU 51 jpayne@69: */ jpayne@69: U_STABLE UDisplayContext U_EXPORT2 jpayne@69: uldn_getContext(const ULocaleDisplayNames *ldn, UDisplayContextType type, jpayne@69: UErrorCode *pErrorCode); jpayne@69: jpayne@69: #endif /* !UCONFIG_NO_FORMATTING */ jpayne@69: #endif /* __ULDNAMES_H__ */