ICU 70.1  70.1
ures.h
Go to the documentation of this file.
1 // © 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
3 /*
4 **********************************************************************
5 * Copyright (C) 1997-2016, International Business Machines
6 * Corporation and others. All Rights Reserved.
7 **********************************************************************
8 *
9 * File URES.H (formerly CRESBUND.H)
10 *
11 * Modification History:
12 *
13 * Date Name Description
14 * 04/01/97 aliu Creation.
15 * 02/22/99 damiba overhaul.
16 * 04/04/99 helena Fixed internal header inclusion.
17 * 04/15/99 Madhu Updated Javadoc
18 * 06/14/99 stephen Removed functions taking a filename suffix.
19 * 07/20/99 stephen Language-independent typedef to void*
20 * 11/09/99 weiv Added ures_getLocale()
21 * 06/24/02 weiv Added support for resource sharing
22 ******************************************************************************
23 */
24 
25 #ifndef URES_H
26 #define URES_H
27 
28 #include "unicode/utypes.h"
29 #include "unicode/uloc.h"
30 
31 #if U_SHOW_CPLUSPLUS_API
32 #include "unicode/localpointer.h"
33 #endif // U_SHOW_CPLUSPLUS_API
34 
57 struct UResourceBundle;
58 
62 typedef struct UResourceBundle UResourceBundle;
63 
69 typedef enum {
72 
75 
78 
81 
90 
99 
102 
109 #ifndef U_HIDE_DEPRECATED_API
128 
133  URES_LIMIT = 16
134 #endif // U_HIDE_DEPRECATED_API
136 
137 /*
138  * Functions to create and destroy resource bundles.
139  */
140 
169 U_CAPI UResourceBundle* U_EXPORT2
170 ures_open(const char* packageName,
171  const char* locale,
172  UErrorCode* status);
173 
174 
192 U_CAPI UResourceBundle* U_EXPORT2
193 ures_openDirect(const char* packageName,
194  const char* locale,
195  UErrorCode* status);
196 
215 U_CAPI UResourceBundle* U_EXPORT2
216 ures_openU(const UChar* packageName,
217  const char* locale,
218  UErrorCode* status);
219 
220 #ifndef U_HIDE_DEPRECATED_API
237 U_DEPRECATED int32_t U_EXPORT2
238 ures_countArrayItems(const UResourceBundle* resourceBundle,
239  const char* resourceKey,
240  UErrorCode* err);
241 #endif /* U_HIDE_DEPRECATED_API */
242 
251 U_CAPI void U_EXPORT2
252 ures_close(UResourceBundle* resourceBundle);
253 
254 #if U_SHOW_CPLUSPLUS_API
255 
256 U_NAMESPACE_BEGIN
257 
268 
269 U_NAMESPACE_END
270 
271 #endif
272 
273 #ifndef U_HIDE_DEPRECATED_API
284 U_DEPRECATED const char* U_EXPORT2
285 ures_getVersionNumber(const UResourceBundle* resourceBundle);
286 #endif /* U_HIDE_DEPRECATED_API */
287 
297 U_CAPI void U_EXPORT2
299  UVersionInfo versionInfo);
300 
301 #ifndef U_HIDE_DEPRECATED_API
314 U_DEPRECATED const char* U_EXPORT2
315 ures_getLocale(const UResourceBundle* resourceBundle,
316  UErrorCode* status);
317 #endif /* U_HIDE_DEPRECATED_API */
318 
331 U_CAPI const char* U_EXPORT2
332 ures_getLocaleByType(const UResourceBundle* resourceBundle,
333  ULocDataLocaleType type,
334  UErrorCode* status);
335 
336 
337 #ifndef U_HIDE_INTERNAL_API
354 U_CAPI void U_EXPORT2
356  const char* packageName,
357  const char* localeID,
358  UErrorCode* status);
359 #endif /* U_HIDE_INTERNAL_API */
360 
378 U_CAPI const UChar* U_EXPORT2
379 ures_getString(const UResourceBundle* resourceBundle,
380  int32_t* len,
381  UErrorCode* status);
382 
430 U_CAPI const char * U_EXPORT2
432  char *dest, int32_t *length,
433  UBool forceCopy,
434  UErrorCode *status);
435 
453 U_CAPI const uint8_t* U_EXPORT2
454 ures_getBinary(const UResourceBundle* resourceBundle,
455  int32_t* len,
456  UErrorCode* status);
457 
475 U_CAPI const int32_t* U_EXPORT2
476 ures_getIntVector(const UResourceBundle* resourceBundle,
477  int32_t* len,
478  UErrorCode* status);
479 
496 U_CAPI uint32_t U_EXPORT2
497 ures_getUInt(const UResourceBundle* resourceBundle,
498  UErrorCode *status);
499 
516 U_CAPI int32_t U_EXPORT2
517 ures_getInt(const UResourceBundle* resourceBundle,
518  UErrorCode *status);
519 
530 U_CAPI int32_t U_EXPORT2
531 ures_getSize(const UResourceBundle *resourceBundle);
532 
541 U_CAPI UResType U_EXPORT2
542 ures_getType(const UResourceBundle *resourceBundle);
543 
552 U_CAPI const char * U_EXPORT2
553 ures_getKey(const UResourceBundle *resourceBundle);
554 
555 /* ITERATION API
556  This API provides means for iterating through a resource
557 */
558 
565 U_CAPI void U_EXPORT2
567 
575 U_CAPI UBool U_EXPORT2
576 ures_hasNext(const UResourceBundle *resourceBundle);
577 
590 U_CAPI UResourceBundle* U_EXPORT2
592  UResourceBundle *fillIn,
593  UErrorCode *status);
594 
607 U_CAPI const UChar* U_EXPORT2
609  int32_t* len,
610  const char ** key,
611  UErrorCode *status);
612 
625 U_CAPI UResourceBundle* U_EXPORT2
626 ures_getByIndex(const UResourceBundle *resourceBundle,
627  int32_t indexR,
628  UResourceBundle *fillIn,
629  UErrorCode *status);
630 
642 U_CAPI const UChar* U_EXPORT2
644  int32_t indexS,
645  int32_t* len,
646  UErrorCode *status);
647 
696 U_CAPI const char * U_EXPORT2
698  int32_t stringIndex,
699  char *dest, int32_t *pLength,
700  UBool forceCopy,
701  UErrorCode *status);
702 
715 U_CAPI UResourceBundle* U_EXPORT2
716 ures_getByKey(const UResourceBundle *resourceBundle,
717  const char* key,
718  UResourceBundle *fillIn,
719  UErrorCode *status);
720 
733 U_CAPI const UChar* U_EXPORT2
735  const char* key,
736  int32_t* len,
737  UErrorCode *status);
738 
789 U_CAPI const char * U_EXPORT2
791  const char *key,
792  char *dest, int32_t *pLength,
793  UBool forceCopy,
794  UErrorCode *status);
795 
796 #if U_SHOW_CPLUSPLUS_API
797 #include "unicode/unistr.h"
798 
799 U_NAMESPACE_BEGIN
811 inline UnicodeString
813  UnicodeString result;
814  int32_t len = 0;
815  const UChar *r = ures_getString(resB, &len, status);
816  if(U_SUCCESS(*status)) {
817  result.setTo(true, r, len);
818  } else {
819  result.setToBogus();
820  }
821  return result;
822 }
823 
836 inline UnicodeString
837 ures_getNextUnicodeString(UResourceBundle *resB, const char ** key, UErrorCode* status) {
838  UnicodeString result;
839  int32_t len = 0;
840  const UChar* r = ures_getNextString(resB, &len, key, status);
841  if(U_SUCCESS(*status)) {
842  result.setTo(true, r, len);
843  } else {
844  result.setToBogus();
845  }
846  return result;
847 }
848 
858 inline UnicodeString
859 ures_getUnicodeStringByIndex(const UResourceBundle *resB, int32_t indexS, UErrorCode* status) {
860  UnicodeString result;
861  int32_t len = 0;
862  const UChar* r = ures_getStringByIndex(resB, indexS, &len, status);
863  if(U_SUCCESS(*status)) {
864  result.setTo(true, r, len);
865  } else {
866  result.setToBogus();
867  }
868  return result;
869 }
870 
881 inline UnicodeString
882 ures_getUnicodeStringByKey(const UResourceBundle *resB, const char* key, UErrorCode* status) {
883  UnicodeString result;
884  int32_t len = 0;
885  const UChar* r = ures_getStringByKey(resB, key, &len, status);
886  if(U_SUCCESS(*status)) {
887  result.setTo(true, r, len);
888  } else {
889  result.setToBogus();
890  }
891  return result;
892 }
893 
894 U_NAMESPACE_END
895 
896 #endif
897 
906 U_CAPI UEnumeration* U_EXPORT2
907 ures_openAvailableLocales(const char *packageName, UErrorCode *status);
908 
909 
910 #endif /*_URES*/
911 /*eof*/
"Smart pointer" class, closes a UResourceBundle via ures_close().
UnicodeString is a string class that stores Unicode characters directly and provides similar function...
Definition: unistr.h:296
void setToBogus()
Make this UnicodeString object invalid.
UnicodeString & setTo(const UnicodeString &srcText, int32_t srcStart)
Set the text in the UnicodeString object to the characters in srcText in the range [srcStart,...
Definition: unistr.h:4585
C++ API: "Smart pointers" for use with and in ICU4C C++ code.
#define U_DEFINE_LOCAL_OPEN_POINTER(LocalPointerClassName, Type, closeFunction)
"Smart pointer" definition macro, deletes objects via the closeFunction.
Definition: localpointer.h:550
UnicodeString ures_getUnicodeString(const UResourceBundle *resB, UErrorCode *status)
Returns the string value from a string resource bundle.
Definition: ures.h:812
UnicodeString ures_getUnicodeStringByIndex(const UResourceBundle *resB, int32_t indexS, UErrorCode *status)
Returns the string in a given resource array or table at the specified index.
Definition: ures.h:859
UnicodeString ures_getNextUnicodeString(UResourceBundle *resB, const char **key, UErrorCode *status)
Returns the next string in a resource, or an empty string if there are no more resources to iterate o...
Definition: ures.h:837
UnicodeString ures_getUnicodeStringByKey(const UResourceBundle *resB, const char *key, UErrorCode *status)
Returns a string in a resource that has a given key.
Definition: ures.h:882
struct UEnumeration UEnumeration
structure representing an enumeration object instance
Definition: uenum.h:44
C API: Locale.
ULocDataLocaleType
Constants for *_getLocale() Allow user to select whether she wants information on requested,...
Definition: uloc.h:338
#define U_DEPRECATED
This is used to declare a function as a deprecated public ICU C API
Definition: umachine.h:116
int8_t UBool
The ICU boolean type, a signed-byte integer.
Definition: umachine.h:269
#define U_CAPI
This is used to declare a function as a public ICU C API.
Definition: umachine.h:110
char16_t UChar
The base type for UTF-16 code units and pointers.
Definition: umachine.h:418
C++ API: Unicode String.
int32_t ures_countArrayItems(const UResourceBundle *resourceBundle, const char *resourceKey, UErrorCode *err)
Returns the number of strings/arrays in resource bundles.
U_CAPI int32_t ures_getInt(const UResourceBundle *resourceBundle, UErrorCode *status)
Returns a signed integer from a resource.
U_CAPI int32_t ures_getSize(const UResourceBundle *resourceBundle)
Returns the size of a resource.
U_CAPI UResourceBundle * ures_openDirect(const char *packageName, const char *locale, UErrorCode *status)
This function does not care what kind of localeID is passed in.
const char * ures_getVersionNumber(const UResourceBundle *resourceBundle)
Return the version number associated with this ResourceBundle as a string.
U_CAPI void ures_resetIterator(UResourceBundle *resourceBundle)
Resets the internal context of a resource so that iteration starts from the first element.
U_CAPI UResourceBundle * ures_open(const char *packageName, const char *locale, UErrorCode *status)
Opens a UResourceBundle, from which users can extract strings by using their corresponding keys.
UResType
Numeric constants for types of resource items.
Definition: ures.h:69
@ RES_BINARY
Definition: ures.h:115
@ URES_TABLE
Resource type constant for tables of key-value pairs.
Definition: ures.h:80
@ RES_ARRAY
Definition: ures.h:123
@ URES_ALIAS
Resource type constant for aliases; internally stores a string which identifies the actual resource s...
Definition: ures.h:89
@ URES_INT_VECTOR
Resource type constant for vectors of 32-bit integers.
Definition: ures.h:108
@ URES_BINARY
Resource type constant for binary data.
Definition: ures.h:77
@ RES_NONE
Definition: ures.h:111
@ URES_ARRAY
Resource type constant for arrays of resources.
Definition: ures.h:101
@ URES_NONE
Resource type constant for "no resource".
Definition: ures.h:71
@ RES_RESERVED
Definition: ures.h:127
@ URES_STRING
Resource type constant for 16-bit Unicode strings.
Definition: ures.h:74
@ RES_INT_VECTOR
Definition: ures.h:125
@ URES_INT
Resource type constant for a single 28-bit integer, interpreted as signed or unsigned by the ures_get...
Definition: ures.h:98
@ RES_TABLE
Definition: ures.h:117
@ RES_STRING
Definition: ures.h:113
@ RES_ALIAS
Definition: ures.h:119
@ RES_INT
Definition: ures.h:121
@ URES_LIMIT
One more than the highest normal UResType value.
Definition: ures.h:133
U_CAPI UResType ures_getType(const UResourceBundle *resourceBundle)
Returns the type of a resource.
U_CAPI UBool ures_hasNext(const UResourceBundle *resourceBundle)
Checks whether the given resource has another element to iterate over.
U_CAPI void ures_close(UResourceBundle *resourceBundle)
Close a resource bundle, all pointers returned from the various ures_getXXX calls on this particular ...
U_CAPI UEnumeration * ures_openAvailableLocales(const char *packageName, UErrorCode *status)
Create a string enumerator, owned by the caller, of all locales located within the specified resource...
U_CAPI const uint8_t * ures_getBinary(const UResourceBundle *resourceBundle, int32_t *len, UErrorCode *status)
Returns a binary data from a binary resource.
U_CAPI const int32_t * ures_getIntVector(const UResourceBundle *resourceBundle, int32_t *len, UErrorCode *status)
Returns a 32 bit integer array from a resource.
U_CAPI const char * ures_getUTF8StringByKey(const UResourceBundle *resB, const char *key, char *dest, int32_t *pLength, UBool forceCopy, UErrorCode *status)
Returns a UTF-8 string from a resource and a key.
struct UResourceBundle UResourceBundle
Definition: ures.h:62
U_CAPI const char * ures_getUTF8StringByIndex(const UResourceBundle *resB, int32_t stringIndex, char *dest, int32_t *pLength, UBool forceCopy, UErrorCode *status)
Returns a UTF-8 string from a resource at the specified index.
const char * ures_getLocale(const UResourceBundle *resourceBundle, UErrorCode *status)
Return the name of the Locale associated with this ResourceBundle.
U_CAPI UResourceBundle * ures_openU(const UChar *packageName, const char *locale, UErrorCode *status)
Same as ures_open() but takes a const UChar *path.
U_CAPI const char * ures_getUTF8String(const UResourceBundle *resB, char *dest, int32_t *length, UBool forceCopy, UErrorCode *status)
Returns a UTF-8 string from a string resource.
U_CAPI void ures_openFillIn(UResourceBundle *r, const char *packageName, const char *localeID, UErrorCode *status)
Same as ures_open() but uses the fill-in parameter instead of allocating a new bundle.
U_CAPI const char * ures_getLocaleByType(const UResourceBundle *resourceBundle, ULocDataLocaleType type, UErrorCode *status)
Return the name of the Locale associated with this ResourceBundle.
U_CAPI const char * ures_getKey(const UResourceBundle *resourceBundle)
Returns the key associated with a given resource.
U_CAPI uint32_t ures_getUInt(const UResourceBundle *resourceBundle, UErrorCode *status)
Returns an unsigned integer from a resource.
U_CAPI UResourceBundle * ures_getNextResource(UResourceBundle *resourceBundle, UResourceBundle *fillIn, UErrorCode *status)
Returns the next resource in a given resource or NULL if there are no more resources to iterate over.
U_CAPI UResourceBundle * ures_getByKey(const UResourceBundle *resourceBundle, const char *key, UResourceBundle *fillIn, UErrorCode *status)
Returns a resource in a given resource that has a given key.
U_CAPI const UChar * ures_getStringByIndex(const UResourceBundle *resourceBundle, int32_t indexS, int32_t *len, UErrorCode *status)
Returns the string in a given resource at the specified index.
U_CAPI const UChar * ures_getNextString(UResourceBundle *resourceBundle, int32_t *len, const char **key, UErrorCode *status)
Returns the next string in a given resource or NULL if there are no more resources to iterate over.
U_CAPI UResourceBundle * ures_getByIndex(const UResourceBundle *resourceBundle, int32_t indexR, UResourceBundle *fillIn, UErrorCode *status)
Returns the resource in a given resource at the specified index.
U_CAPI void ures_getVersion(const UResourceBundle *resB, UVersionInfo versionInfo)
Return the version number associated with this ResourceBundle as an UVersionInfo array.
U_CAPI const UChar * ures_getString(const UResourceBundle *resourceBundle, int32_t *len, UErrorCode *status)
Returns a string from a string resource type.
U_CAPI const UChar * ures_getStringByKey(const UResourceBundle *resB, const char *key, int32_t *len, UErrorCode *status)
Returns a string in a given resource that has a given key.
Basic definitions for ICU, for both C and C++ APIs.
UErrorCode
Standard ICU4C error code type, a substitute for exceptions.
Definition: utypes.h:415
#define U_SUCCESS(x)
Does the error code indicate success?
Definition: utypes.h:712
uint8_t UVersionInfo[U_MAX_VERSION_LENGTH]
The binary form of a version on ICU APIs is an array of 4 uint8_t.
Definition: uversion.h:59