/src/icu/source/common/unicode/appendable.h

Source (jump to first uncovered line)
// © 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
/*
*******************************************************************************
*   Copyright (C) 2011-2012, International Business Machines
*   Corporation and others.  All Rights Reserved.
*******************************************************************************
*   file name:  appendable.h
*   encoding:   UTF-8
*   tab size:   8 (not used)
*   indentation:4
*
*   created on: 2010dec07
*   created by: Markus W. Scherer
*/

#ifndef __APPENDABLE_H__
#define __APPENDABLE_H__

/**
 * \file
 * \brief C++ API: Appendable class: Sink for Unicode code points and 16-bit code units (char16_ts).
 */

#include "unicode/utypes.h"

#if U_SHOW_CPLUSPLUS_API

#include "unicode/uobject.h"

U_NAMESPACE_BEGIN

class UnicodeString;

/**
 * Base class for objects to which Unicode characters and strings can be appended.
 * Combines elements of Java Appendable and ICU4C ByteSink.
 *
 * This class can be used in APIs where it does not matter whether the actual destination is
 * a UnicodeString, a char16_t[] array, a UnicodeSet, or any other object
 * that receives and processes characters and/or strings.
 *
 * Implementation classes must implement at least appendCodeUnit(char16_t).
 * The base class provides default implementations for the other methods.
 *
 * The methods do not take UErrorCode parameters.
 * If an error occurs (e.g., out-of-memory),
 * in addition to returning false from failing operations,
 * the implementation must prevent unexpected behavior (e.g., crashes)
 * from further calls and should make the error condition available separately
 * (e.g., store a UErrorCode, make/keep a UnicodeString bogus).
 * @stable ICU 4.8
 */
class U_COMMON_API Appendable : public UObject {
public:
    /**
     * Destructor.
     * @stable ICU 4.8
     */
    ~Appendable();

    /**
     * Appends a 16-bit code unit.
     * @param c code unit
     * @return true if the operation succeeded
     * @stable ICU 4.8
     */
    virtual UBool appendCodeUnit(char16_t c) = 0;

    /**
     * Appends a code point.
     * The default implementation calls appendCodeUnit(char16_t) once or twice.
     * @param c code point 0..0x10ffff
     * @return true if the operation succeeded
     * @stable ICU 4.8
     */
    virtual UBool appendCodePoint(UChar32 c);

    /**
     * Appends a string.
     * The default implementation calls appendCodeUnit(char16_t) for each code unit.
     * @param s string, must not be NULL if length!=0
     * @param length string length, or -1 if NUL-terminated
     * @return true if the operation succeeded
     * @stable ICU 4.8
     */
    virtual UBool appendString(const char16_t *s, int32_t length);

    /**
     * Tells the object that the caller is going to append roughly
     * appendCapacity char16_ts. A subclass might use this to pre-allocate
     * a larger buffer if necessary.
     * The default implementation does nothing. (It always returns true.)
     * @param appendCapacity estimated number of char16_ts that will be appended
     * @return true if the operation succeeded
     * @stable ICU 4.8
     */
    virtual UBool reserveAppendCapacity(int32_t appendCapacity);

    /**
     * Returns a writable buffer for appending and writes the buffer's capacity to
     * *resultCapacity. Guarantees *resultCapacity>=minCapacity.
     * May return a pointer to the caller-owned scratch buffer which must have
     * scratchCapacity>=minCapacity.
     * The returned buffer is only valid until the next operation
     * on this Appendable.
     *
     * After writing at most *resultCapacity char16_ts, call appendString() with the
     * pointer returned from this function and the number of char16_ts written.
     * Many appendString() implementations will avoid copying char16_ts if this function
     * returned an internal buffer.
     *
     * Partial usage example:
     * \code
     *  int32_t capacity;
     *  char16_t* buffer = app.getAppendBuffer(..., &capacity);
     *  ... Write n char16_ts into buffer, with n <= capacity.
     *  app.appendString(buffer, n);
     * \endcode
     * In many implementations, that call to append will avoid copying char16_ts.
     *
     * If the Appendable allocates or reallocates an internal buffer, it should use
     * the desiredCapacityHint if appropriate.
     * If a caller cannot provide a reasonable guess at the desired capacity,
     * it should pass desiredCapacityHint=0.
     *
     * If a non-scratch buffer is returned, the caller may only pass
     * a prefix to it to appendString().
     * That is, it is not correct to pass an interior pointer to appendString().
     *
     * The default implementation always returns the scratch buffer.
     *
     * @param minCapacity required minimum capacity of the returned buffer;
     *                    must be non-negative
     * @param desiredCapacityHint desired capacity of the returned buffer;
     *                            must be non-negative
     * @param scratch default caller-owned buffer
     * @param scratchCapacity capacity of the scratch buffer
     * @param resultCapacity pointer to an integer which will be set to the
     *                       capacity of the returned buffer
     * @return a buffer with *resultCapacity>=minCapacity
     * @stable ICU 4.8
     */
    virtual char16_t *getAppendBuffer(int32_t minCapacity,
                                   int32_t desiredCapacityHint,
                                   char16_t *scratch, int32_t scratchCapacity,
                                   int32_t *resultCapacity);
};

/**
 * An Appendable implementation which writes to a UnicodeString.
 *
 * This class is not intended for public subclassing.
 * @stable ICU 4.8
 */
class U_COMMON_API UnicodeStringAppendable : public Appendable {
public:
    /**
     * Aliases the UnicodeString (keeps its reference) for writing.
     * @param s The UnicodeString to which this Appendable will write.
     * @stable ICU 4.8
     */
    explicit UnicodeStringAppendable(UnicodeString &s) : str(s) {}

    /**
     * Destructor.
     * @stable ICU 4.8
     */
    ~UnicodeStringAppendable();

    /**
     * Appends a 16-bit code unit to the string.
     * @param c code unit
     * @return true if the operation succeeded
     * @stable ICU 4.8
     */
    virtual UBool appendCodeUnit(char16_t c);

    /**
     * Appends a code point to the string.
     * @param c code point 0..0x10ffff
     * @return true if the operation succeeded
     * @stable ICU 4.8
     */
    virtual UBool appendCodePoint(UChar32 c);

    /**
     * Appends a string to the UnicodeString.
     * @param s string, must not be NULL if length!=0
     * @param length string length, or -1 if NUL-terminated
     * @return true if the operation succeeded
     * @stable ICU 4.8
     */
    virtual UBool appendString(const char16_t *s, int32_t length);

    /**
     * Tells the UnicodeString that the caller is going to append roughly
     * appendCapacity char16_ts.
     * @param appendCapacity estimated number of char16_ts that will be appended
     * @return true if the operation succeeded
     * @stable ICU 4.8
     */
    virtual UBool reserveAppendCapacity(int32_t appendCapacity);

    /**
     * Returns a writable buffer for appending and writes the buffer's capacity to
     * *resultCapacity. Guarantees *resultCapacity>=minCapacity.
     * May return a pointer to the caller-owned scratch buffer which must have
     * scratchCapacity>=minCapacity.
     * The returned buffer is only valid until the next write operation
     * on the UnicodeString.
     *
     * For details see Appendable::getAppendBuffer().
     *
     * @param minCapacity required minimum capacity of the returned buffer;
     *                    must be non-negative
     * @param desiredCapacityHint desired capacity of the returned buffer;
     *                            must be non-negative
     * @param scratch default caller-owned buffer
     * @param scratchCapacity capacity of the scratch buffer
     * @param resultCapacity pointer to an integer which will be set to the
     *                       capacity of the returned buffer
     * @return a buffer with *resultCapacity>=minCapacity
     * @stable ICU 4.8
     */
    virtual char16_t *getAppendBuffer(int32_t minCapacity,
                                   int32_t desiredCapacityHint,
                                   char16_t *scratch, int32_t scratchCapacity,
                                   int32_t *resultCapacity);

private:
    UnicodeString &str;
};

U_NAMESPACE_END

#endif /* U_SHOW_CPLUSPLUS_API */

#endif  // __APPENDABLE_H__

Coverage Report

Created: 2025-01-28 06:38

Line	Count	Source (jump to first uncovered line)
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		*/
163	0	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__