icuSources/common/unicode/resbund.h

   1 /*
   2 ******************************************************************************
   3 *
   4 *   Copyright (C) 1996-2011, 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 #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 */
 425
 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;
 435
 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 */
 446
 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;
 473
 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();
 480
 481 private:
 482     ResourceBundle(); // default constructor not implemented
 483
 484     UResourceBundle *fResource;
 485     void constructForLocale(const UnicodeString& path, const Locale& locale, UErrorCode& error);
 486     Locale *fLocale;
 487
 488 };
 489
 490 U_NAMESPACE_END
 491 #endif