Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Header Files   Compound Members   File Members  

ures.h File Reference

ResourceBundle C API. More...


Typedefs

typedef void* UResourceBundle
A UResourceBundle. More...


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 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 const char* ures_getLocale (const UResourceBundle* resourceBundle, UErrorCode* status)
Return the name of the Locale associated with this ResourceBundle. More...


Detailed Description

ResourceBundle C API.

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 {...}
 .   }
 
The tags are used to retrieve the data later. You may not have multiple instances of the same tag.

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 }
 
This is indistinguishable from a comma-delimited list with only one element, and in fact may be retrieved as such (as an array, or as element 0 or an array).

Comma-delimited lists have the format:

 .   Tag { Data, Data, Data }
 
Parsing is lenient; a final string, after the last element, is allowed.

Tagged lists have the format:

 .   Tag { Subtag { Data } Subtag {Data} }
 
Data is retrieved by specifying the subtag.

Two-dimensional arrays have the format:

 .   TwoD {
 .       { r1c1, r1c2, ..., r1cm },
 .       { r2c1, r2c2, ..., r2cm },
 .       ...
 .       { rnc1, rnc2, ..., rncm }
 .   }
 
where n is the number of rows, and m is the number of columns. Parsing is lenient (as in other data types). A final comma is always allowed after the last element; either the last string in a row, or the last row itself. Furthermore, since there is no ambiguity, the commas between the rows are entirely optional. (However, if a comma is present, there can only be one comma, no more.) It is possible to have zero columns, as follows:
 .   Odd { {} {} {} } // 3 x 0 array
 
But it is impossible to have zero rows. The smallest array is thus a 1 x 0 array, which looks like this:
 .   Smallest { {} } // 1 x 0 array
 
The array must be strictly rectangular; that is, each row must have the same number of elements.

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 );
 

Typedef Documentation

typedef void* UResourceBundle

A UResourceBundle.

For usage in C programs.


Function Documentation

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.

Parameters:
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

Parameters:
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 was used; neither the requested locale nor any of its fall back locales could be found.
Returns:
: a newly allocated resource bundle.
See also:
ures_close()
Draft:

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.

Parameters:
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

Parameters:
status:   fills in the outgoing error code.
See also:
ures_close()
Returns:
: a newly allocated resource bundle.
Draft:

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.

Parameters:
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
Returns:
a library-owned zero-terminated unicode string (its lifetime is that of the resource bundle.)
See also:
ures_getArrayItem() , ures_get2dArrayItem() , ures_getTaggedItem
Draft:

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.

Parameters:
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
Returns:
a library-owned zero-terminated unicode string (its lifetime is that of the resource bundle.)
See also:
ures_get() , ures_get2dArrayItem() , ures_getTaggedItem
Draft:

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.

Parameters:
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
Returns:
a library-owned zero-terminated unicode string (its lifetime is that of the resource bundle.)
See also:
ures_get() , ures_getArrayItem() , ures_getTaggedItem
Draft:

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.

Parameters:
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
Returns:
a library-owned zero-terminated unicode string (its lifetime is that of the resource bundle.)
See also:
ures_get() , ures_getArrayItem() , ures_get2dItem
Draft:

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.

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_ERROR,U_USING_DEFAULT_ERROR
Returns:
for Arrays: returns the number of strings in the array 2d Arrays: returns the number of 1d arrays taggedArrays: returns the number of strings in the array single string: returns 1
See also:
ures_get() , ures_getArrayItem() , ures_getTaggedArrayItem() , ures_get2dArrayItem()
Draft:

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.

Parameters:
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
See also:
ures_open() , ures_openW()
Draft:

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.

Parameters:
resourceBundle:   resource bundle in question
Returns:
A string of the form N.n, where N is the major version number, representing the code version, and n is the minor version number, representing the resource data file. The caller does not own this string.
Draft:

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

Return the name of the Locale associated with this ResourceBundle.

Parameters:
resourceBundle:   resource bundle in question
status:   just for catching illegal arguments
Returns:
A Locale name
Draft:

Generated at Thu Feb 10 15:30:20 2000 for icu by doxygen 1.0.0 written by Dimitri van Heesch, © 1997-1999