jpayne@69: // © 2016 and later: Unicode, Inc. and others.
jpayne@69: // License & terms of use: http://www.unicode.org/copyright.html
jpayne@69: /*
jpayne@69: *******************************************************************************
jpayne@69: *   Copyright (C) 2011-2012, International Business Machines
jpayne@69: *   Corporation and others.  All Rights Reserved.
jpayne@69: *******************************************************************************
jpayne@69: *   file name:  appendable.h
jpayne@69: *   encoding:   UTF-8
jpayne@69: *   tab size:   8 (not used)
jpayne@69: *   indentation:4
jpayne@69: *
jpayne@69: *   created on: 2010dec07
jpayne@69: *   created by: Markus W. Scherer
jpayne@69: */
jpayne@69: 
jpayne@69: #ifndef __APPENDABLE_H__
jpayne@69: #define __APPENDABLE_H__
jpayne@69: 
jpayne@69: /**
jpayne@69:  * \file
jpayne@69:  * \brief C++ API: Appendable class: Sink for Unicode code points and 16-bit code units (char16_ts).
jpayne@69:  */
jpayne@69: 
jpayne@69: #include "unicode/utypes.h"
jpayne@69: 
jpayne@69: #if U_SHOW_CPLUSPLUS_API
jpayne@69: 
jpayne@69: #include "unicode/uobject.h"
jpayne@69: 
jpayne@69: U_NAMESPACE_BEGIN
jpayne@69: 
jpayne@69: class UnicodeString;
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Base class for objects to which Unicode characters and strings can be appended.
jpayne@69:  * Combines elements of Java Appendable and ICU4C ByteSink.
jpayne@69:  *
jpayne@69:  * This class can be used in APIs where it does not matter whether the actual destination is
jpayne@69:  * a UnicodeString, a char16_t[] array, a UnicodeSet, or any other object
jpayne@69:  * that receives and processes characters and/or strings.
jpayne@69:  *
jpayne@69:  * Implementation classes must implement at least appendCodeUnit(char16_t).
jpayne@69:  * The base class provides default implementations for the other methods.
jpayne@69:  *
jpayne@69:  * The methods do not take UErrorCode parameters.
jpayne@69:  * If an error occurs (e.g., out-of-memory),
jpayne@69:  * in addition to returning FALSE from failing operations,
jpayne@69:  * the implementation must prevent unexpected behavior (e.g., crashes)
jpayne@69:  * from further calls and should make the error condition available separately
jpayne@69:  * (e.g., store a UErrorCode, make/keep a UnicodeString bogus).
jpayne@69:  * @stable ICU 4.8
jpayne@69:  */
jpayne@69: class U_COMMON_API Appendable : public UObject {
jpayne@69: public:
jpayne@69:     /**
jpayne@69:      * Destructor.
jpayne@69:      * @stable ICU 4.8
jpayne@69:      */
jpayne@69:     ~Appendable();
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * Appends a 16-bit code unit.
jpayne@69:      * @param c code unit
jpayne@69:      * @return TRUE if the operation succeeded
jpayne@69:      * @stable ICU 4.8
jpayne@69:      */
jpayne@69:     virtual UBool appendCodeUnit(char16_t c) = 0;
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * Appends a code point.
jpayne@69:      * The default implementation calls appendCodeUnit(char16_t) once or twice.
jpayne@69:      * @param c code point 0..0x10ffff
jpayne@69:      * @return TRUE if the operation succeeded
jpayne@69:      * @stable ICU 4.8
jpayne@69:      */
jpayne@69:     virtual UBool appendCodePoint(UChar32 c);
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * Appends a string.
jpayne@69:      * The default implementation calls appendCodeUnit(char16_t) for each code unit.
jpayne@69:      * @param s string, must not be NULL if length!=0
jpayne@69:      * @param length string length, or -1 if NUL-terminated
jpayne@69:      * @return TRUE if the operation succeeded
jpayne@69:      * @stable ICU 4.8
jpayne@69:      */
jpayne@69:     virtual UBool appendString(const char16_t *s, int32_t length);
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * Tells the object that the caller is going to append roughly
jpayne@69:      * appendCapacity char16_ts. A subclass might use this to pre-allocate
jpayne@69:      * a larger buffer if necessary.
jpayne@69:      * The default implementation does nothing. (It always returns TRUE.)
jpayne@69:      * @param appendCapacity estimated number of char16_ts that will be appended
jpayne@69:      * @return TRUE if the operation succeeded
jpayne@69:      * @stable ICU 4.8
jpayne@69:      */
jpayne@69:     virtual UBool reserveAppendCapacity(int32_t appendCapacity);
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * Returns a writable buffer for appending and writes the buffer's capacity to
jpayne@69:      * *resultCapacity. Guarantees *resultCapacity>=minCapacity.
jpayne@69:      * May return a pointer to the caller-owned scratch buffer which must have
jpayne@69:      * scratchCapacity>=minCapacity.
jpayne@69:      * The returned buffer is only valid until the next operation
jpayne@69:      * on this Appendable.
jpayne@69:      *
jpayne@69:      * After writing at most *resultCapacity char16_ts, call appendString() with the
jpayne@69:      * pointer returned from this function and the number of char16_ts written.
jpayne@69:      * Many appendString() implementations will avoid copying char16_ts if this function
jpayne@69:      * returned an internal buffer.
jpayne@69:      *
jpayne@69:      * Partial usage example:
jpayne@69:      * \code
jpayne@69:      *  int32_t capacity;
jpayne@69:      *  char16_t* buffer = app.getAppendBuffer(..., &capacity);
jpayne@69:      *  ... Write n char16_ts into buffer, with n <= capacity.
jpayne@69:      *  app.appendString(buffer, n);
jpayne@69:      * \endcode
jpayne@69:      * In many implementations, that call to append will avoid copying char16_ts.
jpayne@69:      *
jpayne@69:      * If the Appendable allocates or reallocates an internal buffer, it should use
jpayne@69:      * the desiredCapacityHint if appropriate.
jpayne@69:      * If a caller cannot provide a reasonable guess at the desired capacity,
jpayne@69:      * it should pass desiredCapacityHint=0.
jpayne@69:      *
jpayne@69:      * If a non-scratch buffer is returned, the caller may only pass
jpayne@69:      * a prefix to it to appendString().
jpayne@69:      * That is, it is not correct to pass an interior pointer to appendString().
jpayne@69:      *
jpayne@69:      * The default implementation always returns the scratch buffer.
jpayne@69:      *
jpayne@69:      * @param minCapacity required minimum capacity of the returned buffer;
jpayne@69:      *                    must be non-negative
jpayne@69:      * @param desiredCapacityHint desired capacity of the returned buffer;
jpayne@69:      *                            must be non-negative
jpayne@69:      * @param scratch default caller-owned buffer
jpayne@69:      * @param scratchCapacity capacity of the scratch buffer
jpayne@69:      * @param resultCapacity pointer to an integer which will be set to the
jpayne@69:      *                       capacity of the returned buffer
jpayne@69:      * @return a buffer with *resultCapacity>=minCapacity
jpayne@69:      * @stable ICU 4.8
jpayne@69:      */
jpayne@69:     virtual char16_t *getAppendBuffer(int32_t minCapacity,
jpayne@69:                                    int32_t desiredCapacityHint,
jpayne@69:                                    char16_t *scratch, int32_t scratchCapacity,
jpayne@69:                                    int32_t *resultCapacity);
jpayne@69: };
jpayne@69: 
jpayne@69: /**
jpayne@69:  * An Appendable implementation which writes to a UnicodeString.
jpayne@69:  *
jpayne@69:  * This class is not intended for public subclassing.
jpayne@69:  * @stable ICU 4.8
jpayne@69:  */
jpayne@69: class U_COMMON_API UnicodeStringAppendable : public Appendable {
jpayne@69: public:
jpayne@69:     /**
jpayne@69:      * Aliases the UnicodeString (keeps its reference) for writing.
jpayne@69:      * @param s The UnicodeString to which this Appendable will write.
jpayne@69:      * @stable ICU 4.8
jpayne@69:      */
jpayne@69:     explicit UnicodeStringAppendable(UnicodeString &s) : str(s) {}
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * Destructor.
jpayne@69:      * @stable ICU 4.8
jpayne@69:      */
jpayne@69:     ~UnicodeStringAppendable();
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * Appends a 16-bit code unit to the string.
jpayne@69:      * @param c code unit
jpayne@69:      * @return TRUE if the operation succeeded
jpayne@69:      * @stable ICU 4.8
jpayne@69:      */
jpayne@69:     virtual UBool appendCodeUnit(char16_t c);
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * Appends a code point to the string.
jpayne@69:      * @param c code point 0..0x10ffff
jpayne@69:      * @return TRUE if the operation succeeded
jpayne@69:      * @stable ICU 4.8
jpayne@69:      */
jpayne@69:     virtual UBool appendCodePoint(UChar32 c);
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * Appends a string to the UnicodeString.
jpayne@69:      * @param s string, must not be NULL if length!=0
jpayne@69:      * @param length string length, or -1 if NUL-terminated
jpayne@69:      * @return TRUE if the operation succeeded
jpayne@69:      * @stable ICU 4.8
jpayne@69:      */
jpayne@69:     virtual UBool appendString(const char16_t *s, int32_t length);
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * Tells the UnicodeString that the caller is going to append roughly
jpayne@69:      * appendCapacity char16_ts.
jpayne@69:      * @param appendCapacity estimated number of char16_ts that will be appended
jpayne@69:      * @return TRUE if the operation succeeded
jpayne@69:      * @stable ICU 4.8
jpayne@69:      */
jpayne@69:     virtual UBool reserveAppendCapacity(int32_t appendCapacity);
jpayne@69: 
jpayne@69:     /**
jpayne@69:      * Returns a writable buffer for appending and writes the buffer's capacity to
jpayne@69:      * *resultCapacity. Guarantees *resultCapacity>=minCapacity.
jpayne@69:      * May return a pointer to the caller-owned scratch buffer which must have
jpayne@69:      * scratchCapacity>=minCapacity.
jpayne@69:      * The returned buffer is only valid until the next write operation
jpayne@69:      * on the UnicodeString.
jpayne@69:      *
jpayne@69:      * For details see Appendable::getAppendBuffer().
jpayne@69:      *
jpayne@69:      * @param minCapacity required minimum capacity of the returned buffer;
jpayne@69:      *                    must be non-negative
jpayne@69:      * @param desiredCapacityHint desired capacity of the returned buffer;
jpayne@69:      *                            must be non-negative
jpayne@69:      * @param scratch default caller-owned buffer
jpayne@69:      * @param scratchCapacity capacity of the scratch buffer
jpayne@69:      * @param resultCapacity pointer to an integer which will be set to the
jpayne@69:      *                       capacity of the returned buffer
jpayne@69:      * @return a buffer with *resultCapacity>=minCapacity
jpayne@69:      * @stable ICU 4.8
jpayne@69:      */
jpayne@69:     virtual char16_t *getAppendBuffer(int32_t minCapacity,
jpayne@69:                                    int32_t desiredCapacityHint,
jpayne@69:                                    char16_t *scratch, int32_t scratchCapacity,
jpayne@69:                                    int32_t *resultCapacity);
jpayne@69: 
jpayne@69: private:
jpayne@69:     UnicodeString &str;
jpayne@69: };
jpayne@69: 
jpayne@69: U_NAMESPACE_END
jpayne@69: 
jpayne@69: #endif /* U_SHOW_CPLUSPLUS_API */
jpayne@69: 
jpayne@69: #endif  // __APPENDABLE_H__