com.ibm.icu.text
public interface Replaceable
Replaceable
is an interface representing a
string of characters that supports the replacement of a range of
itself with a new string of characters. It is used by APIs that
change a piece of text while retaining metadata. Metadata is data
other than the Unicode characters returned by char32At(). One
example of metadata is style attributes; another is an edit
history, marking each character with an author and revision number.
An implicit aspect of the Replaceable
API is that
during a replace operation, new characters take on the metadata of
the old characters. For example, if the string "the bold
font" has range (4, 8) replaced with "strong", then it becomes "the
strong font".
Replaceable
specifies ranges using a start
offset and a limit offset. The range of characters thus specified
includes the characters at offset start..limit-1. That is, the
start offset is inclusive, and the limit offset is exclusive.
Replaceable
also includes API to access characters
in the string: length()
, charAt()
,
char32At()
, and extractBetween()
.
For a subclass to support metadata, typical behavior of
replace()
is the following:
Copyright © IBM Corporation 1999. All rights reserved.
UNKNOWN: ICU 2.0
Method Summary | |
---|---|
int | char32At(int offset)
Returns the 32-bit code point at the given 16-bit offset into
the text. |
char | charAt(int offset)
Returns the 16-bit code unit at the given offset into the text. |
void | copy(int start, int limit, int dest)
Copies a substring of this object, retaining metadata.
|
void | getChars(int srcStart, int srcLimit, char[] dst, int dstStart)
Copies characters from this object into the destination
character array. |
boolean | hasMetaData()
Returns true if this object contains metadata. |
int | length()
Returns the number of 16-bit code units in the text. |
void | replace(int start, int limit, String text)
Replaces a substring of this object with the given text.
|
void | replace(int start, int limit, char[] chars, int charsStart, int charsLen)
Replaces a substring of this object with the given text.
|
Most subclasses can return
com.ibm.icu.text.UTF16.charAt(this, offset)
.
Parameters: offset an integer between 0 and length()
-1
inclusive
Returns: 32-bit code point of text at given offset
UNKNOWN: ICU 2.0
Parameters: offset an integer between 0 and length()
-1
inclusive
Returns: 16-bit code unit of text at given offset
UNKNOWN: ICU 2.0
hasMetaData()
returns false, subclasses
may use the naive implementation:
char[] text = new char[limit - start]; getChars(start, limit, text, 0); replace(dest, dest, text, 0, limit - start);
Parameters: start the beginning index, inclusive; 0 <= start <=
limit
. limit the ending index, exclusive; start <= limit <=
length()
. dest the destination index. The characters from
start..limit-1
will be copied to dest
.
Implementations of this method may assume that dest <= start ||
dest >= limit
.
UNKNOWN: ICU 2.0
srcStart
; the last character to be copied is at
index srcLimit-1
(thus the total number of
characters to be copied is srcLimit-srcStart
). The
characters are copied into the subarray of dst
starting at index dstStart
and ending at index
dstStart + (srcLimit-srcStart) - 1
.
Parameters: srcStart the beginning index to copy, inclusive; 0
<= start <= limit
. srcLimit the ending index to copy, exclusive;
start <= limit <= length()
. dst the destination array. dstStart the start offset in the destination array.
UNKNOWN: ICU 2.0
Returns: true if this object contains metadata
UNKNOWN: ICU 2.2
Returns: number of 16-bit code units in text
UNKNOWN: ICU 2.0
Subclasses must ensure that if the text between start and limit is equal to the replacement text, that replace has no effect. That is, any metadata should be unaffected. In addition, subclasses are encouraged to check for initial and trailing identical characters, and make a smaller replacement if possible. This will preserve as much metadata as possible.
Parameters: start the beginning index, inclusive; 0 <= start
<= limit
. limit the ending index, exclusive; start <= limit
<= length()
. text the text to replace characters start
to limit - 1
UNKNOWN: ICU 2.0
Subclasses must ensure that if the text between start and limit is equal to the replacement text, that replace has no effect. That is, any metadata should be unaffected. In addition, subclasses are encouraged to check for initial and trailing identical characters, and make a smaller replacement if possible. This will preserve as much metadata as possible.
Parameters: start the beginning index, inclusive; 0 <= start
<= limit
. limit the ending index, exclusive; start <= limit
<= length()
. chars the text to replace characters start
to limit - 1
charsStart the beginning index into chars
,
inclusive; 0 <= start <= limit
. charsLen the number of characters of chars
.
UNKNOWN: ICU 2.0