icuSources/common/unicode/locdspnm.h

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