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 LOCDSPNM_H
jpayne@69: #define LOCDSPNM_H
jpayne@69: 
jpayne@69: #include "unicode/utypes.h"
jpayne@69: 
jpayne@69: #if U_SHOW_CPLUSPLUS_API
jpayne@69: 
jpayne@69: /**
jpayne@69:  * \file
jpayne@69:  * \brief C++ API: Provides display names of Locale and its components.
jpayne@69:  */
jpayne@69: 
jpayne@69: #if !UCONFIG_NO_FORMATTING
jpayne@69: 
jpayne@69: #include "unicode/locid.h"
jpayne@69: #include "unicode/strenum.h"
jpayne@69: #include "unicode/uscript.h"
jpayne@69: #include "unicode/uldnames.h"
jpayne@69: #include "unicode/udisplaycontext.h"
jpayne@69: 
jpayne@69: U_NAMESPACE_BEGIN
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Returns display names of Locales and components of Locales. For
jpayne@69:  * more information on language, script, region, variant, key, and
jpayne@69:  * values, see Locale.
jpayne@69:  * @stable ICU 4.4
jpayne@69:  */
jpayne@69: class U_COMMON_API LocaleDisplayNames : public UObject {
jpayne@69: public:
jpayne@69:     /**
jpayne@69:      * Destructor.
jpayne@69:      * @stable ICU 4.4
jpayne@69:      */
jpayne@69:     virtual ~LocaleDisplayNames();
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * Convenience overload of
jpayne@69:      * {@link #createInstance(const Locale& locale, UDialectHandling dialectHandling)}
jpayne@69:      * that specifies STANDARD dialect handling.
jpayne@69:      * @param locale the display locale
jpayne@69:      * @return a LocaleDisplayNames instance
jpayne@69:      * @stable ICU 4.4
jpayne@69:      */
jpayne@69:     inline static LocaleDisplayNames* U_EXPORT2 createInstance(const Locale& locale);
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.
jpayne@69:      *
jpayne@69:      * @param locale the display locale
jpayne@69:      * @param dialectHandling how to select names for locales
jpayne@69:      * @return a LocaleDisplayNames instance
jpayne@69:      * @stable ICU 4.4
jpayne@69:      */
jpayne@69:     static LocaleDisplayNames* U_EXPORT2 createInstance(const Locale& locale,
jpayne@69:                             UDialectHandling dialectHandling);
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:      * @return a LocaleDisplayNames instance
jpayne@69:      * @stable ICU 51
jpayne@69:      */
jpayne@69:     static LocaleDisplayNames* U_EXPORT2 createInstance(const Locale& locale,
jpayne@69:                             UDisplayContext *contexts, int32_t length);
jpayne@69: 
jpayne@69:     // getters for state
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 #createInstance}.
jpayne@69:      * @return the display locale
jpayne@69:      * @stable ICU 4.4
jpayne@69:      */
jpayne@69:     virtual const Locale& getLocale() const = 0;
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * Returns the dialect handling used in the display names.
jpayne@69:      * @return the dialect handling enum
jpayne@69:      * @stable ICU 4.4
jpayne@69:      */
jpayne@69:     virtual UDialectHandling getDialectHandling() const = 0;
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * Returns the UDisplayContext value for the specified UDisplayContextType.
jpayne@69:      * @param type the UDisplayContextType whose value to return
jpayne@69:      * @return the UDisplayContext for the specified type.
jpayne@69:      * @stable ICU 51
jpayne@69:      */
jpayne@69:     virtual UDisplayContext getContext(UDisplayContextType type) const = 0;
jpayne@69: 
jpayne@69:     // names for entire locales
jpayne@69:     /**
jpayne@69:      * Returns the display name of the provided locale.
jpayne@69:      * @param locale the locale whose display name to return
jpayne@69:      * @param result receives the locale's display name
jpayne@69:      * @return the display name of the provided locale
jpayne@69:      * @stable ICU 4.4
jpayne@69:      */
jpayne@69:     virtual UnicodeString& localeDisplayName(const Locale& locale,
jpayne@69:                          UnicodeString& result) const = 0;
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * Returns the display name of the provided locale id.
jpayne@69:      * @param localeId the id of the locale whose display name to return
jpayne@69:      * @param result receives the locale's display name
jpayne@69:      * @return the display name of the provided locale
jpayne@69:      * @stable ICU 4.4
jpayne@69:      */
jpayne@69:     virtual UnicodeString& localeDisplayName(const char* localeId,
jpayne@69:                          UnicodeString& result) const = 0;
jpayne@69: 
jpayne@69:     // names for components of a locale id
jpayne@69:     /**
jpayne@69:      * Returns the display name of the provided language code.
jpayne@69:      * @param lang the language code
jpayne@69:      * @param result receives the language code's display name
jpayne@69:      * @return the display name of the provided language code
jpayne@69:      * @stable ICU 4.4
jpayne@69:      */
jpayne@69:     virtual UnicodeString& languageDisplayName(const char* lang,
jpayne@69:                            UnicodeString& result) const = 0;
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * Returns the display name of the provided script code.
jpayne@69:      * @param script the script code
jpayne@69:      * @param result receives the script code's display name
jpayne@69:      * @return the display name of the provided script code
jpayne@69:      * @stable ICU 4.4
jpayne@69:      */
jpayne@69:     virtual UnicodeString& scriptDisplayName(const char* script,
jpayne@69:                          UnicodeString& result) const = 0;
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * Returns the display name of the provided script code.
jpayne@69:      * @param scriptCode the script code number
jpayne@69:      * @param result receives the script code's display name
jpayne@69:      * @return the display name of the provided script code
jpayne@69:      * @stable ICU 4.4
jpayne@69:      */
jpayne@69:     virtual UnicodeString& scriptDisplayName(UScriptCode scriptCode,
jpayne@69:                          UnicodeString& result) const = 0;
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * Returns the display name of the provided region code.
jpayne@69:      * @param region the region code
jpayne@69:      * @param result receives the region code's display name
jpayne@69:      * @return the display name of the provided region code
jpayne@69:      * @stable ICU 4.4
jpayne@69:      */
jpayne@69:     virtual UnicodeString& regionDisplayName(const char* region,
jpayne@69:                          UnicodeString& result) const = 0;
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * Returns the display name of the provided variant.
jpayne@69:      * @param variant the variant string
jpayne@69:      * @param result receives the variant's display name
jpayne@69:      * @return the display name of the provided variant
jpayne@69:      * @stable ICU 4.4
jpayne@69:      */
jpayne@69:     virtual UnicodeString& variantDisplayName(const char* variant,
jpayne@69:                           UnicodeString& result) const = 0;
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * Returns the display name of the provided locale key.
jpayne@69:      * @param key the locale key name
jpayne@69:      * @param result receives the locale key's display name
jpayne@69:      * @return the display name of the provided locale key
jpayne@69:      * @stable ICU 4.4
jpayne@69:      */
jpayne@69:     virtual UnicodeString& keyDisplayName(const char* key,
jpayne@69:                       UnicodeString& result) const = 0;
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * Returns the display name of the provided value (used with the provided key).
jpayne@69:      * @param key the locale key name
jpayne@69:      * @param value the locale key's value
jpayne@69:      * @param result receives the value's display name
jpayne@69:      * @return the display name of the provided value
jpayne@69:      * @stable ICU 4.4
jpayne@69:      */
jpayne@69:     virtual UnicodeString& keyValueDisplayName(const char* key, const char* value,
jpayne@69:                            UnicodeString& result) const = 0;
jpayne@69: };
jpayne@69: 
jpayne@69: inline LocaleDisplayNames* LocaleDisplayNames::createInstance(const Locale& locale) {
jpayne@69:   return LocaleDisplayNames::createInstance(locale, ULDN_STANDARD_NAMES);
jpayne@69: }
jpayne@69: 
jpayne@69: U_NAMESPACE_END
jpayne@69: 
jpayne@69: #endif
jpayne@69: 
jpayne@69: #endif /* U_SHOW_CPLUSPLUS_API */
jpayne@69: 
jpayne@69: #endif