1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/common/unicode/appendable.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,232 @@
1.4 +/*
1.5 +*******************************************************************************
1.6 +* Copyright (C) 2011-2012, International Business Machines
1.7 +* Corporation and others. All Rights Reserved.
1.8 +*******************************************************************************
1.9 +* file name: appendable.h
1.10 +* encoding: US-ASCII
1.11 +* tab size: 8 (not used)
1.12 +* indentation:4
1.13 +*
1.14 +* created on: 2010dec07
1.15 +* created by: Markus W. Scherer
1.16 +*/
1.17 +
1.18 +#ifndef __APPENDABLE_H__
1.19 +#define __APPENDABLE_H__
1.20 +
1.21 +/**
1.22 + * \file
1.23 + * \brief C++ API: Appendable class: Sink for Unicode code points and 16-bit code units (UChars).
1.24 + */
1.25 +
1.26 +#include "unicode/utypes.h"
1.27 +#include "unicode/uobject.h"
1.28 +
1.29 +U_NAMESPACE_BEGIN
1.30 +
1.31 +class UnicodeString;
1.32 +
1.33 +/**
1.34 + * Base class for objects to which Unicode characters and strings can be appended.
1.35 + * Combines elements of Java Appendable and ICU4C ByteSink.
1.36 + *
1.37 + * This class can be used in APIs where it does not matter whether the actual destination is
1.38 + * a UnicodeString, a UChar[] array, a UnicodeSet, or any other object
1.39 + * that receives and processes characters and/or strings.
1.40 + *
1.41 + * Implementation classes must implement at least appendCodeUnit(UChar).
1.42 + * The base class provides default implementations for the other methods.
1.43 + *
1.44 + * The methods do not take UErrorCode parameters.
1.45 + * If an error occurs (e.g., out-of-memory),
1.46 + * in addition to returning FALSE from failing operations,
1.47 + * the implementation must prevent unexpected behavior (e.g., crashes)
1.48 + * from further calls and should make the error condition available separately
1.49 + * (e.g., store a UErrorCode, make/keep a UnicodeString bogus).
1.50 + * @stable ICU 4.8
1.51 + */
1.52 +class U_COMMON_API Appendable : public UObject {
1.53 +public:
1.54 + /**
1.55 + * Destructor.
1.56 + * @stable ICU 4.8
1.57 + */
1.58 + ~Appendable();
1.59 +
1.60 + /**
1.61 + * Appends a 16-bit code unit.
1.62 + * @param c code unit
1.63 + * @return TRUE if the operation succeeded
1.64 + * @stable ICU 4.8
1.65 + */
1.66 + virtual UBool appendCodeUnit(UChar c) = 0;
1.67 +
1.68 + /**
1.69 + * Appends a code point.
1.70 + * The default implementation calls appendCodeUnit(UChar) once or twice.
1.71 + * @param c code point 0..0x10ffff
1.72 + * @return TRUE if the operation succeeded
1.73 + * @stable ICU 4.8
1.74 + */
1.75 + virtual UBool appendCodePoint(UChar32 c);
1.76 +
1.77 + /**
1.78 + * Appends a string.
1.79 + * The default implementation calls appendCodeUnit(UChar) for each code unit.
1.80 + * @param s string, must not be NULL if length!=0
1.81 + * @param length string length, or -1 if NUL-terminated
1.82 + * @return TRUE if the operation succeeded
1.83 + * @stable ICU 4.8
1.84 + */
1.85 + virtual UBool appendString(const UChar *s, int32_t length);
1.86 +
1.87 + /**
1.88 + * Tells the object that the caller is going to append roughly
1.89 + * appendCapacity UChars. A subclass might use this to pre-allocate
1.90 + * a larger buffer if necessary.
1.91 + * The default implementation does nothing. (It always returns TRUE.)
1.92 + * @param appendCapacity estimated number of UChars that will be appended
1.93 + * @return TRUE if the operation succeeded
1.94 + * @stable ICU 4.8
1.95 + */
1.96 + virtual UBool reserveAppendCapacity(int32_t appendCapacity);
1.97 +
1.98 + /**
1.99 + * Returns a writable buffer for appending and writes the buffer's capacity to
1.100 + * *resultCapacity. Guarantees *resultCapacity>=minCapacity.
1.101 + * May return a pointer to the caller-owned scratch buffer which must have
1.102 + * scratchCapacity>=minCapacity.
1.103 + * The returned buffer is only valid until the next operation
1.104 + * on this Appendable.
1.105 + *
1.106 + * After writing at most *resultCapacity UChars, call appendString() with the
1.107 + * pointer returned from this function and the number of UChars written.
1.108 + * Many appendString() implementations will avoid copying UChars if this function
1.109 + * returned an internal buffer.
1.110 + *
1.111 + * Partial usage example:
1.112 + * \code
1.113 + * int32_t capacity;
1.114 + * UChar* buffer = app.getAppendBuffer(..., &capacity);
1.115 + * ... Write n UChars into buffer, with n <= capacity.
1.116 + * app.appendString(buffer, n);
1.117 + * \endcode
1.118 + * In many implementations, that call to append will avoid copying UChars.
1.119 + *
1.120 + * If the Appendable allocates or reallocates an internal buffer, it should use
1.121 + * the desiredCapacityHint if appropriate.
1.122 + * If a caller cannot provide a reasonable guess at the desired capacity,
1.123 + * it should pass desiredCapacityHint=0.
1.124 + *
1.125 + * If a non-scratch buffer is returned, the caller may only pass
1.126 + * a prefix to it to appendString().
1.127 + * That is, it is not correct to pass an interior pointer to appendString().
1.128 + *
1.129 + * The default implementation always returns the scratch buffer.
1.130 + *
1.131 + * @param minCapacity required minimum capacity of the returned buffer;
1.132 + * must be non-negative
1.133 + * @param desiredCapacityHint desired capacity of the returned buffer;
1.134 + * must be non-negative
1.135 + * @param scratch default caller-owned buffer
1.136 + * @param scratchCapacity capacity of the scratch buffer
1.137 + * @param resultCapacity pointer to an integer which will be set to the
1.138 + * capacity of the returned buffer
1.139 + * @return a buffer with *resultCapacity>=minCapacity
1.140 + * @stable ICU 4.8
1.141 + */
1.142 + virtual UChar *getAppendBuffer(int32_t minCapacity,
1.143 + int32_t desiredCapacityHint,
1.144 + UChar *scratch, int32_t scratchCapacity,
1.145 + int32_t *resultCapacity);
1.146 +};
1.147 +
1.148 +/**
1.149 + * An Appendable implementation which writes to a UnicodeString.
1.150 + *
1.151 + * This class is not intended for public subclassing.
1.152 + * @stable ICU 4.8
1.153 + */
1.154 +class U_COMMON_API UnicodeStringAppendable : public Appendable {
1.155 +public:
1.156 + /**
1.157 + * Aliases the UnicodeString (keeps its reference) for writing.
1.158 + * @param s The UnicodeString to which this Appendable will write.
1.159 + * @stable ICU 4.8
1.160 + */
1.161 + explicit UnicodeStringAppendable(UnicodeString &s) : str(s) {}
1.162 +
1.163 + /**
1.164 + * Destructor.
1.165 + * @stable ICU 4.8
1.166 + */
1.167 + ~UnicodeStringAppendable();
1.168 +
1.169 + /**
1.170 + * Appends a 16-bit code unit to the string.
1.171 + * @param c code unit
1.172 + * @return TRUE if the operation succeeded
1.173 + * @stable ICU 4.8
1.174 + */
1.175 + virtual UBool appendCodeUnit(UChar c);
1.176 +
1.177 + /**
1.178 + * Appends a code point to the string.
1.179 + * @param c code point 0..0x10ffff
1.180 + * @return TRUE if the operation succeeded
1.181 + * @stable ICU 4.8
1.182 + */
1.183 + virtual UBool appendCodePoint(UChar32 c);
1.184 +
1.185 + /**
1.186 + * Appends a string to the UnicodeString.
1.187 + * @param s string, must not be NULL if length!=0
1.188 + * @param length string length, or -1 if NUL-terminated
1.189 + * @return TRUE if the operation succeeded
1.190 + * @stable ICU 4.8
1.191 + */
1.192 + virtual UBool appendString(const UChar *s, int32_t length);
1.193 +
1.194 + /**
1.195 + * Tells the UnicodeString that the caller is going to append roughly
1.196 + * appendCapacity UChars.
1.197 + * @param appendCapacity estimated number of UChars that will be appended
1.198 + * @return TRUE if the operation succeeded
1.199 + * @stable ICU 4.8
1.200 + */
1.201 + virtual UBool reserveAppendCapacity(int32_t appendCapacity);
1.202 +
1.203 + /**
1.204 + * Returns a writable buffer for appending and writes the buffer's capacity to
1.205 + * *resultCapacity. Guarantees *resultCapacity>=minCapacity.
1.206 + * May return a pointer to the caller-owned scratch buffer which must have
1.207 + * scratchCapacity>=minCapacity.
1.208 + * The returned buffer is only valid until the next write operation
1.209 + * on the UnicodeString.
1.210 + *
1.211 + * For details see Appendable::getAppendBuffer().
1.212 + *
1.213 + * @param minCapacity required minimum capacity of the returned buffer;
1.214 + * must be non-negative
1.215 + * @param desiredCapacityHint desired capacity of the returned buffer;
1.216 + * must be non-negative
1.217 + * @param scratch default caller-owned buffer
1.218 + * @param scratchCapacity capacity of the scratch buffer
1.219 + * @param resultCapacity pointer to an integer which will be set to the
1.220 + * capacity of the returned buffer
1.221 + * @return a buffer with *resultCapacity>=minCapacity
1.222 + * @stable ICU 4.8
1.223 + */
1.224 + virtual UChar *getAppendBuffer(int32_t minCapacity,
1.225 + int32_t desiredCapacityHint,
1.226 + UChar *scratch, int32_t scratchCapacity,
1.227 + int32_t *resultCapacity);
1.228 +
1.229 +private:
1.230 + UnicodeString &str;
1.231 +};
1.232 +
1.233 +U_NAMESPACE_END
1.234 +
1.235 +#endif // __APPENDABLE_H__
