intl/icu/source/common/unicode/resbund.h@6474c204b198
intl/icu/source/common/unicode/resbund.h
Wed, 31 Dec 2014 06:09:35 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 06:09:35 +0100
- changeset 0
- 6474c204b198
- permissions
- -rw-r--r--
Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.
1 /*
2 ******************************************************************************
3 *
4 * Copyright (C) 1996-2013, International Business Machines Corporation
5 * and others. All Rights Reserved.
6 *
7 ******************************************************************************
8 *
9 * File resbund.h
10 *
11 * CREATED BY
12 * Richard Gillam
13 *
14 * Modification History:
15 *
16 * Date Name Description
17 * 2/5/97 aliu Added scanForLocaleInFile. Added
18 * constructor which attempts to read resource bundle
19 * from a specific file, without searching other files.
20 * 2/11/97 aliu Added UErrorCode return values to constructors. Fixed
21 * infinite loops in scanForFile and scanForLocale.
22 * Modified getRawResourceData to not delete storage
23 * in localeData and resourceData which it doesn't own.
24 * Added Mac compatibility #ifdefs for tellp() and
25 * ios::nocreate.
26 * 2/18/97 helena Updated with 100% documentation coverage.
27 * 3/13/97 aliu Rewrote to load in entire resource bundle and store
28 * it as a Hashtable of ResourceBundleData objects.
29 * Added state table to govern parsing of files.
30 * Modified to load locale index out of new file
31 * distinct from default.txt.
32 * 3/25/97 aliu Modified to support 2-d arrays, needed for timezone
33 * data. Added support for custom file suffixes. Again,
34 * needed to support timezone data.
35 * 4/7/97 aliu Cleaned up.
36 * 03/02/99 stephen Removed dependency on FILE*.
37 * 03/29/99 helena Merged Bertrand and Stephen's changes.
38 * 06/11/99 stephen Removed parsing of .txt files.
39 * Reworked to use new binary format.
40 * Cleaned up.
41 * 06/14/99 stephen Removed methods taking a filename suffix.
42 * 11/09/99 weiv Added getLocale(), fRealLocale, removed fRealLocaleID
43 ******************************************************************************
44 */
46 #ifndef RESBUND_H
47 #define RESBUND_H
49 #include "unicode/utypes.h"
50 #include "unicode/uobject.h"
51 #include "unicode/ures.h"
52 #include "unicode/unistr.h"
53 #include "unicode/locid.h"
55 /**
56 * \file
57 * \brief C++ API: Resource Bundle
58 */
60 U_NAMESPACE_BEGIN
62 /**
63 * A class representing a collection of resource information pertaining to a given
64 * locale. A resource bundle provides a way of accessing locale- specfic information in
65 * a data file. You create a resource bundle that manages the resources for a given
66 * locale and then ask it for individual resources.
67 * <P>
68 * Resource bundles in ICU4C are currently defined using text files which conform to the following
69 * <a href="http://source.icu-project.org/repos/icu/icuhtml/trunk/design/bnf_rb.txt">BNF definition</a>.
70 * More on resource bundle concepts and syntax can be found in the
71 * <a href="http://icu-project.org/userguide/ResourceManagement.html">Users Guide</a>.
72 * <P>
73 *
74 * The ResourceBundle class is not suitable for subclassing.
75 *
76 * @stable ICU 2.0
77 */
78 class U_COMMON_API ResourceBundle : public UObject {
79 public:
80 /**
81 * Constructor
82 *
83 * @param packageName The packageName and locale together point to an ICU udata object,
84 * as defined by <code> udata_open( packageName, "res", locale, err) </code>
85 * or equivalent. Typically, packageName will refer to a (.dat) file, or to
86 * a package registered with udata_setAppData(). Using a full file or directory
87 * pathname for packageName is deprecated.
88 * @param locale This is the locale this resource bundle is for. To get resources
89 * for the French locale, for example, you would create a
90 * ResourceBundle passing Locale::FRENCH for the "locale" parameter,
91 * and all subsequent calls to that resource bundle will return
92 * resources that pertain to the French locale. If the caller doesn't
93 * pass a locale parameter, the default locale for the system (as
94 * returned by Locale::getDefault()) will be used.
95 * @param err The Error Code.
96 * The UErrorCode& err parameter is used to return status information to the user. To
97 * check whether the construction succeeded or not, you should check the value of
98 * U_SUCCESS(err). If you wish more detailed information, you can check for
99 * informational error results which still indicate success. U_USING_FALLBACK_WARNING
100 * indicates that a fall back locale was used. For example, 'de_CH' was requested,
101 * but nothing was found there, so 'de' was used. U_USING_DEFAULT_WARNING indicates that
102 * the default locale data was used; neither the requested locale nor any of its
103 * fall back locales could be found.
104 * @stable ICU 2.0
105 */
106 ResourceBundle(const UnicodeString& packageName,
107 const Locale& locale,
108 UErrorCode& err);
110 /**
111 * Construct a resource bundle for the default bundle in the specified package.
112 *
113 * @param packageName The packageName and locale together point to an ICU udata object,
114 * as defined by <code> udata_open( packageName, "res", locale, err) </code>
115 * or equivalent. Typically, packageName will refer to a (.dat) file, or to
116 * a package registered with udata_setAppData(). Using a full file or directory
117 * pathname for packageName is deprecated.
118 * @param err A UErrorCode value
119 * @stable ICU 2.0
120 */
121 ResourceBundle(const UnicodeString& packageName,
122 UErrorCode& err);
124 /**
125 * Construct a resource bundle for the ICU default bundle.
126 *
127 * @param err A UErrorCode value
128 * @stable ICU 2.0
129 */
130 ResourceBundle(UErrorCode &err);
132 /**
133 * Standard constructor, onstructs a resource bundle for the locale-specific
134 * bundle in the specified package.
135 *
136 * @param packageName The packageName and locale together point to an ICU udata object,
137 * as defined by <code> udata_open( packageName, "res", locale, err) </code>
138 * or equivalent. Typically, packageName will refer to a (.dat) file, or to
139 * a package registered with udata_setAppData(). Using a full file or directory
140 * pathname for packageName is deprecated.
141 * NULL is used to refer to ICU data.
142 * @param locale The locale for which to open a resource bundle.
143 * @param err A UErrorCode value
144 * @stable ICU 2.0
145 */
146 ResourceBundle(const char* packageName,
147 const Locale& locale,
148 UErrorCode& err);
150 /**
151 * Copy constructor.
152 *
153 * @param original The resource bundle to copy.
154 * @stable ICU 2.0
155 */
156 ResourceBundle(const ResourceBundle &original);
158 /**
159 * Constructor from a C UResourceBundle. The resource bundle is
160 * copied and not adopted. ures_close will still need to be used on the
161 * original resource bundle.
162 *
163 * @param res A pointer to the C resource bundle.
164 * @param status A UErrorCode value.
165 * @stable ICU 2.0
166 */
167 ResourceBundle(UResourceBundle *res,
168 UErrorCode &status);
170 /**
171 * Assignment operator.
172 *
173 * @param other The resource bundle to copy.
174 * @stable ICU 2.0
175 */
176 ResourceBundle&
177 operator=(const ResourceBundle& other);
179 /** Destructor.
180 * @stable ICU 2.0
181 */
182 virtual ~ResourceBundle();
184 /**
185 * Clone this object.
186 * Clones can be used concurrently in multiple threads.
187 * If an error occurs, then NULL is returned.
188 * The caller must delete the clone.
189 *
190 * @return a clone of this object
191 *
192 * @see getDynamicClassID
193 * @stable ICU 2.8
194 */
195 ResourceBundle *clone() const;
197 /**
198 * Returns the size of a resource. Size for scalar types is always 1, and for vector/table types is
199 * the number of child resources.
200 * @warning Integer array is treated as a scalar type. There are no
201 * APIs to access individual members of an integer array. It
202 * is always returned as a whole.
203 *
204 * @return number of resources in a given resource.
205 * @stable ICU 2.0
206 */
207 int32_t
208 getSize(void) const;
210 /**
211 * returns a string from a string resource type
212 *
213 * @param status fills in the outgoing error code
214 * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
215 * could be a warning
216 * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
217 * @return a pointer to a zero-terminated UChar array which lives in a memory mapped/DLL file.
218 * @stable ICU 2.0
219 */
220 UnicodeString
221 getString(UErrorCode& status) const;
223 /**
224 * returns a binary data from a resource. Can be used at most primitive resource types (binaries,
225 * strings, ints)
226 *
227 * @param len fills in the length of resulting byte chunk
228 * @param status fills in the outgoing error code
229 * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
230 * could be a warning
231 * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
232 * @return a pointer to a chunk of unsigned bytes which live in a memory mapped/DLL file.
233 * @stable ICU 2.0
234 */
235 const uint8_t*
236 getBinary(int32_t& len, UErrorCode& status) const;
239 /**
240 * returns an integer vector from a resource.
241 *
242 * @param len fills in the length of resulting integer vector
243 * @param status fills in the outgoing error code
244 * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
245 * could be a warning
246 * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
247 * @return a pointer to a vector of integers that lives in a memory mapped/DLL file.
248 * @stable ICU 2.0
249 */
250 const int32_t*
251 getIntVector(int32_t& len, UErrorCode& status) const;
253 /**
254 * returns an unsigned integer from a resource.
255 * This integer is originally 28 bits.
256 *
257 * @param status fills in the outgoing error code
258 * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
259 * could be a warning
260 * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
261 * @return an unsigned integer value
262 * @stable ICU 2.0
263 */
264 uint32_t
265 getUInt(UErrorCode& status) const;
267 /**
268 * returns a signed integer from a resource.
269 * This integer is originally 28 bit and the sign gets propagated.
270 *
271 * @param status fills in the outgoing error code
272 * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
273 * could be a warning
274 * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
275 * @return a signed integer value
276 * @stable ICU 2.0
277 */
278 int32_t
279 getInt(UErrorCode& status) const;
281 /**
282 * Checks whether the resource has another element to iterate over.
283 *
284 * @return TRUE if there are more elements, FALSE if there is no more elements
285 * @stable ICU 2.0
286 */
287 UBool
288 hasNext(void) const;
290 /**
291 * Resets the internal context of a resource so that iteration starts from the first element.
292 *
293 * @stable ICU 2.0
294 */
295 void
296 resetIterator(void);
298 /**
299 * Returns the key associated with this resource. Not all the resources have a key - only
300 * those that are members of a table.
301 *
302 * @return a key associated to this resource, or NULL if it doesn't have a key
303 * @stable ICU 2.0
304 */
305 const char*
306 getKey(void) const;
308 /**
309 * Gets the locale ID of the resource bundle as a string.
310 * Same as getLocale().getName() .
311 *
312 * @return the locale ID of the resource bundle as a string
313 * @stable ICU 2.0
314 */
315 const char*
316 getName(void) const;
319 /**
320 * Returns the type of a resource. Available types are defined in enum UResType
321 *
322 * @return type of the given resource.
323 * @stable ICU 2.0
324 */
325 UResType
326 getType(void) const;
328 /**
329 * Returns the next resource in a given resource or NULL if there are no more resources
330 *
331 * @param status fills in the outgoing error code
332 * @return ResourceBundle object.
333 * @stable ICU 2.0
334 */
335 ResourceBundle
336 getNext(UErrorCode& status);
338 /**
339 * Returns the next string in a resource or NULL if there are no more resources
340 * to iterate over.
341 *
342 * @param status fills in the outgoing error code
343 * @return an UnicodeString object.
344 * @stable ICU 2.0
345 */
346 UnicodeString
347 getNextString(UErrorCode& status);
349 /**
350 * Returns the next string in a resource or NULL if there are no more resources
351 * to iterate over.
352 *
353 * @param key fill in for key associated with this string
354 * @param status fills in the outgoing error code
355 * @return an UnicodeString object.
356 * @stable ICU 2.0
357 */
358 UnicodeString
359 getNextString(const char ** key,
360 UErrorCode& status);
362 /**
363 * Returns the resource in a resource at the specified index.
364 *
365 * @param index an index to the wanted resource.
366 * @param status fills in the outgoing error code
367 * @return ResourceBundle object. If there is an error, resource is invalid.
368 * @stable ICU 2.0
369 */
370 ResourceBundle
371 get(int32_t index,
372 UErrorCode& status) const;
374 /**
375 * Returns the string in a given resource at the specified index.
376 *
377 * @param index an index to the wanted string.
378 * @param status fills in the outgoing error code
379 * @return an UnicodeString object. If there is an error, string is bogus
380 * @stable ICU 2.0
381 */
382 UnicodeString
383 getStringEx(int32_t index,
384 UErrorCode& status) const;
386 /**
387 * Returns a resource in a resource that has a given key. This procedure works only with table
388 * resources.
389 *
390 * @param key a key associated with the wanted resource
391 * @param status fills in the outgoing error code.
392 * @return ResourceBundle object. If there is an error, resource is invalid.
393 * @stable ICU 2.0
394 */
395 ResourceBundle
396 get(const char* key,
397 UErrorCode& status) const;
399 /**
400 * Returns a string in a resource that has a given key. This procedure works only with table
401 * resources.
402 *
403 * @param key a key associated with the wanted string
404 * @param status fills in the outgoing error code
405 * @return an UnicodeString object. If there is an error, string is bogus
406 * @stable ICU 2.0
407 */
408 UnicodeString
409 getStringEx(const char* key,
410 UErrorCode& status) const;
412 #ifndef U_HIDE_DEPRECATED_API
413 /**
414 * Return the version number associated with this ResourceBundle as a string. Please
415 * use getVersion, as this method is going to be deprecated.
416 *
417 * @return A version number string as specified in the resource bundle or its parent.
418 * The caller does not own this string.
419 * @see getVersion
420 * @deprecated ICU 2.8 Use getVersion instead.
421 */
422 const char*
423 getVersionNumber(void) const;
424 #endif /* U_HIDE_DEPRECATED_API */
426 /**
427 * Return the version number associated with this ResourceBundle as a UVersionInfo array.
428 *
429 * @param versionInfo A UVersionInfo array that is filled with the version number
430 * as specified in the resource bundle or its parent.
431 * @stable ICU 2.0
432 */
433 void
434 getVersion(UVersionInfo versionInfo) const;
436 #ifndef U_HIDE_DEPRECATED_API
437 /**
438 * Return the Locale associated with this ResourceBundle.
439 *
440 * @return a Locale object
441 * @deprecated ICU 2.8 Use getLocale(ULocDataLocaleType type, UErrorCode &status) overload instead.
442 */
443 const Locale&
444 getLocale(void) const;
445 #endif /* U_HIDE_DEPRECATED_API */
447 /**
448 * Return the Locale associated with this ResourceBundle.
449 * @param type You can choose between requested, valid and actual
450 * locale. For description see the definition of
451 * ULocDataLocaleType in uloc.h
452 * @param status just for catching illegal arguments
453 *
454 * @return a Locale object
455 * @stable ICU 2.8
456 */
457 const Locale
458 getLocale(ULocDataLocaleType type, UErrorCode &status) const;
459 #ifndef U_HIDE_INTERNAL_API
460 /**
461 * This API implements multilevel fallback
462 * @internal
463 */
464 ResourceBundle
465 getWithFallback(const char* key, UErrorCode& status);
466 #endif /* U_HIDE_INTERNAL_API */
467 /**
468 * ICU "poor man's RTTI", returns a UClassID for the actual class.
469 *
470 * @stable ICU 2.2
471 */
472 virtual UClassID getDynamicClassID() const;
474 /**
475 * ICU "poor man's RTTI", returns a UClassID for this class.
476 *
477 * @stable ICU 2.2
478 */
479 static UClassID U_EXPORT2 getStaticClassID();
481 private:
482 ResourceBundle(); // default constructor not implemented
484 UResourceBundle *fResource;
485 void constructForLocale(const UnicodeString& path, const Locale& locale, UErrorCode& error);
486 Locale *fLocale;
487 };
489 U_NAMESPACE_END
490 #endif
