1 /* 2 ****************************************************************************** 3 * 4 * Copyright (C) 1996-2007, 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 */ 45 46 #ifndef RESBUND_H 47 #define RESBUND_H 48 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" 54 55 /** 56 * \file 57 * \brief C++ API: Resource Bundle 58 */ 59 60 U_NAMESPACE_BEGIN 61 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); 109 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); 123 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); 131 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); 149 150 /** 151 * Copy constructor. 152 * 153 * @param original The resource bundle to copy. 154 * @stable ICU 2.0 155 */ 156 ResourceBundle(const ResourceBundle &original); 157 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); 169 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); 178 179 /** Destructor. 180 * @stable ICU 2.0 181 */ 182 virtual ~ResourceBundle(); 183 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; 196 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; 209 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; 222 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; 237 238 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; 252 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; 266 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; 280 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; 289 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); 297 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; 307 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; 317 318 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; 327 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); 337 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); 348 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); 361 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; 373 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; 385 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; 398 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; 411 412 /** 413 * Return the version number associated with this ResourceBundle as a string. Please 414 * use getVersion, as this method is going to be deprecated. 415 * 416 * @return A version number string as specified in the resource bundle or its parent. 417 * The caller does not own this string. 418 * @see getVersion 419 * @deprecated ICU 2.8 Use getVersion instead. 420 */ 421 const char* 422 getVersionNumber(void) const; 423 424 /** 425 * Return the version number associated with this ResourceBundle as a UVersionInfo array. 426 * 427 * @param versionInfo A UVersionInfo array that is filled with the version number 428 * as specified in the resource bundle or its parent. 429 * @stable ICU 2.0 430 */ 431 void 432 getVersion(UVersionInfo versionInfo) const; 433 434 /** 435 * Return the Locale associated with this ResourceBundle. 436 * 437 * @return a Locale object 438 * @deprecated ICU 2.8 Use getLocale(ULocDataLocaleType type, UErrorCode &status) overload instead. 439 */ 440 const Locale& 441 getLocale(void) const; 442 443 /** 444 * Return the Locale associated with this ResourceBundle. 445 * @param type You can choose between requested, valid and actual 446 * locale. For description see the definition of 447 * ULocDataLocaleType in uloc.h 448 * @param status just for catching illegal arguments 449 * 450 * @return a Locale object 451 * @stable ICU 2.8 452 */ 453 const Locale 454 getLocale(ULocDataLocaleType type, UErrorCode &status) const; 455 /** 456 * This API implements multilevel fallback 457 * @internal 458 */ 459 ResourceBundle 460 getWithFallback(const char* key, UErrorCode& status); 461 /** 462 * ICU "poor man's RTTI", returns a UClassID for the actual class. 463 * 464 * @stable ICU 2.2 465 */ 466 virtual UClassID getDynamicClassID() const; 467 468 /** 469 * ICU "poor man's RTTI", returns a UClassID for this class. 470 * 471 * @stable ICU 2.2 472 */ 473 static UClassID U_EXPORT2 getStaticClassID(); 474 475 private: 476 ResourceBundle(); // default constructor not implemented 477 478 UResourceBundle *fResource; 479 void constructForLocale(const UnicodeString& path, const Locale& locale, UErrorCode& error); 480 Locale *fLocale; 481 482 }; 483 484 U_NAMESPACE_END 485 #endif 486
