SourcePro® API Reference Guide

 
Loading...
Searching...
No Matches
RWUResourceBundle Class Reference

Provides a way to store and access locale-dependent data. More...

#include <rw/i18n/RWUResourceBundle.h>

Public Types

enum  ResourceType {
  None , String , Int , IntVec ,
  Binary , Table , Array , Reserved
}
 

Public Member Functions

 RWUResourceBundle (const char *path, const RWULocale &locale=RWULocale::getDefault())
 
 RWUResourceBundle (const RWUResourceBundle &other)
 
 RWUResourceBundle (const RWUString &path, const RWULocale &locale=RWULocale::getDefault())
 
 ~RWUResourceBundle ()
 
RWUResourceBundle get (const RWCString &key) const
 
RWUResourceBundle get (int32_t index) const
 
const uint8_t * getBinary () const
 
int32_t getInt () const
 
const int32_t * getIntVector () const
 
RWCString getKey () const
 
RWULocale getLocale () const
 
RWCString getLocaleName () const
 
int32_t getSize () const
 
RWUStatusCode getStatus () const
 
RWUString getString () const
 
RWUString getString (const RWCString &key) const
 
RWUString getString (int32_t index) const
 
ResourceType getType () const
 
uint32_t getUInt () const
 
RWUResourceBundleoperator= (const RWUResourceBundle &other)
 

Detailed Description

RWUResourceBundle is a mechanism for storing and accessing locale-dependent data.

Every resource bundle contains one or more resources. An individual resource can be of type string, integer, integer vector, or binary. A collection of resources can be arranged as a table or as an array. Each element of a table has a const char* key; each element of an array has an integer index. Any element of a table or array may be either an individual resource or another table or array. Tables and arrays are themselves treated as RWUResourceBundle instances, so RWUResourceBundle instances nest recursively.

Each resource bundle contains data for one locale. The bundles for an application are organized in a logical hierarchy based upon the locales associated with the bundles. At the base of the hierarchy is a "root" resource bundle that contains a resource value for every aspect of the program that needs to be localized; typically, these resource values are expressed in the locale of the application developer. Below the "root" resource bundle are language-specific bundles (for example, en, de, and ja bundles). Below the language-specific bundles are region-specific bundles (for example, de_DE and de_CH), and below the region-specific bundles are variant-specific bundles (for example, de_DE_PREEURO). Typically, only the "root" bundle contains a resource value for every localizable aspect of the application. A fallback mechanism ensures that a child resource bundle need only contain the resources whose values differ from its ancestor bundles.

When an application needs localized data, it constructs an RWUResourceBundle, then queries the bundle for the needed resources. The constructors for RWUResourceBundle accept the name of a directory containing .res files, and the name of a locale. The RWUResourceBundle instances created by these constructors are known as "top-level" resource bundles. These top-level resource bundles are guaranteed to be of type table, containing one or more "top-level" resources associated with string keys.

When creating a top-level RWUResourceBundle, the constructor may succeed, succeed through fallback, or fail, depending on whether an exact match to the requested locale is found, a fallback match is found, or no bundle at all is found. Constructors throw an RWUException if no bundle is found, but otherwise succeed and cache an RWUStatusCode to indicate the level of success. The getStatus() method returns the status of an RWUResourceBundle.

Similarly, when a top-level RWUResourceBundle is queried for a particular top-level resource, the query may succeed, succeed through fallback, or fail. The query throws RWUException if it fails, but otherwise returns an RWUResourceBundle holding a cached RWUStatusCode. Again, the getStatus() method returns the status code.

The fallback mechanism works in three stages. In the first stage, you create an RWUResourceBundle from a locale name and path:

  1. The library first looks for the exact named RWUResourceBundle.
  2. Failing that, the library looks for a parent locale along the named locale's branch.
  3. If no parent locale is found, the library looks for the locale named by RWULocale::getDefault().
  4. Failing that, the library looks for a parent locale along the default locale's branch.
  5. Failing that, the library attempts to open the RWUResourceBundle named root.
  6. Finally, if it can find no information for any of the above mentioned locales, the library throws an RWUException.

For example, suppose there are RWUResourceBundle instances available for root, en, en_US, en_US_POSIX, and es, and that the current default RWULocale is es_ES. If you attempt to open the RWUResourceBundle named ja_JP, the library tries these bundle names in order:

  1. ja_JP – the exact match
  2. ja – the parent
  3. es_ES – the default locale
  4. es – the default parent: Success!
  5. if es been missing, root would have been tried next

In the second stage, you access a resource named at the top level:

  1. The library first looks for the named resource in the currently open RWUResourceBundle.
  2. Failing that, the library looks for the named resource in a parent of the currently open RWUResourceBundle.
  3. Failing that, the library looks in the root resource bundle.
  4. Failing that, the library throws an RWUException.

For example, suppose that in the es resource bundle there is a table named menu containing entries for file, edit, and help. Suppose also that the root resource bundle has, in addition to the menu table, a string resource named currentVersion. If you attempt to access the menu table resource, the library returns the one in the es RWUResourceBundle. If you attempt to access the currentVersion string resource, the library returns the one in root.

In the third stage, you open a resource held within a top-level array or table:

  1. The library looks only in the already open top-level resource.
  2. If the requested datum is not there, an RWUException is thrown.

For instance, continuing from the Stage 2 example, suppose you have opened the menu resource, and now are looking for the tools string within the menu table. Suppose this entry is available in the menu resource in the root resource bundle, but not in the menu resource in the es resource bundle. Your attempt does not fall back–it fails.

Data in a resource bundle are compiled into a compact form. Note that binary data, as well as keyed data, are compiled without regard to platform-specific details. As a result, table data may not be found on a platform where the character encoding (US-ASCII or EBCDIC, for instance) used for the keys is different than that where compiled. For similar reasons, binary data may be wrong if compiled on a big-endian machine and read on a little-endian machine, or vice versa.

See also
RWULocale

Member Enumeration Documentation

◆ ResourceType

The ResourceType enum represents the type of the resource contained by a resource bundle.

Enumerator
None 

indicates that the resource is missing, or not at this index.

String 

indicates that the resource is a const RWUChar16*.

Int 

indicates that the resource is a (signed or unsigned) integer.

IntVec 

indicates that the resource is an array of int32_t.

Binary 

indicates that the resource is binary data.

Table 

that the resource is a table (each element of the table is associated with a const char* key).

Array 

indicates that the resource is an array (each element of the array has an integer index).

Reserved 

reserved for future use.

Constructor & Destructor Documentation

◆ RWUResourceBundle() [1/3]

RWUResourceBundle::RWUResourceBundle ( const RWUString & path,
const RWULocale & locale = RWULocale::getDefault() )

Constructs an RWUResourceBundle from the data specific to locale held within the directory path.

The newly-constructed RWUResourceBundle is a top-level bundle containing table data. Fallback may occur during the construction of the bundle or during the retrieval of its top-level resources. See getStatus() and getLocale().

Exceptions
RWUExceptionThrown if any error occurs during the construction.

◆ RWUResourceBundle() [2/3]

RWUResourceBundle::RWUResourceBundle ( const char * path,
const RWULocale & locale = RWULocale::getDefault() )

Constructs an RWUResourceBundle from the data specific to locale held within the directory path.

The newly-constructed RWUResourceBundle is a top-level bundle containing table data. Fallback may occur during the construction of the bundle or during the retrieval of its top-level resources. See getStatus() and getLocale().

Exceptions
RWUExceptionThrown if any error occurs during the construction.

◆ RWUResourceBundle() [3/3]

RWUResourceBundle::RWUResourceBundle ( const RWUResourceBundle & other)
inline

Copy constructor.

◆ ~RWUResourceBundle()

RWUResourceBundle::~RWUResourceBundle ( )
inline

Destructor.

Member Function Documentation

◆ get() [1/2]

RWUResourceBundle RWUResourceBundle::get ( const RWCString & key) const
inline

Returns the resource associated with the given key.

Exceptions
RWUExceptionThrown if self is not of type RWUResourceBundle::table, or if there is no such key.

◆ get() [2/2]

RWUResourceBundle RWUResourceBundle::get ( int32_t index) const
inline

Returns the resource located at the given offset index within an array.

Exceptions
RWUExceptionThrown if self is not of type RWUResourceBundle::Array, or if the index is out of bounds.

◆ getBinary()

const uint8_t * RWUResourceBundle::getBinary ( ) const
inline

Returns a binary resource as a pointer to an array of unsigned bytes. Call getSize() to find the number of bytes.

Exceptions
RWUExceptionThrown if self is not of type RWUResourceBundle::Binary.

◆ getInt()

int32_t RWUResourceBundle::getInt ( ) const
inline

Returns a signed int32_t.

Exceptions
RWUExceptionThrown if self is not of type RWUResourceBundle::Int.

◆ getIntVector()

const int32_t * RWUResourceBundle::getIntVector ( ) const
inline

Returns an integer vector as a pointer to int32_t. Call getSize() to find the number of integers in the vector.

Exceptions
RWUExceptionThrown if self is not of type RWUResourceBundle::IntVec.

◆ getKey()

RWCString RWUResourceBundle::getKey ( ) const
inline

Returns the key of the resource held by self if the resource is an element of a table; otherwise, an empty string.

◆ getLocale()

RWULocale RWUResourceBundle::getLocale ( ) const
inline

Returns the locale associated with self.

Note
When a top-level resource bundle is constructed, fallback may be used to find resource data, if data for the requested locale is not available. Method getLocale() returns the actual locale where the top-level resource bundle was found, which may not be the requested locale.

◆ getLocaleName()

RWCString RWUResourceBundle::getLocaleName ( ) const
inline

Returns the name of the locale associated with self. Convenience synonym for getLocale().getName().

◆ getSize()

int32_t RWUResourceBundle::getSize ( ) const

Returns the size of the resource held by self. Returns 1 for strings or integers, a count of bytes for binary resources, and a count of elements for integer vectors, arrays, and tables.

◆ getStatus()

RWUStatusCode RWUResourceBundle::getStatus ( ) const
inline

Returns an RWUStatusCode indicating whether fallback occurred during the creation or retrieval of this resource bundle:

  • RWUNoError
    Construction of a top-level resource bundle: There
    was a bundle with an exact match for the requested RWULocale.
    Retrieval of a resource bundle: The queried bundle held this resource directly.
  • RWUUsingFallbackWarning
    Construction of a top-level resource
    bundle: There was a bundle with a fallback match for the requested RWULocale, but there was no exact match.
    Retrieval of a resource
    bundle: The requested bundle was at the top level of a locale's RWUResourceBundle, but was not found in that RWUResourceBundle directly. It was found in a parent of that bundle.
  • RWUUsingDefaultWarning
    Construction of a top-level resource
    bundle: Neither a bundle for the requested RWULocale nor any of its parents were found. The newly-constructed RWUResourceBundle contains data associated with the current RWULocale::getDefault() locale, with one of its parents, or with the root RWUResourceBundle. You can discover which using getLocale() and getLocaleName().
    Retrieval
    of a resource bundle: The resource was found in the root bundle via fallback.

◆ getString() [1/3]

RWUString RWUResourceBundle::getString ( ) const
inline

Returns the string value of a string resource.

Exceptions
RWUExceptionThrown if self is not of type RWUResourceBundle::String.

◆ getString() [2/3]

RWUString RWUResourceBundle::getString ( const RWCString & key) const
inline

Returns the string value associated with the given key. Convenience synonym for get(key).getString().

Exceptions
RWUExceptionThrown if self is not of type RWUResourceBundle::Table, if there is no such key, or if the resource associated with the key is not of type RWUResourceBundle::String.

◆ getString() [3/3]

RWUString RWUResourceBundle::getString ( int32_t index) const
inline

Returns the string value at the given index. Convenience synonym for get(index).getString().

Exceptions
RWUExceptionThrown if self is not of type RWUResourceBundle::Array, if the resource at this index is not of type RWUResourceBundle::String, or if the index is out of bounds.

◆ getType()

RWUResourceBundle::ResourceType RWUResourceBundle::getType ( ) const
inline

Returns the ResourceType of the resource held by self.

If the resource is of type string, integer, integer vector, or binary, then its value may be extracted directly. If the resource is of type table or array, then its elements may be extracted in the form of nested RWUResourceBundle instances. Any attempt to extract a value directly from a table or array results in an exception of type RWUException.

◆ getUInt()

uint32_t RWUResourceBundle::getUInt ( ) const
inline

Returns an unsigned int32_t.

Exceptions
RWUExceptionThrown if self is not of type RWUResourceBundle::Int.

◆ operator=()

RWUResourceBundle & RWUResourceBundle::operator= ( const RWUResourceBundle & other)
inline

Assignment operator. Replaces self with a copy of the resource bundle other.

Copyright © 2024 Rogue Wave Software, Inc., a Perforce company. All Rights Reserved.