Main Page   Class Hierarchy   Alphabetical List   Data Structures   File List   Data Fields   Globals  

ResourceBundle Class Reference

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

#include <resbund.h>


Public Methods

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

 ResourceBundle (const UnicodeString &path, UErrorCode &err)
 Construct a resource bundle for the root bundle in the specified path. More...

 ResourceBundle (UErrorCode &err)
 Construct a resource bundle for the ICU root bundle. More...

 ResourceBundle (const wchar_t *path, const Locale &locale, UErrorCode &err)
 Constructs a ResourceBundle. More...

 ResourceBundle (const char *path, const Locale &locale, UErrorCode &err)
 Standard constructor, onstructs a resource bundle for the locale-specific bundle in the specified path. More...

 ResourceBundle (const ResourceBundle &original)
 Copy constructor. More...

 ResourceBundle (UResourceBundle *res, UErrorCode &status)
 Constructor from a C UResourceBundle. More...

ResourceBundle & operator= (const ResourceBundle &other)
 Assignment operator. More...

 ~ResourceBundle ()
 Destructor. More...

int32_t getSize (void) const
 Returns the size of a resource. More...

UnicodeString getString (UErrorCode &status) const
 returns a string from a string resource type. More...

const uint8_t * getBinary (int32_t &len, UErrorCode &status) const
 returns a binary data from a resource. More...

const int32_t * getIntVector (int32_t &len, UErrorCode &status) const
 returns an integer vector from a resource. More...

uint32_t getUInt (UErrorCode &status) const
 returns an unsigned integer from a resource. More...

int32_t getInt (UErrorCode &status) const
 returns a signed integer from a resource. More...

UBool hasNext (void) const
 Checks whether the resource has another element to iterate over. More...

void resetIterator (void)
 Resets the internal context of a resource so that iteration starts from the first element. More...

const char * getKey (void)
 Returns the key associated with this resource. More...

const char * getName (void)
 Gets the locale ID of the resource bundle as a string. More...

UResType getType (void)
 Returns the type of a resource. More...

ResourceBundle getNext (UErrorCode &status)
 Returns the next resource in a given resource or NULL if there are no more resources. More...

UnicodeString getNextString (UErrorCode &status)
 Returns the next string in a resource or NULL if there are no more resources to iterate over. More...

UnicodeString getNextString (const char **key, UErrorCode &status)
 Returns the next string in a resource or NULL if there are no more resources to iterate over. More...

ResourceBundle get (int32_t index, UErrorCode &status) const
 Returns the resource in a resource at the specified index. More...

UnicodeString getStringEx (int32_t index, UErrorCode &status) const
 Returns the string in a given resource at the specified index. More...

ResourceBundle get (const char *key, UErrorCode &status) const
 Returns a resource in a resource that has a given key. More...

UnicodeString getStringEx (const char *key, UErrorCode &status) const
 Returns a string in a resource that has a given key. More...

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

void getVersion (UVersionInfo versionInfo) const
 Return the version number associated with this ResourceBundle as a UVersionInfo array. More...

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


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


Constructor & Destructor 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. @stable

ResourceBundle::ResourceBundle const UnicodeString   path,
UErrorCode   err
 

Construct a resource bundle for the root bundle in the specified path.

Parameters:
path  A path/basename for the data file(s) containing the bundle.
err  A UErrorCode value @stable

ResourceBundle::ResourceBundle UErrorCode   err
 

Construct a resource bundle for the ICU root bundle.

Parameters:
err  A UErrorCode value @stable

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

Constructs a ResourceBundle.

Deprecated:
Remove after Aug 2002

ResourceBundle::ResourceBundle const char *    path,
const Locale &    locale,
UErrorCode   err
 

Standard constructor, onstructs a resource bundle for the locale-specific bundle in the specified path.

Parameters:
path  A path/basename for the data file(s) containing the bundle. NULL is used for ICU data.
locale  The locale for which to open a resource bundle.
err  A UErrorCode value @stable

ResourceBundle::ResourceBundle const ResourceBundle &    original
 

Copy constructor.

Parameters:
original  The resource bundle to copy. @stable

ResourceBundle::ResourceBundle UResourceBundle   res,
UErrorCode   status
 

Constructor from a C UResourceBundle.

Parameters:
res  A pointer to the C resource bundle.
status  A UErrorCode value. @stable

ResourceBundle::~ResourceBundle  
 

Destructor.

@stable


Member Function Documentation

ResourceBundle ResourceBundle::get const char *    key,
UErrorCode   status
const
 

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

This procedure works only with table resources.

Parameters:
key  a key associated with the wanted resource
status  fills in the outgoing error code.
Returns:
ResourceBundle object. If there is an error, resource is invalid. @stable

ResourceBundle ResourceBundle::get int32_t    index,
UErrorCode   status
const
 

Returns the resource in a resource at the specified index.

Parameters:
index  an index to the wanted resource.
status  fills in the outgoing error code
Returns:
ResourceBundle object. If there is an error, resource is invalid. @stable

const uint8_t* ResourceBundle::getBinary int32_t &    len,
UErrorCode   status
const
 

returns a binary data from a resource.

Can be used at most primitive resource types (binaries, strings, ints)

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</T> if the key is not found could be a non-failing error e.g.: U_USING_FALLBACK_ERROR,U_USING_DEFAULT_ERROR
Returns:
a pointer to a chunk of unsigned bytes which live in a memory mapped/DLL file. @stable

int32_t ResourceBundle::getInt UErrorCode   status const
 

returns a signed integer from a resource.

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

Parameters:
status:  fills in the outgoing error code could be U_MISSING_RESOURCE_ERROR</T> if the key is not found could be a non-failing error e.g.: U_USING_FALLBACK_ERROR,U_USING_DEFAULT_ERROR
Returns:
a signed integer value @draft ICU 2.0

const int32_t* ResourceBundle::getIntVector int32_t &    len,
UErrorCode   status
const
 

returns an integer vector from a resource.

Parameters:
resourceBundle:  a string resource
len:  fills in the length of resulting integer vector
status:  fills in the outgoing error code could be U_MISSING_RESOURCE_ERROR</T> if the key is not found could be a non-failing error e.g.: U_USING_FALLBACK_ERROR,U_USING_DEFAULT_ERROR
Returns:
a pointer to a vector of integers that lives in a memory mapped/DLL file. @stable

const char* ResourceBundle::getKey void   
 

Returns the key associated with this resource.

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

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

const Locale& ResourceBundle::getLocale void    const
 

Return the Locale associated with this ResourceBundle.

Returns:
a Locale object @stable

const char* ResourceBundle::getName void   
 

Gets the locale ID of the resource bundle as a string.

Same as getLocale().getName() .

@stable

ResourceBundle ResourceBundle::getNext UErrorCode   status
 

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

Parameters:
status  fills in the outgoing error code
Returns:
ResourceBundle object. @stable

UnicodeString ResourceBundle::getNextString const char **    key,
UErrorCode   status
 

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

Parameters:
key  fill in for key associated with this string
status  fills in the outgoing error code
Returns:
an UnicodeString object. @stable

UnicodeString ResourceBundle::getNextString UErrorCode   status
 

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

Parameters:
status  fills in the outgoing error code
Returns:
an UnicodeString object. @stable

int32_t ResourceBundle::getSize void    const
 

Returns the size of a resource.

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

Returns:
number of resources in a given resource. @stable

UnicodeString ResourceBundle::getString UErrorCode   status const
 

returns a string from a string resource type.

Parameters:
status:  fills in the outgoing error code could be U_MISSING_RESOURCE_ERROR</T> if the key is not found could be a non-failing error e.g.: U_USING_FALLBACK_ERROR,U_USING_DEFAULT_ERROR
Returns:
a pointer to a zero-terminated UChar array which lives in a memory mapped/DLL file. @stable

UnicodeString ResourceBundle::getStringEx const char *    key,
UErrorCode   status
const
 

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

This procedure works only with table resources.

Parameters:
key  a key associated with the wanted string
status  fills in the outgoing error code
Returns:
an UnicodeString object. If there is an error, string is bogus @stable

UnicodeString ResourceBundle::getStringEx int32_t    index,
UErrorCode   status
const
 

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

Parameters:
index  an index to the wanted string.
status  fills in the outgoing error code
Returns:
an UnicodeString object. If there is an error, string is bogus @stable

UResType ResourceBundle::getType void   
 

Returns the type of a resource.

Available types are defined in enum UResType

Returns:
type of the given resource. @stable

uint32_t ResourceBundle::getUInt UErrorCode   status const
 

returns an unsigned integer from a resource.

This integer is originally 28 bits.

Parameters:
status:  fills in the outgoing error code could be U_MISSING_RESOURCE_ERROR</T> if the key is not found could be a non-failing error e.g.: U_USING_FALLBACK_ERROR,U_USING_DEFAULT_ERROR
Returns:
an unsigned integer value @draft ICU 2.0

void ResourceBundle::getVersion UVersionInfo    versionInfo const
 

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

Parameters:
versionInfo  A UVersionInfo array that is filled with the version number as specified in the resource bundle or its parent. @stable

const char* ResourceBundle::getVersionNumber void    const
 

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

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

UBool ResourceBundle::hasNext void    const
 

Checks whether the resource has another element to iterate over.

Returns:
TRUE if there are more elements, FALSE if there is no more elements @stable

ResourceBundle& ResourceBundle::operator= const ResourceBundle &    other
 

Assignment operator.

Parameters:
other  The resource bundle to copy. @stable

void ResourceBundle::resetIterator void   
 

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

@stable


The documentation for this class was generated from the following file:
Generated on Mon Mar 4 23:19:04 2002 for ICU 2.0 by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002