Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/appendable.h @ 69:33d812a61356

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