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