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