1 /* 2 ******************************************************************************* 3 * Copyright (C) 2011-2012, 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 * @stable ICU 4.8 48 */ 49 class U_COMMON_API Appendable : public UObject { 50 public: 51 /** 52 * Destructor. 53 * @stable ICU 4.8 54 */ 55 ~Appendable(); 56 57 /** 58 * Appends a 16-bit code unit. 59 * @param c code unit 60 * @return TRUE if the operation succeeded 61 * @stable ICU 4.8 62 */ 63 virtual UBool appendCodeUnit(UChar c) = 0; 64 65 /** 66 * Appends a code point. 67 * The default implementation calls appendCodeUnit(UChar) once or twice. 68 * @param c code point 0..0x10ffff 69 * @return TRUE if the operation succeeded 70 * @stable ICU 4.8 71 */ 72 virtual UBool appendCodePoint(UChar32 c); 73 74 /** 75 * Appends a string. 76 * The default implementation calls appendCodeUnit(UChar) for each code unit. 77 * @param s string, must not be NULL if length!=0 78 * @param length string length, or -1 if NUL-terminated 79 * @return TRUE if the operation succeeded 80 * @stable ICU 4.8 81 */ 82 virtual UBool appendString(const UChar *s, int32_t length); 83 84 /** 85 * Tells the object that the caller is going to append roughly 86 * appendCapacity UChars. A subclass might use this to pre-allocate 87 * a larger buffer if necessary. 88 * The default implementation does nothing. (It always returns TRUE.) 89 * @param appendCapacity estimated number of UChars that will be appended 90 * @return TRUE if the operation succeeded 91 * @stable ICU 4.8 92 */ 93 virtual UBool reserveAppendCapacity(int32_t appendCapacity); 94 95 /** 96 * Returns a writable buffer for appending and writes the buffer's capacity to 97 * *resultCapacity. Guarantees *resultCapacity>=minCapacity. 98 * May return a pointer to the caller-owned scratch buffer which must have 99 * scratchCapacity>=minCapacity. 100 * The returned buffer is only valid until the next operation 101 * on this Appendable. 102 * 103 * After writing at most *resultCapacity UChars, call appendString() with the 104 * pointer returned from this function and the number of UChars written. 105 * Many appendString() implementations will avoid copying UChars if this function 106 * returned an internal buffer. 107 * 108 * Partial usage example: 109 * \code 110 * int32_t capacity; 111 * UChar* buffer = app.getAppendBuffer(..., &capacity); 112 * ... Write n UChars into buffer, with n <= capacity. 113 * app.appendString(buffer, n); 114 * \endcode 115 * In many implementations, that call to append will avoid copying UChars. 116 * 117 * If the Appendable allocates or reallocates an internal buffer, it should use 118 * the desiredCapacityHint if appropriate. 119 * If a caller cannot provide a reasonable guess at the desired capacity, 120 * it should pass desiredCapacityHint=0. 121 * 122 * If a non-scratch buffer is returned, the caller may only pass 123 * a prefix to it to appendString(). 124 * That is, it is not correct to pass an interior pointer to appendString(). 125 * 126 * The default implementation always returns the scratch buffer. 127 * 128 * @param minCapacity required minimum capacity of the returned buffer; 129 * must be non-negative 130 * @param desiredCapacityHint desired capacity of the returned buffer; 131 * must be non-negative 132 * @param scratch default caller-owned buffer 133 * @param scratchCapacity capacity of the scratch buffer 134 * @param resultCapacity pointer to an integer which will be set to the 135 * capacity of the returned buffer 136 * @return a buffer with *resultCapacity>=minCapacity 137 * @stable ICU 4.8 138 */ 139 virtual UChar *getAppendBuffer(int32_t minCapacity, 140 int32_t desiredCapacityHint, 141 UChar *scratch, int32_t scratchCapacity, 142 int32_t *resultCapacity); 143 }; 144 145 /** 146 * An Appendable implementation which writes to a UnicodeString. 147 * 148 * This class is not intended for public subclassing. 149 * @stable ICU 4.8 150 */ 151 class U_COMMON_API UnicodeStringAppendable : public Appendable { 152 public: 153 /** 154 * Aliases the UnicodeString (keeps its reference) for writing. 155 * @param s The UnicodeString to which this Appendable will write. 156 * @stable ICU 4.8 157 */ UnicodeStringAppendable(UnicodeString & s)158 explicit UnicodeStringAppendable(UnicodeString &s) : str(s) {} 159 160 /** 161 * Destructor. 162 * @stable ICU 4.8 163 */ 164 ~UnicodeStringAppendable(); 165 166 /** 167 * Appends a 16-bit code unit to the string. 168 * @param c code unit 169 * @return TRUE if the operation succeeded 170 * @stable ICU 4.8 171 */ 172 virtual UBool appendCodeUnit(UChar c); 173 174 /** 175 * Appends a code point to the string. 176 * @param c code point 0..0x10ffff 177 * @return TRUE if the operation succeeded 178 * @stable ICU 4.8 179 */ 180 virtual UBool appendCodePoint(UChar32 c); 181 182 /** 183 * Appends a string to the UnicodeString. 184 * @param s string, must not be NULL if length!=0 185 * @param length string length, or -1 if NUL-terminated 186 * @return TRUE if the operation succeeded 187 * @stable ICU 4.8 188 */ 189 virtual UBool appendString(const UChar *s, int32_t length); 190 191 /** 192 * Tells the UnicodeString that the caller is going to append roughly 193 * appendCapacity UChars. 194 * @param appendCapacity estimated number of UChars that will be appended 195 * @return TRUE if the operation succeeded 196 * @stable ICU 4.8 197 */ 198 virtual UBool reserveAppendCapacity(int32_t appendCapacity); 199 200 /** 201 * Returns a writable buffer for appending and writes the buffer's capacity to 202 * *resultCapacity. Guarantees *resultCapacity>=minCapacity. 203 * May return a pointer to the caller-owned scratch buffer which must have 204 * scratchCapacity>=minCapacity. 205 * The returned buffer is only valid until the next write operation 206 * on the UnicodeString. 207 * 208 * For details see Appendable::getAppendBuffer(). 209 * 210 * @param minCapacity required minimum capacity of the returned buffer; 211 * must be non-negative 212 * @param desiredCapacityHint desired capacity of the returned buffer; 213 * must be non-negative 214 * @param scratch default caller-owned buffer 215 * @param scratchCapacity capacity of the scratch buffer 216 * @param resultCapacity pointer to an integer which will be set to the 217 * capacity of the returned buffer 218 * @return a buffer with *resultCapacity>=minCapacity 219 * @stable ICU 4.8 220 */ 221 virtual UChar *getAppendBuffer(int32_t minCapacity, 222 int32_t desiredCapacityHint, 223 UChar *scratch, int32_t scratchCapacity, 224 int32_t *resultCapacity); 225 226 private: 227 UnicodeString &str; 228 }; 229 230 U_NAMESPACE_END 231 232 #endif // __APPENDABLE_H__ 233