1 /* 2 ******************************************************************************* 3 * Copyright (C) 2011, International Business Machines 4 * Corporation and others. All Rights Reserved. 5 ******************************************************************************* 6 * file name: appendable.h 7 * encoding: US-ASCII 8 * tab size: 8 (not used) 9 * indentation:4 10 * 11 * created on: 2010dec07 12 * created by: Markus W. Scherer 13 */ 14 15 #ifndef __APPENDABLE_H__ 16 #define __APPENDABLE_H__ 17 18 /** 19 * \file 20 * \brief C++ API: Appendable class: Sink for Unicode code points and 16-bit code units (UChars). 21 */ 22 23 #include "unicode/utypes.h" 24 #include "unicode/uobject.h" 25 26 U_NAMESPACE_BEGIN 27 28 class UnicodeString; 29 30 /** 31 * Base class for objects to which Unicode characters and strings can be appended. 32 * Combines elements of Java Appendable and ICU4C ByteSink. 33 * 34 * This class can be used in APIs where it does not matter whether the actual destination is 35 * a UnicodeString, a UChar[] array, a UnicodeSet, or any other object 36 * that receives and processes characters and/or strings. 37 * 38 * Implementation classes must implement at least appendCodeUnit(UChar). 39 * The base class provides default implementations for the other methods. 40 * 41 * The methods do not take UErrorCode parameters. 42 * If an error occurs (e.g., out-of-memory), 43 * in addition to returning FALSE from failing operations, 44 * the implementation must prevent unexpected behavior (e.g., crashes) 45 * from further calls and should make the error condition available separately 46 * (e.g., store a UErrorCode, make/keep a UnicodeString bogus). 47 * @draft ICU 4.8 48 */ 49 class U_COMMON_API Appendable : public UObject { 50 public: 51 /** 52 * Appends a 16-bit code unit. 53 * @param c code unit 54 * @return TRUE if the operation succeeded 55 * @draft ICU 4.8 56 */ 57 virtual UBool appendCodeUnit(UChar c) = 0; 58 59 /** 60 * Appends a code point. 61 * The default implementation calls appendCodeUnit(UChar) once or twice. 62 * @param c code point 0..0x10ffff 63 * @return TRUE if the operation succeeded 64 * @draft ICU 4.8 65 */ 66 virtual UBool appendCodePoint(UChar32 c); 67 68 /** 69 * Appends a string. 70 * The default implementation calls appendCodeUnit(UChar) for each code unit. 71 * @param s string, must not be NULL if length!=0 72 * @param length string length, or -1 if NUL-terminated 73 * @return TRUE if the operation succeeded 74 * @draft ICU 4.8 75 */ 76 virtual UBool appendString(const UChar *s, int32_t length); 77 78 /** 79 * Tells the object that the caller is going to append roughly 80 * appendCapacity UChars. A subclass might use this to pre-allocate 81 * a larger buffer if necessary. 82 * The default implementation does nothing. (It always returns TRUE.) 83 * @param appendCapacity estimated number of UChars that will be appended 84 * @return TRUE if the operation succeeded 85 * @draft ICU 4.8 86 */ 87 virtual UBool reserveAppendCapacity(int32_t appendCapacity); 88 89 /** 90 * Returns a writable buffer for appending and writes the buffer's capacity to 91 * *resultCapacity. Guarantees *resultCapacity>=minCapacity. 92 * May return a pointer to the caller-owned scratch buffer which must have 93 * scratchCapacity>=minCapacity. 94 * The returned buffer is only valid until the next operation 95 * on this Appendable. 96 * 97 * After writing at most *resultCapacity UChars, call appendString() with the 98 * pointer returned from this function and the number of UChars written. 99 * Many appendString() implementations will avoid copying UChars if this function 100 * returned an internal buffer. 101 * 102 * Partial usage example: 103 * \code 104 * int32_t capacity; 105 * UChar* buffer = app.getAppendBuffer(..., &capacity); 106 * ... Write n UChars into buffer, with n <= capacity. 107 * app.appendString(buffer, n); 108 * \endcode 109 * In many implementations, that call to append will avoid copying UChars. 110 * 111 * If the Appendable allocates or reallocates an internal buffer, it should use 112 * the desiredCapacityHint if appropriate. 113 * If a caller cannot provide a reasonable guess at the desired capacity, 114 * it should pass desiredCapacityHint=0. 115 * 116 * If a non-scratch buffer is returned, the caller may only pass 117 * a prefix to it to appendString(). 118 * That is, it is not correct to pass an interior pointer to appendString(). 119 * 120 * The default implementation always returns the scratch buffer. 121 * 122 * @param minCapacity required minimum capacity of the returned buffer; 123 * must be non-negative 124 * @param desiredCapacityHint desired capacity of the returned buffer; 125 * must be non-negative 126 * @param scratch default caller-owned buffer 127 * @param scratchCapacity capacity of the scratch buffer 128 * @param resultCapacity pointer to an integer which will be set to the 129 * capacity of the returned buffer 130 * @return a buffer with *resultCapacity>=minCapacity 131 * @draft ICU 4.8 132 */ 133 virtual UChar *getAppendBuffer(int32_t minCapacity, 134 int32_t desiredCapacityHint, 135 UChar *scratch, int32_t scratchCapacity, 136 int32_t *resultCapacity); 137 138 private: 139 // No ICU "poor man's RTTI" for this class nor its subclasses. 140 virtual UClassID getDynamicClassID() const; 141 }; 142 143 /** 144 * An Appendable implementation which writes to a UnicodeString. 145 * 146 * This class is not intended for public subclassing. 147 * @draft ICU 4.8 148 */ 149 class U_COMMON_API UnicodeStringAppendable : public Appendable { 150 public: 151 /** 152 * Aliases the UnicodeString (keeps its reference) for writing. 153 * @param s The UnicodeString to which this Appendable will write. 154 * @draft ICU 4.8 155 */ 156 explicit UnicodeStringAppendable(UnicodeString &s) : str(s) {} 157 158 /** 159 * Appends a 16-bit code unit to the string. 160 * @param c code unit 161 * @return TRUE if the operation succeeded 162 * @draft ICU 4.8 163 */ 164 virtual UBool appendCodeUnit(UChar c); 165 166 /** 167 * Appends a code point to the string. 168 * @param c code point 0..0x10ffff 169 * @return TRUE if the operation succeeded 170 * @draft ICU 4.8 171 */ 172 virtual UBool appendCodePoint(UChar32 c); 173 174 /** 175 * Appends a string to the UnicodeString. 176 * @param s string, must not be NULL if length!=0 177 * @param length string length, or -1 if NUL-terminated 178 * @return TRUE if the operation succeeded 179 * @draft ICU 4.8 180 */ 181 virtual UBool appendString(const UChar *s, int32_t length); 182 183 /** 184 * Tells the UnicodeString that the caller is going to append roughly 185 * appendCapacity UChars. 186 * @param appendCapacity estimated number of UChars that will be appended 187 * @return TRUE if the operation succeeded 188 * @draft ICU 4.8 189 */ 190 virtual UBool reserveAppendCapacity(int32_t appendCapacity); 191 192 /** 193 * Returns a writable buffer for appending and writes the buffer's capacity to 194 * *resultCapacity. Guarantees *resultCapacity>=minCapacity. 195 * May return a pointer to the caller-owned scratch buffer which must have 196 * scratchCapacity>=minCapacity. 197 * The returned buffer is only valid until the next write operation 198 * on the UnicodeString. 199 * 200 * For details see Appendable::getAppendBuffer(). 201 * 202 * @param minCapacity required minimum capacity of the returned buffer; 203 * must be non-negative 204 * @param desiredCapacityHint desired capacity of the returned buffer; 205 * must be non-negative 206 * @param scratch default caller-owned buffer 207 * @param scratchCapacity capacity of the scratch buffer 208 * @param resultCapacity pointer to an integer which will be set to the 209 * capacity of the returned buffer 210 * @return a buffer with *resultCapacity>=minCapacity 211 * @draft ICU 4.8 212 */ 213 virtual UChar *getAppendBuffer(int32_t minCapacity, 214 int32_t desiredCapacityHint, 215 UChar *scratch, int32_t scratchCapacity, 216 int32_t *resultCapacity); 217 218 private: 219 UnicodeString &str; 220 }; 221 222 U_NAMESPACE_END 223 224 #endif // __APPENDABLE_H__ 225
