Typedefs | |||
![]() | ![]() | typedef struct UResourceBundle | UResourceBundle |
Enumerations | |||
![]() | ![]() | enum | UResType { RES_NONE, RES_STRING, RES_BINARY, RES_TABLE, RES_INT, RES_ARRAY, RES_INT_VECTOR, RES_RESERVED } |
Functions | |||
![]() | ![]() | U_CAPI UResourceBundle* U_EXPORT2 | ures_open (const char* path, const char* locale, UErrorCode* status) |
![]() | ![]() | Opens a UResourceBundle, from which users can extract strings by using their corresponding keys. More... | |
![]() | ![]() | U_CAPI UResourceBundle* U_EXPORT2 | ures_openW (const wchar_t* path, const char* locale, UErrorCode* status) |
![]() | ![]() | Opens a UResourceBundle, from which users can extract strings by using their corresponding keys. More... | |
![]() | ![]() | U_CAPI UResourceBundle* U_EXPORT2 | ures_openU (const UChar* path, const char* locale, UErrorCode* status) |
![]() | ![]() | U_CAPI const UChar* U_EXPORT2 | ures_get (const UResourceBundle* resourceBundle, const char* resourceTag, UErrorCode* status) |
![]() | ![]() | returns a resource string, given a resource bundle and a key. More... | |
![]() | ![]() | U_CAPI const UChar* U_EXPORT2 | ures_getArrayItem (const UResourceBundle* resourceBundle, const char* resourceTag, int32_t resourceIndex, UErrorCode* status) |
![]() | ![]() | Returns a resource string which is part of an array, given a resource bundle a key to the array and the index of the desired string. More... | |
![]() | ![]() | U_CAPI const UChar* U_EXPORT2 | ures_get2dArrayItem (const UResourceBundle* resourceBundle, const char* resourceTag, int32_t rowIndex, int32_t columnIndex, UErrorCode* status) |
![]() | ![]() | Returns a resource string which is part of a 2D array, given a resource bundle a key to the array and the index pair of the desired string. More... | |
![]() | ![]() | U_CAPI const UChar* U_EXPORT2 | ures_getTaggedArrayItem (const UResourceBundle* resourceBundle, const char* resourceTag, const char* itemTag, UErrorCode* status) |
![]() | ![]() | Returns a resource string which is part of a tagged array, given a resource bundle a key to the array and the key of the desired string. More... | |
![]() | ![]() | U_CAPI int32_t U_EXPORT2 | ures_countArrayItems (const UResourceBundle* resourceBundle, const char* resourceKey, UErrorCode* err) |
![]() | ![]() | Returns the number of strings/arrays in resource bundles. More... | |
![]() | ![]() | U_CAPI void U_EXPORT2 | ures_close (UResourceBundle* resourceBundle) |
![]() | ![]() | close a resource bundle, all pointers returned from the various ures_getXXX calls on this particular bundle are INVALID henceforth. More... | |
![]() | ![]() | U_CAPI const char* U_EXPORT2 | ures_getVersionNumber (const UResourceBundle* resourceBundle) |
![]() | ![]() | Return the version number associated with this ResourceBundle. More... | |
![]() | ![]() | U_CAPI void U_EXPORT2 | ures_getVersion (const UResourceBundle* resB, UVersionInfo versionInfo) |
![]() | ![]() | U_CAPI const char* | ures_getLocale (const UResourceBundle* resourceBundle, UErrorCode* status) |
![]() | ![]() | Return the name of the Locale associated with this ResourceBundle. More... | |
![]() | ![]() | U_CAPI void | ures_openFillIn (UResourceBundle *r, const char* path, const char* localeID, UErrorCode* status) |
![]() | ![]() | New API. | |
![]() | ![]() | U_CAPI const UChar* U_EXPORT2 | ures_getString (const UResourceBundle* resourceBundle, int32_t* len, UErrorCode* status) |
![]() | ![]() | returns a string from a string resource type. More... | |
![]() | ![]() | U_CAPI const uint8_t* U_EXPORT2 | ures_getBinary (const UResourceBundle* resourceBundle, int32_t* len, UErrorCode* status) |
![]() | ![]() | returns a binary data from a resource. More... | |
![]() | ![]() | U_CAPI uint32_t U_EXPORT2 | ures_getInt (const UResourceBundle* resourceBundle, UErrorCode *status) |
![]() | ![]() | returns an integer from a resource. More... | |
![]() | ![]() | U_CAPI int32_t U_EXPORT2 | ures_getSize (UResourceBundle *resourceBundle) |
![]() | ![]() | Returns the size of a resource. More... | |
![]() | ![]() | U_CAPI UResType U_EXPORT2 | ures_getType (UResourceBundle *resourceBundle) |
![]() | ![]() | Returns the type of a resource. More... | |
![]() | ![]() | U_CAPI const char* U_EXPORT2 | ures_getKey (UResourceBundle *resB) |
![]() | ![]() | Returns the key associated with a given resource. More... | |
![]() | ![]() | U_CAPI void U_EXPORT2 | ures_resetIterator (UResourceBundle *resourceBundle) |
![]() | ![]() | Resets the internal context of a resource so that iteration starts from the first element. More... | |
![]() | ![]() | U_CAPI UBool U_EXPORT2 | ures_hasNext (UResourceBundle *resourceBundle) |
![]() | ![]() | Checks whether the given resource has another element to iterate over. More... | |
![]() | ![]() | U_CAPI UResourceBundle* U_EXPORT2 | 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* U_EXPORT2 | 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* U_EXPORT2 | 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* U_EXPORT2 | ures_getStringByIndex (const UResourceBundle *resB, int32_t indexS, int32_t* len, UErrorCode *status) |
![]() | ![]() | Returns the string in a given resource at the specified index. More... | |
![]() | ![]() | U_CAPI UResourceBundle* U_EXPORT2 | 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* U_EXPORT2 | 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_CFUNC const char* | ures_getName (const UResourceBundle* resB) |
![]() | ![]() | U_CFUNC const char* | ures_getPath (const UResourceBundle* resB) |
![]() | ![]() | U_CFUNC const char* | ures_getTag (const UResourceBundle* resB) |
Variables | |||
![]() | ![]() | struct | UResourceBundle |
![]() | ![]() | A UResourceBundle. More... |
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.
The resource bundle file is a text (ASCII or Unicode) file with the format:
. locale { . tag1 {...} . tag2 {...} . }
Four data types are supported. These are solitary strings, comma-delimited lists of strings, 2-dimensional arrays of strings, and tagged lists of strings.
Note that all data is textual. Adjacent strings are merged by the low-level tokenizer, so that the following effects occur: foo bar, baz // 2 elements, "foo bar", and "baz" "foo" "bar", baz // 2 elements, "foobar", and "baz" Note that a single intervening space is added between merged strings, unless they are both double quoted. This extends to more than two strings in a row.
Whitespace is ignored, as in a C source file.
Solitary strings have the format:
. Tag { Data }
Comma-delimited lists have the format:
. Tag { Data, Data, Data }
Tagged lists have the format:
. Tag { Subtag { Data } Subtag {Data} }
Two-dimensional arrays have the format:
. TwoD { . { r1c1, r1c2, ..., r1cm }, . { r2c1, r2c2, ..., r2cm }, . ... . { rnc1, rnc2, ..., rncm } . }
. Odd { {} {} {} } // 3 x 0 array
. Smallest { {} } // 1 x 0 array
UResourceBundle
If the data for the requested locale is missing, an effort will be made to obtain most usable data. This process is called fallback. Also, fallback happens when a resource is not present in the given bundle. Then, the other bundles in the fallback chain are also searched for the requested resource.
Retrieving data from resources is possible in several ways, depending on the type of the resources:
1) Access by a key: this approach works only for table resources
2) Access by an index: tables and arrays can be addressed by an index
3) Iteration: works for tables and arrays
To use data in resource bundles, following steps are needed:
1) opening a bundle for a particular locale:
UErrorCode status = U_ZERO_ERROR; UResourceBundle* resB = ures_open("/datadir/resources/GUI", "de_AT_EURO", &status);
This is an example for using a possible custom resource:
. const char *currentLocale; . UErrorCode success = U_ZERO_ERROR; . UResourceBundle* myResources=ures_open("MyResources", currentLocale, &success ); . . UChar *button1Title, *button2Title; . button1Title= ures_get(myResources, "OkKey", &success ); . button2Title= ures_get(myResources, "CancelKey", &success );
Definition in file ures.h.
typedef struct UResourceBundle UResourceBundle |
enum UResType |
RES_NONE | |
RES_STRING | |
RES_BINARY | |
RES_TABLE | |
RES_INT | |
RES_ARRAY | |
RES_INT_VECTOR | |
RES_RESERVED |
U_CAPI UResourceBundle *U_EXPORT2 ures_open (const char * path, 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 succesfully opened resource bundle.
path | : string containing the full path pointing to the directory where the resources reside followed by the package name e.g. "/usr/resource/my_app/resources/guimessages" on a Unix system. if NULL, ICU default data files 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 error results which still indicate success. U_USING_FALLBACK_ERROR 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_ERROR 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. |
U_CAPI UResourceBundle *U_EXPORT2 ures_openW (const wchar_t * path, const char * locale, UErrorCode * status) |
Opens a UResourceBundle, from which users can extract strings by using their corresponding keys.
This version of open requires the path string to be of type const wchar_t*
. Note that the caller is responsible of calling ures_close
on each succesfully opened resource bundle.
path: | string containing the full path pointing to the directory where the resources reside (should end with a directory separator. e.g. "/usr/resource/my_app/resources/" on a Unix system if NULL will use the system's current data directory |
locale: |
specifies the locale for which we want to open the resource if NULL will use the default locale
|
status: | fills in the outgoing error code. |
U_CAPI UResourceBundle* U_EXPORT2 ures_openU (const UChar * path, const char * locale, UErrorCode * status) |
U_CAPI const UChar *U_EXPORT2 ures_get (const UResourceBundle * resourceBundle, const char * resourceTag, UErrorCode * status) |
returns a resource string, given a resource bundle and a key.
resourceBundle: | resourceBundle containing the desired string |
resourceTag: | key tagging the desired string |
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_ERROR ,U_USING_DEFAULT_ERROR |
U_CAPI const UChar *U_EXPORT2 ures_getArrayItem (const UResourceBundle * resourceBundle, const char * resourceTag, int32_t resourceIndex, UErrorCode * status) |
Returns a resource string which is part of an array, given a resource bundle a key to the array and the index of the desired string.
resourceBundle: | resourceBundle containing the desired string |
resourceTag: | key tagging the desired array |
resourceIndex: | index of the desired string |
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_ERROR ,U_USING_DEFAULT_ERROR |
U_CAPI const UChar *U_EXPORT2 ures_get2dArrayItem (const UResourceBundle * resourceBundle, const char * resourceTag, int32_t rowIndex, int32_t columnIndex, UErrorCode * status) |
Returns a resource string which is part of a 2D array, given a resource bundle a key to the array and the index pair of the desired string.
resourceBundle: | resourceBundle containing the desired string |
resourceTag: | key tagging the desired array |
resourceIndex: | x index of the desired string |
resourceIndex: | y index of the desired string |
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_ERROR ,U_USING_DEFAULT_ERROR |
U_CAPI const UChar *U_EXPORT2 ures_getTaggedArrayItem (const UResourceBundle * resourceBundle, const char * resourceTag, const char * itemTag, UErrorCode * status) |
Returns a resource string which is part of a tagged array, given a resource bundle a key to the array and the key of the desired string.
resourceBundle: | resource bundle containing the desired string |
resourceTag: | key tagging the desired array |
resourceIndex: | key tagging the desired string |
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_ERROR ,U_USING_DEFAULT_ERROR |
U_CAPI int32_t U_EXPORT2 ures_countArrayItems (const UResourceBundle * resourceBundle, const char * resourceKey, UErrorCode * err) |
Returns the number of strings/arrays in resource bundles.
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_ERROR ,U_USING_DEFAULT_ERROR |
U_CAPI void U_EXPORT2 ures_close (UResourceBundle * resourceBundle) |
close a resource bundle, all pointers returned from the various ures_getXXX calls on this particular bundle are INVALID henceforth.
resourceBundle: | a succesfully opened resourceBundle. |
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_ERROR ,U_USING_DEFAULT_ERROR |
U_CAPI const char *U_EXPORT2 ures_getVersionNumber (const UResourceBundle * resourceBundle) |
Return the version number associated with this ResourceBundle.
This version number is a string of the form MAJOR.MINOR, where MAJOR is the version number of the current analytic code package, and MINOR is the version number contained in the resource file as the value of the tag "Version". A change in the MINOR version indicated an updated data file. A change in the MAJOR version indicates a new version of the code which is not binary-compatible with the previous version. If no "Version" tag is present in a resource file, the MINOR version "0" is assigned. For example, if the Collation sort key algorithm changes, the MAJOR version increments. If the collation data in a resource file changes, the MINOR version for that file increments.
resourceBundle: | resource bundle in question |
U_CAPI void U_EXPORT2 ures_getVersion (const UResourceBundle * resB, UVersionInfo versionInfo) |
U_CAPI const char * ures_getLocale (const UResourceBundle * resourceBundle, UErrorCode * status) |
Return the name of the Locale associated with this ResourceBundle.
resourceBundle: | resource bundle in question |
status: | just for catching illegal arguments |
U_CAPI void ures_openFillIn (UResourceBundle * r, const char * path, const char * localeID, UErrorCode * status) |
New API.
U_CAPI const UChar *U_EXPORT2 ures_getString (const UResourceBundle * resourceBundle, int32_t * len, UErrorCode * status) |
returns a string from a string resource type.
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 could be a non-failing error e.g.: U_USING_FALLBACK_ERROR ,U_USING_DEFAULT_ERROR |
U_CAPI const uint8_t *U_EXPORT2 ures_getBinary (const UResourceBundle * resourceBundle, int32_t * len, UErrorCode * status) |
returns a binary data from a resource.
Can be used at most primitive resource types (binaries, strings, ints)
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 could be a non-failing error e.g.: U_USING_FALLBACK_ERROR ,U_USING_DEFAULT_ERROR |
U_CAPI uint32_t U_EXPORT2 ures_getInt (const UResourceBundle * resourceBundle, UErrorCode * status) |
returns an integer from a resource.
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_ERROR ,U_USING_DEFAULT_ERROR |
U_CAPI int32_t U_EXPORT2 ures_getSize (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.
resourceBundle: | a resource |
U_CAPI UResType U_EXPORT2 ures_getType (UResourceBundle * resourceBundle) |
Returns the type of a resource.
Available types are defined in enum UResType
resourceBundle: | a resource |
U_CAPI const char *U_EXPORT2 ures_getKey (UResourceBundle * resB) |
Returns the key associated with a given resource.
Not all the resources have a key - only those that are members of a table.
resourceBundle: | a resource |
U_CAPI void U_EXPORT2 ures_resetIterator (UResourceBundle * resourceBundle) |
Resets the internal context of a resource so that iteration starts from the first element.
resourceBundle: | a resource |
U_CAPI UBool U_EXPORT2 ures_hasNext (UResourceBundle * resourceBundle) |
Checks whether the given resource has another element to iterate over.
resourceBundle | a resource |
U_CAPI UResourceBundle *U_EXPORT2 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.
resourceBundle | a resource |
fillIn | if NULL a new UResourceBundle struct is allocated and must be deleted by the caller. Alternatively, you can supply a struct to be filled by this function. |
status | fills in the outgoing error code |
U_CAPI const UChar *U_EXPORT2 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.
resourceBundle | a resource |
len | fill in length of the string |
key | fill in for key associated with this string |
status | fills in the outgoing error code |
U_CAPI UResourceBundle *U_EXPORT2 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.
resourceBundle | a resource |
indexR | an index to the wanted resource. |
fillIn | if NULL a new UResourceBundle struct is allocated and must be deleted by the caller. Alternatively, you can supply a struct to be filled by this function. |
status | fills in the outgoing error code |
U_CAPI const UChar *U_EXPORT2 ures_getStringByIndex (const UResourceBundle * resB, int32_t indexS, int32_t * len, UErrorCode * status) |
Returns the string in a given resource at the specified index.
resourceBundle | a resource |
indexS | an index to the wanted string. |
len | fill in length of the string |
status | fills in the outgoing error code |
U_CAPI UResourceBundle *U_EXPORT2 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.
resourceBundle | a resource |
key | a key associated with the wanted resource |
fillIn | if NULL a new UResourceBundle struct is allocated and must be deleted by the caller. Alternatively, you can supply a struct to be filled by this function. |
status | fills in the outgoing error code. |
U_CAPI const UChar *U_EXPORT2 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.
resourceBundle | a resource |
key | a key associated with the wanted string |
len | fill in length of the string |
status | fills in the outgoing error code |
U_CFUNC const char* ures_getName (const UResourceBundle * resB) |
U_CFUNC const char* ures_getPath (const UResourceBundle * resB) |
U_CFUNC const char* ures_getTag (const UResourceBundle * resB) |
struct UResourceBundle |