icuSources/common/unicode/uldnames.h

   1 /*
   2 *******************************************************************************
   3 *   Copyright (C) 2010-2016, 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 #include "unicode/udisplaycontext.h"
  20
  21 /**
  22  * Enum used in LocaleDisplayNames::createInstance.
  23  * @stable ICU 4.4
  24  */
  25 typedef enum {
  26     /**
  27      * Use standard names when generating a locale name,
  28      * e.g. en_GB displays as 'English (United Kingdom)'.
  29      * @stable ICU 4.4
  30      */
  31     ULDN_STANDARD_NAMES = 0,
  32     /**
  33      * Use dialect names, when generating a locale name,
  34      * e.g. en_GB displays as 'British English'.
  35      * @stable ICU 4.4
  36      */
  37     ULDN_DIALECT_NAMES
  38 } UDialectHandling;
  39
  40 /**
  41  * Opaque C service object type for the locale display names API
  42  * @stable ICU 4.4
  43  */
  44 struct ULocaleDisplayNames;
  45
  46 /**
  47  * C typedef for struct ULocaleDisplayNames.
  48  * @stable ICU 4.4
  49  */
  50 typedef struct ULocaleDisplayNames ULocaleDisplayNames;
  51
  52 #if !UCONFIG_NO_FORMATTING
  53
  54 /**
  55  * Returns an instance of LocaleDisplayNames that returns names
  56  * formatted for the provided locale, using the provided
  57  * dialectHandling.  The usual value for dialectHandling is
  58  * ULOC_STANDARD_NAMES.
  59  *
  60  * @param locale the display locale
  61  * @param dialectHandling how to select names for locales
  62  * @return a ULocaleDisplayNames instance
  63  * @param pErrorCode the status code
  64  * @stable ICU 4.4
  65  */
  66 U_STABLE ULocaleDisplayNames * U_EXPORT2
  67 uldn_open(const char * locale,
  68           UDialectHandling dialectHandling,
  69           UErrorCode *pErrorCode);
  70
  71 /**
  72  * Closes a ULocaleDisplayNames instance obtained from uldn_open().
  73  * @param ldn the ULocaleDisplayNames instance to be closed
  74  * @stable ICU 4.4
  75  */
  76 U_STABLE void U_EXPORT2
  77 uldn_close(ULocaleDisplayNames *ldn);
  78
  79 #if U_SHOW_CPLUSPLUS_API
  80
  81 U_NAMESPACE_BEGIN
  82
  83 /**
  84  * \class LocalULocaleDisplayNamesPointer
  85  * "Smart pointer" class, closes a ULocaleDisplayNames via uldn_close().
  86  * For most methods see the LocalPointerBase base class.
  87  *
  88  * @see LocalPointerBase
  89  * @see LocalPointer
  90  * @stable ICU 4.4
  91  */
  92 U_DEFINE_LOCAL_OPEN_POINTER(LocalULocaleDisplayNamesPointer, ULocaleDisplayNames, uldn_close);
  93
  94 U_NAMESPACE_END
  95
  96 #endif
  97
  98 /* getters for state */
  99
 100 /**
 101  * Returns the locale used to determine the display names. This is
 102  * not necessarily the same locale passed to {@link #uldn_open}.
 103  * @param ldn the LocaleDisplayNames instance
 104  * @return the display locale
 105  * @stable ICU 4.4
 106  */
 107 U_STABLE const char * U_EXPORT2
 108 uldn_getLocale(const ULocaleDisplayNames *ldn);
 109
 110 /**
 111  * Returns the dialect handling used in the display names.
 112  * @param ldn the LocaleDisplayNames instance
 113  * @return the dialect handling enum
 114  * @stable ICU 4.4
 115  */
 116 U_STABLE UDialectHandling U_EXPORT2
 117 uldn_getDialectHandling(const ULocaleDisplayNames *ldn);
 118
 119 /* names for entire locales */
 120
 121 /**
 122  * Returns the display name of the provided locale.
 123  * @param ldn the LocaleDisplayNames instance
 124  * @param locale the locale whose display name to return
 125  * @param result receives the display name
 126  * @param maxResultSize the size of the result buffer
 127  * @param pErrorCode the status code
 128  * @return the actual buffer size needed for the display name.  If it's
 129  * greater than maxResultSize, the returned name will be truncated.
 130  * @stable ICU 4.4
 131  */
 132 U_STABLE int32_t U_EXPORT2
 133 uldn_localeDisplayName(const ULocaleDisplayNames *ldn,
 134                        const char *locale,
 135                        UChar *result,
 136                        int32_t maxResultSize,
 137                        UErrorCode *pErrorCode);
 138
 139 /* names for components of a locale */
 140
 141 /**
 142  * Returns the display name of the provided language code.
 143  * @param ldn the LocaleDisplayNames instance
 144  * @param lang the language code whose display name to return
 145  * @param result receives the display name
 146  * @param maxResultSize the size of the result buffer
 147  * @param pErrorCode the status code
 148  * @return the actual buffer size needed for the display name.  If it's
 149  * greater than maxResultSize, the returned name will be truncated.
 150  * @stable ICU 4.4
 151  */
 152 U_STABLE int32_t U_EXPORT2
 153 uldn_languageDisplayName(const ULocaleDisplayNames *ldn,
 154                          const char *lang,
 155                          UChar *result,
 156                          int32_t maxResultSize,
 157                          UErrorCode *pErrorCode);
 158
 159 /**
 160  * Returns the display name of the provided script.
 161  * @param ldn the LocaleDisplayNames instance
 162  * @param script the script whose display name to return
 163  * @param result receives the display name
 164  * @param maxResultSize the size of the result buffer
 165  * @param pErrorCode the status code
 166  * @return the actual buffer size needed for the display name.  If it's
 167  * greater than maxResultSize, the returned name will be truncated.
 168  * @stable ICU 4.4
 169  */
 170 U_STABLE int32_t U_EXPORT2
 171 uldn_scriptDisplayName(const ULocaleDisplayNames *ldn,
 172                        const char *script,
 173                        UChar *result,
 174                        int32_t maxResultSize,
 175                        UErrorCode *pErrorCode);
 176
 177 /**
 178  * Returns the display name of the provided script code.
 179  * @param ldn the LocaleDisplayNames instance
 180  * @param scriptCode the script code whose display name to return
 181  * @param result receives the display name
 182  * @param maxResultSize the size of the result buffer
 183  * @param pErrorCode the status code
 184  * @return the actual buffer size needed for the display name.  If it's
 185  * greater than maxResultSize, the returned name will be truncated.
 186  * @stable ICU 4.4
 187  */
 188 U_STABLE int32_t U_EXPORT2
 189 uldn_scriptCodeDisplayName(const ULocaleDisplayNames *ldn,
 190                            UScriptCode scriptCode,
 191                            UChar *result,
 192                            int32_t maxResultSize,
 193                            UErrorCode *pErrorCode);
 194
 195 /**
 196  * Returns the display name of the provided region code.
 197  * @param ldn the LocaleDisplayNames instance
 198  * @param region the region code whose display name to return
 199  * @param result receives the display name
 200  * @param maxResultSize the size of the result buffer
 201  * @param pErrorCode the status code
 202  * @return the actual buffer size needed for the display name.  If it's
 203  * greater than maxResultSize, the returned name will be truncated.
 204  * @stable ICU 4.4
 205  */
 206 U_STABLE int32_t U_EXPORT2
 207 uldn_regionDisplayName(const ULocaleDisplayNames *ldn,
 208                        const char *region,
 209                        UChar *result,
 210                        int32_t maxResultSize,
 211                        UErrorCode *pErrorCode);
 212
 213 /**
 214  * Returns the display name of the provided variant
 215  * @param ldn the LocaleDisplayNames instance
 216  * @param variant the variant whose display name to return
 217  * @param result receives the display name
 218  * @param maxResultSize the size of the result buffer
 219  * @param pErrorCode the status code
 220  * @return the actual buffer size needed for the display name.  If it's
 221  * greater than maxResultSize, the returned name will be truncated.
 222  * @stable ICU 4.4
 223  */
 224 U_STABLE int32_t U_EXPORT2
 225 uldn_variantDisplayName(const ULocaleDisplayNames *ldn,
 226                         const char *variant,
 227                         UChar *result,
 228                         int32_t maxResultSize,
 229                         UErrorCode *pErrorCode);
 230
 231 /**
 232  * Returns the display name of the provided locale key
 233  * @param ldn the LocaleDisplayNames instance
 234  * @param key the locale key whose display name to return
 235  * @param result receives the display name
 236  * @param maxResultSize the size of the result buffer
 237  * @param pErrorCode the status code
 238  * @return the actual buffer size needed for the display name.  If it's
 239  * greater than maxResultSize, the returned name will be truncated.
 240  * @stable ICU 4.4
 241  */
 242 U_STABLE int32_t U_EXPORT2
 243 uldn_keyDisplayName(const ULocaleDisplayNames *ldn,
 244                     const char *key,
 245                     UChar *result,
 246                     int32_t maxResultSize,
 247                     UErrorCode *pErrorCode);
 248
 249 /**
 250  * Returns the display name of the provided value (used with the provided key).
 251  * @param ldn the LocaleDisplayNames instance
 252  * @param key the locale key
 253  * @param value the locale key's value
 254  * @param result receives the display name
 255  * @param maxResultSize the size of the result buffer
 256  * @param pErrorCode the status code
 257  * @return the actual buffer size needed for the display name.  If it's
 258  * greater than maxResultSize, the returned name will be truncated.
 259  * @stable ICU 4.4
 260  */
 261 U_STABLE int32_t U_EXPORT2
 262 uldn_keyValueDisplayName(const ULocaleDisplayNames *ldn,
 263                          const char *key,
 264                          const char *value,
 265                          UChar *result,
 266                          int32_t maxResultSize,
 267                          UErrorCode *pErrorCode);
 268
 269 /**
 270 * Returns an instance of LocaleDisplayNames that returns names formatted
 271 * for the provided locale, using the provided UDisplayContext settings.
 272 *
 273 * @param locale The display locale
 274 * @param contexts List of one or more context settings (e.g. for dialect
 275 *               handling, capitalization, etc.
 276 * @param length Number of items in the contexts list
 277 * @param pErrorCode Pointer to UErrorCode input/output status. If at entry this indicates
 278 *               a failure status, the function will do nothing; otherwise this will be
 279 *               updated with any new status from the function.
 280 * @return a ULocaleDisplayNames instance
 281 * @stable ICU 51
 282 */
 283 U_STABLE ULocaleDisplayNames * U_EXPORT2
 284 uldn_openForContext(const char * locale, UDisplayContext *contexts,
 285                     int32_t length, UErrorCode *pErrorCode);
 286
 287 /**
 288 * Returns the UDisplayContext value for the specified UDisplayContextType.
 289 * @param ldn the ULocaleDisplayNames instance
 290 * @param type the UDisplayContextType whose value to return
 291 * @param pErrorCode Pointer to UErrorCode input/output status. If at entry this indicates
 292 *               a failure status, the function will do nothing; otherwise this will be
 293 *               updated with any new status from the function.
 294 * @return the UDisplayContextValue for the specified type.
 295 * @stable ICU 51
 296 */
 297 U_STABLE UDisplayContext U_EXPORT2
 298 uldn_getContext(const ULocaleDisplayNames *ldn, UDisplayContextType type,
 299                 UErrorCode *pErrorCode);
 300
 301 #endif  /* !UCONFIG_NO_FORMATTING */
 302 #endif  /* __ULDNAMES_H__ */