include/unicode/appendable.h

0001 // © 2016 and later: Unicode, Inc. and others.
0002 // License & terms of use: http://www.unicode.org/copyright.html
0003 /*
0004 *******************************************************************************
0005 *   Copyright (C) 2011-2012, International Business Machines
0006 *   Corporation and others.  All Rights Reserved.
0007 *******************************************************************************
0008 *   file name:  appendable.h
0009 *   encoding:   UTF-8
0010 *   tab size:   8 (not used)
0011 *   indentation:4
0012 *
0013 *   created on: 2010dec07
0014 *   created by: Markus W. Scherer
0015 */
0016
0017 #ifndef __APPENDABLE_H__
0018 #define __APPENDABLE_H__
0019
0020 /**
0021  * \file
0022  * \brief C++ API: Appendable class: Sink for Unicode code points and 16-bit code units (char16_ts).
0023  */
0024
0025 #include "unicode/utypes.h"
0026
0027 #if U_SHOW_CPLUSPLUS_API
0028
0029 #include "unicode/uobject.h"
0030
0031 U_NAMESPACE_BEGIN
0032
0033 class UnicodeString;
0034
0035 /**
0036  * Base class for objects to which Unicode characters and strings can be appended.
0037  * Combines elements of Java Appendable and ICU4C ByteSink.
0038  *
0039  * This class can be used in APIs where it does not matter whether the actual destination is
0040  * a UnicodeString, a char16_t[] array, a UnicodeSet, or any other object
0041  * that receives and processes characters and/or strings.
0042  *
0043  * Implementation classes must implement at least appendCodeUnit(char16_t).
0044  * The base class provides default implementations for the other methods.
0045  *
0046  * The methods do not take UErrorCode parameters.
0047  * If an error occurs (e.g., out-of-memory),
0048  * in addition to returning false from failing operations,
0049  * the implementation must prevent unexpected behavior (e.g., crashes)
0050  * from further calls and should make the error condition available separately
0051  * (e.g., store a UErrorCode, make/keep a UnicodeString bogus).
0052  * @stable ICU 4.8
0053  */
0054 class U_COMMON_API Appendable : public UObject {
0055 public:
0056     /**
0057      * Destructor.
0058      * @stable ICU 4.8
0059      */
0060     ~Appendable();
0061
0062     /**
0063      * Appends a 16-bit code unit.
0064      * @param c code unit
0065      * @return true if the operation succeeded
0066      * @stable ICU 4.8
0067      */
0068     virtual UBool appendCodeUnit(char16_t c) = 0;
0069
0070     /**
0071      * Appends a code point.
0072      * The default implementation calls appendCodeUnit(char16_t) once or twice.
0073      * @param c code point 0..0x10ffff
0074      * @return true if the operation succeeded
0075      * @stable ICU 4.8
0076      */
0077     virtual UBool appendCodePoint(UChar32 c);
0078
0079     /**
0080      * Appends a string.
0081      * The default implementation calls appendCodeUnit(char16_t) for each code unit.
0082      * @param s string, must not be nullptr if length!=0
0083      * @param length string length, or -1 if NUL-terminated
0084      * @return true if the operation succeeded
0085      * @stable ICU 4.8
0086      */
0087     virtual UBool appendString(const char16_t *s, int32_t length);
0088
0089     /**
0090      * Tells the object that the caller is going to append roughly
0091      * appendCapacity char16_ts. A subclass might use this to pre-allocate
0092      * a larger buffer if necessary.
0093      * The default implementation does nothing. (It always returns true.)
0094      * @param appendCapacity estimated number of char16_ts that will be appended
0095      * @return true if the operation succeeded
0096      * @stable ICU 4.8
0097      */
0098     virtual UBool reserveAppendCapacity(int32_t appendCapacity);
0099
0100     /**
0101      * Returns a writable buffer for appending and writes the buffer's capacity to
0102      * *resultCapacity. Guarantees *resultCapacity>=minCapacity.
0103      * May return a pointer to the caller-owned scratch buffer which must have
0104      * scratchCapacity>=minCapacity.
0105      * The returned buffer is only valid until the next operation
0106      * on this Appendable.
0107      *
0108      * After writing at most *resultCapacity char16_ts, call appendString() with the
0109      * pointer returned from this function and the number of char16_ts written.
0110      * Many appendString() implementations will avoid copying char16_ts if this function
0111      * returned an internal buffer.
0112      *
0113      * Partial usage example:
0114      * \code
0115      *  int32_t capacity;
0116      *  char16_t* buffer = app.getAppendBuffer(..., &capacity);
0117      *  ... Write n char16_ts into buffer, with n <= capacity.
0118      *  app.appendString(buffer, n);
0119      * \endcode
0120      * In many implementations, that call to append will avoid copying char16_ts.
0121      *
0122      * If the Appendable allocates or reallocates an internal buffer, it should use
0123      * the desiredCapacityHint if appropriate.
0124      * If a caller cannot provide a reasonable guess at the desired capacity,
0125      * it should pass desiredCapacityHint=0.
0126      *
0127      * If a non-scratch buffer is returned, the caller may only pass
0128      * a prefix to it to appendString().
0129      * That is, it is not correct to pass an interior pointer to appendString().
0130      *
0131      * The default implementation always returns the scratch buffer.
0132      *
0133      * @param minCapacity required minimum capacity of the returned buffer;
0134      *                    must be non-negative
0135      * @param desiredCapacityHint desired capacity of the returned buffer;
0136      *                            must be non-negative
0137      * @param scratch default caller-owned buffer
0138      * @param scratchCapacity capacity of the scratch buffer
0139      * @param resultCapacity pointer to an integer which will be set to the
0140      *                       capacity of the returned buffer
0141      * @return a buffer with *resultCapacity>=minCapacity
0142      * @stable ICU 4.8
0143      */
0144     virtual char16_t *getAppendBuffer(int32_t minCapacity,
0145                                    int32_t desiredCapacityHint,
0146                                    char16_t *scratch, int32_t scratchCapacity,
0147                                    int32_t *resultCapacity);
0148 };
0149
0150 /**
0151  * An Appendable implementation which writes to a UnicodeString.
0152  *
0153  * This class is not intended for public subclassing.
0154  * @stable ICU 4.8
0155  */
0156 class U_COMMON_API UnicodeStringAppendable : public Appendable {
0157 public:
0158     /**
0159      * Aliases the UnicodeString (keeps its reference) for writing.
0160      * @param s The UnicodeString to which this Appendable will write.
0161      * @stable ICU 4.8
0162      */
0163     explicit UnicodeStringAppendable(UnicodeString &s) : str(s) {}
0164
0165     /**
0166      * Destructor.
0167      * @stable ICU 4.8
0168      */
0169     ~UnicodeStringAppendable();
0170
0171     /**
0172      * Appends a 16-bit code unit to the string.
0173      * @param c code unit
0174      * @return true if the operation succeeded
0175      * @stable ICU 4.8
0176      */
0177     virtual UBool appendCodeUnit(char16_t c) override;
0178
0179     /**
0180      * Appends a code point to the string.
0181      * @param c code point 0..0x10ffff
0182      * @return true if the operation succeeded
0183      * @stable ICU 4.8
0184      */
0185     virtual UBool appendCodePoint(UChar32 c) override;
0186
0187     /**
0188      * Appends a string to the UnicodeString.
0189      * @param s string, must not be nullptr if length!=0
0190      * @param length string length, or -1 if NUL-terminated
0191      * @return true if the operation succeeded
0192      * @stable ICU 4.8
0193      */
0194     virtual UBool appendString(const char16_t *s, int32_t length) override;
0195
0196     /**
0197      * Tells the UnicodeString that the caller is going to append roughly
0198      * appendCapacity char16_ts.
0199      * @param appendCapacity estimated number of char16_ts that will be appended
0200      * @return true if the operation succeeded
0201      * @stable ICU 4.8
0202      */
0203     virtual UBool reserveAppendCapacity(int32_t appendCapacity) override;
0204
0205     /**
0206      * Returns a writable buffer for appending and writes the buffer's capacity to
0207      * *resultCapacity. Guarantees *resultCapacity>=minCapacity.
0208      * May return a pointer to the caller-owned scratch buffer which must have
0209      * scratchCapacity>=minCapacity.
0210      * The returned buffer is only valid until the next write operation
0211      * on the UnicodeString.
0212      *
0213      * For details see Appendable::getAppendBuffer().
0214      *
0215      * @param minCapacity required minimum capacity of the returned buffer;
0216      *                    must be non-negative
0217      * @param desiredCapacityHint desired capacity of the returned buffer;
0218      *                            must be non-negative
0219      * @param scratch default caller-owned buffer
0220      * @param scratchCapacity capacity of the scratch buffer
0221      * @param resultCapacity pointer to an integer which will be set to the
0222      *                       capacity of the returned buffer
0223      * @return a buffer with *resultCapacity>=minCapacity
0224      * @stable ICU 4.8
0225      */
0226     virtual char16_t *getAppendBuffer(int32_t minCapacity,
0227                                    int32_t desiredCapacityHint,
0228                                    char16_t *scratch, int32_t scratchCapacity,
0229                                    int32_t *resultCapacity) override;
0230
0231 private:
0232     UnicodeString &str;
0233 };
0234
0235 U_NAMESPACE_END
0236
0237 #endif /* U_SHOW_CPLUSPLUS_API */
0238
0239 #endif  // __APPENDABLE_H__