icuSources/common/unicode/locdspnm.h

   1 /*
   2 ******************************************************************************
   3 * Copyright (C) 2010-2016, International Business Machines Corporation and
   4 * others. All Rights Reserved.
   5 ******************************************************************************
   6 */
   7
   8 #ifndef LOCDSPNM_H
   9 #define LOCDSPNM_H
  10
  11 #include "unicode/utypes.h"
  12
  13 /**
  14  * \file
  15  * \brief C++ API: Provides display names of Locale and its components.
  16  */
  17
  18 #if !UCONFIG_NO_FORMATTING
  19
  20 #include "unicode/locid.h"
  21 #include "unicode/uscript.h"
  22 #include "unicode/uldnames.h"
  23 #include "unicode/udisplaycontext.h"
  24
  25 U_NAMESPACE_BEGIN
  26
  27 /**
  28  * Returns display names of Locales and components of Locales. For
  29  * more information on language, script, region, variant, key, and
  30  * values, see Locale.
  31  * @stable ICU 4.4
  32  */
  33 class U_COMMON_API LocaleDisplayNames : public UObject {
  34 public:
  35     /**
  36      * Destructor.
  37      * @stable ICU 4.4
  38      */
  39     virtual ~LocaleDisplayNames();
  40
  41     /**
  42      * Convenience overload of
  43      * {@link #createInstance(const Locale& locale, UDialectHandling dialectHandling)}
  44      * that specifies STANDARD dialect handling.
  45      * @param locale the display locale
  46      * @return a LocaleDisplayNames instance
  47      * @stable ICU 4.4
  48      */
  49     static LocaleDisplayNames* U_EXPORT2 createInstance(const Locale& locale);
  50
  51     /**
  52      * Returns an instance of LocaleDisplayNames that returns names
  53      * formatted for the provided locale, using the provided
  54      * dialectHandling.
  55      *
  56      * @param locale the display locale
  57      * @param dialectHandling how to select names for locales
  58      * @return a LocaleDisplayNames instance
  59      * @stable ICU 4.4
  60      */
  61     static LocaleDisplayNames* U_EXPORT2 createInstance(const Locale& locale,
  62                             UDialectHandling dialectHandling);
  63
  64     /**
  65      * Returns an instance of LocaleDisplayNames that returns names formatted
  66      * for the provided locale, using the provided UDisplayContext settings.
  67      *
  68      * @param locale the display locale
  69      * @param contexts List of one or more context settings (e.g. for dialect
  70      *               handling, capitalization, etc.
  71      * @param length Number of items in the contexts list
  72      * @return a LocaleDisplayNames instance
  73      * @stable ICU 51
  74      */
  75     static LocaleDisplayNames* U_EXPORT2 createInstance(const Locale& locale,
  76                             UDisplayContext *contexts, int32_t length);
  77
  78     // getters for state
  79     /**
  80      * Returns the locale used to determine the display names. This is
  81      * not necessarily the same locale passed to {@link #createInstance}.
  82      * @return the display locale
  83      * @stable ICU 4.4
  84      */
  85     virtual const Locale& getLocale() const = 0;
  86
  87     /**
  88      * Returns the dialect handling used in the display names.
  89      * @return the dialect handling enum
  90      * @stable ICU 4.4
  91      */
  92     virtual UDialectHandling getDialectHandling() const = 0;
  93
  94     /**
  95      * Returns the UDisplayContext value for the specified UDisplayContextType.
  96      * @param type the UDisplayContextType whose value to return
  97      * @return the UDisplayContext for the specified type.
  98      * @stable ICU 51
  99      */
 100     virtual UDisplayContext getContext(UDisplayContextType type) const = 0;
 101
 102     // names for entire locales
 103     /**
 104      * Returns the display name of the provided locale.
 105      * @param locale the locale whose display name to return
 106      * @param result receives the locale's display name
 107      * @return the display name of the provided locale
 108      * @stable ICU 4.4
 109      */
 110     virtual UnicodeString& localeDisplayName(const Locale& locale,
 111                          UnicodeString& result) const = 0;
 112
 113     /**
 114      * Returns the display name of the provided locale id.
 115      * @param localeId the id of the locale whose display name to return
 116      * @param result receives the locale's display name
 117      * @return the display name of the provided locale
 118      * @stable ICU 4.4
 119      */
 120     virtual UnicodeString& localeDisplayName(const char* localeId,
 121                          UnicodeString& result) const = 0;
 122
 123     // names for components of a locale id
 124     /**
 125      * Returns the display name of the provided language code.
 126      * @param lang the language code
 127      * @param result receives the language code's display name
 128      * @return the display name of the provided language code
 129      * @stable ICU 4.4
 130      */
 131     virtual UnicodeString& languageDisplayName(const char* lang,
 132                            UnicodeString& result) const = 0;
 133
 134     /**
 135      * Returns the display name of the provided script code.
 136      * @param script the script code
 137      * @param result receives the script code's display name
 138      * @return the display name of the provided script code
 139      * @stable ICU 4.4
 140      */
 141     virtual UnicodeString& scriptDisplayName(const char* script,
 142                          UnicodeString& result) const = 0;
 143
 144     /**
 145      * Returns the display name of the provided script code.
 146      * @param scriptCode the script code number
 147      * @param result receives the script code's display name
 148      * @return the display name of the provided script code
 149      * @stable ICU 4.4
 150      */
 151     virtual UnicodeString& scriptDisplayName(UScriptCode scriptCode,
 152                          UnicodeString& result) const = 0;
 153
 154     /**
 155      * Returns the display name of the provided region code.
 156      * @param region the region code
 157      * @param result receives the region code's display name
 158      * @return the display name of the provided region code
 159      * @stable ICU 4.4
 160      */
 161     virtual UnicodeString& regionDisplayName(const char* region,
 162                          UnicodeString& result) const = 0;
 163
 164     /**
 165      * Returns the display name of the provided variant.
 166      * @param variant the variant string
 167      * @param result receives the variant's display name
 168      * @return the display name of the provided variant
 169      * @stable ICU 4.4
 170      */
 171     virtual UnicodeString& variantDisplayName(const char* variant,
 172                           UnicodeString& result) const = 0;
 173
 174     /**
 175      * Returns the display name of the provided locale key.
 176      * @param key the locale key name
 177      * @param result receives the locale key's display name
 178      * @return the display name of the provided locale key
 179      * @stable ICU 4.4
 180      */
 181     virtual UnicodeString& keyDisplayName(const char* key,
 182                       UnicodeString& result) const = 0;
 183
 184     /**
 185      * Returns the display name of the provided value (used with the provided key).
 186      * @param key the locale key name
 187      * @param value the locale key's value
 188      * @param result receives the value's display name
 189      * @return the display name of the provided value
 190      * @stable ICU 4.4
 191      */
 192     virtual UnicodeString& keyValueDisplayName(const char* key, const char* value,
 193                            UnicodeString& result) const = 0;
 194 };
 195
 196 inline LocaleDisplayNames* LocaleDisplayNames::createInstance(const Locale& locale) {
 197   return LocaleDisplayNames::createInstance(locale, ULDN_STANDARD_NAMES);
 198 }
 199
 200 U_NAMESPACE_END
 201
 202 #endif
 203
 204 #endif