ICU 69.1: ures.h File Reference

ICU 69.1 69.1

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

C API: Resource Bundle. More...

`#include "unicode/utypes.h"`
`#include "unicode/uloc.h"`
`#include "unicode/localpointer.h"`
`#include "unicode/unistr.h"`

Go to the source code of this file.

## Namespaces
| icu
| File coll.h.

## Typedefs
typedef struct UResourceBundle | UResourceBundle

## Enumerations
enum | UResType { URES_NONE =-1 , URES_STRING =0 , URES_BINARY =1 , URES_TABLE =2 , URES_ALIAS =3 , URES_INT =7 , URES_ARRAY =8 , URES_INT_VECTOR = 14 , RES_NONE =URES_NONE , RES_STRING =URES_STRING , RES_BINARY =URES_BINARY , RES_TABLE =URES_TABLE , RES_ALIAS =URES_ALIAS , RES_INT =URES_INT , RES_ARRAY =URES_ARRAY , RES_INT_VECTOR =URES_INT_VECTOR , RES_RESERVED =15 , URES_LIMIT = 16 }
| Numeric constants for types of resource items. More...

## Functions
U_CAPI UResourceBundle * | ures_open (const char *packageName, const char *locale, UErrorCode *status)
| Opens a UResourceBundle, from which users can extract strings by using their corresponding keys. More...
U_CAPI UResourceBundle * | ures_openDirect (const char *packageName, const char *locale, UErrorCode *status)
| This function does not care what kind of localeID is passed in. More...
U_CAPI UResourceBundle * | ures_openU (const UChar *packageName, const char *locale, UErrorCode *status)
| Same as ures_open() but takes a const UChar *path. More...
int32_t | ures_countArrayItems (const UResourceBundle *resourceBundle, const char *resourceKey, UErrorCode *err)
| Returns the number of strings/arrays in resource bundles. More...
U_CAPI void | ures_close (UResourceBundle *resourceBundle)
| Close a resource bundle, all pointers returned from the various ures_getXXX calls on this particular bundle should be considered invalid henceforth. More...
const char * | ures_getVersionNumber (const UResourceBundle *resourceBundle)
| Return the version number associated with this ResourceBundle as a string. More...
U_CAPI void | ures_getVersion (const UResourceBundle *resB, UVersionInfo versionInfo)
| Return the version number associated with this ResourceBundle as an UVersionInfo array. More...
const char * | ures_getLocale (const UResourceBundle *resourceBundle, UErrorCode *status)
| Return the name of the Locale associated with this ResourceBundle. More...
U_CAPI const char * | ures_getLocaleByType (const UResourceBundle *resourceBundle, ULocDataLocaleType type, UErrorCode *status)
| Return the name of the Locale associated with this ResourceBundle. More...
U_CAPI void | ures_openFillIn (UResourceBundle *r, const char *packageName, const char *localeID, UErrorCode *status)
| Same as ures_open() but uses the fill-in parameter instead of allocating a new bundle. More...
U_CAPI const UChar * | ures_getString (const UResourceBundle *resourceBundle, int32_t *len, UErrorCode *status)
| Returns a string from a string resource type. More...
U_CAPI const char * | ures_getUTF8String (const UResourceBundle *resB, char *dest, int32_t *length, UBool forceCopy, UErrorCode *status)
| Returns a UTF-8 string from a string resource. More...
U_CAPI const uint8_t * | ures_getBinary (const UResourceBundle *resourceBundle, int32_t *len, UErrorCode *status)
| Returns a binary data from a binary resource. More...
U_CAPI const int32_t * | ures_getIntVector (const UResourceBundle *resourceBundle, int32_t *len, UErrorCode *status)
| Returns a 32 bit integer array from a resource. More...
U_CAPI uint32_t | ures_getUInt (const UResourceBundle *resourceBundle, UErrorCode *status)
| Returns an unsigned integer from a resource. More...
U_CAPI int32_t | ures_getInt (const UResourceBundle *resourceBundle, UErrorCode *status)
| Returns a signed integer from a resource. More...
U_CAPI int32_t | ures_getSize (const UResourceBundle *resourceBundle)
| Returns the size of a resource. More...
U_CAPI UResType | ures_getType (const UResourceBundle *resourceBundle)
| Returns the type of a resource. More...
U_CAPI const char * | ures_getKey (const UResourceBundle *resourceBundle)
| Returns the key associated with a given resource. More...
U_CAPI void | ures_resetIterator (UResourceBundle *resourceBundle)
| Resets the internal context of a resource so that iteration starts from the first element. More...
U_CAPI UBool | ures_hasNext (const UResourceBundle *resourceBundle)
| Checks whether the given resource has another element to iterate over. More...
U_CAPI UResourceBundle * | ures_getNextResource (UResourceBundle *resourceBundle, UResourceBundle *fillIn, UErrorCode *status)
| Returns the next resource in a given resource or NULL if there are no more resources to iterate over. More...
U_CAPI const UChar * | ures_getNextString (UResourceBundle *resourceBundle, int32_t *len, const char **key, UErrorCode *status)
| Returns the next string in a given resource or NULL if there are no more resources to iterate over. More...
U_CAPI UResourceBundle * | ures_getByIndex (const UResourceBundle *resourceBundle, int32_t indexR, UResourceBundle *fillIn, UErrorCode *status)
| Returns the resource in a given resource at the specified index. More...
U_CAPI const UChar * | ures_getStringByIndex (const UResourceBundle *resourceBundle, int32_t indexS, int32_t *len, UErrorCode *status)
| Returns the string in a given resource at the specified index. More...
U_CAPI const char * | ures_getUTF8StringByIndex (const UResourceBundle *resB, int32_t stringIndex, char *dest, int32_t *pLength, UBool forceCopy, UErrorCode *status)
| Returns a UTF-8 string from a resource at the specified index. More...
U_CAPI UResourceBundle * | ures_getByKey (const UResourceBundle *resourceBundle, const char *key, UResourceBundle *fillIn, UErrorCode *status)
| Returns a resource in a given resource that has a given key. More...
U_CAPI const UChar * | ures_getStringByKey (const UResourceBundle *resB, const char *key, int32_t *len, UErrorCode *status)
| Returns a string in a given resource that has a given key. More...
U_CAPI const char * | ures_getUTF8StringByKey (const UResourceBundle *resB, const char *key, char *dest, int32_t *pLength, UBool forceCopy, UErrorCode *status)
| Returns a UTF-8 string from a resource and a key. More...
UnicodeString | icu::ures_getUnicodeString (const UResourceBundle *resB, UErrorCode *status)
| Returns the string value from a string resource bundle. More...
UnicodeString | icu::ures_getNextUnicodeString (UResourceBundle *resB, const char **key, UErrorCode *status)
| Returns the next string in a resource, or an empty string if there are no more resources to iterate over. More...
UnicodeString | icu::ures_getUnicodeStringByIndex (const UResourceBundle *resB, int32_t indexS, UErrorCode *status)
| Returns the string in a given resource array or table at the specified index. More...
UnicodeString | icu::ures_getUnicodeStringByKey (const UResourceBundle *resB, const char *key, UErrorCode *status)
| Returns a string in a resource that has a given key. More...
U_CAPI UEnumeration * | ures_openAvailableLocales (const char *packageName, UErrorCode *status)
| Create a string enumerator, owned by the caller, of all locales located within the specified resource tree. More...

## Detailed Description

C API: Resource Bundle.

## C API: Resource Bundle

C API representing a collection of resource information pertaining to a given locale. A resource bundle provides a way of accessing locale- specific information in a data file. You create a resource bundle that manages the resources for a given locale and then ask it for individual resources.

Resource bundles in ICU4C are currently defined using text files which conform to the following BNF definition. More on resource bundle concepts and syntax can be found in the Users Guide.

Definition in file ures.h.

## Typedef Documentation

## ◆ UResourceBundle

typedef struct UResourceBundle UResourceBundle

Stable:
  ICU 2.0

Definition at line 1 of file ures.h.

## Enumeration Type Documentation

## ◆ UResType

enum UResType

Numeric constants for types of resource items.

See also
  ures_getType

Stable:
  ICU 2.0

Enumerator
URES_NONE | Resource type constant for "no resource". Stable: ICU 2.6
URES_STRING | Resource type constant for 16-bit Unicode strings. Stable: ICU 2.6
URES_BINARY | Resource type constant for binary data. Stable: ICU 2.6
URES_TABLE | Resource type constant for tables of key-value pairs. Stable: ICU 2.6
URES_ALIAS | Resource type constant for aliases; internally stores a string which identifies the actual resource storing the data (can be in a different resource bundle). Resolved internally before delivering the actual resource through the API. Stable: ICU 2.6
URES_INT | Resource type constant for a single 28-bit integer, interpreted as signed or unsigned by the ures_getInt() or ures_getUInt() function. See also ures_getInt ures_getUInt Stable: ICU 2.6
URES_ARRAY | Resource type constant for arrays of resources. Stable: ICU 2.6
URES_INT_VECTOR | Resource type constant for vectors of 32-bit integers. See also ures_getIntVector Stable: ICU 2.6
RES_NONE | Deprecated: ICU 2.6 Use the URES_ constant instead.
RES_STRING | Deprecated: ICU 2.6 Use the URES_ constant instead.
RES_BINARY | Deprecated: ICU 2.6 Use the URES_ constant instead.
RES_TABLE | Deprecated: ICU 2.6 Use the URES_ constant instead.
RES_ALIAS | Deprecated: ICU 2.6 Use the URES_ constant instead.
RES_INT | Deprecated: ICU 2.6 Use the URES_ constant instead.
RES_ARRAY | Deprecated: ICU 2.6 Use the URES_ constant instead.
RES_INT_VECTOR | Deprecated: ICU 2.6 Use the URES_ constant instead.
RES_RESERVED | Deprecated: ICU 2.6 Not used.
URES_LIMIT | One more than the highest normal UResType value. Deprecated: ICU 58 The numeric value may change over time, see ICU ticket #12420.

Definition at line 69 of file ures.h.

## Function Documentation

## ◆ ures_close()

U_CAPI void ures_close | ( | UResourceBundle * | resourceBundle | ) |

Close a resource bundle, all pointers returned from the various ures_getXXX calls on this particular bundle should be considered invalid henceforth.

Parameters

  resourceBundle | a pointer to a resourceBundle struct. Can be NULL.

See also
  ures_open

Stable:
  ICU 2.0

## ◆ ures_countArrayItems()

int32_t ures_countArrayItems | ( | const UResourceBundle * | resourceBundle,
|  | const char * | resourceKey,
|  | UErrorCode * | err
| ) |  |

Returns the number of strings/arrays in resource bundles.

Better to use ures_getSize, as this function will be deprecated.

Parameters

  resourceBundle | resource bundle containing the desired strings
  resourceKey | key tagging the resource
  err | fills in the outgoing error code could be `U_MISSING_RESOURCE_ERROR` if the key is not found could be a non-failing error e.g.: `U_USING_FALLBACK_WARNING`,`U_USING_FALLBACK_WARNING`

Returns
  : for Arrays: returns the number of resources in the array Tables: returns the number of resources in the table single string: returns 1

See also
  ures_getSize

Deprecated:
  ICU 2.8 User ures_getSize instead

## ◆ ures_getBinary()

U_CAPI const uint8_t* ures_getBinary | ( | const UResourceBundle * | resourceBundle,
|  | int32_t * | len,
|  | UErrorCode * | status
| ) |  |

Returns a binary data from a binary resource.

Parameters

  resourceBundle | a string resource
  len | fills in the length of resulting byte chunk
  status | fills in the outgoing error code could be `U_MISSING_RESOURCE_ERROR` if the key is not found Always check the value of status. Don't count on returning NULL. could be a non-failing error e.g.: `U_USING_FALLBACK_WARNING`,`U_USING_DEFAULT_WARNING`

Returns
  a pointer to a chunk of unsigned bytes which live in a memory mapped/DLL file.

See also
  ures_getString
  ures_getIntVector
  ures_getInt
  ures_getUInt

Stable:
  ICU 2.0

## ◆ ures_getByIndex()

U_CAPI UResourceBundle* ures_getByIndex | ( | const UResourceBundle * | resourceBundle,
|  | int32_t | indexR,
|  | UResourceBundle * | fillIn,
|  | UErrorCode * | status
| ) |  |

Returns the resource in a given resource at the specified index.

Features a fill-in parameter.

Parameters

  resourceBundle | the resource bundle from which to get a sub-resource
  indexR | an index to the wanted resource.
  fillIn | if NULL a new UResourceBundle struct is allocated and must be closed by the caller. Alternatively, you can supply a struct to be filled by this function.
  status | fills in the outgoing error code. Don't count on NULL being returned if an error has occurred. Check status instead.

Returns
  a pointer to a UResourceBundle struct. If fill in param was NULL, caller must close it

Stable:
  ICU 2.0

## ◆ ures_getByKey()

U_CAPI UResourceBundle* ures_getByKey | ( | const UResourceBundle * | resourceBundle,
|  | const char * | key,
|  | UResourceBundle * | fillIn,
|  | UErrorCode * | status
| ) |  |

Returns a resource in a given resource that has a given key.

This procedure works only with table resources. Features a fill-in parameter.

Parameters

  resourceBundle | a resource
  key | a key associated with the wanted resource
  fillIn | if NULL a new UResourceBundle struct is allocated and must be closed by the caller. Alternatively, you can supply a struct to be filled by this function.
  status | fills in the outgoing error code.

Returns
  a pointer to a UResourceBundle struct. If fill in param was NULL, caller must close it

Stable:
  ICU 2.0

## ◆ ures_getInt()

U_CAPI int32_t ures_getInt | ( | const UResourceBundle * | resourceBundle,
|  | UErrorCode * | status
| ) |  |

Returns a signed integer from a resource.

This integer is originally 28 bit and the sign gets propagated.

Parameters

  resourceBundle | a string resource
  status | fills in the outgoing error code could be `U_MISSING_RESOURCE_ERROR` if the key is not found could be a non-failing error e.g.: `U_USING_FALLBACK_WARNING`,`U_USING_DEFAULT_WARNING`

Returns
  an integer value

See also
  ures_getUInt
  ures_getIntVector
  ures_getBinary
  ures_getString

Stable:
  ICU 2.0

## ◆ ures_getIntVector()

U_CAPI const int32_t* ures_getIntVector | ( | const UResourceBundle * | resourceBundle,
|  | int32_t * | len,
|  | UErrorCode * | status
| ) |  |

Returns a 32 bit integer array from a resource.

Parameters

  resourceBundle | an int vector resource
  len | fills in the length of resulting byte chunk
  status | fills in the outgoing error code could be `U_MISSING_RESOURCE_ERROR` if the key is not found Always check the value of status. Don't count on returning NULL. could be a non-failing error e.g.: `U_USING_FALLBACK_WARNING`,`U_USING_DEFAULT_WARNING`

Returns
  a pointer to a chunk of integers which live in a memory mapped/DLL file.

See also
  ures_getBinary
  ures_getString
  ures_getInt
  ures_getUInt

Stable:
  ICU 2.0

## ◆ ures_getKey()

U_CAPI const char* ures_getKey | ( | const UResourceBundle * | resourceBundle | ) |

Returns the key associated with a given resource.

Not all the resources have a key - only those that are members of a table.

Parameters

  resourceBundle | a resource

Returns
  a key associated to this resource, or NULL if it doesn't have a key

Stable:
  ICU 2.0

## ◆ ures_getLocale()

const char* ures_getLocale | ( | const UResourceBundle * | resourceBundle,
|  | UErrorCode * | status
| ) |  |

Return the name of the Locale associated with this ResourceBundle.

This API allows you to query for the real locale of the resource. For example, if you requested "en_US_CALIFORNIA" and only "en_US" bundle exists, "en_US" will be returned. For subresources, the locale where this resource comes from will be returned. If fallback has occurred, getLocale will reflect this.

Parameters

  resourceBundle | resource bundle in question
  status | just for catching illegal arguments

Returns
  A Locale name

Deprecated:
  ICU 2.8 Use ures_getLocaleByType instead.

## ◆ ures_getLocaleByType()

U_CAPI const char* ures_getLocaleByType | ( | const UResourceBundle * | resourceBundle,
|  | ULocDataLocaleType | type,
|  | UErrorCode * | status
| ) |  |

Return the name of the Locale associated with this ResourceBundle.

You can choose between requested, valid and real locale.

Parameters

  resourceBundle | resource bundle in question
  type | You can choose between requested, valid and actual locale. For description see the definition of ULocDataLocaleType in uloc.h
  status | just for catching illegal arguments

Returns
  A Locale name

Stable:
  ICU 2.8

## ◆ ures_getNextResource()

U_CAPI UResourceBundle* ures_getNextResource | ( | UResourceBundle * | resourceBundle,
|  | UResourceBundle * | fillIn,
|  | UErrorCode * | status
| ) |  |

Returns the next resource in a given resource or NULL if there are no more resources to iterate over.

Features a fill-in parameter.

Parameters

  resourceBundle | a resource
  fillIn | if NULL a new UResourceBundle struct is allocated and must be closed by the caller. Alternatively, you can supply a struct to be filled by this function.
  status | fills in the outgoing error code. You may still get a non NULL result even if an error occurred. Check status instead.

Returns
  a pointer to a UResourceBundle struct. If fill in param was NULL, caller must close it

Stable:
  ICU 2.0

## ◆ ures_getNextString()

U_CAPI const UChar* ures_getNextString | ( | UResourceBundle * | resourceBundle,
|  | int32_t * | len,
|  | const char ** | key,
|  | UErrorCode * | status
| ) |  |

Returns the next string in a given resource or NULL if there are no more resources to iterate over.

Parameters

  resourceBundle | a resource
  len | fill in length of the string
  key | fill in for key associated with this string. NULL if no key
  status | fills in the outgoing error code. If an error occurred, we may return NULL, but don't count on it. Check status instead!

Returns
  a pointer to a zero-terminated UChar array which lives in a memory mapped/DLL file.

Stable:
  ICU 2.0

Referenced by icu::ures_getNextUnicodeString().

## ◆ ures_getSize()

U_CAPI int32_t ures_getSize | ( | const UResourceBundle * | resourceBundle | ) |

Returns the size of a resource.

Size for scalar types is always 1, and for vector/table types is the number of child resources.

Warning
  Integer array is treated as a scalar type. There are no APIs to access individual members of an integer array. It is always returned as a whole.

Parameters

  resourceBundle | a resource

Returns
  number of resources in a given resource.

Stable:
  ICU 2.0

## ◆ ures_getString()

U_CAPI const UChar* ures_getString | ( | const UResourceBundle * | resourceBundle,
|  | int32_t * | len,
|  | UErrorCode * | status
| ) |  |

Returns a string from a string resource type.

Parameters

  resourceBundle | a string resource
  len | fills in the length of resulting string
  status | fills in the outgoing error code could be `U_MISSING_RESOURCE_ERROR` if the key is not found Always check the value of status. Don't count on returning NULL. could be a non-failing error e.g.: `U_USING_FALLBACK_WARNING`,`U_USING_DEFAULT_WARNING`

Returns
  a pointer to a zero-terminated UChar array which lives in a memory mapped/DLL file.

See also
  ures_getBinary
  ures_getIntVector
  ures_getInt
  ures_getUInt

Stable:
  ICU 2.0

Referenced by icu::ures_getUnicodeString().

## ◆ ures_getStringByIndex()

U_CAPI const UChar* ures_getStringByIndex | ( | const UResourceBundle * | resourceBundle,
|  | int32_t | indexS,
|  | int32_t * | len,
|  | UErrorCode * | status
| ) |  |

Returns the string in a given resource at the specified index.

Parameters

  resourceBundle | a resource
  indexS | an index to the wanted string.
  len | fill in length of the string
  status | fills in the outgoing error code. If an error occurred, we may return NULL, but don't count on it. Check status instead!

Returns
  a pointer to a zero-terminated UChar array which lives in a memory mapped/DLL file.

Stable:
  ICU 2.0

Referenced by icu::ures_getUnicodeStringByIndex().

## ◆ ures_getStringByKey()

U_CAPI const UChar* ures_getStringByKey | ( | const UResourceBundle * | resB,
|  | const char * | key,
|  | int32_t * | len,
|  | UErrorCode * | status
| ) |  |

Returns a string in a given resource that has a given key.

This procedure works only with table resources.

Parameters

  resB | a resource
  key | a key associated with the wanted string
  len | fill in length of the string
  status | fills in the outgoing error code. If an error occurred, we may return NULL, but don't count on it. Check status instead!

Returns
  a pointer to a zero-terminated UChar array which lives in a memory mapped/DLL file.

Stable:
  ICU 2.0

Referenced by icu::ures_getUnicodeStringByKey().

## ◆ ures_getType()

U_CAPI UResType ures_getType | ( | const UResourceBundle * | resourceBundle | ) |

Returns the type of a resource.

Available types are defined in enum UResType

Parameters

  resourceBundle | a resource

Returns
  type of the given resource.

See also
  UResType

Stable:
  ICU 2.0

## ◆ ures_getUInt()

U_CAPI uint32_t ures_getUInt | ( | const UResourceBundle * | resourceBundle,
|  | UErrorCode * | status
| ) |  |

Returns an unsigned integer from a resource.

This integer is originally 28 bits.

Parameters

  resourceBundle | a string resource
  status | fills in the outgoing error code could be `U_MISSING_RESOURCE_ERROR` if the key is not found could be a non-failing error e.g.: `U_USING_FALLBACK_WARNING`,`U_USING_DEFAULT_WARNING`

Returns
  an integer value

See also
  ures_getInt
  ures_getIntVector
  ures_getBinary
  ures_getString

Stable:
  ICU 2.0

## ◆ ures_getUTF8String()

U_CAPI const char* ures_getUTF8String | ( | const UResourceBundle * | resB,
|  | char * | dest,
|  | int32_t * | length,
|  | UBool | forceCopy,
|  | UErrorCode * | status
| ) |  |

Returns a UTF-8 string from a string resource.

The UTF-8 string may be returnable directly as a pointer, or it may need to be copied, or transformed from UTF-16 using u_strToUTF8() or equivalent.

If forceCopy==true, then the string is always written to the dest buffer and dest is returned.

If forceCopy==false, then the string is returned as a pointer if possible, without needing a dest buffer (it can be NULL). If the string needs to be copied or transformed, then it may be placed into dest at an arbitrary offset.

If the string is to be written to dest, then U_BUFFER_OVERFLOW_ERROR and U_STRING_NOT_TERMINATED_WARNING are set if appropriate, as usual.

If the string is transformed from UTF-16, then a conversion error may occur if an unpaired surrogate is encountered. If the function is successful, then the output UTF-8 string is always well-formed.

Parameters

  resB | Resource bundle.
  dest | Destination buffer. Can be NULL only if capacity=*length==0.
  length | Input: Capacity of destination buffer. Output: Actual length of the UTF-8 string, not counting the terminating NUL, even in case of U_BUFFER_OVERFLOW_ERROR. Can be NULL, meaning capacity=0 and the string length is not returned to the caller.
  forceCopy | If true, then the output string will always be written to dest, with U_BUFFER_OVERFLOW_ERROR and U_STRING_NOT_TERMINATED_WARNING set if appropriate. If false, then the dest buffer may or may not contain a copy of the string. dest may or may not be modified. If a copy needs to be written, then the UErrorCode parameter indicates overflow etc. as usual.
  status | Pointer to a standard ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)

Returns
  The pointer to the UTF-8 string. It may be dest, or at some offset from dest (only if !forceCopy), or in unrelated memory. Always NUL-terminated unless the string was written to dest and length==capacity (in which case U_STRING_NOT_TERMINATED_WARNING is set).

See also
  ures_getString
  u_strToUTF8

Stable:
  ICU 3.6

## ◆ ures_getUTF8StringByIndex()

U_CAPI const char* ures_getUTF8StringByIndex | ( | const UResourceBundle * | resB,
|  | int32_t | stringIndex,
|  | char * | dest,
|  | int32_t * | pLength,
|  | UBool | forceCopy,
|  | UErrorCode * | status
| ) |  |

Returns a UTF-8 string from a resource at the specified index.

The UTF-8 string may be returnable directly as a pointer, or it may need to be copied, or transformed from UTF-16 using u_strToUTF8() or equivalent.

If forceCopy==true, then the string is always written to the dest buffer and dest is returned.

If forceCopy==false, then the string is returned as a pointer if possible, without needing a dest buffer (it can be NULL). If the string needs to be copied or transformed, then it may be placed into dest at an arbitrary offset.

If the string is to be written to dest, then U_BUFFER_OVERFLOW_ERROR and U_STRING_NOT_TERMINATED_WARNING are set if appropriate, as usual.

If the string is transformed from UTF-16, then a conversion error may occur if an unpaired surrogate is encountered. If the function is successful, then the output UTF-8 string is always well-formed.

Parameters

  resB | Resource bundle.
  stringIndex | An index to the wanted string.
  dest | Destination buffer. Can be NULL only if capacity=*length==0.
  pLength | Input: Capacity of destination buffer. Output: Actual length of the UTF-8 string, not counting the terminating NUL, even in case of U_BUFFER_OVERFLOW_ERROR. Can be NULL, meaning capacity=0 and the string length is not returned to the caller.
  forceCopy | If true, then the output string will always be written to dest, with U_BUFFER_OVERFLOW_ERROR and U_STRING_NOT_TERMINATED_WARNING set if appropriate. If false, then the dest buffer may or may not contain a copy of the string. dest may or may not be modified. If a copy needs to be written, then the UErrorCode parameter indicates overflow etc. as usual.
  status | Pointer to a standard ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)

Returns
  The pointer to the UTF-8 string. It may be dest, or at some offset from dest (only if !forceCopy), or in unrelated memory. Always NUL-terminated unless the string was written to dest and length==capacity (in which case U_STRING_NOT_TERMINATED_WARNING is set).

See also
  ures_getStringByIndex
  u_strToUTF8

Stable:
  ICU 3.6

## ◆ ures_getUTF8StringByKey()

U_CAPI const char* ures_getUTF8StringByKey | ( | const UResourceBundle * | resB,
|  | const char * | key,
|  | char * | dest,
|  | int32_t * | pLength,
|  | UBool | forceCopy,
|  | UErrorCode * | status
| ) |  |

Returns a UTF-8 string from a resource and a key.

This function works only with table resources.

The UTF-8 string may be returnable directly as a pointer, or it may need to be copied, or transformed from UTF-16 using u_strToUTF8() or equivalent.

If forceCopy==true, then the string is always written to the dest buffer and dest is returned.

If forceCopy==false, then the string is returned as a pointer if possible, without needing a dest buffer (it can be NULL). If the string needs to be copied or transformed, then it may be placed into dest at an arbitrary offset.

If the string is to be written to dest, then U_BUFFER_OVERFLOW_ERROR and U_STRING_NOT_TERMINATED_WARNING are set if appropriate, as usual.

If the string is transformed from UTF-16, then a conversion error may occur if an unpaired surrogate is encountered. If the function is successful, then the output UTF-8 string is always well-formed.

Parameters

  resB | Resource bundle.
  key | A key associated with the wanted resource
  dest | Destination buffer. Can be NULL only if capacity=*length==0.
  pLength | Input: Capacity of destination buffer. Output: Actual length of the UTF-8 string, not counting the terminating NUL, even in case of U_BUFFER_OVERFLOW_ERROR. Can be NULL, meaning capacity=0 and the string length is not returned to the caller.
  forceCopy | If true, then the output string will always be written to dest, with U_BUFFER_OVERFLOW_ERROR and U_STRING_NOT_TERMINATED_WARNING set if appropriate. If false, then the dest buffer may or may not contain a copy of the string. dest may or may not be modified. If a copy needs to be written, then the UErrorCode parameter indicates overflow etc. as usual.
  status | Pointer to a standard ICU error code. Its input value must pass the U_SUCCESS() test, or else the function returns immediately. Check for U_FAILURE() on output or use with function chaining. (See User Guide for details.)

Returns
  The pointer to the UTF-8 string. It may be dest, or at some offset from dest (only if !forceCopy), or in unrelated memory. Always NUL-terminated unless the string was written to dest and length==capacity (in which case U_STRING_NOT_TERMINATED_WARNING is set).

See also
  ures_getStringByKey
  u_strToUTF8

Stable:
  ICU 3.6

## ◆ ures_getVersion()

U_CAPI void ures_getVersion | ( | const UResourceBundle * | resB,
|  | UVersionInfo | versionInfo
| ) |  |

Return the version number associated with this ResourceBundle as an UVersionInfo array.

Parameters

  resB | The resource bundle for which the version is checked.
  versionInfo | A UVersionInfo array that is filled with the version number as specified in the resource bundle or its parent.

Stable:
  ICU 2.0

## ◆ ures_getVersionNumber()

const char* ures_getVersionNumber | ( | const UResourceBundle * | resourceBundle | ) |

Return the version number associated with this ResourceBundle as a string.

Please use ures_getVersion as this function is going to be deprecated.

Parameters

  resourceBundle | The resource bundle for which the version is checked.

Returns
  A version number string as specified in the resource bundle or its parent. The caller does not own this string.

See also
  ures_getVersion

Deprecated:
  ICU 2.8 Use ures_getVersion instead.

## ◆ ures_hasNext()

U_CAPI UBool ures_hasNext | ( | const UResourceBundle * | resourceBundle | ) |

Checks whether the given resource has another element to iterate over.

Parameters

  resourceBundle | a resource

Returns
  true if there are more elements, false if there is no more elements

Stable:
  ICU 2.0

## ◆ ures_open()

U_CAPI UResourceBundle* ures_open | ( | const char * | packageName,
|  | const char * | locale,
|  | UErrorCode * | status
| ) |  |

Opens a UResourceBundle, from which users can extract strings by using their corresponding keys.

Note that the caller is responsible of calling `ures_close` on each successfully opened resource bundle.

Parameters

  packageName | The packageName and locale together point to an ICU udata object, as defined by `udata_open( packageName, "res", locale, err)` or equivalent. Typically, packageName will refer to a (.dat) file, or to a package registered with udata_setAppData(). Using a full file or directory pathname for packageName is deprecated. If NULL, ICU data will be used.
  locale | specifies the locale for which we want to open the resource if NULL, the default locale will be used. If strlen(locale) == 0 root locale will be used.
  status | fills in the outgoing error code. The UErrorCode err parameter is used to return status information to the user. To check whether the construction succeeded or not, you should check the value of U_SUCCESS(err). If you wish more detailed information, you can check for informational status results which still indicate success. U_USING_FALLBACK_WARNING indicates that a fall back locale was used. For example, 'de_CH' was requested, but nothing was found there, so 'de' was used. U_USING_DEFAULT_WARNING indicates that the default locale data or root locale data was used; neither the requested locale nor any of its fall back locales could be found. Please see the users guide for more information on this topic.

Returns
  a newly allocated resource bundle.

See also
  ures_close

Stable:
  ICU 2.0

## ◆ ures_openAvailableLocales()

U_CAPI UEnumeration* ures_openAvailableLocales | ( | const char * | packageName,
|  | UErrorCode * | status
| ) |  |

Create a string enumerator, owned by the caller, of all locales located within the specified resource tree.

Parameters

  packageName | name of the tree, such as (NULL) or U_ICUDATA_ALIAS or or "ICUDATA-coll" This call is similar to uloc_getAvailable().
  status | error code

Stable:
  ICU 3.2

## ◆ ures_openDirect()

U_CAPI UResourceBundle* ures_openDirect | ( | const char * | packageName,
|  | const char * | locale,
|  | UErrorCode * | status
| ) |  |

This function does not care what kind of localeID is passed in.

It simply opens a bundle with that name. Fallback mechanism is disabled for the new bundle. If the requested bundle contains an %ALIAS directive, the results are undefined.

Parameters

  packageName | The packageName and locale together point to an ICU udata object, as defined by `udata_open( packageName, "res", locale, err)` or equivalent. Typically, packageName will refer to a (.dat) file, or to a package registered with udata_setAppData(). Using a full file or directory pathname for packageName is deprecated. If NULL, ICU data will be used.
  locale | specifies the locale for which we want to open the resource if NULL, the default locale will be used. If strlen(locale) == 0 root locale will be used.
  status | fills in the outgoing error code. Either U_ZERO_ERROR or U_MISSING_RESOURCE_ERROR

Returns
  a newly allocated resource bundle or NULL if it doesn't exist.

See also
  ures_close

Stable:
  ICU 2.0

## ◆ ures_openFillIn()

U_CAPI void ures_openFillIn | ( | UResourceBundle * | r,
|  | const char * | packageName,
|  | const char * | localeID,
|  | UErrorCode * | status
| ) |  |

Same as ures_open() but uses the fill-in parameter instead of allocating a new bundle.

TODO need to revisit usefulness of this function and usage model for fillIn parameters without knowing sizeof(UResourceBundle)

Parameters

  r | The existing UResourceBundle to fill in. If NULL then status will be set to U_ILLEGAL_ARGUMENT_ERROR.
  packageName | The packageName and locale together point to an ICU udata object, as defined by `udata_open( packageName, "res", locale, err)` or equivalent. Typically, packageName will refer to a (.dat) file, or to a package registered with udata_setAppData(). Using a full file or directory pathname for packageName is deprecated. If NULL, ICU data will be used.
  localeID | specifies the locale for which we want to open the resource
  status | The error code.

Internal:
  Do not use. This API is for internal use only.

## ◆ ures_openU()

U_CAPI UResourceBundle* ures_openU | ( | const UChar * | packageName,
|  | const char * | locale,
|  | UErrorCode * | status
| ) |  |

Same as ures_open() but takes a const UChar *path.

This path will be converted to char * using the default converter, then ures_open() is called.

Parameters

  packageName | The packageName and locale together point to an ICU udata object, as defined by `udata_open( packageName, "res", locale, err)` or equivalent. Typically, packageName will refer to a (.dat) file, or to a package registered with udata_setAppData(). Using a full file or directory pathname for packageName is deprecated. If NULL, ICU data will be used.
  locale | specifies the locale for which we want to open the resource if NULL, the default locale will be used. If strlen(locale) == 0 root locale will be used.
  status | fills in the outgoing error code.

Returns
  a newly allocated resource bundle.

See also
  ures_open

Stable:
  ICU 2.0

## ◆ ures_resetIterator()

U_CAPI void ures_resetIterator | ( | UResourceBundle * | resourceBundle | ) |

Resets the internal context of a resource so that iteration starts from the first element.

Parameters

  resourceBundle | a resource

Stable:
  ICU 2.0