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) 1999-2012, International Business Machines Corporation and jpayne@69: * others. All Rights Reserved. jpayne@69: ************************************************************************** jpayne@69: * Date Name Description jpayne@69: * 11/17/99 aliu Creation. Ported from java. Modified to jpayne@69: * match current UnicodeString API. Forced jpayne@69: * to use name "handleReplaceBetween" because jpayne@69: * of existing methods in UnicodeString. jpayne@69: ************************************************************************** jpayne@69: */ jpayne@69: jpayne@69: #ifndef REP_H jpayne@69: #define REP_H 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: /** jpayne@69: * \file jpayne@69: * \brief C++ API: Replaceable String jpayne@69: */ jpayne@69: jpayne@69: U_NAMESPACE_BEGIN jpayne@69: jpayne@69: class UnicodeString; jpayne@69: jpayne@69: /** jpayne@69: * Replaceable is an abstract base class representing a jpayne@69: * string of characters that supports the replacement of a range of jpayne@69: * itself with a new string of characters. It is used by APIs that jpayne@69: * change a piece of text while retaining metadata. Metadata is data jpayne@69: * other than the Unicode characters returned by char32At(). One jpayne@69: * example of metadata is style attributes; another is an edit jpayne@69: * history, marking each character with an author and revision number. jpayne@69: * jpayne@69: *

An implicit aspect of the Replaceable API is that jpayne@69: * during a replace operation, new characters take on the metadata of jpayne@69: * the old characters. For example, if the string "the bold jpayne@69: * font" has range (4, 8) replaced with "strong", then it becomes "the jpayne@69: * strong font". jpayne@69: * jpayne@69: *

Replaceable specifies ranges using a start jpayne@69: * offset and a limit offset. The range of characters thus specified jpayne@69: * includes the characters at offset start..limit-1. That is, the jpayne@69: * start offset is inclusive, and the limit offset is exclusive. jpayne@69: * jpayne@69: *

Replaceable also includes API to access characters jpayne@69: * in the string: length(), charAt(), jpayne@69: * char32At(), and extractBetween(). jpayne@69: * jpayne@69: *

For a subclass to support metadata, typical behavior of jpayne@69: * replace() is the following: jpayne@69: *

jpayne@69: * If this is not the behavior, the subclass should document any differences. jpayne@69: * @author Alan Liu jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: class U_COMMON_API Replaceable : public UObject { jpayne@69: jpayne@69: public: jpayne@69: /** jpayne@69: * Destructor. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual ~Replaceable(); jpayne@69: jpayne@69: /** jpayne@69: * Returns the number of 16-bit code units in the text. jpayne@69: * @return number of 16-bit code units in text jpayne@69: * @stable ICU 1.8 jpayne@69: */ jpayne@69: inline int32_t length() const; jpayne@69: jpayne@69: /** jpayne@69: * Returns the 16-bit code unit at the given offset into the text. jpayne@69: * @param offset an integer between 0 and length()-1 jpayne@69: * inclusive jpayne@69: * @return 16-bit code unit of text at given offset jpayne@69: * @stable ICU 1.8 jpayne@69: */ jpayne@69: inline char16_t charAt(int32_t offset) const; jpayne@69: jpayne@69: /** jpayne@69: * Returns the 32-bit code point at the given 16-bit offset into jpayne@69: * the text. This assumes the text is stored as 16-bit code units jpayne@69: * with surrogate pairs intermixed. If the offset of a leading or jpayne@69: * trailing code unit of a surrogate pair is given, return the jpayne@69: * code point of the surrogate pair. jpayne@69: * jpayne@69: * @param offset an integer between 0 and length()-1 jpayne@69: * inclusive jpayne@69: * @return 32-bit code point of text at given offset jpayne@69: * @stable ICU 1.8 jpayne@69: */ jpayne@69: inline UChar32 char32At(int32_t offset) const; jpayne@69: jpayne@69: /** jpayne@69: * Copies characters in the range [start, limit) jpayne@69: * into the UnicodeString target. jpayne@69: * @param start offset of first character which will be copied jpayne@69: * @param limit offset immediately following the last character to jpayne@69: * be copied jpayne@69: * @param target UnicodeString into which to copy characters. jpayne@69: * @return A reference to target jpayne@69: * @stable ICU 2.1 jpayne@69: */ jpayne@69: virtual void extractBetween(int32_t start, jpayne@69: int32_t limit, jpayne@69: UnicodeString& target) const = 0; jpayne@69: jpayne@69: /** jpayne@69: * Replaces a substring of this object with the given text. If the jpayne@69: * characters being replaced have metadata, the new characters jpayne@69: * that replace them should be given the same metadata. jpayne@69: * jpayne@69: *

Subclasses must ensure that if the text between start and jpayne@69: * limit is equal to the replacement text, that replace has no jpayne@69: * effect. That is, any metadata jpayne@69: * should be unaffected. In addition, subclasses are encouraged to jpayne@69: * check for initial and trailing identical characters, and make a jpayne@69: * smaller replacement if possible. This will preserve as much jpayne@69: * metadata as possible. jpayne@69: * @param start the beginning index, inclusive; 0 <= start jpayne@69: * <= limit. jpayne@69: * @param limit the ending index, exclusive; start <= limit jpayne@69: * <= length(). jpayne@69: * @param text the text to replace characters start jpayne@69: * to limit - 1 jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual void handleReplaceBetween(int32_t start, jpayne@69: int32_t limit, jpayne@69: const UnicodeString& text) = 0; jpayne@69: // Note: All other methods in this class take the names of jpayne@69: // existing UnicodeString methods. This method is the exception. jpayne@69: // It is named differently because all replace methods of jpayne@69: // UnicodeString return a UnicodeString&. The 'between' is jpayne@69: // required in order to conform to the UnicodeString naming jpayne@69: // convention; API taking start/length are named , and jpayne@69: // those taking start/limit are named . The jpayne@69: // 'handle' is added because 'replaceBetween' and jpayne@69: // 'doReplaceBetween' are already taken. jpayne@69: jpayne@69: /** jpayne@69: * Copies a substring of this object, retaining metadata. jpayne@69: * This method is used to duplicate or reorder substrings. jpayne@69: * The destination index must not overlap the source range. jpayne@69: * jpayne@69: * @param start the beginning index, inclusive; 0 <= start <= jpayne@69: * limit. jpayne@69: * @param limit the ending index, exclusive; start <= limit <= jpayne@69: * length(). jpayne@69: * @param dest the destination index. The characters from jpayne@69: * start..limit-1 will be copied to dest. jpayne@69: * Implementations of this method may assume that dest <= start || jpayne@69: * dest >= limit. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: virtual void copy(int32_t start, int32_t limit, int32_t dest) = 0; jpayne@69: jpayne@69: /** jpayne@69: * Returns true if this object contains metadata. If a jpayne@69: * Replaceable object has metadata, calls to the Replaceable API jpayne@69: * must be made so as to preserve metadata. If it does not, calls jpayne@69: * to the Replaceable API may be optimized to improve performance. jpayne@69: * The default implementation returns true. jpayne@69: * @return true if this object contains metadata jpayne@69: * @stable ICU 2.2 jpayne@69: */ jpayne@69: virtual UBool hasMetaData() const; jpayne@69: jpayne@69: /** jpayne@69: * Clone this object, an instance of a subclass of Replaceable. jpayne@69: * Clones can be used concurrently in multiple threads. jpayne@69: * If a subclass does not implement clone(), or if an error occurs, jpayne@69: * then NULL is returned. jpayne@69: * The caller must delete the clone. jpayne@69: * jpayne@69: * @return a clone of this object jpayne@69: * jpayne@69: * @see getDynamicClassID jpayne@69: * @stable ICU 2.6 jpayne@69: */ jpayne@69: virtual Replaceable *clone() const; jpayne@69: jpayne@69: protected: jpayne@69: jpayne@69: /** jpayne@69: * Default constructor. jpayne@69: * @stable ICU 2.4 jpayne@69: */ jpayne@69: inline Replaceable(); jpayne@69: jpayne@69: /* jpayne@69: * Assignment operator not declared. The compiler will provide one jpayne@69: * which does nothing since this class does not contain any data members. jpayne@69: * API/code coverage may show the assignment operator as present and jpayne@69: * untested - ignore. jpayne@69: * Subclasses need this assignment operator if they use compiler-provided jpayne@69: * assignment operators of their own. An alternative to not declaring one jpayne@69: * here would be to declare and empty-implement a protected or public one. jpayne@69: Replaceable &Replaceable::operator=(const Replaceable &); jpayne@69: */ jpayne@69: jpayne@69: /** jpayne@69: * Virtual version of length(). jpayne@69: * @stable ICU 2.4 jpayne@69: */ jpayne@69: virtual int32_t getLength() const = 0; jpayne@69: jpayne@69: /** jpayne@69: * Virtual version of charAt(). jpayne@69: * @stable ICU 2.4 jpayne@69: */ jpayne@69: virtual char16_t getCharAt(int32_t offset) const = 0; jpayne@69: jpayne@69: /** jpayne@69: * Virtual version of char32At(). jpayne@69: * @stable ICU 2.4 jpayne@69: */ jpayne@69: virtual UChar32 getChar32At(int32_t offset) const = 0; jpayne@69: }; jpayne@69: jpayne@69: inline Replaceable::Replaceable() {} jpayne@69: jpayne@69: inline int32_t jpayne@69: Replaceable::length() const { jpayne@69: return getLength(); jpayne@69: } jpayne@69: jpayne@69: inline char16_t jpayne@69: Replaceable::charAt(int32_t offset) const { jpayne@69: return getCharAt(offset); jpayne@69: } jpayne@69: jpayne@69: inline UChar32 jpayne@69: Replaceable::char32At(int32_t offset) const { jpayne@69: return getChar32At(offset); jpayne@69: } jpayne@69: jpayne@69: // There is no rep.cpp, see unistr.cpp for Replaceable function implementations. jpayne@69: jpayne@69: U_NAMESPACE_END jpayne@69: jpayne@69: #endif /* U_SHOW_CPLUSPLUS_API */ jpayne@69: jpayne@69: #endif