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

ResourceBundle Class Reference

A class representing a collection of resource information pertaining to a given locale. More...

#include <resbund.h>

List of all members.


Public Members

 ResourceBundle ( const UnicodeString& path, const Locale& locale, UErrorCode& err)
Constructor. More...

 ResourceBundle ( const UnicodeString& path, UErrorCode& err)
 ResourceBundle ( const wchar_t* path, const Locale& locale, UErrorCode& err)
 ~ResourceBundle ()
void getString ( const char *resourceTag, UnicodeString& theString, UErrorCode& err) const
Returns the contents of a string resource. More...

const UnicodeStringgetString ( const char *resourceTag, UErrorCode& err) const
Returns the contents of a string resource. More...

const UnicodeStringgetStringArray ( const char *resourceTag, int32_t& numArrayItems, UErrorCode& err) const
Returns the contents of a string-array resource. More...

void getArrayItem ( const char *resourceTag, int32_t index, UnicodeString& theArrayItem, UErrorCode& err) const
Returns a single item from a string-array resource. More...

const UnicodeStringgetArrayItem ( const char *resourceTag, int32_t index, UErrorCode& err) const
Returns a single item from a string-array resource. More...

const UnicodeString** get2dArray (const char *resourceTag, int32_t& rowCount, int32_t& columnCount, UErrorCode& err) const
Return the contents of a 2-dimensional array resource. More...

void get2dArrayItem (const char *resourceTag, int32_t rowIndex, int32_t columnIndex, UnicodeString& theArrayItem, UErrorCode& err) const
Return a single string from a 2-dimensional array resource. More...

const UnicodeStringget2dArrayItem ( const char *resourceTag, int32_t rowIndex, int32_t columnIndex, UErrorCode& err) const
Return a single string from a 2-dimensional array resource. More...

void getTaggedArrayItem ( const char *resourceTag, const UnicodeString& itemTag, UnicodeString& theArrayItem, UErrorCode& err) const
Returns a single item from a tagged-array resource This will return the contents of a single item in a resource of type tagged-array. More...

const UnicodeStringgetTaggedArrayItem ( const char *resourceTag, const UnicodeString& itemTag, UErrorCode& err) const
Returns a single item from a tagged-array resource This will return the contents of a single item in a resource of type tagged-array. More...

void getTaggedArray ( const char *resourceTag, UnicodeString*& itemTags, UnicodeString*& items, int32_t& numItems, UErrorCode& err) const
Returns a tagged-array resource. More...

const char* getVersionNumber (void) const
Return the version number associated with this ResourceBundle. More...

const LocalegetLocale (void) const
Return the Locale associated with this ResourceBundle. More...


Friends

int32_t T_ResourceBundle_countArrayItemsImplementation (const ResourceBundle* resourceBundle, const char* resourceKey, UErrorCode& err)
const UnicodeString** listInstalledLocalesImplementation (const char* path, int32_t* numInstalledLocales)
void getTaggedArrayUCharsImplementation ( const ResourceBundle* bundle, const char *resourceTag, UChar const** itemTags, UChar const** items, int32_t maxItems, int32_t& numItems, UErrorCode& err)
class  Locale
class  RuleBasedCollator


Detailed Description

A class representing a collection of resource information pertaining to a given locale.

A resource bundle provides a way of accessing locale- specfic 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:

 .    Locale currentLocale;
 .    UErrorCode success = U_ZERO_ERROR;
 .    ResourceBundle myResources("MyResources", currentLocale, success );
 .
 .    UnicodeString button1Title, button2Title;
 .    myResources.getString("OkKey", button1Title, success );
 .    myResources.getString("CancelKey", button2Title, success );
 
Draft:

Member Function Documentation

ResourceBundle::ResourceBundle (const UnicodeString & path, const Locale & locale, UErrorCode & err)

Constructor.

Parameters:
path   This is a full pathname in the platform-specific format for the directory containing the resource data files we want to load resources from. We use locale IDs to generate filenames, and the filenames have this string prepended to them before being passed to the C++ I/O functions. Therefore, this string must always end with a directory delimiter (whatever that is for the target OS) for this class to work correctly.
locale   This is the locale this resource bundle is for. To get resources for the French locale, for example, you would create a ResourceBundle passing Locale::FRENCH for the "locale" parameter, and all subsequent calls to that resource bundle will return resources that pertain to the French locale. If the caller doesn't pass a locale parameter, the default locale for the system (as returned by Locale::getDefault()) will be used. 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.
Draft:

ResourceBundle::ResourceBundle (const UnicodeString & path, UErrorCode & err)

ResourceBundle::ResourceBundle (const wchar_t * path, const Locale & locale, UErrorCode & err)

ResourceBundle::~ResourceBundle ()

void ResourceBundle::getString (const char * resourceTag, UnicodeString & theString, UErrorCode & err) const

Returns the contents of a string resource.

Resource data is undifferentiated Unicode text. The resource file may contain quoted strings or escape sequences; these will be parsed prior to the data's return. [THIS FUNCTION IS DERECATED; USE THE OVERLOAD BELOW INSTEAD]

Parameters:
resourceTag   The resource tag of the string resource the caller wants
theString   Receives the actual data in the resource
err   Set to U_MISSING_RESOURCE_ERROR if a resource with the specified tag couldn't be found.
Draft:

const UnicodeString * ResourceBundle::getString (const char * resourceTag, UErrorCode & err) const

Returns the contents of a string resource.

Resource data is undifferentiated Unicode text. The resource file may contain quoted strings or escape sequences; these will be parsed prior to the data's return.

Parameters:
resourceTag   The resource tag of the string resource the caller wants
err   Set to U_MISSING_RESOURCE_ERROR if a resource with the specified tag couldn't be found.
Returns:
A pointer to the string from the resource bundle, or NULL if there was an error.
Draft:

const UnicodeString * ResourceBundle::getStringArray (const char * resourceTag, int32_t & numArrayItems, UErrorCode & err) const

Returns the contents of a string-array resource.

This will return the contents of a string-array (comma-delimited-list) resource as a C++ array of UnicodeString objects. The number of elements in the array is returned in numArrayItems. Calling getStringArray on a resource of type string will return an array with one element; calling it on a resource of type tagged-array results in a U_MISSING_RESOURCE_ERROR error.

Parameters:
resourceTag   The resource tag of the string-array resource the caller wants
numArrayItems   Receives the number of items in the array the function returns.
err   Set to U_MISSING_RESOURCE_ERROR if a resource with the specified tag couldn't be found.
Returns:
The resource requested, as a pointer to an array of UnicodeStrings. The caller does not own the storage and must not delete it.
Draft:

void ResourceBundle::getArrayItem (const char * resourceTag, int32_t index, UnicodeString & theArrayItem, UErrorCode & err) const

Returns a single item from a string-array resource.

This will return the contents of a single item in a resource of string-array (comma-delimited-list) type. If the resource is not an array, a U_MISSING_RESOURCE_ERROR will be returned in err. [THIS FUNCTION IS DEPRECATED; USE THE OVERLOAD BELOW INSTEAD]

Parameters:
resourceTag   The resource tag of the resource the caller wants to extract an item from.
index   The index (zero-based) of the particular array item the user wants to extract from the resource.
theArrayItem   Receives the actual text of the desired array item.
err   Set to U_MISSING_RESOURCE_ERROR if a resource with the specified tag couldn't be found, or if the index was out of range.
Draft:

const UnicodeString * ResourceBundle::getArrayItem (const char * resourceTag, int32_t index, UErrorCode & err) const

Returns a single item from a string-array resource.

This will return the contents of a single item in a resource of string-array (comma-delimited-list) type. If the resource is not an array, a U_MISSING_RESOURCE_ERROR will be returned in err.

Parameters:
resourceTag   The resource tag of the resource the caller wants to extract an item from.
index   The index (zero-based) of the particular array item the user wants to extract from the resource.
err   Set to U_MISSING_RESOURCE_ERROR if a resource with the specified tag couldn't be found, or if the index was out of range.
Returns:
A pointer to the text of the array item, or NULL is there was an error.
Draft:

const UnicodeString ** ResourceBundle::get2dArray (const char * resourceTag, int32_t & rowCount, int32_t & columnCount, UErrorCode & err) const

Return the contents of a 2-dimensional array resource.

The return value will be a UnicodeString** array. (This is really an array of pointers; each pointer is a ROW of the data.) The number of rows and columns is returned. If the resource is of the wrong type, or not present, U_MISSING_RESOURCE_ERROR is placed in err.

Parameters:
resourceTag   The resource tag of the string-array resource the caller wants
rowCount   Receives the number of rows in the array the function returns.
columnCount   Receives the number of columns in the array the function returns.
err   Set to U_MISSING_RESOURCE_ERROR if a resource with the specified tag couldn't be found.
Returns:
The resource requested, as a UnicodeStrings**. The caller does not own the storage and must not delete it.
Draft:

void ResourceBundle::get2dArrayItem (const char * resourceTag, int32_t rowIndex, int32_t columnIndex, UnicodeString & theArrayItem, UErrorCode & err) const

Return a single string from a 2-dimensional array resource.

If the resource does not exists, or if it is not a 2-d array, or if the row or column indices are out of bounds, err is set to U_MISSING_RESOURCE_ERROR. [THIS FUNCTION IS DEPRECATED; USE THE OVERLOAD BELOW INSTEAD]

Parameters:
resourceTag   The resource tag of the resource the caller wants to extract an item from.
rowIndex   The row index (zero-based) of the array item the user wants to extract from the resource.
columnIndex   The column index (zero-based) of the array item the user wants to extract from the resource.
theArrayItem   Receives the actual text of the desired array item.
err   Set to U_MISSING_RESOURCE_ERROR if a resource with the specified tag couldn't be found, if the resource data was in the wrong format, or if either index is out of bounds.
Draft:

const UnicodeString * ResourceBundle::get2dArrayItem (const char * resourceTag, int32_t rowIndex, int32_t columnIndex, UErrorCode & err) const

Return a single string from a 2-dimensional array resource.

If the resource does not exists, or if it is not a 2-d array, or if the row or column indices are out of bounds, err is set to U_MISSING_RESOURCE_ERROR.

Parameters:
resourceTag   The resource tag of the resource the caller wants to extract an item from.
rowIndex   The row index (zero-based) of the array item the user wants to extract from the resource.
columnIndex   The column index (zero-based) of the array item the user wants to extract from the resource.
err   Set to U_MISSING_RESOURCE_ERROR if a resource with the specified tag couldn't be found, if the resource data was in the wrong format, or if either index is out of bounds.
Returns:
A pointer to the text of the array item, or NULL is there was an error.
Draft:

void ResourceBundle::getTaggedArrayItem (const char * resourceTag, const UnicodeString & itemTag, UnicodeString & theArrayItem, UErrorCode & err) const

Returns a single item from a tagged-array resource This will return the contents of a single item in a resource of type tagged-array.

If this function is called for a resource that is not of type tagged-array, it will set err to MISSING_RESOUCE_ERROR. [THIS FUNCTION IS DEPRECATED; USE THE OVERLOAD BELOW INSTEAD]

Parameters:
resourceTag   The resource tag of the resource the caller wants to extract an item from.
itemTag   The item tag for the item the caller wants to extract.
theArrayItem   Receives the text of the desired array item.
err   Set to U_MISSING_RESOURCE_ERROR if a resource with the specified resource tag couldn't be found, or if an item with the specified item tag couldn't be found in the resource.
Draft:

const UnicodeString * ResourceBundle::getTaggedArrayItem (const char * resourceTag, const UnicodeString & itemTag, UErrorCode & err) const

Returns a single item from a tagged-array resource This will return the contents of a single item in a resource of type tagged-array.

If this function is called for a resource that is not of type tagged-array, it will set err to MISSING_RESOUCE_ERROR.

Parameters:
resourceTag   The resource tag of the resource the caller wants to extract an item from.
itemTag   The item tag for the item the caller wants to extract.
err   Set to U_MISSING_RESOURCE_ERROR if a resource with the specified resource tag couldn't be found, or if an item with the specified item tag coldn't be found in the resource.
Returns:
A pointer to the text of the array item, or NULL is there was an error.
Draft:

void ResourceBundle::getTaggedArray (const char * resourceTag, UnicodeString *& itemTags, UnicodeString *& items, int32_t & numItems, UErrorCode & err) const

Returns a tagged-array resource.

The contents of the resource is returned as two separate arrays of UnicodeStrings, the addresses of which are placed in "itemTags" and "items". After calling this function, the items in the resource will be in the list pointed to by "items", and for each items[i], itemTags[i] will be the tag that corresponds to it. The total number of entries in both arrays is returned in numItems.

Parameters:
resourceTag   The resource tag of the resource the caller wants to extract an item from.
itemTags   Set to point to an array of UnicodeStrings representing the tags in the specified resource. The caller DOES own this array, and must delete it.
items   Set to point to an array of UnicodeStrings containing the individual resource items themselves. itemTags[i] will contain the tag corresponding to items[i]. The caller DOES own this array, and must delete it.
numItems   Receives the number of items in the arrays pointed to by items and itemTags.
err   Set to U_MISSING_RESOURCE_ERROR if a resource with the specified tag couldn't be found.
Draft:

const char * ResourceBundle::getVersionNumber (void) const

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.

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:

const Locale & ResourceBundle::getLocale (void) const

Return the Locale associated with this ResourceBundle.

Returns:
a Locale object
Draft:

Friends And Related Function Documentation

int32_t T_ResourceBundle_countArrayItemsImplementation (const ResourceBundle * resourceBundle, const char * resourceKey, UErrorCode & err) [friend]

const UnicodeString** listInstalledLocalesImplementation (const char * path, int32_t * numInstalledLocales) [friend]

void getTaggedArrayUCharsImplementation (const ResourceBundle * bundle, const char * resourceTag, UChar const ** itemTags, UChar const ** items, int32_t maxItems, int32_t & numItems, UErrorCode & err) [friend]

friend class Locale [friend]

friend class RuleBasedCollator [friend]


The documentation for this class was generated from the following file:
Generated at Thu Feb 10 15:30:52 2000 for icu by doxygen 1.0.0 written by Dimitri van Heesch, © 1997-1999