source/common/unicode/locdspnm.h

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