Replaceable is an abstract base class representing a
michael@0: * string of characters that supports the replacement of a range of
michael@0: * itself with a new string of characters. It is used by APIs that
michael@0: * change a piece of text while retaining metadata. Metadata is data
michael@0: * other than the Unicode characters returned by char32At(). One
michael@0: * example of metadata is style attributes; another is an edit
michael@0: * history, marking each character with an author and revision number.
michael@0: *
michael@0: * An implicit aspect of the Replaceable API is that
michael@0: * during a replace operation, new characters take on the metadata of
michael@0: * the old characters. For example, if the string "the bold
michael@0: * font" has range (4, 8) replaced with "strong", then it becomes "the
michael@0: * strong font".
michael@0: *
michael@0: *
Replaceable specifies ranges using a start
michael@0: * offset and a limit offset. The range of characters thus specified
michael@0: * includes the characters at offset start..limit-1. That is, the
michael@0: * start offset is inclusive, and the limit offset is exclusive.
michael@0: *
michael@0: *
Replaceable also includes API to access characters
michael@0: * in the string: length(), charAt(),
michael@0: * char32At(), and extractBetween().
michael@0: *
michael@0: *
For a subclass to support metadata, typical behavior of
michael@0: * replace() is the following:
michael@0: *
length()-1
michael@0: * inclusive
michael@0: * @return 16-bit code unit of text at given offset
michael@0: * @stable ICU 1.8
michael@0: */
michael@0: inline UChar charAt(int32_t offset) const;
michael@0:
michael@0: /**
michael@0: * Returns the 32-bit code point at the given 16-bit offset into
michael@0: * the text. This assumes the text is stored as 16-bit code units
michael@0: * with surrogate pairs intermixed. If the offset of a leading or
michael@0: * trailing code unit of a surrogate pair is given, return the
michael@0: * code point of the surrogate pair.
michael@0: *
michael@0: * @param offset an integer between 0 and length()-1
michael@0: * inclusive
michael@0: * @return 32-bit code point of text at given offset
michael@0: * @stable ICU 1.8
michael@0: */
michael@0: inline UChar32 char32At(int32_t offset) const;
michael@0:
michael@0: /**
michael@0: * Copies characters in the range [start, limit)
michael@0: * into the UnicodeString target.
michael@0: * @param start offset of first character which will be copied
michael@0: * @param limit offset immediately following the last character to
michael@0: * be copied
michael@0: * @param target UnicodeString into which to copy characters.
michael@0: * @return A reference to target
michael@0: * @stable ICU 2.1
michael@0: */
michael@0: virtual void extractBetween(int32_t start,
michael@0: int32_t limit,
michael@0: UnicodeString& target) const = 0;
michael@0:
michael@0: /**
michael@0: * Replaces a substring of this object with the given text. If the
michael@0: * characters being replaced have metadata, the new characters
michael@0: * that replace them should be given the same metadata.
michael@0: *
michael@0: * Subclasses must ensure that if the text between start and
michael@0: * limit is equal to the replacement text, that replace has no
michael@0: * effect. That is, any metadata
michael@0: * should be unaffected. In addition, subclasses are encouraged to
michael@0: * check for initial and trailing identical characters, and make a
michael@0: * smaller replacement if possible. This will preserve as much
michael@0: * metadata as possible.
michael@0: * @param start the beginning index, inclusive; 0 <= start
michael@0: * <= limit.
michael@0: * @param limit the ending index, exclusive; start <= limit
michael@0: * <= length().
michael@0: * @param text the text to replace characters start
michael@0: * to limit - 1
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: virtual void handleReplaceBetween(int32_t start,
michael@0: int32_t limit,
michael@0: const UnicodeString& text) = 0;
michael@0: // Note: All other methods in this class take the names of
michael@0: // existing UnicodeString methods. This method is the exception.
michael@0: // It is named differently because all replace methods of
michael@0: // UnicodeString return a UnicodeString&. The 'between' is
michael@0: // required in order to conform to the UnicodeString naming
michael@0: // convention; API taking start/length are named 0 <= start <=
michael@0: * limit.
michael@0: * @param limit the ending index, exclusive; start <= limit <=
michael@0: * length().
michael@0: * @param dest the destination index. The characters from
michael@0: * start..limit-1 will be copied to dest.
michael@0: * Implementations of this method may assume that dest <= start ||
michael@0: * dest >= limit.
michael@0: * @stable ICU 2.0
michael@0: */
michael@0: virtual void copy(int32_t start, int32_t limit, int32_t dest) = 0;
michael@0:
michael@0: /**
michael@0: * Returns true if this object contains metadata. If a
michael@0: * Replaceable object has metadata, calls to the Replaceable API
michael@0: * must be made so as to preserve metadata. If it does not, calls
michael@0: * to the Replaceable API may be optimized to improve performance.
michael@0: * The default implementation returns true.
michael@0: * @return true if this object contains metadata
michael@0: * @stable ICU 2.2
michael@0: */
michael@0: virtual UBool hasMetaData() const;
michael@0:
michael@0: /**
michael@0: * Clone this object, an instance of a subclass of Replaceable.
michael@0: * Clones can be used concurrently in multiple threads.
michael@0: * If a subclass does not implement clone(), or if an error occurs,
michael@0: * then NULL is returned.
michael@0: * The clone functions in all subclasses return a pointer to a Replaceable
michael@0: * because some compilers do not support covariant (same-as-this)
michael@0: * return types; cast to the appropriate subclass if necessary.
michael@0: * The caller must delete the clone.
michael@0: *
michael@0: * @return a clone of this object
michael@0: *
michael@0: * @see getDynamicClassID
michael@0: * @stable ICU 2.6
michael@0: */
michael@0: virtual Replaceable *clone() const;
michael@0:
michael@0: protected:
michael@0:
michael@0: /**
michael@0: * Default constructor.
michael@0: * @stable ICU 2.4
michael@0: */
michael@0: inline Replaceable();
michael@0:
michael@0: /*
michael@0: * Assignment operator not declared. The compiler will provide one
michael@0: * which does nothing since this class does not contain any data members.
michael@0: * API/code coverage may show the assignment operator as present and
michael@0: * untested - ignore.
michael@0: * Subclasses need this assignment operator if they use compiler-provided
michael@0: * assignment operators of their own. An alternative to not declaring one
michael@0: * here would be to declare and empty-implement a protected or public one.
michael@0: Replaceable &Replaceable::operator=(const Replaceable &);
michael@0: */
michael@0:
michael@0: /**
michael@0: * Virtual version of length().
michael@0: * @stable ICU 2.4
michael@0: */
michael@0: virtual int32_t getLength() const = 0;
michael@0:
michael@0: /**
michael@0: * Virtual version of charAt().
michael@0: * @stable ICU 2.4
michael@0: */
michael@0: virtual UChar getCharAt(int32_t offset) const = 0;
michael@0:
michael@0: /**
michael@0: * Virtual version of char32At().
michael@0: * @stable ICU 2.4
michael@0: */
michael@0: virtual UChar32 getChar32At(int32_t offset) const = 0;
michael@0: };
michael@0:
michael@0: inline Replaceable::Replaceable() {}
michael@0:
michael@0: inline int32_t
michael@0: Replaceable::length() const {
michael@0: return getLength();
michael@0: }
michael@0:
michael@0: inline UChar
michael@0: Replaceable::charAt(int32_t offset) const {
michael@0: return getCharAt(offset);
michael@0: }
michael@0:
michael@0: inline UChar32
michael@0: Replaceable::char32At(int32_t offset) const {
michael@0: return getChar32At(offset);
michael@0: }
michael@0:
michael@0: // There is no rep.cpp, see unistr.cpp for Replaceable function implementations.
michael@0:
michael@0: U_NAMESPACE_END
michael@0:
michael@0: #endif