include/unicode/resbund.h

0001 // © 2016 and later: Unicode, Inc. and others.
0002 // License & terms of use: http://www.unicode.org/copyright.html
0003 /*
0004 ******************************************************************************
0005 *
0006 *   Copyright (C) 1996-2013, International Business Machines Corporation
0007 *   and others.  All Rights Reserved.
0008 *
0009 ******************************************************************************
0010 *
0011 * File resbund.h
0012 *
0013 *   CREATED BY
0014 *       Richard Gillam
0015 *
0016 * Modification History:
0017 *
0018 *   Date        Name        Description
0019 *   2/5/97      aliu        Added scanForLocaleInFile.  Added
0020 *                           constructor which attempts to read resource bundle
0021 *                           from a specific file, without searching other files.
0022 *   2/11/97     aliu        Added UErrorCode return values to constructors.  Fixed
0023 *                           infinite loops in scanForFile and scanForLocale.
0024 *                           Modified getRawResourceData to not delete storage
0025 *                           in localeData and resourceData which it doesn't own.
0026 *                           Added Mac compatibility #ifdefs for tellp() and
0027 *                           ios::nocreate.
0028 *   2/18/97     helena      Updated with 100% documentation coverage.
0029 *   3/13/97     aliu        Rewrote to load in entire resource bundle and store
0030 *                           it as a Hashtable of ResourceBundleData objects.
0031 *                           Added state table to govern parsing of files.
0032 *                           Modified to load locale index out of new file
0033 *                           distinct from default.txt.
0034 *   3/25/97     aliu        Modified to support 2-d arrays, needed for timezone
0035 *                           data. Added support for custom file suffixes.  Again,
0036 *                           needed to support timezone data.
0037 *   4/7/97      aliu        Cleaned up.
0038 * 03/02/99      stephen     Removed dependency on FILE*.
0039 * 03/29/99      helena      Merged Bertrand and Stephen's changes.
0040 * 06/11/99      stephen     Removed parsing of .txt files.
0041 *                           Reworked to use new binary format.
0042 *                           Cleaned up.
0043 * 06/14/99      stephen     Removed methods taking a filename suffix.
0044 * 11/09/99      weiv        Added getLocale(), fRealLocale, removed fRealLocaleID
0045 ******************************************************************************
0046 */
0047
0048 #ifndef RESBUND_H
0049 #define RESBUND_H
0050
0051 #include "unicode/utypes.h"
0052
0053 #if U_SHOW_CPLUSPLUS_API
0054
0055 #include "unicode/uobject.h"
0056 #include "unicode/ures.h"
0057 #include "unicode/unistr.h"
0058 #include "unicode/locid.h"
0059
0060 /**
0061  * \file
0062  * \brief C++ API: Resource Bundle
0063  */
0064
0065 U_NAMESPACE_BEGIN
0066
0067 /**
0068  * A class representing a collection of resource information pertaining to a given
0069  * locale. A resource bundle provides a way of accessing locale- specific information in
0070  * a data file. You create a resource bundle that manages the resources for a given
0071  * locale and then ask it for individual resources.
0072  * <P>
0073  * Resource bundles in ICU4C are currently defined using text files which conform to the following
0074  * <a href="https://github.com/unicode-org/icu-docs/blob/main/design/bnf_rb.txt">BNF definition</a>.
0075  * More on resource bundle concepts and syntax can be found in the
0076  * <a href="https://unicode-org.github.io/icu/userguide/locale/resources">Users Guide</a>.
0077  * <P>
0078  *
0079  * The ResourceBundle class is not suitable for subclassing.
0080  *
0081  * @stable ICU 2.0
0082  */
0083 class U_COMMON_API ResourceBundle : public UObject {
0084 public:
0085     /**
0086      * Constructor
0087      *
0088      * @param packageName   The packageName and locale together point to an ICU udata object,
0089      *                      as defined by <code> udata_open( packageName, "res", locale, err) </code>
0090      *                      or equivalent.  Typically, packageName will refer to a (.dat) file, or to
0091      *                      a package registered with udata_setAppData(). Using a full file or directory
0092      *                      pathname for packageName is deprecated.
0093      * @param locale  This is the locale this resource bundle is for. To get resources
0094      *                for the French locale, for example, you would create a
0095      *                ResourceBundle passing Locale::FRENCH for the "locale" parameter,
0096      *                and all subsequent calls to that resource bundle will return
0097      *                resources that pertain to the French locale. If the caller doesn't
0098      *                pass a locale parameter, the default locale for the system (as
0099      *                returned by Locale::getDefault()) will be used.
0100      * @param err     The Error Code.
0101      * The UErrorCode& err parameter is used to return status information to the user. To
0102      * check whether the construction succeeded or not, you should check the value of
0103      * U_SUCCESS(err). If you wish more detailed information, you can check for
0104      * informational error results which still indicate success. U_USING_FALLBACK_WARNING
0105      * indicates that a fall back locale was used. For example, 'de_CH' was requested,
0106      * but nothing was found there, so 'de' was used. U_USING_DEFAULT_WARNING indicates that
0107      * the default locale data was used; neither the requested locale nor any of its
0108      * fall back locales could be found.
0109      * @stable ICU 2.0
0110      */
0111     ResourceBundle(const UnicodeString&    packageName,
0112                    const Locale&           locale,
0113                    UErrorCode&              err);
0114
0115     /**
0116      * Construct a resource bundle for the default bundle in the specified package.
0117      *
0118      * @param packageName   The packageName and locale together point to an ICU udata object,
0119      *                      as defined by <code> udata_open( packageName, "res", locale, err) </code>
0120      *                      or equivalent.  Typically, packageName will refer to a (.dat) file, or to
0121      *                      a package registered with udata_setAppData(). Using a full file or directory
0122      *                      pathname for packageName is deprecated.
0123      * @param err A UErrorCode value
0124      * @stable ICU 2.0
0125      */
0126     ResourceBundle(const UnicodeString&    packageName,
0127                    UErrorCode&              err);
0128
0129     /**
0130      * Construct a resource bundle for the ICU default bundle.
0131      *
0132      * @param err A UErrorCode value
0133      * @stable ICU 2.0
0134      */
0135     ResourceBundle(UErrorCode &err);
0136
0137     /**
0138      * Standard constructor, constructs a resource bundle for the locale-specific
0139      * bundle in the specified package.
0140      *
0141      * @param packageName   The packageName and locale together point to an ICU udata object,
0142      *                      as defined by <code> udata_open( packageName, "res", locale, err) </code>
0143      *                      or equivalent.  Typically, packageName will refer to a (.dat) file, or to
0144      *                      a package registered with udata_setAppData(). Using a full file or directory
0145      *                      pathname for packageName is deprecated.
0146      *                      nullptr is used to refer to ICU data.
0147      * @param locale The locale for which to open a resource bundle.
0148      * @param err A UErrorCode value
0149      * @stable ICU 2.0
0150      */
0151     ResourceBundle(const char* packageName,
0152                    const Locale& locale,
0153                    UErrorCode& err);
0154
0155     /**
0156      * Copy constructor.
0157      *
0158      * @param original The resource bundle to copy.
0159      * @stable ICU 2.0
0160      */
0161     ResourceBundle(const ResourceBundle &original);
0162
0163     /**
0164      * Constructor from a C UResourceBundle. The resource bundle is
0165      * copied and not adopted. ures_close will still need to be used on the
0166      * original resource bundle.
0167      *
0168      * @param res A pointer to the C resource bundle.
0169      * @param status A UErrorCode value.
0170      * @stable ICU 2.0
0171      */
0172     ResourceBundle(UResourceBundle *res,
0173                    UErrorCode &status);
0174
0175     /**
0176      * Assignment operator.
0177      *
0178      * @param other The resource bundle to copy.
0179      * @stable ICU 2.0
0180      */
0181     ResourceBundle&
0182       operator=(const ResourceBundle& other);
0183
0184     /** Destructor.
0185      * @stable ICU 2.0
0186      */
0187     virtual ~ResourceBundle();
0188
0189     /**
0190      * Clone this object.
0191      * Clones can be used concurrently in multiple threads.
0192      * If an error occurs, then nullptr is returned.
0193      * The caller must delete the clone.
0194      *
0195      * @return a clone of this object
0196      *
0197      * @see getDynamicClassID
0198      * @stable ICU 2.8
0199      */
0200     ResourceBundle *clone() const;
0201
0202     /**
0203      * Returns the size of a resource. Size for scalar types is always 1, and for vector/table types is
0204      * the number of child resources.
0205      * @warning Integer array is treated as a scalar type. There are no
0206      *          APIs to access individual members of an integer array. It
0207      *          is always returned as a whole.
0208      *
0209      * @return number of resources in a given resource.
0210      * @stable ICU 2.0
0211      */
0212     int32_t
0213       getSize(void) const;
0214
0215     /**
0216      * returns a string from a string resource type
0217      *
0218      * @param status  fills in the outgoing error code
0219      *                could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
0220      *                could be a warning
0221      *                e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
0222      * @return a pointer to a zero-terminated char16_t array which lives in a memory mapped/DLL file.
0223      * @stable ICU 2.0
0224      */
0225     UnicodeString
0226       getString(UErrorCode& status) const;
0227
0228     /**
0229      * returns a binary data from a resource. Can be used at most primitive resource types (binaries,
0230      * strings, ints)
0231      *
0232      * @param len     fills in the length of resulting byte chunk
0233      * @param status  fills in the outgoing error code
0234      *                could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
0235      *                could be a warning
0236      *                e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
0237      * @return a pointer to a chunk of unsigned bytes which live in a memory mapped/DLL file.
0238      * @stable ICU 2.0
0239      */
0240     const uint8_t*
0241       getBinary(int32_t& len, UErrorCode& status) const;
0242
0243
0244     /**
0245      * returns an integer vector from a resource.
0246      *
0247      * @param len     fills in the length of resulting integer vector
0248      * @param status  fills in the outgoing error code
0249      *                could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
0250      *                could be a warning
0251      *                e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
0252      * @return a pointer to a vector of integers that lives in a memory mapped/DLL file.
0253      * @stable ICU 2.0
0254      */
0255     const int32_t*
0256       getIntVector(int32_t& len, UErrorCode& status) const;
0257
0258     /**
0259      * returns an unsigned integer from a resource.
0260      * This integer is originally 28 bits.
0261      *
0262      * @param status  fills in the outgoing error code
0263      *                could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
0264      *                could be a warning
0265      *                e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
0266      * @return an unsigned integer value
0267      * @stable ICU 2.0
0268      */
0269     uint32_t
0270       getUInt(UErrorCode& status) const;
0271
0272     /**
0273      * returns a signed integer from a resource.
0274      * This integer is originally 28 bit and the sign gets propagated.
0275      *
0276      * @param status  fills in the outgoing error code
0277      *                could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
0278      *                could be a warning
0279      *                e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
0280      * @return a signed integer value
0281      * @stable ICU 2.0
0282      */
0283     int32_t
0284       getInt(UErrorCode& status) const;
0285
0286     /**
0287      * Checks whether the resource has another element to iterate over.
0288      *
0289      * @return true if there are more elements, false if there is no more elements
0290      * @stable ICU 2.0
0291      */
0292     UBool
0293       hasNext(void) const;
0294
0295     /**
0296      * Resets the internal context of a resource so that iteration starts from the first element.
0297      *
0298      * @stable ICU 2.0
0299      */
0300     void
0301       resetIterator(void);
0302
0303     /**
0304      * Returns the key associated with this resource. Not all the resources have a key - only
0305      * those that are members of a table.
0306      *
0307      * @return a key associated to this resource, or nullptr if it doesn't have a key
0308      * @stable ICU 2.0
0309      */
0310     const char*
0311       getKey(void) const;
0312
0313     /**
0314      * Gets the locale ID of the resource bundle as a string.
0315      * Same as getLocale().getName() .
0316      *
0317      * @return the locale ID of the resource bundle as a string
0318      * @stable ICU 2.0
0319      */
0320     const char*
0321       getName(void) const;
0322
0323
0324     /**
0325      * Returns the type of a resource. Available types are defined in enum UResType
0326      *
0327      * @return type of the given resource.
0328      * @stable ICU 2.0
0329      */
0330     UResType
0331       getType(void) const;
0332
0333     /**
0334      * Returns the next resource in a given resource or nullptr if there are no more resources
0335      *
0336      * @param status            fills in the outgoing error code
0337      * @return                  ResourceBundle object.
0338      * @stable ICU 2.0
0339      */
0340     ResourceBundle
0341       getNext(UErrorCode& status);
0342
0343     /**
0344      * Returns the next string in a resource or nullptr if there are no more resources
0345      * to iterate over.
0346      *
0347      * @param status            fills in the outgoing error code
0348      * @return an UnicodeString object.
0349      * @stable ICU 2.0
0350      */
0351     UnicodeString
0352       getNextString(UErrorCode& status);
0353
0354     /**
0355      * Returns the next string in a resource or nullptr if there are no more resources
0356      * to iterate over.
0357      *
0358      * @param key               fill in for key associated with this string
0359      * @param status            fills in the outgoing error code
0360      * @return an UnicodeString object.
0361      * @stable ICU 2.0
0362      */
0363     UnicodeString
0364       getNextString(const char ** key,
0365                     UErrorCode& status);
0366
0367     /**
0368      * Returns the resource in a resource at the specified index.
0369      *
0370      * @param index             an index to the wanted resource.
0371      * @param status            fills in the outgoing error code
0372      * @return                  ResourceBundle object. If there is an error, resource is invalid.
0373      * @stable ICU 2.0
0374      */
0375     ResourceBundle
0376       get(int32_t index,
0377           UErrorCode& status) const;
0378
0379     /**
0380      * Returns the string in a given resource at the specified index.
0381      *
0382      * @param index             an index to the wanted string.
0383      * @param status            fills in the outgoing error code
0384      * @return                  an UnicodeString object. If there is an error, string is bogus
0385      * @stable ICU 2.0
0386      */
0387     UnicodeString
0388       getStringEx(int32_t index,
0389                   UErrorCode& status) const;
0390
0391     /**
0392      * Returns a resource in a resource that has a given key. This procedure works only with table
0393      * resources.
0394      *
0395      * @param key               a key associated with the wanted resource
0396      * @param status            fills in the outgoing error code.
0397      * @return                  ResourceBundle object. If there is an error, resource is invalid.
0398      * @stable ICU 2.0
0399      */
0400     ResourceBundle
0401       get(const char* key,
0402           UErrorCode& status) const;
0403
0404     /**
0405      * Returns a string in a resource that has a given key. This procedure works only with table
0406      * resources.
0407      *
0408      * @param key               a key associated with the wanted string
0409      * @param status            fills in the outgoing error code
0410      * @return                  an UnicodeString object. If there is an error, string is bogus
0411      * @stable ICU 2.0
0412      */
0413     UnicodeString
0414       getStringEx(const char* key,
0415                   UErrorCode& status) const;
0416
0417 #ifndef U_HIDE_DEPRECATED_API
0418     /**
0419      * Return the version number associated with this ResourceBundle as a string. Please
0420      * use getVersion, as this method is going to be deprecated.
0421      *
0422      * @return  A version number string as specified in the resource bundle or its parent.
0423      *          The caller does not own this string.
0424      * @see getVersion
0425      * @deprecated ICU 2.8 Use getVersion instead.
0426      */
0427     const char*
0428       getVersionNumber(void) const;
0429 #endif  /* U_HIDE_DEPRECATED_API */
0430
0431     /**
0432      * Return the version number associated with this ResourceBundle as a UVersionInfo array.
0433      *
0434      * @param versionInfo A UVersionInfo array that is filled with the version number
0435      *                    as specified in the resource bundle or its parent.
0436      * @stable ICU 2.0
0437      */
0438     void
0439       getVersion(UVersionInfo versionInfo) const;
0440
0441 #ifndef U_HIDE_DEPRECATED_API
0442     /**
0443      * Return the Locale associated with this ResourceBundle.
0444      *
0445      * @return a Locale object
0446      * @deprecated ICU 2.8 Use getLocale(ULocDataLocaleType type, UErrorCode &status) overload instead.
0447      */
0448     const Locale&
0449       getLocale(void) const;
0450 #endif  /* U_HIDE_DEPRECATED_API */
0451
0452     /**
0453      * Return the Locale associated with this ResourceBundle.
0454      * @param type You can choose between requested, valid and actual
0455      *             locale. For description see the definition of
0456      *             ULocDataLocaleType in uloc.h
0457      * @param status just for catching illegal arguments
0458      *
0459      * @return a Locale object
0460      * @stable ICU 2.8
0461      */
0462     const Locale
0463       getLocale(ULocDataLocaleType type, UErrorCode &status) const;
0464 #ifndef U_HIDE_INTERNAL_API
0465     /**
0466      * This API implements multilevel fallback
0467      * @internal
0468      */
0469     ResourceBundle
0470         getWithFallback(const char* key, UErrorCode& status);
0471 #endif  /* U_HIDE_INTERNAL_API */
0472     /**
0473      * ICU "poor man's RTTI", returns a UClassID for the actual class.
0474      *
0475      * @stable ICU 2.2
0476      */
0477     virtual UClassID getDynamicClassID() const override;
0478
0479     /**
0480      * ICU "poor man's RTTI", returns a UClassID for this class.
0481      *
0482      * @stable ICU 2.2
0483      */
0484     static UClassID U_EXPORT2 getStaticClassID();
0485
0486 private:
0487     ResourceBundle() = delete; // default constructor not implemented
0488
0489     UResourceBundle *fResource;
0490     void constructForLocale(const UnicodeString& path, const Locale& locale, UErrorCode& error);
0491     Locale *fLocale;
0492 };
0493
0494 U_NAMESPACE_END
0495
0496 #endif /* U_SHOW_CPLUSPLUS_API */
0497
0498 #endif