Replaceable


1   /*
2    *******************************************************************************
3    * Copyright (C) 1996-2004, International Business Machines Corporation and    *
4    * others. All Rights Reserved.                                                *
5    *******************************************************************************
6    */
7   package com.ibm.icu.text;
8   
9   /**
10   * <code>Replaceable</code> is an interface representing a
11   * string of characters that supports the replacement of a range of
12   * itself with a new string of characters.  It is used by APIs that
13   * change a piece of text while retaining metadata.  Metadata is data
14   * other than the Unicode characters returned by char32At().  One
15   * example of metadata is style attributes; another is an edit
16   * history, marking each character with an author and revision number.
17   *
18   * <p>An implicit aspect of the <code>Replaceable</code> API is that
19   * during a replace operation, new characters take on the metadata of
20   * the old characters.  For example, if the string "the <b>bold</b>
21   * font" has range (4, 8) replaced with "strong", then it becomes "the
22   * <b>strong</b> font".
23   *
24   * <p><code>Replaceable</code> specifies ranges using a start
25   * offset and a limit offset.  The range of characters thus specified
26   * includes the characters at offset start..limit-1.  That is, the
27   * start offset is inclusive, and the limit offset is exclusive.
28   *
29   * <p><code>Replaceable</code> also includes API to access characters
30   * in the string: <code>length()</code>, <code>charAt()</code>,
31   * <code>char32At()</code>, and <code>extractBetween()</code>.
32   *
33   * <p>For a subclass to support metadata, typical behavior of
34   * <code>replace()</code> is the following:
35   * <ul>
36   *   <li>Set the metadata of the new text to the metadata of the first
37   *   character replaced</li>
38   *   <li>If no characters are replaced, use the metadata of the
39   *   previous character</li>
40   *   <li>If there is no previous character (i.e. start == 0), use the
41   *   following character</li>
42   *   <li>If there is no following character (i.e. the replaceable was
43   *   empty), use default metadata<br>
44   *   <li>If the code point U+FFFF is seen, it should be interpreted as
45   *   a special marker having no metadata<li>
46   *   </li>
47   * </ul>
48   * If this is not the behavior, the subclass should document any differences.
49   * 
50   * <p>Copyright &copy; IBM Corporation 1999.  All rights reserved.
51   *
52   * @author Alan Liu
53   * @stable ICU 2.0
54   */
55  public interface Replaceable {
56      /**
57       * Returns the number of 16-bit code units in the text.
58       * @return number of 16-bit code units in text
59       * @stable ICU 2.0
60       */ 
61      int length();
62  
63      /**
64       * Returns the 16-bit code unit at the given offset into the text.
65       * @param offset an integer between 0 and <code>length()</code>-1
66       * inclusive
67       * @return 16-bit code unit of text at given offset
68       * @stable ICU 2.0
69       */
70      char charAt(int offset);
71  
72      /**
73       * Returns the 32-bit code point at the given 16-bit offset into
74       * the text.  This assumes the text is stored as 16-bit code units
75       * with surrogate pairs intermixed.  If the offset of a leading or
76       * trailing code unit of a surrogate pair is given, return the
77       * code point of the surrogate pair.
78       *
79       * <p>Most subclasses can return
80       * <code>com.ibm.icu.text.UTF16.charAt(this, offset)</code>.
81       * @param offset an integer between 0 and <code>length()</code>-1
82       * inclusive
83       * @return 32-bit code point of text at given offset
84       * @stable ICU 2.0
85       */
86      int char32At(int offset);
87  
88      /**
89       * Copies characters from this object into the destination
90       * character array.  The first character to be copied is at index
91       * <code>srcStart</code>; the last character to be copied is at
92       * index <code>srcLimit-1</code> (thus the total number of
93       * characters to be copied is <code>srcLimit-srcStart</code>). The
94       * characters are copied into the subarray of <code>dst</code>
95       * starting at index <code>dstStart</code> and ending at index
96       * <code>dstStart + (srcLimit-srcStart) - 1</code>.
97       *
98       * @param srcStart the beginning index to copy, inclusive; <code>0
99       * <= start <= limit</code>.
100      * @param srcLimit the ending index to copy, exclusive;
101      * <code>start <= limit <= length()</code>.
102      * @param dst the destination array.
103      * @param dstStart the start offset in the destination array.
104      * @stable ICU 2.0
105      */
106     void getChars(int srcStart, int srcLimit, char dst[], int dstStart);
107 
108     /**
109      * Replaces a substring of this object with the given text.
110      *
111      * <p>Subclasses must ensure that if the text between start and
112      * limit is equal to the replacement text, that replace has no
113      * effect. That is, any metadata
114      * should be unaffected. In addition, subclasses are encouraged to
115      * check for initial and trailing identical characters, and make a
116      * smaller replacement if possible. This will preserve as much
117      * metadata as possible.
118      * @param start the beginning index, inclusive; <code>0 <= start
119      * <= limit</code>.
120      * @param limit the ending index, exclusive; <code>start <= limit
121      * <= length()</code>.
122      * @param text the text to replace characters <code>start</code>
123      * to <code>limit - 1</code>
124      * @stable ICU 2.0
125      */
126     void replace(int start, int limit, String   text);
127 
128     /**
129      * Replaces a substring of this object with the given text.
130      *
131      * <p>Subclasses must ensure that if the text between start and
132      * limit is equal to the replacement text, that replace has no
133      * effect. That is, any metadata
134      * should be unaffected. In addition, subclasses are encouraged to
135      * check for initial and trailing identical characters, and make a
136      * smaller replacement if possible. This will preserve as much
137      * metadata as possible.
138      * @param start the beginning index, inclusive; <code>0 <= start
139      * <= limit</code>.
140      * @param limit the ending index, exclusive; <code>start <= limit
141      * <= length()</code>.
142      * @param chars the text to replace characters <code>start</code>
143      * to <code>limit - 1</code>
144      * @param charsStart the beginning index into <code>chars</code>,
145      * inclusive; <code>0 <= start <= limit</code>.
146      * @param charsLen the number of characters of <code>chars</code>.
147      * @stable ICU 2.0
148      */
149     void replace(int start, int limit, char[] chars,
150                  int charsStart, int charsLen);
151     // Note: We use length rather than limit to conform to StringBuffer
152     // and System.arraycopy.
153 
154     /**
155      * Copies a substring of this object, retaining metadata.
156      * This method is used to duplicate or reorder substrings.
157      * The destination index must not overlap the source range.
158      * If <code>hasMetaData()</code> returns false, subclasses
159      * may use the naive implementation:
160      *
161      * <pre> char[] text = new char[limit - start];
162      * getChars(start, limit, text, 0);
163      * replace(dest, dest, text, 0, limit - start);</pre>
164      * 
165      * @param start the beginning index, inclusive; <code>0 <= start <=
166      * limit</code>.
167      * @param limit the ending index, exclusive; <code>start <= limit <=
168      * length()</code>.
169      * @param dest the destination index.  The characters from
170      * <code>start..limit-1</code> will be copied to <code>dest</code>.
171      * Implementations of this method may assume that <code>dest <= start ||
172      * dest >= limit</code>.
173      * @stable ICU 2.0
174      */
175     void copy(int start, int limit, int dest);
176     
177     /**
178      * Returns true if this object contains metadata.  If a
179      * Replaceable object has metadata, calls to the Replaceable API
180      * must be made so as to preserve metadata.  If it does not, calls
181      * to the Replaceable API may be optimized to improve performance.
182      * @return true if this object contains metadata
183      * @stable ICU 2.2
184      */
185     boolean hasMetaData();
186 }
187
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags