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__ |
240 | |