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