1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/common/unicode/resbund.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,490 @@
1.4 +/*
1.5 +******************************************************************************
1.6 +*
1.7 +* Copyright (C) 1996-2013, International Business Machines Corporation
1.8 +* and others. All Rights Reserved.
1.9 +*
1.10 +******************************************************************************
1.11 +*
1.12 +* File resbund.h
1.13 +*
1.14 +* CREATED BY
1.15 +* Richard Gillam
1.16 +*
1.17 +* Modification History:
1.18 +*
1.19 +* Date Name Description
1.20 +* 2/5/97 aliu Added scanForLocaleInFile. Added
1.21 +* constructor which attempts to read resource bundle
1.22 +* from a specific file, without searching other files.
1.23 +* 2/11/97 aliu Added UErrorCode return values to constructors. Fixed
1.24 +* infinite loops in scanForFile and scanForLocale.
1.25 +* Modified getRawResourceData to not delete storage
1.26 +* in localeData and resourceData which it doesn't own.
1.27 +* Added Mac compatibility #ifdefs for tellp() and
1.28 +* ios::nocreate.
1.29 +* 2/18/97 helena Updated with 100% documentation coverage.
1.30 +* 3/13/97 aliu Rewrote to load in entire resource bundle and store
1.31 +* it as a Hashtable of ResourceBundleData objects.
1.32 +* Added state table to govern parsing of files.
1.33 +* Modified to load locale index out of new file
1.34 +* distinct from default.txt.
1.35 +* 3/25/97 aliu Modified to support 2-d arrays, needed for timezone
1.36 +* data. Added support for custom file suffixes. Again,
1.37 +* needed to support timezone data.
1.38 +* 4/7/97 aliu Cleaned up.
1.39 +* 03/02/99 stephen Removed dependency on FILE*.
1.40 +* 03/29/99 helena Merged Bertrand and Stephen's changes.
1.41 +* 06/11/99 stephen Removed parsing of .txt files.
1.42 +* Reworked to use new binary format.
1.43 +* Cleaned up.
1.44 +* 06/14/99 stephen Removed methods taking a filename suffix.
1.45 +* 11/09/99 weiv Added getLocale(), fRealLocale, removed fRealLocaleID
1.46 +******************************************************************************
1.47 +*/
1.48 +
1.49 +#ifndef RESBUND_H
1.50 +#define RESBUND_H
1.51 +
1.52 +#include "unicode/utypes.h"
1.53 +#include "unicode/uobject.h"
1.54 +#include "unicode/ures.h"
1.55 +#include "unicode/unistr.h"
1.56 +#include "unicode/locid.h"
1.57 +
1.58 +/**
1.59 + * \file
1.60 + * \brief C++ API: Resource Bundle
1.61 + */
1.62 +
1.63 +U_NAMESPACE_BEGIN
1.64 +
1.65 +/**
1.66 + * A class representing a collection of resource information pertaining to a given
1.67 + * locale. A resource bundle provides a way of accessing locale- specfic information in
1.68 + * a data file. You create a resource bundle that manages the resources for a given
1.69 + * locale and then ask it for individual resources.
1.70 + * <P>
1.71 + * Resource bundles in ICU4C are currently defined using text files which conform to the following
1.72 + * <a href="http://source.icu-project.org/repos/icu/icuhtml/trunk/design/bnf_rb.txt">BNF definition</a>.
1.73 + * More on resource bundle concepts and syntax can be found in the
1.74 + * <a href="http://icu-project.org/userguide/ResourceManagement.html">Users Guide</a>.
1.75 + * <P>
1.76 + *
1.77 + * The ResourceBundle class is not suitable for subclassing.
1.78 + *
1.79 + * @stable ICU 2.0
1.80 + */
1.81 +class U_COMMON_API ResourceBundle : public UObject {
1.82 +public:
1.83 + /**
1.84 + * Constructor
1.85 + *
1.86 + * @param packageName The packageName and locale together point to an ICU udata object,
1.87 + * as defined by <code> udata_open( packageName, "res", locale, err) </code>
1.88 + * or equivalent. Typically, packageName will refer to a (.dat) file, or to
1.89 + * a package registered with udata_setAppData(). Using a full file or directory
1.90 + * pathname for packageName is deprecated.
1.91 + * @param locale This is the locale this resource bundle is for. To get resources
1.92 + * for the French locale, for example, you would create a
1.93 + * ResourceBundle passing Locale::FRENCH for the "locale" parameter,
1.94 + * and all subsequent calls to that resource bundle will return
1.95 + * resources that pertain to the French locale. If the caller doesn't
1.96 + * pass a locale parameter, the default locale for the system (as
1.97 + * returned by Locale::getDefault()) will be used.
1.98 + * @param err The Error Code.
1.99 + * The UErrorCode& err parameter is used to return status information to the user. To
1.100 + * check whether the construction succeeded or not, you should check the value of
1.101 + * U_SUCCESS(err). If you wish more detailed information, you can check for
1.102 + * informational error results which still indicate success. U_USING_FALLBACK_WARNING
1.103 + * indicates that a fall back locale was used. For example, 'de_CH' was requested,
1.104 + * but nothing was found there, so 'de' was used. U_USING_DEFAULT_WARNING indicates that
1.105 + * the default locale data was used; neither the requested locale nor any of its
1.106 + * fall back locales could be found.
1.107 + * @stable ICU 2.0
1.108 + */
1.109 + ResourceBundle(const UnicodeString& packageName,
1.110 + const Locale& locale,
1.111 + UErrorCode& err);
1.112 +
1.113 + /**
1.114 + * Construct a resource bundle for the default bundle in the specified package.
1.115 + *
1.116 + * @param packageName The packageName and locale together point to an ICU udata object,
1.117 + * as defined by <code> udata_open( packageName, "res", locale, err) </code>
1.118 + * or equivalent. Typically, packageName will refer to a (.dat) file, or to
1.119 + * a package registered with udata_setAppData(). Using a full file or directory
1.120 + * pathname for packageName is deprecated.
1.121 + * @param err A UErrorCode value
1.122 + * @stable ICU 2.0
1.123 + */
1.124 + ResourceBundle(const UnicodeString& packageName,
1.125 + UErrorCode& err);
1.126 +
1.127 + /**
1.128 + * Construct a resource bundle for the ICU default bundle.
1.129 + *
1.130 + * @param err A UErrorCode value
1.131 + * @stable ICU 2.0
1.132 + */
1.133 + ResourceBundle(UErrorCode &err);
1.134 +
1.135 + /**
1.136 + * Standard constructor, onstructs a resource bundle for the locale-specific
1.137 + * bundle in the specified package.
1.138 + *
1.139 + * @param packageName The packageName and locale together point to an ICU udata object,
1.140 + * as defined by <code> udata_open( packageName, "res", locale, err) </code>
1.141 + * or equivalent. Typically, packageName will refer to a (.dat) file, or to
1.142 + * a package registered with udata_setAppData(). Using a full file or directory
1.143 + * pathname for packageName is deprecated.
1.144 + * NULL is used to refer to ICU data.
1.145 + * @param locale The locale for which to open a resource bundle.
1.146 + * @param err A UErrorCode value
1.147 + * @stable ICU 2.0
1.148 + */
1.149 + ResourceBundle(const char* packageName,
1.150 + const Locale& locale,
1.151 + UErrorCode& err);
1.152 +
1.153 + /**
1.154 + * Copy constructor.
1.155 + *
1.156 + * @param original The resource bundle to copy.
1.157 + * @stable ICU 2.0
1.158 + */
1.159 + ResourceBundle(const ResourceBundle &original);
1.160 +
1.161 + /**
1.162 + * Constructor from a C UResourceBundle. The resource bundle is
1.163 + * copied and not adopted. ures_close will still need to be used on the
1.164 + * original resource bundle.
1.165 + *
1.166 + * @param res A pointer to the C resource bundle.
1.167 + * @param status A UErrorCode value.
1.168 + * @stable ICU 2.0
1.169 + */
1.170 + ResourceBundle(UResourceBundle *res,
1.171 + UErrorCode &status);
1.172 +
1.173 + /**
1.174 + * Assignment operator.
1.175 + *
1.176 + * @param other The resource bundle to copy.
1.177 + * @stable ICU 2.0
1.178 + */
1.179 + ResourceBundle&
1.180 + operator=(const ResourceBundle& other);
1.181 +
1.182 + /** Destructor.
1.183 + * @stable ICU 2.0
1.184 + */
1.185 + virtual ~ResourceBundle();
1.186 +
1.187 + /**
1.188 + * Clone this object.
1.189 + * Clones can be used concurrently in multiple threads.
1.190 + * If an error occurs, then NULL is returned.
1.191 + * The caller must delete the clone.
1.192 + *
1.193 + * @return a clone of this object
1.194 + *
1.195 + * @see getDynamicClassID
1.196 + * @stable ICU 2.8
1.197 + */
1.198 + ResourceBundle *clone() const;
1.199 +
1.200 + /**
1.201 + * Returns the size of a resource. Size for scalar types is always 1, and for vector/table types is
1.202 + * the number of child resources.
1.203 + * @warning Integer array is treated as a scalar type. There are no
1.204 + * APIs to access individual members of an integer array. It
1.205 + * is always returned as a whole.
1.206 + *
1.207 + * @return number of resources in a given resource.
1.208 + * @stable ICU 2.0
1.209 + */
1.210 + int32_t
1.211 + getSize(void) const;
1.212 +
1.213 + /**
1.214 + * returns a string from a string resource type
1.215 + *
1.216 + * @param status fills in the outgoing error code
1.217 + * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
1.218 + * could be a warning
1.219 + * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
1.220 + * @return a pointer to a zero-terminated UChar array which lives in a memory mapped/DLL file.
1.221 + * @stable ICU 2.0
1.222 + */
1.223 + UnicodeString
1.224 + getString(UErrorCode& status) const;
1.225 +
1.226 + /**
1.227 + * returns a binary data from a resource. Can be used at most primitive resource types (binaries,
1.228 + * strings, ints)
1.229 + *
1.230 + * @param len fills in the length of resulting byte chunk
1.231 + * @param status fills in the outgoing error code
1.232 + * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
1.233 + * could be a warning
1.234 + * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
1.235 + * @return a pointer to a chunk of unsigned bytes which live in a memory mapped/DLL file.
1.236 + * @stable ICU 2.0
1.237 + */
1.238 + const uint8_t*
1.239 + getBinary(int32_t& len, UErrorCode& status) const;
1.240 +
1.241 +
1.242 + /**
1.243 + * returns an integer vector from a resource.
1.244 + *
1.245 + * @param len fills in the length of resulting integer vector
1.246 + * @param status fills in the outgoing error code
1.247 + * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
1.248 + * could be a warning
1.249 + * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
1.250 + * @return a pointer to a vector of integers that lives in a memory mapped/DLL file.
1.251 + * @stable ICU 2.0
1.252 + */
1.253 + const int32_t*
1.254 + getIntVector(int32_t& len, UErrorCode& status) const;
1.255 +
1.256 + /**
1.257 + * returns an unsigned integer from a resource.
1.258 + * This integer is originally 28 bits.
1.259 + *
1.260 + * @param status fills in the outgoing error code
1.261 + * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
1.262 + * could be a warning
1.263 + * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
1.264 + * @return an unsigned integer value
1.265 + * @stable ICU 2.0
1.266 + */
1.267 + uint32_t
1.268 + getUInt(UErrorCode& status) const;
1.269 +
1.270 + /**
1.271 + * returns a signed integer from a resource.
1.272 + * This integer is originally 28 bit and the sign gets propagated.
1.273 + *
1.274 + * @param status fills in the outgoing error code
1.275 + * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
1.276 + * could be a warning
1.277 + * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
1.278 + * @return a signed integer value
1.279 + * @stable ICU 2.0
1.280 + */
1.281 + int32_t
1.282 + getInt(UErrorCode& status) const;
1.283 +
1.284 + /**
1.285 + * Checks whether the resource has another element to iterate over.
1.286 + *
1.287 + * @return TRUE if there are more elements, FALSE if there is no more elements
1.288 + * @stable ICU 2.0
1.289 + */
1.290 + UBool
1.291 + hasNext(void) const;
1.292 +
1.293 + /**
1.294 + * Resets the internal context of a resource so that iteration starts from the first element.
1.295 + *
1.296 + * @stable ICU 2.0
1.297 + */
1.298 + void
1.299 + resetIterator(void);
1.300 +
1.301 + /**
1.302 + * Returns the key associated with this resource. Not all the resources have a key - only
1.303 + * those that are members of a table.
1.304 + *
1.305 + * @return a key associated to this resource, or NULL if it doesn't have a key
1.306 + * @stable ICU 2.0
1.307 + */
1.308 + const char*
1.309 + getKey(void) const;
1.310 +
1.311 + /**
1.312 + * Gets the locale ID of the resource bundle as a string.
1.313 + * Same as getLocale().getName() .
1.314 + *
1.315 + * @return the locale ID of the resource bundle as a string
1.316 + * @stable ICU 2.0
1.317 + */
1.318 + const char*
1.319 + getName(void) const;
1.320 +
1.321 +
1.322 + /**
1.323 + * Returns the type of a resource. Available types are defined in enum UResType
1.324 + *
1.325 + * @return type of the given resource.
1.326 + * @stable ICU 2.0
1.327 + */
1.328 + UResType
1.329 + getType(void) const;
1.330 +
1.331 + /**
1.332 + * Returns the next resource in a given resource or NULL if there are no more resources
1.333 + *
1.334 + * @param status fills in the outgoing error code
1.335 + * @return ResourceBundle object.
1.336 + * @stable ICU 2.0
1.337 + */
1.338 + ResourceBundle
1.339 + getNext(UErrorCode& status);
1.340 +
1.341 + /**
1.342 + * Returns the next string in a resource or NULL if there are no more resources
1.343 + * to iterate over.
1.344 + *
1.345 + * @param status fills in the outgoing error code
1.346 + * @return an UnicodeString object.
1.347 + * @stable ICU 2.0
1.348 + */
1.349 + UnicodeString
1.350 + getNextString(UErrorCode& status);
1.351 +
1.352 + /**
1.353 + * Returns the next string in a resource or NULL if there are no more resources
1.354 + * to iterate over.
1.355 + *
1.356 + * @param key fill in for key associated with this string
1.357 + * @param status fills in the outgoing error code
1.358 + * @return an UnicodeString object.
1.359 + * @stable ICU 2.0
1.360 + */
1.361 + UnicodeString
1.362 + getNextString(const char ** key,
1.363 + UErrorCode& status);
1.364 +
1.365 + /**
1.366 + * Returns the resource in a resource at the specified index.
1.367 + *
1.368 + * @param index an index to the wanted resource.
1.369 + * @param status fills in the outgoing error code
1.370 + * @return ResourceBundle object. If there is an error, resource is invalid.
1.371 + * @stable ICU 2.0
1.372 + */
1.373 + ResourceBundle
1.374 + get(int32_t index,
1.375 + UErrorCode& status) const;
1.376 +
1.377 + /**
1.378 + * Returns the string in a given resource at the specified index.
1.379 + *
1.380 + * @param index an index to the wanted string.
1.381 + * @param status fills in the outgoing error code
1.382 + * @return an UnicodeString object. If there is an error, string is bogus
1.383 + * @stable ICU 2.0
1.384 + */
1.385 + UnicodeString
1.386 + getStringEx(int32_t index,
1.387 + UErrorCode& status) const;
1.388 +
1.389 + /**
1.390 + * Returns a resource in a resource that has a given key. This procedure works only with table
1.391 + * resources.
1.392 + *
1.393 + * @param key a key associated with the wanted resource
1.394 + * @param status fills in the outgoing error code.
1.395 + * @return ResourceBundle object. If there is an error, resource is invalid.
1.396 + * @stable ICU 2.0
1.397 + */
1.398 + ResourceBundle
1.399 + get(const char* key,
1.400 + UErrorCode& status) const;
1.401 +
1.402 + /**
1.403 + * Returns a string in a resource that has a given key. This procedure works only with table
1.404 + * resources.
1.405 + *
1.406 + * @param key a key associated with the wanted string
1.407 + * @param status fills in the outgoing error code
1.408 + * @return an UnicodeString object. If there is an error, string is bogus
1.409 + * @stable ICU 2.0
1.410 + */
1.411 + UnicodeString
1.412 + getStringEx(const char* key,
1.413 + UErrorCode& status) const;
1.414 +
1.415 +#ifndef U_HIDE_DEPRECATED_API
1.416 + /**
1.417 + * Return the version number associated with this ResourceBundle as a string. Please
1.418 + * use getVersion, as this method is going to be deprecated.
1.419 + *
1.420 + * @return A version number string as specified in the resource bundle or its parent.
1.421 + * The caller does not own this string.
1.422 + * @see getVersion
1.423 + * @deprecated ICU 2.8 Use getVersion instead.
1.424 + */
1.425 + const char*
1.426 + getVersionNumber(void) const;
1.427 +#endif /* U_HIDE_DEPRECATED_API */
1.428 +
1.429 + /**
1.430 + * Return the version number associated with this ResourceBundle as a UVersionInfo array.
1.431 + *
1.432 + * @param versionInfo A UVersionInfo array that is filled with the version number
1.433 + * as specified in the resource bundle or its parent.
1.434 + * @stable ICU 2.0
1.435 + */
1.436 + void
1.437 + getVersion(UVersionInfo versionInfo) const;
1.438 +
1.439 +#ifndef U_HIDE_DEPRECATED_API
1.440 + /**
1.441 + * Return the Locale associated with this ResourceBundle.
1.442 + *
1.443 + * @return a Locale object
1.444 + * @deprecated ICU 2.8 Use getLocale(ULocDataLocaleType type, UErrorCode &status) overload instead.
1.445 + */
1.446 + const Locale&
1.447 + getLocale(void) const;
1.448 +#endif /* U_HIDE_DEPRECATED_API */
1.449 +
1.450 + /**
1.451 + * Return the Locale associated with this ResourceBundle.
1.452 + * @param type You can choose between requested, valid and actual
1.453 + * locale. For description see the definition of
1.454 + * ULocDataLocaleType in uloc.h
1.455 + * @param status just for catching illegal arguments
1.456 + *
1.457 + * @return a Locale object
1.458 + * @stable ICU 2.8
1.459 + */
1.460 + const Locale
1.461 + getLocale(ULocDataLocaleType type, UErrorCode &status) const;
1.462 +#ifndef U_HIDE_INTERNAL_API
1.463 + /**
1.464 + * This API implements multilevel fallback
1.465 + * @internal
1.466 + */
1.467 + ResourceBundle
1.468 + getWithFallback(const char* key, UErrorCode& status);
1.469 +#endif /* U_HIDE_INTERNAL_API */
1.470 + /**
1.471 + * ICU "poor man's RTTI", returns a UClassID for the actual class.
1.472 + *
1.473 + * @stable ICU 2.2
1.474 + */
1.475 + virtual UClassID getDynamicClassID() const;
1.476 +
1.477 + /**
1.478 + * ICU "poor man's RTTI", returns a UClassID for this class.
1.479 + *
1.480 + * @stable ICU 2.2
1.481 + */
1.482 + static UClassID U_EXPORT2 getStaticClassID();
1.483 +
1.484 +private:
1.485 + ResourceBundle(); // default constructor not implemented
1.486 +
1.487 + UResourceBundle *fResource;
1.488 + void constructForLocale(const UnicodeString& path, const Locale& locale, UErrorCode& error);
1.489 + Locale *fLocale;
1.490 +};
1.491 +
1.492 +U_NAMESPACE_END
1.493 +#endif
