icuSources/common/unicode/appendable.h

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