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 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  */
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      */
UnicodeStringAppendable(UnicodeString & s)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 
231 private:
232     UnicodeString &str;
233 };
234 
235 U_NAMESPACE_END
236 
237 #endif /* U_SHOW_CPLUSPLUS_API */
238 
239 #endif  // __APPENDABLE_H__
240