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