ICU 77.1: common/unicode/uldnames.h File Reference

ICU 77.1 77.1

Namespaces | Typedefs | Enumerations | Functions
uldnames.h File Reference

C API: Provides display names of Locale ids and their components. More...

`#include "unicode/utypes.h"`
`#include "unicode/uscript.h"`
`#include "unicode/udisplaycontext.h"`
`#include "unicode/localpointer.h"`

Go to the source code of this file.

## Namespaces
| icu
| File coll.h.

## Typedefs
typedef struct ULocaleDisplayNames | ULocaleDisplayNames
| C typedef for struct ULocaleDisplayNames. More...

## Enumerations
enum | UDialectHandling { ULDN_STANDARD_NAMES = 0 , ULDN_DIALECT_NAMES }
| Enum used in LocaleDisplayNames::createInstance. More...

## Functions
U_CAPI ULocaleDisplayNames * | uldn_open (const char *locale, UDialectHandling dialectHandling, UErrorCode *pErrorCode)
| Returns an instance of LocaleDisplayNames that returns names formatted for the provided locale, using the provided dialectHandling. More...
U_CAPI void | uldn_close (ULocaleDisplayNames *ldn)
| Closes a ULocaleDisplayNames instance obtained from uldn_open(). More...
U_CAPI const char * | uldn_getLocale (const ULocaleDisplayNames *ldn)
| Returns the locale used to determine the display names. More...
U_CAPI UDialectHandling | uldn_getDialectHandling (const ULocaleDisplayNames *ldn)
| Returns the dialect handling used in the display names. More...
U_CAPI int32_t | uldn_localeDisplayName (const ULocaleDisplayNames *ldn, const char *locale, UChar *result, int32_t maxResultSize, UErrorCode *pErrorCode)
| Returns the display name of the provided locale. More...
U_CAPI int32_t | uldn_languageDisplayName (const ULocaleDisplayNames *ldn, const char *lang, UChar *result, int32_t maxResultSize, UErrorCode *pErrorCode)
| Returns the display name of the provided language code. More...
U_CAPI int32_t | uldn_scriptDisplayName (const ULocaleDisplayNames *ldn, const char *script, UChar *result, int32_t maxResultSize, UErrorCode *pErrorCode)
| Returns the display name of the provided script. More...
U_CAPI int32_t | uldn_scriptCodeDisplayName (const ULocaleDisplayNames *ldn, UScriptCode scriptCode, UChar *result, int32_t maxResultSize, UErrorCode *pErrorCode)
| Returns the display name of the provided script code. More...
U_CAPI int32_t | uldn_regionDisplayName (const ULocaleDisplayNames *ldn, const char *region, UChar *result, int32_t maxResultSize, UErrorCode *pErrorCode)
| Returns the display name of the provided region code. More...
U_CAPI int32_t | uldn_variantDisplayName (const ULocaleDisplayNames *ldn, const char *variant, UChar *result, int32_t maxResultSize, UErrorCode *pErrorCode)
| Returns the display name of the provided variant. More...
U_CAPI int32_t | uldn_keyDisplayName (const ULocaleDisplayNames *ldn, const char *key, UChar *result, int32_t maxResultSize, UErrorCode *pErrorCode)
| Returns the display name of the provided locale key. More...
U_CAPI int32_t | uldn_keyValueDisplayName (const ULocaleDisplayNames *ldn, const char *key, const char *value, UChar *result, int32_t maxResultSize, UErrorCode *pErrorCode)
| Returns the display name of the provided value (used with the provided key). More...
U_CAPI ULocaleDisplayNames * | uldn_openForContext (const char *locale, UDisplayContext *contexts, int32_t length, UErrorCode *pErrorCode)
| Returns an instance of LocaleDisplayNames that returns names formatted for the provided locale, using the provided UDisplayContext settings. More...
U_CAPI UDisplayContext | uldn_getContext (const ULocaleDisplayNames *ldn, UDisplayContextType type, UErrorCode *pErrorCode)
| Returns the UDisplayContext value for the specified UDisplayContextType. More...

## Detailed Description

C API: Provides display names of Locale ids and their components.

Definition in file uldnames.h.

## Typedef Documentation

## ◆ ULocaleDisplayNames

typedef struct ULocaleDisplayNames ULocaleDisplayNames

C typedef for struct ULocaleDisplayNames.

Stable:
  ICU 4.4

Definition at line 1 of file uldnames.h.

## Enumeration Type Documentation

## ◆ UDialectHandling

enum UDialectHandling

Enum used in LocaleDisplayNames::createInstance.

Stable:
  ICU 4.4

Enumerator
ULDN_STANDARD_NAMES | Use standard names when generating a locale name, e.g. en_GB displays as 'English (United Kingdom)'. Stable: ICU 4.4
ULDN_DIALECT_NAMES | Use dialect names, when generating a locale name, e.g. en_GB displays as 'British English'. Stable: ICU 4.4

Definition at line 30 of file uldnames.h.

## Function Documentation

## ◆ uldn_close()

U_CAPI void uldn_close | ( | ULocaleDisplayNames * | ldn | ) |

Closes a ULocaleDisplayNames instance obtained from uldn_open().

Parameters

  ldn | the ULocaleDisplayNames instance to be closed

Stable:
  ICU 4.4

## ◆ uldn_getContext()

U_CAPI UDisplayContext uldn_getContext | ( | const ULocaleDisplayNames * | ldn,
|  | UDisplayContextType | type,
|  | UErrorCode * | pErrorCode
| ) |  |

Returns the UDisplayContext value for the specified UDisplayContextType.

Parameters

  ldn | the ULocaleDisplayNames instance
  type | the UDisplayContextType whose value to return
  pErrorCode | Pointer to UErrorCode input/output status. If at entry this indicates a failure status, the function will do nothing; otherwise this will be updated with any new status from the function.

Returns
  the UDisplayContextValue for the specified type.

Stable:
  ICU 51

## ◆ uldn_getDialectHandling()

U_CAPI UDialectHandling uldn_getDialectHandling | ( | const ULocaleDisplayNames * | ldn | ) |

Returns the dialect handling used in the display names.

Parameters

  ldn | the LocaleDisplayNames instance

Returns
  the dialect handling enum

Stable:
  ICU 4.4

## ◆ uldn_getLocale()

U_CAPI const char* uldn_getLocale | ( | const ULocaleDisplayNames * | ldn | ) |

Returns the locale used to determine the display names.

This is not necessarily the same locale passed to uldn_open.

Parameters

  ldn | the LocaleDisplayNames instance

Returns
  the display locale

Stable:
  ICU 4.4

## ◆ uldn_keyDisplayName()

U_CAPI int32_t uldn_keyDisplayName | ( | const ULocaleDisplayNames * | ldn,
|  | const char * | key,
|  | UChar * | result,
|  | int32_t | maxResultSize,
|  | UErrorCode * | pErrorCode
| ) |  |

Returns the display name of the provided locale key.

Parameters

  ldn | the LocaleDisplayNames instance
  key | the locale key whose display name to return
  result | receives the display name
  maxResultSize | the size of the result buffer
  pErrorCode | the status code

Returns
  the actual buffer size needed for the display name. If it's greater than maxResultSize, the returned name will be truncated.

Stable:
  ICU 4.4

## ◆ uldn_keyValueDisplayName()

U_CAPI int32_t uldn_keyValueDisplayName | ( | const ULocaleDisplayNames * | ldn,
|  | const char * | key,
|  | const char * | value,
|  | UChar * | result,
|  | int32_t | maxResultSize,
|  | UErrorCode * | pErrorCode
| ) |  |

Returns the display name of the provided value (used with the provided key).

Parameters

  ldn | the LocaleDisplayNames instance
  key | the locale key
  value | the locale key's value
  result | receives the display name
  maxResultSize | the size of the result buffer
  pErrorCode | the status code

Returns
  the actual buffer size needed for the display name. If it's greater than maxResultSize, the returned name will be truncated.

Stable:
  ICU 4.4

## ◆ uldn_languageDisplayName()

U_CAPI int32_t uldn_languageDisplayName | ( | const ULocaleDisplayNames * | ldn,
|  | const char * | lang,
|  | UChar * | result,
|  | int32_t | maxResultSize,
|  | UErrorCode * | pErrorCode
| ) |  |

Returns the display name of the provided language code.

Parameters

  ldn | the LocaleDisplayNames instance
  lang | the language code whose display name to return
  result | receives the display name
  maxResultSize | the size of the result buffer
  pErrorCode | the status code

Returns
  the actual buffer size needed for the display name. If it's greater than maxResultSize, the returned name will be truncated.

Stable:
  ICU 4.4

## ◆ uldn_localeDisplayName()

U_CAPI int32_t uldn_localeDisplayName | ( | const ULocaleDisplayNames * | ldn,
|  | const char * | locale,
|  | UChar * | result,
|  | int32_t | maxResultSize,
|  | UErrorCode * | pErrorCode
| ) |  |

Returns the display name of the provided locale.

Parameters

  ldn | the LocaleDisplayNames instance
  locale | the locale whose display name to return
  result | receives the display name
  maxResultSize | the size of the result buffer
  pErrorCode | the status code

Returns
  the actual buffer size needed for the display name. If it's greater than maxResultSize, the returned name will be truncated.

Stable:
  ICU 4.4

## ◆ uldn_open()

U_CAPI ULocaleDisplayNames* uldn_open | ( | const char * | locale,
|  | UDialectHandling | dialectHandling,
|  | UErrorCode * | pErrorCode
| ) |  |

Returns an instance of LocaleDisplayNames that returns names formatted for the provided locale, using the provided dialectHandling.

The usual value for dialectHandling is ULOC_STANDARD_NAMES.

Parameters

  locale | the display locale
  dialectHandling | how to select names for locales

Returns
  a ULocaleDisplayNames instance

Parameters

  pErrorCode | the status code

Stable:
  ICU 4.4

## ◆ uldn_openForContext()

U_CAPI ULocaleDisplayNames* uldn_openForContext | ( | const char * | locale,
|  | UDisplayContext * | contexts,
|  | int32_t | length,
|  | UErrorCode * | pErrorCode
| ) |  |

Returns an instance of LocaleDisplayNames that returns names formatted for the provided locale, using the provided UDisplayContext settings.

Parameters

  locale | The display locale
  contexts | List of one or more context settings (e.g. for dialect handling, capitalization, etc.
  length | Number of items in the contexts list
  pErrorCode | Pointer to UErrorCode input/output status. If at entry this indicates a failure status, the function will do nothing; otherwise this will be updated with any new status from the function.

Returns
  a ULocaleDisplayNames instance

Stable:
  ICU 51

## ◆ uldn_regionDisplayName()

U_CAPI int32_t uldn_regionDisplayName | ( | const ULocaleDisplayNames * | ldn,
|  | const char * | region,
|  | UChar * | result,
|  | int32_t | maxResultSize,
|  | UErrorCode * | pErrorCode
| ) |  |

Returns the display name of the provided region code.

Parameters

  ldn | the LocaleDisplayNames instance
  region | the region code whose display name to return
  result | receives the display name
  maxResultSize | the size of the result buffer
  pErrorCode | the status code

Returns
  the actual buffer size needed for the display name. If it's greater than maxResultSize, the returned name will be truncated.

Stable:
  ICU 4.4

## ◆ uldn_scriptCodeDisplayName()

U_CAPI int32_t uldn_scriptCodeDisplayName | ( | const ULocaleDisplayNames * | ldn,
|  | UScriptCode | scriptCode,
|  | UChar * | result,
|  | int32_t | maxResultSize,
|  | UErrorCode * | pErrorCode
| ) |  |

Returns the display name of the provided script code.

Parameters

  ldn | the LocaleDisplayNames instance
  scriptCode | the script code whose display name to return
  result | receives the display name
  maxResultSize | the size of the result buffer
  pErrorCode | the status code

Returns
  the actual buffer size needed for the display name. If it's greater than maxResultSize, the returned name will be truncated.

Stable:
  ICU 4.4

## ◆ uldn_scriptDisplayName()

U_CAPI int32_t uldn_scriptDisplayName | ( | const ULocaleDisplayNames * | ldn,
|  | const char * | script,
|  | UChar * | result,
|  | int32_t | maxResultSize,
|  | UErrorCode * | pErrorCode
| ) |  |

Returns the display name of the provided script.

Parameters

  ldn | the LocaleDisplayNames instance
  script | the script whose display name to return
  result | receives the display name
  maxResultSize | the size of the result buffer
  pErrorCode | the status code

Returns
  the actual buffer size needed for the display name. If it's greater than maxResultSize, the returned name will be truncated.

Stable:
  ICU 4.4

## ◆ uldn_variantDisplayName()

U_CAPI int32_t uldn_variantDisplayName | ( | const ULocaleDisplayNames * | ldn,
|  | const char * | variant,
|  | UChar * | result,
|  | int32_t | maxResultSize,
|  | UErrorCode * | pErrorCode
| ) |  |

Returns the display name of the provided variant.

Parameters

  ldn | the LocaleDisplayNames instance
  variant | the variant whose display name to return
  result | receives the display name
  maxResultSize | the size of the result buffer
  pErrorCode | the status code

Returns
  the actual buffer size needed for the display name. If it's greater than maxResultSize, the returned name will be truncated.

Stable:
  ICU 4.4