icuSources/common/unicode/resbund.h

   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 #include "unicode/uobject.h"
  53 #include "unicode/ures.h"
  54 #include "unicode/unistr.h"
  55 #include "unicode/locid.h"
  56
  57 /**
  58  * \file
  59  * \brief C++ API: Resource Bundle
  60  */
  61
  62 #if U_SHOW_CPLUSPLUS_API
  63 U_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
  72  * <a href="http://source.icu-project.org/repos/icu/icuhtml/trunk/design/bnf_rb.txt">BNF definition</a>.
  73  * More on resource bundle concepts and syntax can be found in the
  74  * <a href="http://icu-project.org/userguide/ResourceManagement.html">Users Guide</a>.
  75  * <P>
  76  *
  77  * The ResourceBundle class is not suitable for subclassing.
  78  *
  79  * @stable ICU 2.0
  80  */
  81 class U_COMMON_API ResourceBundle : public UObject {
  82 public:
  83     /**
  84      * Constructor
  85      *
  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.
  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      */
 109     ResourceBundle(const UnicodeString&    packageName,
 110                    const Locale&           locale,
 111                    UErrorCode&              err);
 112
 113     /**
 114      * Construct a resource bundle for the default bundle in the specified package.
 115      *
 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.
 121      * @param err A UErrorCode value
 122      * @stable ICU 2.0
 123      */
 124     ResourceBundle(const UnicodeString&    packageName,
 125                    UErrorCode&              err);
 126
 127     /**
 128      * Construct a resource bundle for the ICU default bundle.
 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
 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.
 145      * @param locale The locale for which to open a resource bundle.
 146      * @param err A UErrorCode value
 147      * @stable ICU 2.0
 148      */
 149     ResourceBundle(const char* packageName,
 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     /**
 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.
 165      *
 166      * @param res A pointer to the C resource bundle.
 167      * @param status A UErrorCode value.
 168      * @stable ICU 2.0
 169      */
 170     ResourceBundle(UResourceBundle *res,
 171                    UErrorCode &status);
 172
 173     /**
 174      * Assignment operator.
 175      *
 176      * @param other The resource bundle to copy.
 177      * @stable ICU 2.0
 178      */
 179     ResourceBundle&
 180       operator=(const ResourceBundle& other);
 181
 182     /** Destructor.
 183      * @stable ICU 2.0
 184      */
 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
 196      * @stable ICU 2.8
 197      */
 198     ResourceBundle *clone() const;
 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.
 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.
 206      *
 207      * @return number of resources in a given resource.
 208      * @stable ICU 2.0
 209      */
 210     int32_t
 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
 217      *                could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
 218      *                could be a warning
 219      *                e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
 220      * @return a pointer to a zero-terminated char16_t array which lives in a memory mapped/DLL file.
 221      * @stable ICU 2.0
 222      */
 223     UnicodeString
 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
 232      *                could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
 233      *                could be a warning
 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     /**
 243      * returns an integer vector from a resource.
 244      *
 245      * @param len     fills in the length of resulting integer vector
 246      * @param status  fills in the outgoing error code
 247      *                could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
 248      *                could be a warning
 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     /**
 257      * returns an unsigned integer from a resource.
 258      * This integer is originally 28 bits.
 259      *
 260      * @param status  fills in the outgoing error code
 261      *                could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
 262      *                could be a warning
 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      */
 267     uint32_t
 268       getUInt(UErrorCode& status) const;
 269
 270     /**
 271      * returns a signed integer from a resource.
 272      * This integer is originally 28 bit and the sign gets propagated.
 273      *
 274      * @param status  fills in the outgoing error code
 275      *                could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
 276      *                could be a warning
 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      */
 281     int32_t
 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      */
 290     UBool
 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      */
 298     void
 299       resetIterator(void);
 300
 301     /**
 302      * Returns the key associated with this resource. Not all the resources have a key - only
 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*
 309       getKey(void) const;
 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*
 319       getName(void) const;
 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      */
 328     UResType
 329       getType(void) const;
 330
 331     /**
 332      * Returns the next resource in a given resource or NULL if there are no more resources
 333      *
 334      * @param status            fills in the outgoing error code
 335      * @return                  ResourceBundle object.
 336      * @stable ICU 2.0
 337      */
 338     ResourceBundle
 339       getNext(UErrorCode& status);
 340
 341     /**
 342      * Returns the next string in a resource or NULL if there are no more resources
 343      * to iterate over.
 344      *
 345      * @param status            fills in the outgoing error code
 346      * @return an UnicodeString object.
 347      * @stable ICU 2.0
 348      */
 349     UnicodeString
 350       getNextString(UErrorCode& status);
 351
 352     /**
 353      * Returns the next string in a resource or NULL if there are no more resources
 354      * to iterate over.
 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      */
 361     UnicodeString
 362       getNextString(const char ** key,
 363                     UErrorCode& status);
 364
 365     /**
 366      * Returns the resource in a resource at the specified index.
 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      */
 373     ResourceBundle
 374       get(int32_t index,
 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      */
 385     UnicodeString
 386       getStringEx(int32_t index,
 387                   UErrorCode& status) const;
 388
 389     /**
 390      * Returns a resource in a resource that has a given key. This procedure works only with table
 391      * resources.
 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      */
 398     ResourceBundle
 399       get(const char* key,
 400           UErrorCode& status) const;
 401
 402     /**
 403      * Returns a string in a resource that has a given key. This procedure works only with table
 404      * resources.
 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      */
 411     UnicodeString
 412       getStringEx(const char* key,
 413                   UErrorCode& status) const;
 414
 415 #ifndef U_HIDE_DEPRECATED_API
 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
 423      * @deprecated ICU 2.8 Use getVersion instead.
 424      */
 425     const char*
 426       getVersionNumber(void) const;
 427 #endif  /* U_HIDE_DEPRECATED_API */
 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      */
 436     void
 437       getVersion(UVersionInfo versionInfo) const;
 438
 439 #ifndef U_HIDE_DEPRECATED_API
 440     /**
 441      * Return the Locale associated with this ResourceBundle.
 442      *
 443      * @return a Locale object
 444      * @deprecated ICU 2.8 Use getLocale(ULocDataLocaleType type, UErrorCode &status) overload instead.
 445      */
 446     const Locale&
 447       getLocale(void) const;
 448 #endif  /* U_HIDE_DEPRECATED_API */
 449
 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
 458      * @stable ICU 2.8
 459      */
 460     const Locale
 461       getLocale(ULocDataLocaleType type, UErrorCode &status) const;
 462 #ifndef U_HIDE_INTERNAL_API
 463     /**
 464      * This API implements multilevel fallback
 465      * @internal
 466      */
 467     ResourceBundle
 468         getWithFallback(const char* key, UErrorCode& status);
 469 #endif  /* U_HIDE_INTERNAL_API */
 470     /**
 471      * ICU "poor man's RTTI", returns a UClassID for the actual class.
 472      *
 473      * @stable ICU 2.2
 474      */
 475     virtual UClassID getDynamicClassID() const;
 476
 477     /**
 478      * ICU "poor man's RTTI", returns a UClassID for this class.
 479      *
 480      * @stable ICU 2.2
 481      */
 482     static UClassID U_EXPORT2 getStaticClassID();
 483
 484 private:
 485     ResourceBundle(); // default constructor not implemented
 486
 487     UResourceBundle *fResource;
 488     void constructForLocale(const UnicodeString& path, const Locale& locale, UErrorCode& error);
 489     Locale *fLocale;
 490 };
 491
 492 U_NAMESPACE_END
 493 #endif // U_SHOW_CPLUSPLUS_API
 494
 495 #endif