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
31U_NAMESPACE_BEGIN
32
33class 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 */
54class U_COMMON_API Appendable : public UObject {
55public:
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 NULL 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 */
156class U_COMMON_API UnicodeStringAppendable : public Appendable {
157public:
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);
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);
186
187 /**
188 * Appends a string to the UnicodeString.
189 * @param s string, must not be NULL 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);
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);
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);
230
231private:
232 UnicodeString &str;
233};
234
235U_NAMESPACE_END
236
237#endif /* U_SHOW_CPLUSPLUS_API */
238
239#endif // __APPENDABLE_H__
240