ulocale.h File Reference

C API: Locale ID functionality similar to C++ class Locale. More...

`#include "unicode/localpointer.h"`
`#include "unicode/uenum.h"`
`#include "unicode/utypes.h"`

Go to the source code of this file.

## Namespaces

namespace | icu
| File coll.h.

## Typedefs

typedef struct ULocale | ULocale
| C typedef for struct ULocale.

## Functions

U_CAPI ULocale * | ulocale_openForLocaleID (const char *localeID, int32_t length, UErrorCode *err)
| Constructs an ULocale from the locale ID.
U_CAPI ULocale * | ulocale_openForLanguageTag (const char *tag, int32_t length, UErrorCode *err)
| Constructs an ULocale from the provided IETF BCP 47 language tag.
U_CAPI void | ulocale_close (ULocale *locale)
| Close the locale and destroy it's internal states.
U_CAPI const char * | ulocale_getLanguage (const ULocale *locale)
| Returns the locale's ISO-639 language code.
U_CAPI const char * | ulocale_getScript (const ULocale *locale)
| Returns the locale's ISO-15924 abbreviation script code.
U_CAPI const char * | ulocale_getRegion (const ULocale *locale)
| Returns the locale's ISO-3166 region code.
U_CAPI const char * | ulocale_getVariant (const ULocale *locale)
| Returns the locale's variant code.
U_CAPI const char * | ulocale_getLocaleID (const ULocale *locale)
| Returns the programmatic name of the entire locale, with the language, country and variant separated by underbars.
U_CAPI const char * | ulocale_getBaseName (const ULocale *locale)
| Returns the programmatic name of the entire locale as ulocale_getLocaleID() would return, but without keywords.
U_CAPI bool | ulocale_isBogus (const ULocale *locale)
| Gets the bogus state.
U_CAPI UEnumeration * | ulocale_getKeywords (const ULocale *locale, UErrorCode *err)
| Gets the list of keywords for the specified locale.
U_CAPI UEnumeration * | ulocale_getUnicodeKeywords (const ULocale *locale, UErrorCode *err)
| Gets the list of unicode keywords for the specified locale.
U_CAPI int32_t | ulocale_getKeywordValue (const ULocale *locale, const char *keyword, int32_t keywordLength, char *valueBuffer, int32_t valueBufferCapacity, UErrorCode *err)
| Gets the value for a keyword.
U_CAPI int32_t | ulocale_getUnicodeKeywordValue (const ULocale *locale, const char *keyword, int32_t keywordLength, char *valueBuffer, int32_t valueBufferCapacity, UErrorCode *err)
| Gets the Unicode value for a Unicode keyword.

## Detailed Description

C API: Locale ID functionality similar to C++ class Locale.

Definition in file ulocale.h.

## Typedef Documentation

## ULocale

typedef struct ULocale ULocale

C typedef for struct ULocale.

Stable:
  ICU 74

Definition at line 26 of file ulocale.h.

## Function Documentation

## ulocale_close()

U_CAPI void ulocale_close | ( | ULocale * | locale | ) |

Close the locale and destroy it's internal states.

Parameters

  locale | the locale

Stable:
  ICU 74

## ulocale_getBaseName()

U_CAPI const char * ulocale_getBaseName | ( | const ULocale * | locale | ) |

Returns the programmatic name of the entire locale as ulocale_getLocaleID() would return, but without keywords.

Parameters

  locale | the locale

Returns
  A pointer to "base name".

Stable:
  ICU 74

## ulocale_getKeywords()

U_CAPI UEnumeration * ulocale_getKeywords | ( | const ULocale * | locale,
|  | UErrorCode * | err
| ) |  |

Gets the list of keywords for the specified locale.

Parameters

  locale | the locale
  err | the error code

Returns
  pointer to UEnumeration, or nullptr if there are no keywords. Client must call uenum_close() to dispose the returned value.

Stable:
  ICU 74

## ulocale_getKeywordValue()

U_CAPI int32_t ulocale_getKeywordValue | ( | const ULocale * | locale,
|  | const char * | keyword,
|  | int32_t | keywordLength,
|  | char * | valueBuffer,
|  | int32_t | valueBufferCapacity,
|  | UErrorCode * | err
| ) |  |

Gets the value for a keyword.

This uses legacy keyword=value pairs, like "collation=phonebook".

Parameters

  locale | the locale
  keyword | the keyword, a const char * pointer (need not be terminated when the length is non-negative)
  keywordLength | the length of the keyword; if negative, then the keyword need to be null terminated.
  valueBuffer | The buffer to receive the value.
  valueBufferCapacity | The capacity of receiving valueBuffer.
  err | the error code

Stable:
  ICU 74

## ulocale_getLanguage()

U_CAPI const char * ulocale_getLanguage | ( | const ULocale * | locale | ) |

Returns the locale's ISO-639 language code.

Parameters

  locale | the locale

Returns
  the language code of the locale.

Stable:
  ICU 74

## ulocale_getLocaleID()

U_CAPI const char * ulocale_getLocaleID | ( | const ULocale * | locale | ) |

Returns the programmatic name of the entire locale, with the language, country and variant separated by underbars.

If a field is missing, up to two leading underbars will occur. Example: "en", "de_DE", "en_US_WIN", "de__POSIX", "fr__MAC", "__MAC", "_MT", "_FR_EURO"

Parameters

  locale | the locale

Returns
  A pointer to "name".

Stable:
  ICU 74

## ulocale_getRegion()

U_CAPI const char * ulocale_getRegion | ( | const ULocale * | locale | ) |

Returns the locale's ISO-3166 region code.

Parameters

  locale | the locale

Returns
  A pointer to the region.

Stable:
  ICU 74

## ulocale_getScript()

U_CAPI const char * ulocale_getScript | ( | const ULocale * | locale | ) |

Returns the locale's ISO-15924 abbreviation script code.

Parameters

  locale | the locale

Returns
  A pointer to the script.

Stable:
  ICU 74

## ulocale_getUnicodeKeywords()

U_CAPI UEnumeration * ulocale_getUnicodeKeywords | ( | const ULocale * | locale,
|  | UErrorCode * | err
| ) |  |

Gets the list of unicode keywords for the specified locale.

Parameters

  locale | the locale
  err | the error code

Returns
  pointer to UEnumeration, or nullptr if there are no keywords. Client must call uenum_close() to dispose the returned value.

Stable:
  ICU 74

## ulocale_getUnicodeKeywordValue()

U_CAPI int32_t ulocale_getUnicodeKeywordValue | ( | const ULocale * | locale,
|  | const char * | keyword,
|  | int32_t | keywordLength,
|  | char * | valueBuffer,
|  | int32_t | valueBufferCapacity,
|  | UErrorCode * | err
| ) |  |

Gets the Unicode value for a Unicode keyword.

This uses Unicode key-value pairs, like "co-phonebk".

Parameters

  locale | the locale
  keyword | the Unicode keyword, a const char * pointer (need not be terminated when the length is non-negative)
  keywordLength | the length of the Unicode keyword; if negative, then the keyword need to be null terminated.
  valueBuffer | The buffer to receive the Unicode value.
  valueBufferCapacity | The capacity of receiving valueBuffer.
  err | the error code

Stable:
  ICU 74

## ulocale_getVariant()

U_CAPI const char * ulocale_getVariant | ( | const ULocale * | locale | ) |

Returns the locale's variant code.

Parameters

  locale | the locale

Returns
  A pointer to the variant.

Stable:
  ICU 74

## ulocale_isBogus()

U_CAPI bool ulocale_isBogus | ( | const ULocale * | locale | ) |

Gets the bogus state.

Locale object can be bogus if it doesn't exist

Parameters

  locale | the locale

Returns
  false if it is a real locale, true if it is a bogus locale

Stable:
  ICU 74

## ulocale_openForLanguageTag()

U_CAPI ULocale * ulocale_openForLanguageTag | ( | const char * | tag,
|  | int32_t | length,
|  | UErrorCode * | err
| ) |  |

Constructs an ULocale from the provided IETF BCP 47 language tag.

The created ULocale should be destroyed by calling ulocale_close();

Parameters

  tag | the language tag, defined as IETF BCP 47 language tag, const char* pointer (need not be terminated when the length is non-negative)
  length | the length of the tag; if negative, then the tag need to be null terminated.
  err | the error code

Returns
  the locale.

Stable:
  ICU 74

## ulocale_openForLocaleID()

U_CAPI ULocale * ulocale_openForLocaleID | ( | const char * | localeID,
|  | int32_t | length,
|  | UErrorCode * | err
| ) |  |

Constructs an ULocale from the locale ID.

The created ULocale should be destroyed by calling ulocale_close();

Parameters

  localeID | the locale, a const char * pointer (need not be terminated when the length is non-negative)
  length | the length of the locale; if negative, then the locale need to be null terminated.
  err | the error code

Returns
  the locale.

Stable:
  ICU 74