Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/ures.h @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
rev   line source
jpayne@69 1 // © 2016 and later: Unicode, Inc. and others.
jpayne@69 2 // License & terms of use: http://www.unicode.org/copyright.html
jpayne@69 3 /*
jpayne@69 4 **********************************************************************
jpayne@69 5 * Copyright (C) 1997-2016, International Business Machines
jpayne@69 6 * Corporation and others. All Rights Reserved.
jpayne@69 7 **********************************************************************
jpayne@69 8 *
jpayne@69 9 * File URES.H (formerly CRESBUND.H)
jpayne@69 10 *
jpayne@69 11 * Modification History:
jpayne@69 12 *
jpayne@69 13 * Date Name Description
jpayne@69 14 * 04/01/97 aliu Creation.
jpayne@69 15 * 02/22/99 damiba overhaul.
jpayne@69 16 * 04/04/99 helena Fixed internal header inclusion.
jpayne@69 17 * 04/15/99 Madhu Updated Javadoc
jpayne@69 18 * 06/14/99 stephen Removed functions taking a filename suffix.
jpayne@69 19 * 07/20/99 stephen Language-independent typedef to void*
jpayne@69 20 * 11/09/99 weiv Added ures_getLocale()
jpayne@69 21 * 06/24/02 weiv Added support for resource sharing
jpayne@69 22 ******************************************************************************
jpayne@69 23 */
jpayne@69 24
jpayne@69 25 #ifndef URES_H
jpayne@69 26 #define URES_H
jpayne@69 27
jpayne@69 28 #include "unicode/utypes.h"
jpayne@69 29 #include "unicode/uloc.h"
jpayne@69 30 #include "unicode/localpointer.h"
jpayne@69 31
jpayne@69 32 /**
jpayne@69 33 * \file
jpayne@69 34 * \brief C API: Resource Bundle
jpayne@69 35 *
jpayne@69 36 * <h2>C API: Resource Bundle</h2>
jpayne@69 37 *
jpayne@69 38 * C API representing a collection of resource information pertaining to a given
jpayne@69 39 * locale. A resource bundle provides a way of accessing locale- specific information in
jpayne@69 40 * a data file. You create a resource bundle that manages the resources for a given
jpayne@69 41 * locale and then ask it for individual resources.
jpayne@69 42 * <P>
jpayne@69 43 * Resource bundles in ICU4C are currently defined using text files which conform to the following
jpayne@69 44 * <a href="http://source.icu-project.org/repos/icu/icuhtml/trunk/design/bnf_rb.txt">BNF definition</a>.
jpayne@69 45 * More on resource bundle concepts and syntax can be found in the
jpayne@69 46 * <a href="http://icu-project.org/userguide/ResourceManagement.html">Users Guide</a>.
jpayne@69 47 * <P>
jpayne@69 48 */
jpayne@69 49
jpayne@69 50 /**
jpayne@69 51 * UResourceBundle is an opaque type for handles for resource bundles in C APIs.
jpayne@69 52 * @stable ICU 2.0
jpayne@69 53 */
jpayne@69 54 struct UResourceBundle;
jpayne@69 55
jpayne@69 56 /**
jpayne@69 57 * @stable ICU 2.0
jpayne@69 58 */
jpayne@69 59 typedef struct UResourceBundle UResourceBundle;
jpayne@69 60
jpayne@69 61 /**
jpayne@69 62 * Numeric constants for types of resource items.
jpayne@69 63 * @see ures_getType
jpayne@69 64 * @stable ICU 2.0
jpayne@69 65 */
jpayne@69 66 typedef enum {
jpayne@69 67 /** Resource type constant for "no resource". @stable ICU 2.6 */
jpayne@69 68 URES_NONE=-1,
jpayne@69 69
jpayne@69 70 /** Resource type constant for 16-bit Unicode strings. @stable ICU 2.6 */
jpayne@69 71 URES_STRING=0,
jpayne@69 72
jpayne@69 73 /** Resource type constant for binary data. @stable ICU 2.6 */
jpayne@69 74 URES_BINARY=1,
jpayne@69 75
jpayne@69 76 /** Resource type constant for tables of key-value pairs. @stable ICU 2.6 */
jpayne@69 77 URES_TABLE=2,
jpayne@69 78
jpayne@69 79 /**
jpayne@69 80 * Resource type constant for aliases;
jpayne@69 81 * internally stores a string which identifies the actual resource
jpayne@69 82 * storing the data (can be in a different resource bundle).
jpayne@69 83 * Resolved internally before delivering the actual resource through the API.
jpayne@69 84 * @stable ICU 2.6
jpayne@69 85 */
jpayne@69 86 URES_ALIAS=3,
jpayne@69 87
jpayne@69 88 /**
jpayne@69 89 * Resource type constant for a single 28-bit integer, interpreted as
jpayne@69 90 * signed or unsigned by the ures_getInt() or ures_getUInt() function.
jpayne@69 91 * @see ures_getInt
jpayne@69 92 * @see ures_getUInt
jpayne@69 93 * @stable ICU 2.6
jpayne@69 94 */
jpayne@69 95 URES_INT=7,
jpayne@69 96
jpayne@69 97 /** Resource type constant for arrays of resources. @stable ICU 2.6 */
jpayne@69 98 URES_ARRAY=8,
jpayne@69 99
jpayne@69 100 /**
jpayne@69 101 * Resource type constant for vectors of 32-bit integers.
jpayne@69 102 * @see ures_getIntVector
jpayne@69 103 * @stable ICU 2.6
jpayne@69 104 */
jpayne@69 105 URES_INT_VECTOR = 14,
jpayne@69 106 #ifndef U_HIDE_DEPRECATED_API
jpayne@69 107 /** @deprecated ICU 2.6 Use the URES_ constant instead. */
jpayne@69 108 RES_NONE=URES_NONE,
jpayne@69 109 /** @deprecated ICU 2.6 Use the URES_ constant instead. */
jpayne@69 110 RES_STRING=URES_STRING,
jpayne@69 111 /** @deprecated ICU 2.6 Use the URES_ constant instead. */
jpayne@69 112 RES_BINARY=URES_BINARY,
jpayne@69 113 /** @deprecated ICU 2.6 Use the URES_ constant instead. */
jpayne@69 114 RES_TABLE=URES_TABLE,
jpayne@69 115 /** @deprecated ICU 2.6 Use the URES_ constant instead. */
jpayne@69 116 RES_ALIAS=URES_ALIAS,
jpayne@69 117 /** @deprecated ICU 2.6 Use the URES_ constant instead. */
jpayne@69 118 RES_INT=URES_INT,
jpayne@69 119 /** @deprecated ICU 2.6 Use the URES_ constant instead. */
jpayne@69 120 RES_ARRAY=URES_ARRAY,
jpayne@69 121 /** @deprecated ICU 2.6 Use the URES_ constant instead. */
jpayne@69 122 RES_INT_VECTOR=URES_INT_VECTOR,
jpayne@69 123 /** @deprecated ICU 2.6 Not used. */
jpayne@69 124 RES_RESERVED=15,
jpayne@69 125
jpayne@69 126 /**
jpayne@69 127 * One more than the highest normal UResType value.
jpayne@69 128 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
jpayne@69 129 */
jpayne@69 130 URES_LIMIT = 16
jpayne@69 131 #endif // U_HIDE_DEPRECATED_API
jpayne@69 132 } UResType;
jpayne@69 133
jpayne@69 134 /*
jpayne@69 135 * Functions to create and destroy resource bundles.
jpayne@69 136 */
jpayne@69 137
jpayne@69 138 /**
jpayne@69 139 * Opens a UResourceBundle, from which users can extract strings by using
jpayne@69 140 * their corresponding keys.
jpayne@69 141 * Note that the caller is responsible of calling <TT>ures_close</TT> on each successfully
jpayne@69 142 * opened resource bundle.
jpayne@69 143 * @param packageName The packageName and locale together point to an ICU udata object,
jpayne@69 144 * as defined by <code> udata_open( packageName, "res", locale, err) </code>
jpayne@69 145 * or equivalent. Typically, packageName will refer to a (.dat) file, or to
jpayne@69 146 * a package registered with udata_setAppData(). Using a full file or directory
jpayne@69 147 * pathname for packageName is deprecated. If NULL, ICU data will be used.
jpayne@69 148 * @param locale specifies the locale for which we want to open the resource
jpayne@69 149 * if NULL, the default locale will be used. If strlen(locale) == 0
jpayne@69 150 * root locale will be used.
jpayne@69 151 *
jpayne@69 152 * @param status fills in the outgoing error code.
jpayne@69 153 * The UErrorCode err parameter is used to return status information to the user. To
jpayne@69 154 * check whether the construction succeeded or not, you should check the value of
jpayne@69 155 * U_SUCCESS(err). If you wish more detailed information, you can check for
jpayne@69 156 * informational status results which still indicate success. U_USING_FALLBACK_WARNING
jpayne@69 157 * indicates that a fall back locale was used. For example, 'de_CH' was requested,
jpayne@69 158 * but nothing was found there, so 'de' was used. U_USING_DEFAULT_WARNING indicates that
jpayne@69 159 * the default locale data or root locale data was used; neither the requested locale
jpayne@69 160 * nor any of its fall back locales could be found. Please see the users guide for more
jpayne@69 161 * information on this topic.
jpayne@69 162 * @return a newly allocated resource bundle.
jpayne@69 163 * @see ures_close
jpayne@69 164 * @stable ICU 2.0
jpayne@69 165 */
jpayne@69 166 U_STABLE UResourceBundle* U_EXPORT2
jpayne@69 167 ures_open(const char* packageName,
jpayne@69 168 const char* locale,
jpayne@69 169 UErrorCode* status);
jpayne@69 170
jpayne@69 171
jpayne@69 172 /** This function does not care what kind of localeID is passed in. It simply opens a bundle with
jpayne@69 173 * that name. Fallback mechanism is disabled for the new bundle. If the requested bundle contains
jpayne@69 174 * an %%ALIAS directive, the results are undefined.
jpayne@69 175 * @param packageName The packageName and locale together point to an ICU udata object,
jpayne@69 176 * as defined by <code> udata_open( packageName, "res", locale, err) </code>
jpayne@69 177 * or equivalent. Typically, packageName will refer to a (.dat) file, or to
jpayne@69 178 * a package registered with udata_setAppData(). Using a full file or directory
jpayne@69 179 * pathname for packageName is deprecated. If NULL, ICU data will be used.
jpayne@69 180 * @param locale specifies the locale for which we want to open the resource
jpayne@69 181 * if NULL, the default locale will be used. If strlen(locale) == 0
jpayne@69 182 * root locale will be used.
jpayne@69 183 *
jpayne@69 184 * @param status fills in the outgoing error code. Either U_ZERO_ERROR or U_MISSING_RESOURCE_ERROR
jpayne@69 185 * @return a newly allocated resource bundle or NULL if it doesn't exist.
jpayne@69 186 * @see ures_close
jpayne@69 187 * @stable ICU 2.0
jpayne@69 188 */
jpayne@69 189 U_STABLE UResourceBundle* U_EXPORT2
jpayne@69 190 ures_openDirect(const char* packageName,
jpayne@69 191 const char* locale,
jpayne@69 192 UErrorCode* status);
jpayne@69 193
jpayne@69 194 /**
jpayne@69 195 * Same as ures_open() but takes a const UChar *path.
jpayne@69 196 * This path will be converted to char * using the default converter,
jpayne@69 197 * then ures_open() is called.
jpayne@69 198 *
jpayne@69 199 * @param packageName The packageName and locale together point to an ICU udata object,
jpayne@69 200 * as defined by <code> udata_open( packageName, "res", locale, err) </code>
jpayne@69 201 * or equivalent. Typically, packageName will refer to a (.dat) file, or to
jpayne@69 202 * a package registered with udata_setAppData(). Using a full file or directory
jpayne@69 203 * pathname for packageName is deprecated. If NULL, ICU data will be used.
jpayne@69 204 * @param locale specifies the locale for which we want to open the resource
jpayne@69 205 * if NULL, the default locale will be used. If strlen(locale) == 0
jpayne@69 206 * root locale will be used.
jpayne@69 207 * @param status fills in the outgoing error code.
jpayne@69 208 * @return a newly allocated resource bundle.
jpayne@69 209 * @see ures_open
jpayne@69 210 * @stable ICU 2.0
jpayne@69 211 */
jpayne@69 212 U_STABLE UResourceBundle* U_EXPORT2
jpayne@69 213 ures_openU(const UChar* packageName,
jpayne@69 214 const char* locale,
jpayne@69 215 UErrorCode* status);
jpayne@69 216
jpayne@69 217 #ifndef U_HIDE_DEPRECATED_API
jpayne@69 218 /**
jpayne@69 219 * Returns the number of strings/arrays in resource bundles.
jpayne@69 220 * Better to use ures_getSize, as this function will be deprecated.
jpayne@69 221 *
jpayne@69 222 *@param resourceBundle resource bundle containing the desired strings
jpayne@69 223 *@param resourceKey key tagging the resource
jpayne@69 224 *@param err fills in the outgoing error code
jpayne@69 225 * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
jpayne@69 226 * could be a non-failing error
jpayne@69 227 * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_FALLBACK_WARNING </TT>
jpayne@69 228 *@return: for <STRONG>Arrays</STRONG>: returns the number of resources in the array
jpayne@69 229 * <STRONG>Tables</STRONG>: returns the number of resources in the table
jpayne@69 230 * <STRONG>single string</STRONG>: returns 1
jpayne@69 231 *@see ures_getSize
jpayne@69 232 * @deprecated ICU 2.8 User ures_getSize instead
jpayne@69 233 */
jpayne@69 234 U_DEPRECATED int32_t U_EXPORT2
jpayne@69 235 ures_countArrayItems(const UResourceBundle* resourceBundle,
jpayne@69 236 const char* resourceKey,
jpayne@69 237 UErrorCode* err);
jpayne@69 238 #endif /* U_HIDE_DEPRECATED_API */
jpayne@69 239
jpayne@69 240 /**
jpayne@69 241 * Close a resource bundle, all pointers returned from the various ures_getXXX calls
jpayne@69 242 * on this particular bundle should be considered invalid henceforth.
jpayne@69 243 *
jpayne@69 244 * @param resourceBundle a pointer to a resourceBundle struct. Can be NULL.
jpayne@69 245 * @see ures_open
jpayne@69 246 * @stable ICU 2.0
jpayne@69 247 */
jpayne@69 248 U_STABLE void U_EXPORT2
jpayne@69 249 ures_close(UResourceBundle* resourceBundle);
jpayne@69 250
jpayne@69 251 #if U_SHOW_CPLUSPLUS_API
jpayne@69 252
jpayne@69 253 U_NAMESPACE_BEGIN
jpayne@69 254
jpayne@69 255 /**
jpayne@69 256 * \class LocalUResourceBundlePointer
jpayne@69 257 * "Smart pointer" class, closes a UResourceBundle via ures_close().
jpayne@69 258 * For most methods see the LocalPointerBase base class.
jpayne@69 259 *
jpayne@69 260 * @see LocalPointerBase
jpayne@69 261 * @see LocalPointer
jpayne@69 262 * @stable ICU 4.4
jpayne@69 263 */
jpayne@69 264 U_DEFINE_LOCAL_OPEN_POINTER(LocalUResourceBundlePointer, UResourceBundle, ures_close);
jpayne@69 265
jpayne@69 266 U_NAMESPACE_END
jpayne@69 267
jpayne@69 268 #endif
jpayne@69 269
jpayne@69 270 #ifndef U_HIDE_DEPRECATED_API
jpayne@69 271 /**
jpayne@69 272 * Return the version number associated with this ResourceBundle as a string. Please
jpayne@69 273 * use ures_getVersion as this function is going to be deprecated.
jpayne@69 274 *
jpayne@69 275 * @param resourceBundle The resource bundle for which the version is checked.
jpayne@69 276 * @return A version number string as specified in the resource bundle or its parent.
jpayne@69 277 * The caller does not own this string.
jpayne@69 278 * @see ures_getVersion
jpayne@69 279 * @deprecated ICU 2.8 Use ures_getVersion instead.
jpayne@69 280 */
jpayne@69 281 U_DEPRECATED const char* U_EXPORT2
jpayne@69 282 ures_getVersionNumber(const UResourceBundle* resourceBundle);
jpayne@69 283 #endif /* U_HIDE_DEPRECATED_API */
jpayne@69 284
jpayne@69 285 /**
jpayne@69 286 * Return the version number associated with this ResourceBundle as an
jpayne@69 287 * UVersionInfo array.
jpayne@69 288 *
jpayne@69 289 * @param resB The resource bundle for which the version is checked.
jpayne@69 290 * @param versionInfo A UVersionInfo array that is filled with the version number
jpayne@69 291 * as specified in the resource bundle or its parent.
jpayne@69 292 * @stable ICU 2.0
jpayne@69 293 */
jpayne@69 294 U_STABLE void U_EXPORT2
jpayne@69 295 ures_getVersion(const UResourceBundle* resB,
jpayne@69 296 UVersionInfo versionInfo);
jpayne@69 297
jpayne@69 298 #ifndef U_HIDE_DEPRECATED_API
jpayne@69 299 /**
jpayne@69 300 * Return the name of the Locale associated with this ResourceBundle. This API allows
jpayne@69 301 * you to query for the real locale of the resource. For example, if you requested
jpayne@69 302 * "en_US_CALIFORNIA" and only "en_US" bundle exists, "en_US" will be returned.
jpayne@69 303 * For subresources, the locale where this resource comes from will be returned.
jpayne@69 304 * If fallback has occurred, getLocale will reflect this.
jpayne@69 305 *
jpayne@69 306 * @param resourceBundle resource bundle in question
jpayne@69 307 * @param status just for catching illegal arguments
jpayne@69 308 * @return A Locale name
jpayne@69 309 * @deprecated ICU 2.8 Use ures_getLocaleByType instead.
jpayne@69 310 */
jpayne@69 311 U_DEPRECATED const char* U_EXPORT2
jpayne@69 312 ures_getLocale(const UResourceBundle* resourceBundle,
jpayne@69 313 UErrorCode* status);
jpayne@69 314 #endif /* U_HIDE_DEPRECATED_API */
jpayne@69 315
jpayne@69 316 /**
jpayne@69 317 * Return the name of the Locale associated with this ResourceBundle.
jpayne@69 318 * You can choose between requested, valid and real locale.
jpayne@69 319 *
jpayne@69 320 * @param resourceBundle resource bundle in question
jpayne@69 321 * @param type You can choose between requested, valid and actual
jpayne@69 322 * locale. For description see the definition of
jpayne@69 323 * ULocDataLocaleType in uloc.h
jpayne@69 324 * @param status just for catching illegal arguments
jpayne@69 325 * @return A Locale name
jpayne@69 326 * @stable ICU 2.8
jpayne@69 327 */
jpayne@69 328 U_STABLE const char* U_EXPORT2
jpayne@69 329 ures_getLocaleByType(const UResourceBundle* resourceBundle,
jpayne@69 330 ULocDataLocaleType type,
jpayne@69 331 UErrorCode* status);
jpayne@69 332
jpayne@69 333
jpayne@69 334 #ifndef U_HIDE_INTERNAL_API
jpayne@69 335 /**
jpayne@69 336 * Same as ures_open() but uses the fill-in parameter instead of allocating a new bundle.
jpayne@69 337 *
jpayne@69 338 * TODO need to revisit usefulness of this function
jpayne@69 339 * and usage model for fillIn parameters without knowing sizeof(UResourceBundle)
jpayne@69 340 * @param r The existing UResourceBundle to fill in. If NULL then status will be
jpayne@69 341 * set to U_ILLEGAL_ARGUMENT_ERROR.
jpayne@69 342 * @param packageName The packageName and locale together point to an ICU udata object,
jpayne@69 343 * as defined by <code> udata_open( packageName, "res", locale, err) </code>
jpayne@69 344 * or equivalent. Typically, packageName will refer to a (.dat) file, or to
jpayne@69 345 * a package registered with udata_setAppData(). Using a full file or directory
jpayne@69 346 * pathname for packageName is deprecated. If NULL, ICU data will be used.
jpayne@69 347 * @param localeID specifies the locale for which we want to open the resource
jpayne@69 348 * @param status The error code.
jpayne@69 349 * @internal
jpayne@69 350 */
jpayne@69 351 U_INTERNAL void U_EXPORT2
jpayne@69 352 ures_openFillIn(UResourceBundle *r,
jpayne@69 353 const char* packageName,
jpayne@69 354 const char* localeID,
jpayne@69 355 UErrorCode* status);
jpayne@69 356 #endif /* U_HIDE_INTERNAL_API */
jpayne@69 357
jpayne@69 358 /**
jpayne@69 359 * Returns a string from a string resource type
jpayne@69 360 *
jpayne@69 361 * @param resourceBundle a string resource
jpayne@69 362 * @param len fills in the length of resulting string
jpayne@69 363 * @param status fills in the outgoing error code
jpayne@69 364 * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
jpayne@69 365 * Always check the value of status. Don't count on returning NULL.
jpayne@69 366 * could be a non-failing error
jpayne@69 367 * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
jpayne@69 368 * @return a pointer to a zero-terminated UChar array which lives in a memory mapped/DLL file.
jpayne@69 369 * @see ures_getBinary
jpayne@69 370 * @see ures_getIntVector
jpayne@69 371 * @see ures_getInt
jpayne@69 372 * @see ures_getUInt
jpayne@69 373 * @stable ICU 2.0
jpayne@69 374 */
jpayne@69 375 U_STABLE const UChar* U_EXPORT2
jpayne@69 376 ures_getString(const UResourceBundle* resourceBundle,
jpayne@69 377 int32_t* len,
jpayne@69 378 UErrorCode* status);
jpayne@69 379
jpayne@69 380 /**
jpayne@69 381 * Returns a UTF-8 string from a string resource.
jpayne@69 382 * The UTF-8 string may be returnable directly as a pointer, or
jpayne@69 383 * it may need to be copied, or transformed from UTF-16 using u_strToUTF8()
jpayne@69 384 * or equivalent.
jpayne@69 385 *
jpayne@69 386 * If forceCopy==TRUE, then the string is always written to the dest buffer
jpayne@69 387 * and dest is returned.
jpayne@69 388 *
jpayne@69 389 * If forceCopy==FALSE, then the string is returned as a pointer if possible,
jpayne@69 390 * without needing a dest buffer (it can be NULL). If the string needs to be
jpayne@69 391 * copied or transformed, then it may be placed into dest at an arbitrary offset.
jpayne@69 392 *
jpayne@69 393 * If the string is to be written to dest, then U_BUFFER_OVERFLOW_ERROR and
jpayne@69 394 * U_STRING_NOT_TERMINATED_WARNING are set if appropriate, as usual.
jpayne@69 395 *
jpayne@69 396 * If the string is transformed from UTF-16, then a conversion error may occur
jpayne@69 397 * if an unpaired surrogate is encountered. If the function is successful, then
jpayne@69 398 * the output UTF-8 string is always well-formed.
jpayne@69 399 *
jpayne@69 400 * @param resB Resource bundle.
jpayne@69 401 * @param dest Destination buffer. Can be NULL only if capacity=*length==0.
jpayne@69 402 * @param length Input: Capacity of destination buffer.
jpayne@69 403 * Output: Actual length of the UTF-8 string, not counting the
jpayne@69 404 * terminating NUL, even in case of U_BUFFER_OVERFLOW_ERROR.
jpayne@69 405 * Can be NULL, meaning capacity=0 and the string length is not
jpayne@69 406 * returned to the caller.
jpayne@69 407 * @param forceCopy If TRUE, then the output string will always be written to
jpayne@69 408 * dest, with U_BUFFER_OVERFLOW_ERROR and
jpayne@69 409 * U_STRING_NOT_TERMINATED_WARNING set if appropriate.
jpayne@69 410 * If FALSE, then the dest buffer may or may not contain a
jpayne@69 411 * copy of the string. dest may or may not be modified.
jpayne@69 412 * If a copy needs to be written, then the UErrorCode parameter
jpayne@69 413 * indicates overflow etc. as usual.
jpayne@69 414 * @param status Pointer to a standard ICU error code. Its input value must
jpayne@69 415 * pass the U_SUCCESS() test, or else the function returns
jpayne@69 416 * immediately. Check for U_FAILURE() on output or use with
jpayne@69 417 * function chaining. (See User Guide for details.)
jpayne@69 418 * @return The pointer to the UTF-8 string. It may be dest, or at some offset
jpayne@69 419 * from dest (only if !forceCopy), or in unrelated memory.
jpayne@69 420 * Always NUL-terminated unless the string was written to dest and
jpayne@69 421 * length==capacity (in which case U_STRING_NOT_TERMINATED_WARNING is set).
jpayne@69 422 *
jpayne@69 423 * @see ures_getString
jpayne@69 424 * @see u_strToUTF8
jpayne@69 425 * @stable ICU 3.6
jpayne@69 426 */
jpayne@69 427 U_STABLE const char * U_EXPORT2
jpayne@69 428 ures_getUTF8String(const UResourceBundle *resB,
jpayne@69 429 char *dest, int32_t *length,
jpayne@69 430 UBool forceCopy,
jpayne@69 431 UErrorCode *status);
jpayne@69 432
jpayne@69 433 /**
jpayne@69 434 * Returns a binary data from a binary resource.
jpayne@69 435 *
jpayne@69 436 * @param resourceBundle a string resource
jpayne@69 437 * @param len fills in the length of resulting byte chunk
jpayne@69 438 * @param status fills in the outgoing error code
jpayne@69 439 * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
jpayne@69 440 * Always check the value of status. Don't count on returning NULL.
jpayne@69 441 * could be a non-failing error
jpayne@69 442 * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
jpayne@69 443 * @return a pointer to a chunk of unsigned bytes which live in a memory mapped/DLL file.
jpayne@69 444 * @see ures_getString
jpayne@69 445 * @see ures_getIntVector
jpayne@69 446 * @see ures_getInt
jpayne@69 447 * @see ures_getUInt
jpayne@69 448 * @stable ICU 2.0
jpayne@69 449 */
jpayne@69 450 U_STABLE const uint8_t* U_EXPORT2
jpayne@69 451 ures_getBinary(const UResourceBundle* resourceBundle,
jpayne@69 452 int32_t* len,
jpayne@69 453 UErrorCode* status);
jpayne@69 454
jpayne@69 455 /**
jpayne@69 456 * Returns a 32 bit integer array from a resource.
jpayne@69 457 *
jpayne@69 458 * @param resourceBundle an int vector resource
jpayne@69 459 * @param len fills in the length of resulting byte chunk
jpayne@69 460 * @param status fills in the outgoing error code
jpayne@69 461 * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
jpayne@69 462 * Always check the value of status. Don't count on returning NULL.
jpayne@69 463 * could be a non-failing error
jpayne@69 464 * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
jpayne@69 465 * @return a pointer to a chunk of integers which live in a memory mapped/DLL file.
jpayne@69 466 * @see ures_getBinary
jpayne@69 467 * @see ures_getString
jpayne@69 468 * @see ures_getInt
jpayne@69 469 * @see ures_getUInt
jpayne@69 470 * @stable ICU 2.0
jpayne@69 471 */
jpayne@69 472 U_STABLE const int32_t* U_EXPORT2
jpayne@69 473 ures_getIntVector(const UResourceBundle* resourceBundle,
jpayne@69 474 int32_t* len,
jpayne@69 475 UErrorCode* status);
jpayne@69 476
jpayne@69 477 /**
jpayne@69 478 * Returns an unsigned integer from a resource.
jpayne@69 479 * This integer is originally 28 bits.
jpayne@69 480 *
jpayne@69 481 * @param resourceBundle a string resource
jpayne@69 482 * @param status fills in the outgoing error code
jpayne@69 483 * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
jpayne@69 484 * could be a non-failing error
jpayne@69 485 * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
jpayne@69 486 * @return an integer value
jpayne@69 487 * @see ures_getInt
jpayne@69 488 * @see ures_getIntVector
jpayne@69 489 * @see ures_getBinary
jpayne@69 490 * @see ures_getString
jpayne@69 491 * @stable ICU 2.0
jpayne@69 492 */
jpayne@69 493 U_STABLE uint32_t U_EXPORT2
jpayne@69 494 ures_getUInt(const UResourceBundle* resourceBundle,
jpayne@69 495 UErrorCode *status);
jpayne@69 496
jpayne@69 497 /**
jpayne@69 498 * Returns a signed integer from a resource.
jpayne@69 499 * This integer is originally 28 bit and the sign gets propagated.
jpayne@69 500 *
jpayne@69 501 * @param resourceBundle a string resource
jpayne@69 502 * @param status fills in the outgoing error code
jpayne@69 503 * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
jpayne@69 504 * could be a non-failing error
jpayne@69 505 * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
jpayne@69 506 * @return an integer value
jpayne@69 507 * @see ures_getUInt
jpayne@69 508 * @see ures_getIntVector
jpayne@69 509 * @see ures_getBinary
jpayne@69 510 * @see ures_getString
jpayne@69 511 * @stable ICU 2.0
jpayne@69 512 */
jpayne@69 513 U_STABLE int32_t U_EXPORT2
jpayne@69 514 ures_getInt(const UResourceBundle* resourceBundle,
jpayne@69 515 UErrorCode *status);
jpayne@69 516
jpayne@69 517 /**
jpayne@69 518 * Returns the size of a resource. Size for scalar types is always 1,
jpayne@69 519 * and for vector/table types is the number of child resources.
jpayne@69 520 * @warning Integer array is treated as a scalar type. There are no
jpayne@69 521 * APIs to access individual members of an integer array. It
jpayne@69 522 * is always returned as a whole.
jpayne@69 523 * @param resourceBundle a resource
jpayne@69 524 * @return number of resources in a given resource.
jpayne@69 525 * @stable ICU 2.0
jpayne@69 526 */
jpayne@69 527 U_STABLE int32_t U_EXPORT2
jpayne@69 528 ures_getSize(const UResourceBundle *resourceBundle);
jpayne@69 529
jpayne@69 530 /**
jpayne@69 531 * Returns the type of a resource. Available types are defined in enum UResType
jpayne@69 532 *
jpayne@69 533 * @param resourceBundle a resource
jpayne@69 534 * @return type of the given resource.
jpayne@69 535 * @see UResType
jpayne@69 536 * @stable ICU 2.0
jpayne@69 537 */
jpayne@69 538 U_STABLE UResType U_EXPORT2
jpayne@69 539 ures_getType(const UResourceBundle *resourceBundle);
jpayne@69 540
jpayne@69 541 /**
jpayne@69 542 * Returns the key associated with a given resource. Not all the resources have a key - only
jpayne@69 543 * those that are members of a table.
jpayne@69 544 *
jpayne@69 545 * @param resourceBundle a resource
jpayne@69 546 * @return a key associated to this resource, or NULL if it doesn't have a key
jpayne@69 547 * @stable ICU 2.0
jpayne@69 548 */
jpayne@69 549 U_STABLE const char * U_EXPORT2
jpayne@69 550 ures_getKey(const UResourceBundle *resourceBundle);
jpayne@69 551
jpayne@69 552 /* ITERATION API
jpayne@69 553 This API provides means for iterating through a resource
jpayne@69 554 */
jpayne@69 555
jpayne@69 556 /**
jpayne@69 557 * Resets the internal context of a resource so that iteration starts from the first element.
jpayne@69 558 *
jpayne@69 559 * @param resourceBundle a resource
jpayne@69 560 * @stable ICU 2.0
jpayne@69 561 */
jpayne@69 562 U_STABLE void U_EXPORT2
jpayne@69 563 ures_resetIterator(UResourceBundle *resourceBundle);
jpayne@69 564
jpayne@69 565 /**
jpayne@69 566 * Checks whether the given resource has another element to iterate over.
jpayne@69 567 *
jpayne@69 568 * @param resourceBundle a resource
jpayne@69 569 * @return TRUE if there are more elements, FALSE if there is no more elements
jpayne@69 570 * @stable ICU 2.0
jpayne@69 571 */
jpayne@69 572 U_STABLE UBool U_EXPORT2
jpayne@69 573 ures_hasNext(const UResourceBundle *resourceBundle);
jpayne@69 574
jpayne@69 575 /**
jpayne@69 576 * Returns the next resource in a given resource or NULL if there are no more resources
jpayne@69 577 * to iterate over. Features a fill-in parameter.
jpayne@69 578 *
jpayne@69 579 * @param resourceBundle a resource
jpayne@69 580 * @param fillIn if NULL a new UResourceBundle struct is allocated and must be closed by the caller.
jpayne@69 581 * Alternatively, you can supply a struct to be filled by this function.
jpayne@69 582 * @param status fills in the outgoing error code. You may still get a non NULL result even if an
jpayne@69 583 * error occurred. Check status instead.
jpayne@69 584 * @return a pointer to a UResourceBundle struct. If fill in param was NULL, caller must close it
jpayne@69 585 * @stable ICU 2.0
jpayne@69 586 */
jpayne@69 587 U_STABLE UResourceBundle* U_EXPORT2
jpayne@69 588 ures_getNextResource(UResourceBundle *resourceBundle,
jpayne@69 589 UResourceBundle *fillIn,
jpayne@69 590 UErrorCode *status);
jpayne@69 591
jpayne@69 592 /**
jpayne@69 593 * Returns the next string in a given resource or NULL if there are no more resources
jpayne@69 594 * to iterate over.
jpayne@69 595 *
jpayne@69 596 * @param resourceBundle a resource
jpayne@69 597 * @param len fill in length of the string
jpayne@69 598 * @param key fill in for key associated with this string. NULL if no key
jpayne@69 599 * @param status fills in the outgoing error code. If an error occurred, we may return NULL, but don't
jpayne@69 600 * count on it. Check status instead!
jpayne@69 601 * @return a pointer to a zero-terminated UChar array which lives in a memory mapped/DLL file.
jpayne@69 602 * @stable ICU 2.0
jpayne@69 603 */
jpayne@69 604 U_STABLE const UChar* U_EXPORT2
jpayne@69 605 ures_getNextString(UResourceBundle *resourceBundle,
jpayne@69 606 int32_t* len,
jpayne@69 607 const char ** key,
jpayne@69 608 UErrorCode *status);
jpayne@69 609
jpayne@69 610 /**
jpayne@69 611 * Returns the resource in a given resource at the specified index. Features a fill-in parameter.
jpayne@69 612 *
jpayne@69 613 * @param resourceBundle the resource bundle from which to get a sub-resource
jpayne@69 614 * @param indexR an index to the wanted resource.
jpayne@69 615 * @param fillIn if NULL a new UResourceBundle struct is allocated and must be closed by the caller.
jpayne@69 616 * Alternatively, you can supply a struct to be filled by this function.
jpayne@69 617 * @param status fills in the outgoing error code. Don't count on NULL being returned if an error has
jpayne@69 618 * occurred. Check status instead.
jpayne@69 619 * @return a pointer to a UResourceBundle struct. If fill in param was NULL, caller must close it
jpayne@69 620 * @stable ICU 2.0
jpayne@69 621 */
jpayne@69 622 U_STABLE UResourceBundle* U_EXPORT2
jpayne@69 623 ures_getByIndex(const UResourceBundle *resourceBundle,
jpayne@69 624 int32_t indexR,
jpayne@69 625 UResourceBundle *fillIn,
jpayne@69 626 UErrorCode *status);
jpayne@69 627
jpayne@69 628 /**
jpayne@69 629 * Returns the string in a given resource at the specified index.
jpayne@69 630 *
jpayne@69 631 * @param resourceBundle a resource
jpayne@69 632 * @param indexS an index to the wanted string.
jpayne@69 633 * @param len fill in length of the string
jpayne@69 634 * @param status fills in the outgoing error code. If an error occurred, we may return NULL, but don't
jpayne@69 635 * count on it. Check status instead!
jpayne@69 636 * @return a pointer to a zero-terminated UChar array which lives in a memory mapped/DLL file.
jpayne@69 637 * @stable ICU 2.0
jpayne@69 638 */
jpayne@69 639 U_STABLE const UChar* U_EXPORT2
jpayne@69 640 ures_getStringByIndex(const UResourceBundle *resourceBundle,
jpayne@69 641 int32_t indexS,
jpayne@69 642 int32_t* len,
jpayne@69 643 UErrorCode *status);
jpayne@69 644
jpayne@69 645 /**
jpayne@69 646 * Returns a UTF-8 string from a resource at the specified index.
jpayne@69 647 * The UTF-8 string may be returnable directly as a pointer, or
jpayne@69 648 * it may need to be copied, or transformed from UTF-16 using u_strToUTF8()
jpayne@69 649 * or equivalent.
jpayne@69 650 *
jpayne@69 651 * If forceCopy==TRUE, then the string is always written to the dest buffer
jpayne@69 652 * and dest is returned.
jpayne@69 653 *
jpayne@69 654 * If forceCopy==FALSE, then the string is returned as a pointer if possible,
jpayne@69 655 * without needing a dest buffer (it can be NULL). If the string needs to be
jpayne@69 656 * copied or transformed, then it may be placed into dest at an arbitrary offset.
jpayne@69 657 *
jpayne@69 658 * If the string is to be written to dest, then U_BUFFER_OVERFLOW_ERROR and
jpayne@69 659 * U_STRING_NOT_TERMINATED_WARNING are set if appropriate, as usual.
jpayne@69 660 *
jpayne@69 661 * If the string is transformed from UTF-16, then a conversion error may occur
jpayne@69 662 * if an unpaired surrogate is encountered. If the function is successful, then
jpayne@69 663 * the output UTF-8 string is always well-formed.
jpayne@69 664 *
jpayne@69 665 * @param resB Resource bundle.
jpayne@69 666 * @param stringIndex An index to the wanted string.
jpayne@69 667 * @param dest Destination buffer. Can be NULL only if capacity=*length==0.
jpayne@69 668 * @param pLength Input: Capacity of destination buffer.
jpayne@69 669 * Output: Actual length of the UTF-8 string, not counting the
jpayne@69 670 * terminating NUL, even in case of U_BUFFER_OVERFLOW_ERROR.
jpayne@69 671 * Can be NULL, meaning capacity=0 and the string length is not
jpayne@69 672 * returned to the caller.
jpayne@69 673 * @param forceCopy If TRUE, then the output string will always be written to
jpayne@69 674 * dest, with U_BUFFER_OVERFLOW_ERROR and
jpayne@69 675 * U_STRING_NOT_TERMINATED_WARNING set if appropriate.
jpayne@69 676 * If FALSE, then the dest buffer may or may not contain a
jpayne@69 677 * copy of the string. dest may or may not be modified.
jpayne@69 678 * If a copy needs to be written, then the UErrorCode parameter
jpayne@69 679 * indicates overflow etc. as usual.
jpayne@69 680 * @param status Pointer to a standard ICU error code. Its input value must
jpayne@69 681 * pass the U_SUCCESS() test, or else the function returns
jpayne@69 682 * immediately. Check for U_FAILURE() on output or use with
jpayne@69 683 * function chaining. (See User Guide for details.)
jpayne@69 684 * @return The pointer to the UTF-8 string. It may be dest, or at some offset
jpayne@69 685 * from dest (only if !forceCopy), or in unrelated memory.
jpayne@69 686 * Always NUL-terminated unless the string was written to dest and
jpayne@69 687 * length==capacity (in which case U_STRING_NOT_TERMINATED_WARNING is set).
jpayne@69 688 *
jpayne@69 689 * @see ures_getStringByIndex
jpayne@69 690 * @see u_strToUTF8
jpayne@69 691 * @stable ICU 3.6
jpayne@69 692 */
jpayne@69 693 U_STABLE const char * U_EXPORT2
jpayne@69 694 ures_getUTF8StringByIndex(const UResourceBundle *resB,
jpayne@69 695 int32_t stringIndex,
jpayne@69 696 char *dest, int32_t *pLength,
jpayne@69 697 UBool forceCopy,
jpayne@69 698 UErrorCode *status);
jpayne@69 699
jpayne@69 700 /**
jpayne@69 701 * Returns a resource in a given resource that has a given key. This procedure works only with table
jpayne@69 702 * resources. Features a fill-in parameter.
jpayne@69 703 *
jpayne@69 704 * @param resourceBundle a resource
jpayne@69 705 * @param key a key associated with the wanted resource
jpayne@69 706 * @param fillIn if NULL a new UResourceBundle struct is allocated and must be closed by the caller.
jpayne@69 707 * Alternatively, you can supply a struct to be filled by this function.
jpayne@69 708 * @param status fills in the outgoing error code.
jpayne@69 709 * @return a pointer to a UResourceBundle struct. If fill in param was NULL, caller must close it
jpayne@69 710 * @stable ICU 2.0
jpayne@69 711 */
jpayne@69 712 U_STABLE UResourceBundle* U_EXPORT2
jpayne@69 713 ures_getByKey(const UResourceBundle *resourceBundle,
jpayne@69 714 const char* key,
jpayne@69 715 UResourceBundle *fillIn,
jpayne@69 716 UErrorCode *status);
jpayne@69 717
jpayne@69 718 /**
jpayne@69 719 * Returns a string in a given resource that has a given key. This procedure works only with table
jpayne@69 720 * resources.
jpayne@69 721 *
jpayne@69 722 * @param resB a resource
jpayne@69 723 * @param key a key associated with the wanted string
jpayne@69 724 * @param len fill in length of the string
jpayne@69 725 * @param status fills in the outgoing error code. If an error occurred, we may return NULL, but don't
jpayne@69 726 * count on it. Check status instead!
jpayne@69 727 * @return a pointer to a zero-terminated UChar array which lives in a memory mapped/DLL file.
jpayne@69 728 * @stable ICU 2.0
jpayne@69 729 */
jpayne@69 730 U_STABLE const UChar* U_EXPORT2
jpayne@69 731 ures_getStringByKey(const UResourceBundle *resB,
jpayne@69 732 const char* key,
jpayne@69 733 int32_t* len,
jpayne@69 734 UErrorCode *status);
jpayne@69 735
jpayne@69 736 /**
jpayne@69 737 * Returns a UTF-8 string from a resource and a key.
jpayne@69 738 * This function works only with table resources.
jpayne@69 739 *
jpayne@69 740 * The UTF-8 string may be returnable directly as a pointer, or
jpayne@69 741 * it may need to be copied, or transformed from UTF-16 using u_strToUTF8()
jpayne@69 742 * or equivalent.
jpayne@69 743 *
jpayne@69 744 * If forceCopy==TRUE, then the string is always written to the dest buffer
jpayne@69 745 * and dest is returned.
jpayne@69 746 *
jpayne@69 747 * If forceCopy==FALSE, then the string is returned as a pointer if possible,
jpayne@69 748 * without needing a dest buffer (it can be NULL). If the string needs to be
jpayne@69 749 * copied or transformed, then it may be placed into dest at an arbitrary offset.
jpayne@69 750 *
jpayne@69 751 * If the string is to be written to dest, then U_BUFFER_OVERFLOW_ERROR and
jpayne@69 752 * U_STRING_NOT_TERMINATED_WARNING are set if appropriate, as usual.
jpayne@69 753 *
jpayne@69 754 * If the string is transformed from UTF-16, then a conversion error may occur
jpayne@69 755 * if an unpaired surrogate is encountered. If the function is successful, then
jpayne@69 756 * the output UTF-8 string is always well-formed.
jpayne@69 757 *
jpayne@69 758 * @param resB Resource bundle.
jpayne@69 759 * @param key A key associated with the wanted resource
jpayne@69 760 * @param dest Destination buffer. Can be NULL only if capacity=*length==0.
jpayne@69 761 * @param pLength Input: Capacity of destination buffer.
jpayne@69 762 * Output: Actual length of the UTF-8 string, not counting the
jpayne@69 763 * terminating NUL, even in case of U_BUFFER_OVERFLOW_ERROR.
jpayne@69 764 * Can be NULL, meaning capacity=0 and the string length is not
jpayne@69 765 * returned to the caller.
jpayne@69 766 * @param forceCopy If TRUE, then the output string will always be written to
jpayne@69 767 * dest, with U_BUFFER_OVERFLOW_ERROR and
jpayne@69 768 * U_STRING_NOT_TERMINATED_WARNING set if appropriate.
jpayne@69 769 * If FALSE, then the dest buffer may or may not contain a
jpayne@69 770 * copy of the string. dest may or may not be modified.
jpayne@69 771 * If a copy needs to be written, then the UErrorCode parameter
jpayne@69 772 * indicates overflow etc. as usual.
jpayne@69 773 * @param status Pointer to a standard ICU error code. Its input value must
jpayne@69 774 * pass the U_SUCCESS() test, or else the function returns
jpayne@69 775 * immediately. Check for U_FAILURE() on output or use with
jpayne@69 776 * function chaining. (See User Guide for details.)
jpayne@69 777 * @return The pointer to the UTF-8 string. It may be dest, or at some offset
jpayne@69 778 * from dest (only if !forceCopy), or in unrelated memory.
jpayne@69 779 * Always NUL-terminated unless the string was written to dest and
jpayne@69 780 * length==capacity (in which case U_STRING_NOT_TERMINATED_WARNING is set).
jpayne@69 781 *
jpayne@69 782 * @see ures_getStringByKey
jpayne@69 783 * @see u_strToUTF8
jpayne@69 784 * @stable ICU 3.6
jpayne@69 785 */
jpayne@69 786 U_STABLE const char * U_EXPORT2
jpayne@69 787 ures_getUTF8StringByKey(const UResourceBundle *resB,
jpayne@69 788 const char *key,
jpayne@69 789 char *dest, int32_t *pLength,
jpayne@69 790 UBool forceCopy,
jpayne@69 791 UErrorCode *status);
jpayne@69 792
jpayne@69 793 #if U_SHOW_CPLUSPLUS_API
jpayne@69 794 #include "unicode/unistr.h"
jpayne@69 795
jpayne@69 796 U_NAMESPACE_BEGIN
jpayne@69 797 /**
jpayne@69 798 * Returns the string value from a string resource bundle.
jpayne@69 799 *
jpayne@69 800 * @param resB a resource, should have type URES_STRING
jpayne@69 801 * @param status: fills in the outgoing error code
jpayne@69 802 * could be <TT>U_MISSING_RESOURCE_ERROR</TT> if the key is not found
jpayne@69 803 * could be a non-failing error
jpayne@69 804 * e.g.: <TT>U_USING_FALLBACK_WARNING</TT>,<TT>U_USING_DEFAULT_WARNING </TT>
jpayne@69 805 * @return The string value, or a bogus string if there is a failure UErrorCode.
jpayne@69 806 * @stable ICU 2.0
jpayne@69 807 */
jpayne@69 808 inline UnicodeString
jpayne@69 809 ures_getUnicodeString(const UResourceBundle *resB, UErrorCode* status) {
jpayne@69 810 UnicodeString result;
jpayne@69 811 int32_t len = 0;
jpayne@69 812 const UChar *r = ures_getString(resB, &len, status);
jpayne@69 813 if(U_SUCCESS(*status)) {
jpayne@69 814 result.setTo(TRUE, r, len);
jpayne@69 815 } else {
jpayne@69 816 result.setToBogus();
jpayne@69 817 }
jpayne@69 818 return result;
jpayne@69 819 }
jpayne@69 820
jpayne@69 821 /**
jpayne@69 822 * Returns the next string in a resource, or an empty string if there are no more resources
jpayne@69 823 * to iterate over.
jpayne@69 824 * Use ures_getNextString() instead to distinguish between
jpayne@69 825 * the end of the iteration and a real empty string value.
jpayne@69 826 *
jpayne@69 827 * @param resB a resource
jpayne@69 828 * @param key fill in for key associated with this string
jpayne@69 829 * @param status fills in the outgoing error code
jpayne@69 830 * @return The string value, or a bogus string if there is a failure UErrorCode.
jpayne@69 831 * @stable ICU 2.0
jpayne@69 832 */
jpayne@69 833 inline UnicodeString
jpayne@69 834 ures_getNextUnicodeString(UResourceBundle *resB, const char ** key, UErrorCode* status) {
jpayne@69 835 UnicodeString result;
jpayne@69 836 int32_t len = 0;
jpayne@69 837 const UChar* r = ures_getNextString(resB, &len, key, status);
jpayne@69 838 if(U_SUCCESS(*status)) {
jpayne@69 839 result.setTo(TRUE, r, len);
jpayne@69 840 } else {
jpayne@69 841 result.setToBogus();
jpayne@69 842 }
jpayne@69 843 return result;
jpayne@69 844 }
jpayne@69 845
jpayne@69 846 /**
jpayne@69 847 * Returns the string in a given resource array or table at the specified index.
jpayne@69 848 *
jpayne@69 849 * @param resB a resource
jpayne@69 850 * @param indexS an index to the wanted string.
jpayne@69 851 * @param status fills in the outgoing error code
jpayne@69 852 * @return The string value, or a bogus string if there is a failure UErrorCode.
jpayne@69 853 * @stable ICU 2.0
jpayne@69 854 */
jpayne@69 855 inline UnicodeString
jpayne@69 856 ures_getUnicodeStringByIndex(const UResourceBundle *resB, int32_t indexS, UErrorCode* status) {
jpayne@69 857 UnicodeString result;
jpayne@69 858 int32_t len = 0;
jpayne@69 859 const UChar* r = ures_getStringByIndex(resB, indexS, &len, status);
jpayne@69 860 if(U_SUCCESS(*status)) {
jpayne@69 861 result.setTo(TRUE, r, len);
jpayne@69 862 } else {
jpayne@69 863 result.setToBogus();
jpayne@69 864 }
jpayne@69 865 return result;
jpayne@69 866 }
jpayne@69 867
jpayne@69 868 /**
jpayne@69 869 * Returns a string in a resource that has a given key.
jpayne@69 870 * This procedure works only with table resources.
jpayne@69 871 *
jpayne@69 872 * @param resB a resource
jpayne@69 873 * @param key a key associated with the wanted string
jpayne@69 874 * @param status fills in the outgoing error code
jpayne@69 875 * @return The string value, or a bogus string if there is a failure UErrorCode.
jpayne@69 876 * @stable ICU 2.0
jpayne@69 877 */
jpayne@69 878 inline UnicodeString
jpayne@69 879 ures_getUnicodeStringByKey(const UResourceBundle *resB, const char* key, UErrorCode* status) {
jpayne@69 880 UnicodeString result;
jpayne@69 881 int32_t len = 0;
jpayne@69 882 const UChar* r = ures_getStringByKey(resB, key, &len, status);
jpayne@69 883 if(U_SUCCESS(*status)) {
jpayne@69 884 result.setTo(TRUE, r, len);
jpayne@69 885 } else {
jpayne@69 886 result.setToBogus();
jpayne@69 887 }
jpayne@69 888 return result;
jpayne@69 889 }
jpayne@69 890
jpayne@69 891 U_NAMESPACE_END
jpayne@69 892
jpayne@69 893 #endif
jpayne@69 894
jpayne@69 895 /**
jpayne@69 896 * Create a string enumerator, owned by the caller, of all locales located within
jpayne@69 897 * the specified resource tree.
jpayne@69 898 * @param packageName name of the tree, such as (NULL) or U_ICUDATA_ALIAS or or "ICUDATA-coll"
jpayne@69 899 * This call is similar to uloc_getAvailable().
jpayne@69 900 * @param status error code
jpayne@69 901 * @stable ICU 3.2
jpayne@69 902 */
jpayne@69 903 U_STABLE UEnumeration* U_EXPORT2
jpayne@69 904 ures_openAvailableLocales(const char *packageName, UErrorCode *status);
jpayne@69 905
jpayne@69 906
jpayne@69 907 #endif /*_URES*/
jpayne@69 908 /*eof*/