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