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:
| Modifier and Type | Method and Description |
|---|---|
| public int | Returns: 32-bit code point of text at given offsetan integer between 0 and offset)length()-1
inclusiveReturns the 32-bit code point at the given 16-bit offset into the text. |
| public char | Returns: 16-bit code unit of text at given offsetan integer between 0 and offset)length()-1
inclusiveReturns the 16-bit code unit at the given offset into the text. |
| public void | copy(int
the beginning index, inclusive; start, int 0 <= start <=
limit.the ending index, exclusive; limit, int start <= limit <=
length().the destination index. The characters from
dest)start..limit-1 will be copied to dest.
Implementations of this method may assume that dest <= start ||
dest >= limit.Copies a substring of this object, retaining metadata. |
| public void | getChars(int
the beginning index to copy, inclusive; srcStart, int 0
<= start <= limit.the ending index to copy, exclusive;
srcLimit, char[] start <= limit <= length().the destination array. dst, int the start offset in the destination array. dstStart)Copies characters from this object into the destination character array. |
| public boolean | Returns: true if this object contains metadataR Returns true if this object contains metadata. |
| public int | Returns: number of 16-bit code units in textReturns the number of 16-bit code units in the text. |
| public void | |
| public void | replace(int
the beginning index, inclusive; start, int 0 <= start
<= limit.the ending index, exclusive; limit, char[] start <= limit
<= length().the text to replace characters chars, int start
to limit - 1the beginning index into charsStart, int chars,
inclusive; 0 <= start <= limit.the number of characters of charsLen)chars.Replaces a substring of this object with the given text. |
| char32At | back to summary |
|---|---|
| public int char32At(int offset) Returns the 32-bit code point at the given 16-bit offset into the text. This assumes the text is stored as 16-bit code units with surrogate pairs intermixed. If the offset of a leading or trailing code unit of a surrogate pair is given, return the code point of the surrogate pair. Most subclasses can return
| |
| charAt | back to summary |
|---|---|
| public char charAt(int offset) Returns the 16-bit code unit at the given offset into the text.
| |
| copy | back to summary |
|---|---|
| public void copy(int start, int limit, int dest) Copies a substring of this object, retaining metadata.
This method is used to duplicate or reorder substrings.
The destination index must not overlap the source range.
If char[] text = new char[limit - start]; getChars(start, limit, text, 0); replace(dest, dest, text, 0, limit - start);
| |
| getChars | back to summary |
|---|---|
| public void getChars(int srcStart, int srcLimit, char[] dst, int dstStart) Copies characters from this object into the destination
character array. The first character to be copied is at index
| |
| hasMetaData | back to summary |
|---|---|
| public boolean hasMetaData() R Returns true if this object contains metadata. If a Replaceable object has metadata, calls to the Replaceable API must be made so as to preserve metadata. If it does not, calls to the Replaceable API may be optimized to improve performance.
| |
| length | back to summary |
|---|---|
| public int length() Returns the number of 16-bit code units in the text.
| |
| replace | back to summary |
|---|---|
| public void replace(int start, int limit, String text) Replaces a substring of this object with the given text. 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. | |
| replace | back to summary |
|---|---|
| public void replace(int start, int limit, char[] chars, int charsStart, int charsLen) Replaces a substring of this object with the given text. 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.
| |