1 // Copyright (C) 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
4 ******************************************************************************
6 * Copyright (C) 1996-2013, International Business Machines Corporation
7 * and others. All Rights Reserved.
9 ******************************************************************************
16 * Modification History:
18 * Date Name Description
19 * 2/5/97 aliu Added scanForLocaleInFile. Added
20 * constructor which attempts to read resource bundle
21 * from a specific file, without searching other files.
22 * 2/11/97 aliu Added UErrorCode return values to constructors. Fixed
23 * infinite loops in scanForFile and scanForLocale.
24 * Modified getRawResourceData to not delete storage
25 * in localeData and resourceData which it doesn't own.
26 * Added Mac compatibility #ifdefs for tellp() and
28 * 2/18/97 helena Updated with 100% documentation coverage.
29 * 3/13/97 aliu Rewrote to load in entire resource bundle and store
30 * it as a Hashtable of ResourceBundleData objects.
31 * Added state table to govern parsing of files.
32 * Modified to load locale index out of new file
33 * distinct from default.txt.
34 * 3/25/97 aliu Modified to support 2-d arrays, needed for timezone
35 * data. Added support for custom file suffixes. Again,
36 * needed to support timezone data.
37 * 4/7/97 aliu Cleaned up.
38 * 03/02/99 stephen Removed dependency on FILE*.
39 * 03/29/99 helena Merged Bertrand and Stephen's changes.
40 * 06/11/99 stephen Removed parsing of .txt files.
41 * Reworked to use new binary format.
43 * 06/14/99 stephen Removed methods taking a filename suffix.
44 * 11/09/99 weiv Added getLocale(), fRealLocale, removed fRealLocaleID
45 ******************************************************************************
51 #include "unicode/utypes.h"
52 #include "unicode/uobject.h"
53 #include "unicode/ures.h"
54 #include "unicode/unistr.h"
55 #include "unicode/locid.h"
59 * \brief C++ API: Resource Bundle
65 * A class representing a collection of resource information pertaining to a given
66 * locale. A resource bundle provides a way of accessing locale- specfic information in
67 * a data file. You create a resource bundle that manages the resources for a given
68 * locale and then ask it for individual resources.
70 * Resource bundles in ICU4C are currently defined using text files which conform to the following
71 * <a href="http://source.icu-project.org/repos/icu/icuhtml/trunk/design/bnf_rb.txt">BNF definition</a>.
72 * More on resource bundle concepts and syntax can be found in the
73 * <a href="http://icu-project.org/userguide/ResourceManagement.html">Users Guide</a>.
76 * The ResourceBundle class is not suitable for subclassing.
80 class U_COMMON_API ResourceBundle : public UObject {
85 * @param packageName The packageName and locale together point to an ICU udata object,
86 * as defined by <code> udata_open( packageName, "res", locale, err) </code>
87 * or equivalent. Typically, packageName will refer to a (.dat) file, or to
88 * a package registered with udata_setAppData(). Using a full file or directory
89 * pathname for packageName is deprecated.
90 * @param locale This is the locale this resource bundle is for. To get resources
91 * for the French locale, for example, you would create a
92 * ResourceBundle passing Locale::FRENCH for the "locale" parameter,
93 * and all subsequent calls to that resource bundle will return
94 * resources that pertain to the French locale. If the caller doesn't
95 * pass a locale parameter, the default locale for the system (as
96 * returned by Locale::getDefault()) will be used.
97 * @param err The Error Code.
98 * The UErrorCode& err parameter is used to return status information to the user. To
99 * check whether the construction succeeded or not, you should check the value of
100 * U_SUCCESS(err). If you wish more detailed information, you can check for
101 * informational error results which still indicate success. U_USING_FALLBACK_WARNING
102 * indicates that a fall back locale was used. For example, 'de_CH' was requested,
103 * but nothing was found there, so 'de' was used. U_USING_DEFAULT_WARNING indicates that
104 * the default locale data was used; neither the requested locale nor any of its
105 * fall back locales could be found.
108 ResourceBundle(const UnicodeString& packageName,
109 const Locale& locale,
113 * Construct a resource bundle for the default bundle in the specified package.
115 * @param packageName The packageName and locale together point to an ICU udata object,
116 * as defined by <code> udata_open( packageName, "res", locale, err) </code>
117 * or equivalent. Typically, packageName will refer to a (.dat) file, or to
118 * a package registered with udata_setAppData(). Using a full file or directory
119 * pathname for packageName is deprecated.
120 * @param err A UErrorCode value
123 ResourceBundle(const UnicodeString& packageName,
127 * Construct a resource bundle for the ICU default bundle.
129 * @param err A UErrorCode value
132 ResourceBundle(UErrorCode &err);
135 * Standard constructor, onstructs a resource bundle for the locale-specific
136 * bundle in the specified package.
138 * @param packageName The packageName and locale together point to an ICU udata object,
139 * as defined by <code> udata_open( packageName, "res", locale, err) </code>
140 * or equivalent. Typically, packageName will refer to a (.dat) file, or to
141 * a package registered with udata_setAppData(). Using a full file or directory
142 * pathname for packageName is deprecated.
143 * NULL is used to refer to ICU data.
144 * @param locale The locale for which to open a resource bundle.
145 * @param err A UErrorCode value
148 ResourceBundle(const char* packageName,
149 const Locale& locale,
155 * @param original The resource bundle to copy.
158 ResourceBundle(const ResourceBundle &original);
161 * Constructor from a C UResourceBundle. The resource bundle is
162 * copied and not adopted. ures_close will still need to be used on the
163 * original resource bundle.
165 * @param res A pointer to the C resource bundle.
166 * @param status A UErrorCode value.
169 ResourceBundle(UResourceBundle *res,
173 * Assignment operator.
175 * @param other The resource bundle to copy.
179 operator=(const ResourceBundle& other);
184 virtual ~ResourceBundle();
188 * Clones can be used concurrently in multiple threads.
189 * If an error occurs, then NULL is returned.
190 * The caller must delete the clone.
192 * @return a clone of this object
194 * @see getDynamicClassID
197 ResourceBundle *clone() const;
200 * Returns the size of a resource. Size for scalar types is always 1, and for vector/table types is
201 * the number of child resources.
202 * @warning Integer array is treated as a scalar type. There are no
203 * APIs to access individual members of an integer array. It
204 * is always returned as a whole.
206 * @return number of resources in a given resource.
213 * returns a string from a string resource type
215 * @param status fills in the outgoing error code
216 * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
218 * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
219 * @return a pointer to a zero-terminated UChar array which lives in a memory mapped/DLL file.
223 getString(UErrorCode& status) const;
226 * returns a binary data from a resource. Can be used at most primitive resource types (binaries,
229 * @param len fills in the length of resulting byte chunk
230 * @param status fills in the outgoing error code
231 * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
233 * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
234 * @return a pointer to a chunk of unsigned bytes which live in a memory mapped/DLL file.
238 getBinary(int32_t& len, UErrorCode& status) const;
242 * returns an integer vector from a resource.
244 * @param len fills in the length of resulting integer vector
245 * @param status fills in the outgoing error code
246 * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
248 * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
249 * @return a pointer to a vector of integers that lives in a memory mapped/DLL file.
253 getIntVector(int32_t& len, UErrorCode& status) const;
256 * returns an unsigned integer from a resource.
257 * This integer is originally 28 bits.
259 * @param status fills in the outgoing error code
260 * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
262 * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
263 * @return an unsigned integer value
267 getUInt(UErrorCode& status) const;
270 * returns a signed integer from a resource.
271 * This integer is originally 28 bit and the sign gets propagated.
273 * @param status fills in the outgoing error code
274 * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
276 * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
277 * @return a signed integer value
281 getInt(UErrorCode& status) const;
284 * Checks whether the resource has another element to iterate over.
286 * @return TRUE if there are more elements, FALSE if there is no more elements
293 * Resets the internal context of a resource so that iteration starts from the first element.
301 * Returns the key associated with this resource. Not all the resources have a key - only
302 * those that are members of a table.
304 * @return a key associated to this resource, or NULL if it doesn't have a key
311 * Gets the locale ID of the resource bundle as a string.
312 * Same as getLocale().getName() .
314 * @return the locale ID of the resource bundle as a string
322 * Returns the type of a resource. Available types are defined in enum UResType
324 * @return type of the given resource.
331 * Returns the next resource in a given resource or NULL if there are no more resources
333 * @param status fills in the outgoing error code
334 * @return ResourceBundle object.
338 getNext(UErrorCode& status);
341 * Returns the next string in a resource or NULL if there are no more resources
344 * @param status fills in the outgoing error code
345 * @return an UnicodeString object.
349 getNextString(UErrorCode& status);
352 * Returns the next string in a resource or NULL if there are no more resources
355 * @param key fill in for key associated with this string
356 * @param status fills in the outgoing error code
357 * @return an UnicodeString object.
361 getNextString(const char ** key,
365 * Returns the resource in a resource at the specified index.
367 * @param index an index to the wanted resource.
368 * @param status fills in the outgoing error code
369 * @return ResourceBundle object. If there is an error, resource is invalid.
374 UErrorCode& status) const;
377 * Returns the string in a given resource at the specified index.
379 * @param index an index to the wanted string.
380 * @param status fills in the outgoing error code
381 * @return an UnicodeString object. If there is an error, string is bogus
385 getStringEx(int32_t index,
386 UErrorCode& status) const;
389 * Returns a resource in a resource that has a given key. This procedure works only with table
392 * @param key a key associated with the wanted resource
393 * @param status fills in the outgoing error code.
394 * @return ResourceBundle object. If there is an error, resource is invalid.
399 UErrorCode& status) const;
402 * Returns a string in a resource that has a given key. This procedure works only with table
405 * @param key a key associated with the wanted string
406 * @param status fills in the outgoing error code
407 * @return an UnicodeString object. If there is an error, string is bogus
411 getStringEx(const char* key,
412 UErrorCode& status) const;
414 #ifndef U_HIDE_DEPRECATED_API
416 * Return the version number associated with this ResourceBundle as a string. Please
417 * use getVersion, as this method is going to be deprecated.
419 * @return A version number string as specified in the resource bundle or its parent.
420 * The caller does not own this string.
422 * @deprecated ICU 2.8 Use getVersion instead.
425 getVersionNumber(void) const;
426 #endif /* U_HIDE_DEPRECATED_API */
429 * Return the version number associated with this ResourceBundle as a UVersionInfo array.
431 * @param versionInfo A UVersionInfo array that is filled with the version number
432 * as specified in the resource bundle or its parent.
436 getVersion(UVersionInfo versionInfo) const;
438 #ifndef U_HIDE_DEPRECATED_API
440 * Return the Locale associated with this ResourceBundle.
442 * @return a Locale object
443 * @deprecated ICU 2.8 Use getLocale(ULocDataLocaleType type, UErrorCode &status) overload instead.
446 getLocale(void) const;
447 #endif /* U_HIDE_DEPRECATED_API */
450 * Return the Locale associated with this ResourceBundle.
451 * @param type You can choose between requested, valid and actual
452 * locale. For description see the definition of
453 * ULocDataLocaleType in uloc.h
454 * @param status just for catching illegal arguments
456 * @return a Locale object
460 getLocale(ULocDataLocaleType type, UErrorCode &status) const;
461 #ifndef U_HIDE_INTERNAL_API
463 * This API implements multilevel fallback
467 getWithFallback(const char* key, UErrorCode& status);
468 #endif /* U_HIDE_INTERNAL_API */
470 * ICU "poor man's RTTI", returns a UClassID for the actual class.
474 virtual UClassID getDynamicClassID() const;
477 * ICU "poor man's RTTI", returns a UClassID for this class.
481 static UClassID U_EXPORT2 getStaticClassID();
484 ResourceBundle(); // default constructor not implemented
486 UResourceBundle *fResource;
487 void constructForLocale(const UnicodeString& path, const Locale& locale, UErrorCode& error);