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