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