icuSources/common/unicode/resbund.h

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