icuSources/common/resource.h

   1 // © 2016 and later: Unicode, Inc. and others.
   2 // License & terms of use: http://www.unicode.org/copyright.html
   3 /*
   4 *******************************************************************************
   5 * Copyright (C) 2015-2016, International Business Machines
   6 * Corporation and others.  All Rights Reserved.
   7 *******************************************************************************
   8 * resource.h
   9 *
  10 * created on: 2015nov04
  11 * created by: Markus W. Scherer
  12 */
  13
  14 #ifndef __URESOURCE_H__
  15 #define __URESOURCE_H__
  16
  17 /**
  18  * \file
  19  * \brief ICU resource bundle key and value types.
  20  */
  21
  22 // Note: Ported from ICU4J class UResource and its nested classes,
  23 // but the C++ classes are separate, not nested.
  24
  25 // We use the Resource prefix for C++ classes, as usual.
  26 // The UResource prefix would be used for C types.
  27
  28 #include "unicode/utypes.h"
  29 #include "unicode/unistr.h"
  30 #include "unicode/ures.h"
  31
  32 struct ResourceData;
  33
  34 U_NAMESPACE_BEGIN
  35
  36 class ResourceValue;
  37
  38 // Note: In C++, we use const char * pointers for keys,
  39 // rather than an abstraction like Java UResource.Key.
  40
  41 /**
  42  * Interface for iterating over a resource bundle array resource.
  43  */
  44 class U_COMMON_API ResourceArray {
  45 public:
  46     /** Constructs an empty array object. */
  47     ResourceArray() : items16(NULL), items32(NULL), length(0) {}
  48
  49     /** Only for implementation use. @internal */
  50     ResourceArray(const uint16_t *i16, const uint32_t *i32, int32_t len) :
  51             items16(i16), items32(i32), length(len) {}
  52
  53     /**
  54      * @return The number of items in the array resource.
  55      */
  56     int32_t getSize() const { return length; }
  57     /**
  58      * @param i Array item index.
  59      * @param value Output-only, receives the value of the i'th item.
  60      * @return TRUE if i is non-negative and less than getSize().
  61      */
  62     UBool getValue(int32_t i, ResourceValue &value) const;
  63
  64     /** Only for implementation use. @internal */
  65     uint32_t internalGetResource(const ResourceData *pResData, int32_t i) const;
  66
  67 private:
  68     const uint16_t *items16;
  69     const uint32_t *items32;
  70     int32_t length;
  71 };
  72
  73 /**
  74  * Interface for iterating over a resource bundle table resource.
  75  */
  76 class U_COMMON_API ResourceTable {
  77 public:
  78     /** Constructs an empty table object. */
  79     ResourceTable() : keys16(NULL), keys32(NULL), items16(NULL), items32(NULL), length(0) {}
  80
  81     /** Only for implementation use. @internal */
  82     ResourceTable(const uint16_t *k16, const int32_t *k32,
  83                   const uint16_t *i16, const uint32_t *i32, int32_t len) :
  84             keys16(k16), keys32(k32), items16(i16), items32(i32), length(len) {}
  85
  86     /**
  87      * @return The number of items in the array resource.
  88      */
  89     int32_t getSize() const { return length; }
  90     /**
  91      * @param i Array item index.
  92      * @param key Output-only, receives the key of the i'th item.
  93      * @param value Output-only, receives the value of the i'th item.
  94      * @return TRUE if i is non-negative and less than getSize().
  95      */
  96     UBool getKeyAndValue(int32_t i, const char *&key, ResourceValue &value) const;
  97
  98 private:
  99     const uint16_t *keys16;
 100     const int32_t *keys32;
 101     const uint16_t *items16;
 102     const uint32_t *items32;
 103     int32_t length;
 104 };
 105
 106 /**
 107  * Represents a resource bundle item's value.
 108  * Avoids object creations as much as possible.
 109  * Mutable, not thread-safe.
 110  */
 111 class U_COMMON_API ResourceValue : public UObject {
 112 public:
 113     virtual ~ResourceValue();
 114
 115     /**
 116      * @return ICU resource type, for example, URES_STRING
 117      */
 118     virtual UResType getType() const = 0;
 119
 120     /**
 121      * Sets U_RESOURCE_TYPE_MISMATCH if this is not a string resource.
 122      *
 123      * @see ures_getString()
 124      */
 125     virtual const UChar *getString(int32_t &length, UErrorCode &errorCode) const = 0;
 126
 127     inline UnicodeString getUnicodeString(UErrorCode &errorCode) const {
 128         int32_t len = 0;
 129         const UChar *r = getString(len, errorCode);
 130         return UnicodeString(TRUE, r, len);
 131     }
 132
 133     /**
 134      * Sets U_RESOURCE_TYPE_MISMATCH if this is not an alias resource.
 135      */
 136     virtual const UChar *getAliasString(int32_t &length, UErrorCode &errorCode) const = 0;
 137
 138     inline UnicodeString getAliasUnicodeString(UErrorCode &errorCode) const {
 139         int32_t len = 0;
 140         const UChar *r = getAliasString(len, errorCode);
 141         return UnicodeString(TRUE, r, len);
 142     }
 143
 144     /**
 145      * Sets U_RESOURCE_TYPE_MISMATCH if this is not an integer resource.
 146      *
 147      * @see ures_getInt()
 148      */
 149     virtual int32_t getInt(UErrorCode &errorCode) const = 0;
 150
 151     /**
 152      * Sets U_RESOURCE_TYPE_MISMATCH if this is not an integer resource.
 153      *
 154      * @see ures_getUInt()
 155      */
 156     virtual uint32_t getUInt(UErrorCode &errorCode) const = 0;
 157
 158     /**
 159      * Sets U_RESOURCE_TYPE_MISMATCH if this is not an intvector resource.
 160      *
 161      * @see ures_getIntVector()
 162      */
 163     virtual const int32_t *getIntVector(int32_t &length, UErrorCode &errorCode) const = 0;
 164
 165     /**
 166      * Sets U_RESOURCE_TYPE_MISMATCH if this is not a binary-blob resource.
 167      *
 168      * @see ures_getBinary()
 169      */
 170     virtual const uint8_t *getBinary(int32_t &length, UErrorCode &errorCode) const = 0;
 171
 172     /**
 173      * Sets U_RESOURCE_TYPE_MISMATCH if this is not an array resource
 174      */
 175     virtual ResourceArray getArray(UErrorCode &errorCode) const = 0;
 176
 177     /**
 178      * Sets U_RESOURCE_TYPE_MISMATCH if this is not a table resource
 179      */
 180     virtual ResourceTable getTable(UErrorCode &errorCode) const = 0;
 181
 182     /**
 183      * Is this a no-fallback/no-inheritance marker string?
 184      * Such a marker is used for
 185      * CLDR no-fallback data values of (three empty-set symbols)=={2205, 2205, 2205}
 186      * when enumerating tables with fallback from the specific resource bundle to root.
 187      *
 188      * @return TRUE if this is a no-inheritance marker string
 189      */
 190     virtual UBool isNoInheritanceMarker() const = 0;
 191
 192     /**
 193      * Sets the dest strings from the string values in this array resource.
 194      *
 195      * @return the number of strings in this array resource.
 196      *     If greater than capacity, then an overflow error is set.
 197      *
 198      * Sets U_RESOURCE_TYPE_MISMATCH if this is not an array resource
 199      *     or if any of the array items is not a string
 200      */
 201     virtual int32_t getStringArray(UnicodeString *dest, int32_t capacity,
 202                                    UErrorCode &errorCode) const = 0;
 203
 204     /**
 205      * Same as
 206      * <pre>
 207      * if (getType() == URES_STRING) {
 208      *     return new String[] { getString(); }
 209      * } else {
 210      *     return getStringArray();
 211      * }
 212      * </pre>
 213      *
 214      * Sets U_RESOURCE_TYPE_MISMATCH if this is
 215      *     neither a string resource nor an array resource containing strings
 216      * @see getString()
 217      * @see getStringArray()
 218      */
 219     virtual int32_t getStringArrayOrStringAsArray(UnicodeString *dest, int32_t capacity,
 220                                                   UErrorCode &errorCode) const = 0;
 221
 222     /**
 223      * Same as
 224      * <pre>
 225      * if (getType() == URES_STRING) {
 226      *     return getString();
 227      * } else {
 228      *     return getStringArray()[0];
 229      * }
 230      * </pre>
 231      *
 232      * Sets U_RESOURCE_TYPE_MISMATCH if this is
 233      *     neither a string resource nor an array resource containing strings
 234      * @see getString()
 235      * @see getStringArray()
 236      */
 237     virtual UnicodeString getStringOrFirstOfArray(UErrorCode &errorCode) const = 0;
 238
 239 protected:
 240     ResourceValue() {}
 241
 242 private:
 243     ResourceValue(const ResourceValue &);  // no copy constructor
 244     ResourceValue &operator=(const ResourceValue &);  // no assignment operator
 245 };
 246
 247 /**
 248  * Sink for ICU resource bundle contents.
 249  */
 250 class U_COMMON_API ResourceSink : public UObject {
 251 public:
 252     ResourceSink() {}
 253     virtual ~ResourceSink();
 254
 255     /**
 256      * Called once for each bundle (child-parent-...-root).
 257      * The value is normally an array or table resource,
 258      * and implementations of this method normally iterate over the
 259      * tree of resource items stored there.
 260      *
 261      * @param key The key string of the enumeration-start resource.
 262      *     Empty if the enumeration starts at the top level of the bundle.
 263      * @param value Call getArray() or getTable() as appropriate.
 264      *     Then reuse for output values from Array and Table getters.
 265      * @param noFallback true if the bundle has no parent;
 266      *     that is, its top-level table has the nofallback attribute,
 267      *     or it is the root bundle of a locale tree.
 268      */
 269     virtual void put(const char *key, ResourceValue &value, UBool noFallback,
 270                      UErrorCode &errorCode) = 0;
 271
 272 private:
 273     ResourceSink(const ResourceSink &);  // no copy constructor
 274     ResourceSink &operator=(const ResourceSink &);  // no assignment operator
 275 };
 276
 277 U_NAMESPACE_END
 278
 279 #endif