jpayne@69: // © 2016 and later: Unicode, Inc. and others. jpayne@69: // License & terms of use: http://www.unicode.org/copyright.html jpayne@69: /* jpayne@69: ****************************************************************************** jpayne@69: * jpayne@69: * Copyright (C) 1996-2013, International Business Machines Corporation jpayne@69: * and others. All Rights Reserved. jpayne@69: * jpayne@69: ****************************************************************************** jpayne@69: * jpayne@69: * File resbund.h jpayne@69: * jpayne@69: * CREATED BY jpayne@69: * Richard Gillam jpayne@69: * jpayne@69: * Modification History: jpayne@69: * jpayne@69: * Date Name Description jpayne@69: * 2/5/97 aliu Added scanForLocaleInFile. Added jpayne@69: * constructor which attempts to read resource bundle jpayne@69: * from a specific file, without searching other files. jpayne@69: * 2/11/97 aliu Added UErrorCode return values to constructors. Fixed jpayne@69: * infinite loops in scanForFile and scanForLocale. jpayne@69: * Modified getRawResourceData to not delete storage jpayne@69: * in localeData and resourceData which it doesn't own. jpayne@69: * Added Mac compatibility #ifdefs for tellp() and jpayne@69: * ios::nocreate. jpayne@69: * 2/18/97 helena Updated with 100% documentation coverage. jpayne@69: * 3/13/97 aliu Rewrote to load in entire resource bundle and store jpayne@69: * it as a Hashtable of ResourceBundleData objects. jpayne@69: * Added state table to govern parsing of files. jpayne@69: * Modified to load locale index out of new file jpayne@69: * distinct from default.txt. jpayne@69: * 3/25/97 aliu Modified to support 2-d arrays, needed for timezone jpayne@69: * data. Added support for custom file suffixes. Again, jpayne@69: * needed to support timezone data. jpayne@69: * 4/7/97 aliu Cleaned up. jpayne@69: * 03/02/99 stephen Removed dependency on FILE*. jpayne@69: * 03/29/99 helena Merged Bertrand and Stephen's changes. jpayne@69: * 06/11/99 stephen Removed parsing of .txt files. jpayne@69: * Reworked to use new binary format. jpayne@69: * Cleaned up. jpayne@69: * 06/14/99 stephen Removed methods taking a filename suffix. jpayne@69: * 11/09/99 weiv Added getLocale(), fRealLocale, removed fRealLocaleID jpayne@69: ****************************************************************************** jpayne@69: */ jpayne@69: jpayne@69: #ifndef RESBUND_H jpayne@69: #define RESBUND_H jpayne@69: jpayne@69: #include "unicode/utypes.h" jpayne@69: jpayne@69: #if U_SHOW_CPLUSPLUS_API jpayne@69: jpayne@69: #include "unicode/uobject.h" jpayne@69: #include "unicode/ures.h" jpayne@69: #include "unicode/unistr.h" jpayne@69: #include "unicode/locid.h" jpayne@69: jpayne@69: /** jpayne@69: * \file jpayne@69: * \brief C++ API: Resource Bundle jpayne@69: */ jpayne@69: jpayne@69: U_NAMESPACE_BEGIN jpayne@69: jpayne@69: /** jpayne@69: * A class representing a collection of resource information pertaining to a given jpayne@69: * locale. A resource bundle provides a way of accessing locale- specfic information in jpayne@69: * a data file. You create a resource bundle that manages the resources for a given jpayne@69: * locale and then ask it for individual resources. jpayne@69: *

jpayne@69: * Resource bundles in ICU4C are currently defined using text files which conform to the following jpayne@69: * BNF definition. jpayne@69: * More on resource bundle concepts and syntax can be found in the jpayne@69: * Users Guide. jpayne@69: *

jpayne@69: * jpayne@69: * The ResourceBundle class is not suitable for subclassing. jpayne@69: * jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: class U_COMMON_API ResourceBundle : public UObject { jpayne@69: public: jpayne@69: /** jpayne@69: * Constructor jpayne@69: * jpayne@69: * @param packageName The packageName and locale together point to an ICU udata object, jpayne@69: * as defined by udata_open( packageName, "res", locale, err) jpayne@69: * or equivalent. Typically, packageName will refer to a (.dat) file, or to jpayne@69: * a package registered with udata_setAppData(). Using a full file or directory jpayne@69: * pathname for packageName is deprecated. jpayne@69: * @param locale This is the locale this resource bundle is for. To get resources jpayne@69: * for the French locale, for example, you would create a jpayne@69: * ResourceBundle passing Locale::FRENCH for the "locale" parameter, jpayne@69: * and all subsequent calls to that resource bundle will return jpayne@69: * resources that pertain to the French locale. If the caller doesn't jpayne@69: * pass a locale parameter, the default locale for the system (as jpayne@69: * returned by Locale::getDefault()) will be used. jpayne@69: * @param err The Error Code. jpayne@69: * The UErrorCode& err parameter is used to return status information to the user. To jpayne@69: * check whether the construction succeeded or not, you should check the value of jpayne@69: * U_SUCCESS(err). If you wish more detailed information, you can check for jpayne@69: * informational error results which still indicate success. U_USING_FALLBACK_WARNING jpayne@69: * indicates that a fall back locale was used. For example, 'de_CH' was requested, jpayne@69: * but nothing was found there, so 'de' was used. U_USING_DEFAULT_WARNING indicates that jpayne@69: * the default locale data was used; neither the requested locale nor any of its jpayne@69: * fall back locales could be found. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: ResourceBundle(const UnicodeString& packageName, jpayne@69: const Locale& locale, jpayne@69: UErrorCode& err); jpayne@69: jpayne@69: /** jpayne@69: * Construct a resource bundle for the default bundle in the specified package. jpayne@69: * jpayne@69: * @param packageName The packageName and locale together point to an ICU udata object, jpayne@69: * as defined by udata_open( packageName, "res", locale, err) jpayne@69: * or equivalent. Typically, packageName will refer to a (.dat) file, or to jpayne@69: * a package registered with udata_setAppData(). Using a full file or directory jpayne@69: * pathname for packageName is deprecated. jpayne@69: * @param err A UErrorCode value jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: ResourceBundle(const UnicodeString& packageName, jpayne@69: UErrorCode& err); jpayne@69: jpayne@69: /** jpayne@69: * Construct a resource bundle for the ICU default bundle. jpayne@69: * jpayne@69: * @param err A UErrorCode value jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: ResourceBundle(UErrorCode &err); jpayne@69: jpayne@69: /** jpayne@69: * Standard constructor, constructs a resource bundle for the locale-specific jpayne@69: * bundle in the specified package. jpayne@69: * jpayne@69: * @param packageName The packageName and locale together point to an ICU udata object, jpayne@69: * as defined by udata_open( packageName, "res", locale, err) jpayne@69: * or equivalent. Typically, packageName will refer to a (.dat) file, or to jpayne@69: * a package registered with udata_setAppData(). Using a full file or directory jpayne@69: * pathname for packageName is deprecated. jpayne@69: * NULL is used to refer to ICU data. jpayne@69: * @param locale The locale for which to open a resource bundle. jpayne@69: * @param err A UErrorCode value jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: ResourceBundle(const char* packageName, jpayne@69: const Locale& locale, jpayne@69: UErrorCode& err); jpayne@69: jpayne@69: /** jpayne@69: * Copy constructor. jpayne@69: * jpayne@69: * @param original The resource bundle to copy. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: ResourceBundle(const ResourceBundle &original); jpayne@69: jpayne@69: /** jpayne@69: * Constructor from a C UResourceBundle. The resource bundle is jpayne@69: * copied and not adopted. ures_close will still need to be used on the jpayne@69: * original resource bundle. jpayne@69: * jpayne@69: * @param res A pointer to the C resource bundle. jpayne@69: * @param status A UErrorCode value. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: ResourceBundle(UResourceBundle *res, jpayne@69: UErrorCode &status); jpayne@69: jpayne@69: /** jpayne@69: * Assignment operator. jpayne@69: * jpayne@69: * @param other The resource bundle to copy. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: ResourceBundle& jpayne@69: operator=(const ResourceBundle& other); jpayne@69: jpayne@69: /** Destructor. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual ~ResourceBundle(); jpayne@69: jpayne@69: /** jpayne@69: * Clone this object. jpayne@69: * Clones can be used concurrently in multiple threads. jpayne@69: * If an error occurs, then NULL is returned. jpayne@69: * The caller must delete the clone. jpayne@69: * jpayne@69: * @return a clone of this object jpayne@69: * jpayne@69: * @see getDynamicClassID jpayne@69: * @stable ICU 2.8 jpayne@69: */ jpayne@69: ResourceBundle *clone() const; jpayne@69: jpayne@69: /** jpayne@69: * Returns the size of a resource. Size for scalar types is always 1, and for vector/table types is jpayne@69: * the number of child resources. jpayne@69: * @warning Integer array is treated as a scalar type. There are no jpayne@69: * APIs to access individual members of an integer array. It jpayne@69: * is always returned as a whole. jpayne@69: * jpayne@69: * @return number of resources in a given resource. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: int32_t jpayne@69: getSize(void) const; jpayne@69: jpayne@69: /** jpayne@69: * returns a string from a string resource type jpayne@69: * jpayne@69: * @param status fills in the outgoing error code jpayne@69: * could be U_MISSING_RESOURCE_ERROR if the key is not found jpayne@69: * could be a warning jpayne@69: * e.g.: U_USING_FALLBACK_WARNING,U_USING_DEFAULT_WARNING jpayne@69: * @return a pointer to a zero-terminated char16_t array which lives in a memory mapped/DLL file. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: UnicodeString jpayne@69: getString(UErrorCode& status) const; jpayne@69: jpayne@69: /** jpayne@69: * returns a binary data from a resource. Can be used at most primitive resource types (binaries, jpayne@69: * strings, ints) jpayne@69: * jpayne@69: * @param len fills in the length of resulting byte chunk jpayne@69: * @param status fills in the outgoing error code jpayne@69: * could be U_MISSING_RESOURCE_ERROR if the key is not found jpayne@69: * could be a warning jpayne@69: * e.g.: U_USING_FALLBACK_WARNING,U_USING_DEFAULT_WARNING jpayne@69: * @return a pointer to a chunk of unsigned bytes which live in a memory mapped/DLL file. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: const uint8_t* jpayne@69: getBinary(int32_t& len, UErrorCode& status) const; jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * returns an integer vector from a resource. jpayne@69: * jpayne@69: * @param len fills in the length of resulting integer vector jpayne@69: * @param status fills in the outgoing error code jpayne@69: * could be U_MISSING_RESOURCE_ERROR if the key is not found jpayne@69: * could be a warning jpayne@69: * e.g.: U_USING_FALLBACK_WARNING,U_USING_DEFAULT_WARNING jpayne@69: * @return a pointer to a vector of integers that lives in a memory mapped/DLL file. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: const int32_t* jpayne@69: getIntVector(int32_t& len, UErrorCode& status) const; jpayne@69: jpayne@69: /** jpayne@69: * returns an unsigned integer from a resource. jpayne@69: * This integer is originally 28 bits. jpayne@69: * jpayne@69: * @param status fills in the outgoing error code jpayne@69: * could be U_MISSING_RESOURCE_ERROR if the key is not found jpayne@69: * could be a warning jpayne@69: * e.g.: U_USING_FALLBACK_WARNING,U_USING_DEFAULT_WARNING jpayne@69: * @return an unsigned integer value jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: uint32_t jpayne@69: getUInt(UErrorCode& status) const; jpayne@69: jpayne@69: /** jpayne@69: * returns a signed integer from a resource. jpayne@69: * This integer is originally 28 bit and the sign gets propagated. jpayne@69: * jpayne@69: * @param status fills in the outgoing error code jpayne@69: * could be U_MISSING_RESOURCE_ERROR if the key is not found jpayne@69: * could be a warning jpayne@69: * e.g.: U_USING_FALLBACK_WARNING,U_USING_DEFAULT_WARNING jpayne@69: * @return a signed integer value jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: int32_t jpayne@69: getInt(UErrorCode& status) const; jpayne@69: jpayne@69: /** jpayne@69: * Checks whether the resource has another element to iterate over. jpayne@69: * jpayne@69: * @return TRUE if there are more elements, FALSE if there is no more elements jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: UBool jpayne@69: hasNext(void) const; jpayne@69: jpayne@69: /** jpayne@69: * Resets the internal context of a resource so that iteration starts from the first element. jpayne@69: * jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: void jpayne@69: resetIterator(void); jpayne@69: jpayne@69: /** jpayne@69: * Returns the key associated with this resource. Not all the resources have a key - only jpayne@69: * those that are members of a table. jpayne@69: * jpayne@69: * @return a key associated to this resource, or NULL if it doesn't have a key jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: const char* jpayne@69: getKey(void) const; jpayne@69: jpayne@69: /** jpayne@69: * Gets the locale ID of the resource bundle as a string. jpayne@69: * Same as getLocale().getName() . jpayne@69: * jpayne@69: * @return the locale ID of the resource bundle as a string jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: const char* jpayne@69: getName(void) const; jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * Returns the type of a resource. Available types are defined in enum UResType jpayne@69: * jpayne@69: * @return type of the given resource. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: UResType jpayne@69: getType(void) const; jpayne@69: jpayne@69: /** jpayne@69: * Returns the next resource in a given resource or NULL if there are no more resources jpayne@69: * jpayne@69: * @param status fills in the outgoing error code jpayne@69: * @return ResourceBundle object. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: ResourceBundle jpayne@69: getNext(UErrorCode& status); jpayne@69: jpayne@69: /** jpayne@69: * Returns the next string in a resource or NULL if there are no more resources jpayne@69: * to iterate over. jpayne@69: * jpayne@69: * @param status fills in the outgoing error code jpayne@69: * @return an UnicodeString object. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: UnicodeString jpayne@69: getNextString(UErrorCode& status); jpayne@69: jpayne@69: /** jpayne@69: * Returns the next string in a resource or NULL if there are no more resources jpayne@69: * to iterate over. jpayne@69: * jpayne@69: * @param key fill in for key associated with this string jpayne@69: * @param status fills in the outgoing error code jpayne@69: * @return an UnicodeString object. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: UnicodeString jpayne@69: getNextString(const char ** key, jpayne@69: UErrorCode& status); jpayne@69: jpayne@69: /** jpayne@69: * Returns the resource in a resource at the specified index. jpayne@69: * jpayne@69: * @param index an index to the wanted resource. jpayne@69: * @param status fills in the outgoing error code jpayne@69: * @return ResourceBundle object. If there is an error, resource is invalid. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: ResourceBundle jpayne@69: get(int32_t index, jpayne@69: UErrorCode& status) const; jpayne@69: jpayne@69: /** jpayne@69: * Returns the string in a given resource at the specified index. jpayne@69: * jpayne@69: * @param index an index to the wanted string. jpayne@69: * @param status fills in the outgoing error code jpayne@69: * @return an UnicodeString object. If there is an error, string is bogus jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: UnicodeString jpayne@69: getStringEx(int32_t index, jpayne@69: UErrorCode& status) const; jpayne@69: jpayne@69: /** jpayne@69: * Returns a resource in a resource that has a given key. This procedure works only with table jpayne@69: * resources. jpayne@69: * jpayne@69: * @param key a key associated with the wanted resource jpayne@69: * @param status fills in the outgoing error code. jpayne@69: * @return ResourceBundle object. If there is an error, resource is invalid. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: ResourceBundle jpayne@69: get(const char* key, jpayne@69: UErrorCode& status) const; jpayne@69: jpayne@69: /** jpayne@69: * Returns a string in a resource that has a given key. This procedure works only with table jpayne@69: * resources. jpayne@69: * jpayne@69: * @param key a key associated with the wanted string jpayne@69: * @param status fills in the outgoing error code jpayne@69: * @return an UnicodeString object. If there is an error, string is bogus jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: UnicodeString jpayne@69: getStringEx(const char* key, jpayne@69: UErrorCode& status) const; jpayne@69: jpayne@69: #ifndef U_HIDE_DEPRECATED_API jpayne@69: /** jpayne@69: * Return the version number associated with this ResourceBundle as a string. Please jpayne@69: * use getVersion, as this method is going to be deprecated. jpayne@69: * jpayne@69: * @return A version number string as specified in the resource bundle or its parent. jpayne@69: * The caller does not own this string. jpayne@69: * @see getVersion jpayne@69: * @deprecated ICU 2.8 Use getVersion instead. jpayne@69: */ jpayne@69: const char* jpayne@69: getVersionNumber(void) const; jpayne@69: #endif /* U_HIDE_DEPRECATED_API */ jpayne@69: jpayne@69: /** jpayne@69: * Return the version number associated with this ResourceBundle as a UVersionInfo array. jpayne@69: * jpayne@69: * @param versionInfo A UVersionInfo array that is filled with the version number jpayne@69: * as specified in the resource bundle or its parent. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: void jpayne@69: getVersion(UVersionInfo versionInfo) const; jpayne@69: jpayne@69: #ifndef U_HIDE_DEPRECATED_API jpayne@69: /** jpayne@69: * Return the Locale associated with this ResourceBundle. jpayne@69: * jpayne@69: * @return a Locale object jpayne@69: * @deprecated ICU 2.8 Use getLocale(ULocDataLocaleType type, UErrorCode &status) overload instead. jpayne@69: */ jpayne@69: const Locale& jpayne@69: getLocale(void) const; jpayne@69: #endif /* U_HIDE_DEPRECATED_API */ jpayne@69: jpayne@69: /** jpayne@69: * Return the Locale associated with this ResourceBundle. jpayne@69: * @param type You can choose between requested, valid and actual jpayne@69: * locale. For description see the definition of jpayne@69: * ULocDataLocaleType in uloc.h jpayne@69: * @param status just for catching illegal arguments jpayne@69: * jpayne@69: * @return a Locale object jpayne@69: * @stable ICU 2.8 jpayne@69: */ jpayne@69: const Locale jpayne@69: getLocale(ULocDataLocaleType type, UErrorCode &status) const; jpayne@69: #ifndef U_HIDE_INTERNAL_API jpayne@69: /** jpayne@69: * This API implements multilevel fallback jpayne@69: * @internal jpayne@69: */ jpayne@69: ResourceBundle jpayne@69: getWithFallback(const char* key, UErrorCode& status); jpayne@69: #endif /* U_HIDE_INTERNAL_API */ jpayne@69: /** jpayne@69: * ICU "poor man's RTTI", returns a UClassID for the actual class. jpayne@69: * jpayne@69: * @stable ICU 2.2 jpayne@69: */ jpayne@69: virtual UClassID getDynamicClassID() const; jpayne@69: jpayne@69: /** jpayne@69: * ICU "poor man's RTTI", returns a UClassID for this class. jpayne@69: * jpayne@69: * @stable ICU 2.2 jpayne@69: */ jpayne@69: static UClassID U_EXPORT2 getStaticClassID(); jpayne@69: jpayne@69: private: jpayne@69: ResourceBundle(); // default constructor not implemented jpayne@69: jpayne@69: UResourceBundle *fResource; jpayne@69: void constructForLocale(const UnicodeString& path, const Locale& locale, UErrorCode& error); jpayne@69: Locale *fLocale; jpayne@69: }; jpayne@69: jpayne@69: U_NAMESPACE_END jpayne@69: jpayne@69: #endif /* U_SHOW_CPLUSPLUS_API */ jpayne@69: jpayne@69: #endif