icuSources/i18n/unicode/uldnames.h

   1 /*
   2 *******************************************************************************
   3 *   Copyright (C) 2010, International Business Machines Corporation and       *
   4 *   others.  All Rights Reserved.                                             *
   5 *******************************************************************************
   6 */
   7
   8 #ifndef __ULDNAMES_H__
   9 #define __ULDNAMES_H__
  10
  11 /**
  12  * \file
  13  * \brief C++ API: Provides display names of Locale ids and their components.
  14  */
  15
  16 #include "unicode/utypes.h"
  17 #include "unicode/localpointer.h"
  18 #include "unicode/uscript.h"
  19
  20 /**
  21  * Enum used in LocaleDisplayNames::createInstance.
  22  * @stable ICU 4.4
  23  */
  24 typedef enum {
  25     /**
  26      * Use standard names when generating a locale name,
  27      * e.g. en_GB displays as 'English (United Kingdom)'.
  28      * @stable ICU 4.4
  29      */
  30     ULDN_STANDARD_NAMES = 0,
  31     /**
  32      * Use dialect names, when generating a locale name,
  33      * e.g. en_GB displays as 'British English'.
  34      * @stable ICU 4.4
  35      */
  36     ULDN_DIALECT_NAMES
  37 } UDialectHandling;
  38
  39 /**
  40  * Opaque C service object type for the locale display names API
  41  * @stable ICU 4.4
  42  */
  43 struct ULocaleDisplayNames;
  44
  45 /**
  46  * C typedef for struct ULocaleDisplayNames.
  47  * @stable ICU 4.4
  48  */
  49 typedef struct ULocaleDisplayNames ULocaleDisplayNames;
  50
  51 #if !UCONFIG_NO_FORMATTING
  52
  53 /**
  54  * Returns an instance of LocaleDisplayNames that returns names
  55  * formatted for the provided locale, using the provided
  56  * dialectHandling.  The usual value for dialectHandling is
  57  * ULOC_STANDARD_NAMES.
  58  *
  59  * @param locale the display locale
  60  * @param dialectHandling how to select names for locales
  61  * @return a ULocaleDisplayNames instance
  62  * @param pErrorCode the status code
  63  * @stable ICU 4.4
  64  */
  65 U_STABLE ULocaleDisplayNames * U_EXPORT2
  66 uldn_open(const char * locale,
  67           UDialectHandling dialectHandling,
  68           UErrorCode *pErrorCode);
  69
  70 /**
  71  * Closes a ULocaleDisplayNames instance obtained from uldn_open().
  72  * @param ldn the ULocaleDisplayNames instance to be closed
  73  * @stable ICU 4.4
  74  */
  75 U_STABLE void U_EXPORT2
  76 uldn_close(ULocaleDisplayNames *ldn);
  77
  78 #if U_SHOW_CPLUSPLUS_API
  79
  80 U_NAMESPACE_BEGIN
  81
  82 /**
  83  * \class LocalULocaleDisplayNamesPointer
  84  * "Smart pointer" class, closes a ULocaleDisplayNames via uldn_close().
  85  * For most methods see the LocalPointerBase base class.
  86  *
  87  * @see LocalPointerBase
  88  * @see LocalPointer
  89  * @stable ICU 4.4
  90  */
  91 U_DEFINE_LOCAL_OPEN_POINTER(LocalULocaleDisplayNamesPointer, ULocaleDisplayNames, uldn_close);
  92
  93 U_NAMESPACE_END
  94
  95 #endif
  96
  97 /* getters for state */
  98
  99 /**
 100  * Returns the locale used to determine the display names. This is
 101  * not necessarily the same locale passed to {@link #uldn_open}.
 102  * @param ldn the LocaleDisplayNames instance
 103  * @return the display locale
 104  * @stable ICU 4.4
 105  */
 106 U_STABLE const char * U_EXPORT2
 107 uldn_getLocale(const ULocaleDisplayNames *ldn);
 108
 109 /**
 110  * Returns the dialect handling used in the display names.
 111  * @param ldn the LocaleDisplayNames instance
 112  * @return the dialect handling enum
 113  * @stable ICU 4.4
 114  */
 115 U_STABLE UDialectHandling U_EXPORT2
 116 uldn_getDialectHandling(const ULocaleDisplayNames *ldn);
 117
 118 /* names for entire locales */
 119
 120 /**
 121  * Returns the display name of the provided locale.
 122  * @param ldn the LocaleDisplayNames instance
 123  * @param locale the locale whose display name to return
 124  * @param result receives the display name
 125  * @param maxResultSize the size of the result buffer
 126  * @param pErrorCode the status code
 127  * @return the actual buffer size needed for the display name.  If it's
 128  * greater than maxResultSize, the returned name will be truncated.
 129  * @stable ICU 4.4
 130  */
 131 U_STABLE int32_t U_EXPORT2
 132 uldn_localeDisplayName(const ULocaleDisplayNames *ldn,
 133                        const char *locale,
 134                        UChar *result,
 135                        int32_t maxResultSize,
 136                        UErrorCode *pErrorCode);
 137
 138 /* names for components of a locale */
 139
 140 /**
 141  * Returns the display name of the provided language code.
 142  * @param ldn the LocaleDisplayNames instance
 143  * @param lang the language code whose display name to return
 144  * @param result receives the display name
 145  * @param maxResultSize the size of the result buffer
 146  * @param pErrorCode the status code
 147  * @return the actual buffer size needed for the display name.  If it's
 148  * greater than maxResultSize, the returned name will be truncated.
 149  * @stable ICU 4.4
 150  */
 151 U_STABLE int32_t U_EXPORT2
 152 uldn_languageDisplayName(const ULocaleDisplayNames *ldn,
 153                          const char *lang,
 154                          UChar *result,
 155                          int32_t maxResultSize,
 156                          UErrorCode *pErrorCode);
 157
 158 /**
 159  * Returns the display name of the provided script.
 160  * @param ldn the LocaleDisplayNames instance
 161  * @param script the script whose display name to return
 162  * @param result receives the display name
 163  * @param maxResultSize the size of the result buffer
 164  * @param pErrorCode the status code
 165  * @return the actual buffer size needed for the display name.  If it's
 166  * greater than maxResultSize, the returned name will be truncated.
 167  * @stable ICU 4.4
 168  */
 169 U_STABLE int32_t U_EXPORT2
 170 uldn_scriptDisplayName(const ULocaleDisplayNames *ldn,
 171                        const char *script,
 172                        UChar *result,
 173                        int32_t maxResultSize,
 174                        UErrorCode *pErrorCode);
 175
 176 /**
 177  * Returns the display name of the provided script code.
 178  * @param ldn the LocaleDisplayNames instance
 179  * @param scriptCode the script code whose display name to return
 180  * @param result receives the display name
 181  * @param maxResultSize the size of the result buffer
 182  * @param pErrorCode the status code
 183  * @return the actual buffer size needed for the display name.  If it's
 184  * greater than maxResultSize, the returned name will be truncated.
 185  * @stable ICU 4.4
 186  */
 187 U_STABLE int32_t U_EXPORT2
 188 uldn_scriptCodeDisplayName(const ULocaleDisplayNames *ldn,
 189                            UScriptCode scriptCode,
 190                            UChar *result,
 191                            int32_t maxResultSize,
 192                            UErrorCode *pErrorCode);
 193
 194 /**
 195  * Returns the display name of the provided region code.
 196  * @param ldn the LocaleDisplayNames instance
 197  * @param region the region code whose display name to return
 198  * @param result receives the display name
 199  * @param maxResultSize the size of the result buffer
 200  * @param pErrorCode the status code
 201  * @return the actual buffer size needed for the display name.  If it's
 202  * greater than maxResultSize, the returned name will be truncated.
 203  * @stable ICU 4.4
 204  */
 205 U_STABLE int32_t U_EXPORT2
 206 uldn_regionDisplayName(const ULocaleDisplayNames *ldn,
 207                        const char *region,
 208                        UChar *result,
 209                        int32_t maxResultSize,
 210                        UErrorCode *pErrorCode);
 211
 212 /**
 213  * Returns the display name of the provided variant
 214  * @param ldn the LocaleDisplayNames instance
 215  * @param variant the variant whose display name to return
 216  * @param result receives the display name
 217  * @param maxResultSize the size of the result buffer
 218  * @param pErrorCode the status code
 219  * @return the actual buffer size needed for the display name.  If it's
 220  * greater than maxResultSize, the returned name will be truncated.
 221  * @stable ICU 4.4
 222  */
 223 U_STABLE int32_t U_EXPORT2
 224 uldn_variantDisplayName(const ULocaleDisplayNames *ldn,
 225                         const char *variant,
 226                         UChar *result,
 227                         int32_t maxResultSize,
 228                         UErrorCode *pErrorCode);
 229
 230 /**
 231  * Returns the display name of the provided locale key
 232  * @param ldn the LocaleDisplayNames instance
 233  * @param key the locale key whose display name to return
 234  * @param result receives the display name
 235  * @param maxResultSize the size of the result buffer
 236  * @param pErrorCode the status code
 237  * @return the actual buffer size needed for the display name.  If it's
 238  * greater than maxResultSize, the returned name will be truncated.
 239  * @stable ICU 4.4
 240  */
 241 U_STABLE int32_t U_EXPORT2
 242 uldn_keyDisplayName(const ULocaleDisplayNames *ldn,
 243                     const char *key,
 244                     UChar *result,
 245                     int32_t maxResultSize,
 246                     UErrorCode *pErrorCode);
 247
 248 /**
 249  * Returns the display name of the provided value (used with the provided key).
 250  * @param ldn the LocaleDisplayNames instance
 251  * @param key the locale key
 252  * @param value the locale key's value
 253  * @param result receives the display name
 254  * @param maxResultSize the size of the result buffer
 255  * @param pErrorCode the status code
 256  * @return the actual buffer size needed for the display name.  If it's
 257  * greater than maxResultSize, the returned name will be truncated.
 258  * @stable ICU 4.4
 259  */
 260 U_STABLE int32_t U_EXPORT2
 261 uldn_keyValueDisplayName(const ULocaleDisplayNames *ldn,
 262                          const char *key,
 263                          const char *value,
 264                          UChar *result,
 265                          int32_t maxResultSize,
 266                          UErrorCode *pErrorCode);
 267
 268
 269 #endif  /* !UCONFIG_NO_FORMATTING */
 270 #endif  /* __ULDNAMES_H__ */