Home | History | Annotate | Download | only in unicode
      1 /*
      2 ******************************************************************************
      3 *
      4 *   Copyright (C) 1996-2013, 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 U_NAMESPACE_END
    490 #endif
    491