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