|
1 /* |
|
2 ************************************************************************** |
|
3 * Copyright (C) 1999-2005, International Business Machines Corporation and |
|
4 * others. All Rights Reserved. |
|
5 ************************************************************************** |
|
6 * Date Name Description |
|
7 * 11/17/99 aliu Creation. Ported from java. Modified to |
|
8 * match current UnicodeString API. Forced |
|
9 * to use name "handleReplaceBetween" because |
|
10 * of existing methods in UnicodeString. |
|
11 ************************************************************************** |
|
12 */ |
|
13 |
|
14 #ifndef REP_H |
|
15 #define REP_H |
|
16 |
|
17 #include "unicode/uobject.h" |
|
18 |
|
19 /** |
|
20 * \file |
|
21 * \brief C++ API: Replaceable String |
|
22 */ |
|
23 |
|
24 U_NAMESPACE_BEGIN |
|
25 |
|
26 class UnicodeString; |
|
27 |
|
28 /** |
|
29 * <code>Replaceable</code> is an abstract base class representing a |
|
30 * string of characters that supports the replacement of a range of |
|
31 * itself with a new string of characters. It is used by APIs that |
|
32 * change a piece of text while retaining metadata. Metadata is data |
|
33 * other than the Unicode characters returned by char32At(). One |
|
34 * example of metadata is style attributes; another is an edit |
|
35 * history, marking each character with an author and revision number. |
|
36 * |
|
37 * <p>An implicit aspect of the <code>Replaceable</code> API is that |
|
38 * during a replace operation, new characters take on the metadata of |
|
39 * the old characters. For example, if the string "the <b>bold</b> |
|
40 * font" has range (4, 8) replaced with "strong", then it becomes "the |
|
41 * <b>strong</b> font". |
|
42 * |
|
43 * <p><code>Replaceable</code> specifies ranges using a start |
|
44 * offset and a limit offset. The range of characters thus specified |
|
45 * includes the characters at offset start..limit-1. That is, the |
|
46 * start offset is inclusive, and the limit offset is exclusive. |
|
47 * |
|
48 * <p><code>Replaceable</code> also includes API to access characters |
|
49 * in the string: <code>length()</code>, <code>charAt()</code>, |
|
50 * <code>char32At()</code>, and <code>extractBetween()</code>. |
|
51 * |
|
52 * <p>For a subclass to support metadata, typical behavior of |
|
53 * <code>replace()</code> is the following: |
|
54 * <ul> |
|
55 * <li>Set the metadata of the new text to the metadata of the first |
|
56 * character replaced</li> |
|
57 * <li>If no characters are replaced, use the metadata of the |
|
58 * previous character</li> |
|
59 * <li>If there is no previous character (i.e. start == 0), use the |
|
60 * following character</li> |
|
61 * <li>If there is no following character (i.e. the replaceable was |
|
62 * empty), use default metadata.<br> |
|
63 * <li>If the code point U+FFFF is seen, it should be interpreted as |
|
64 * a special marker having no metadata<li> |
|
65 * </li> |
|
66 * </ul> |
|
67 * If this is not the behavior, the subclass should document any differences. |
|
68 * @author Alan Liu |
|
69 * @stable ICU 2.0 |
|
70 */ |
|
71 class U_COMMON_API Replaceable : public UObject { |
|
72 |
|
73 public: |
|
74 /** |
|
75 * Destructor. |
|
76 * @stable ICU 2.0 |
|
77 */ |
|
78 virtual ~Replaceable(); |
|
79 |
|
80 /** |
|
81 * Returns the number of 16-bit code units in the text. |
|
82 * @return number of 16-bit code units in text |
|
83 * @stable ICU 1.8 |
|
84 */ |
|
85 inline int32_t length() const; |
|
86 |
|
87 /** |
|
88 * Returns the 16-bit code unit at the given offset into the text. |
|
89 * @param offset an integer between 0 and <code>length()</code>-1 |
|
90 * inclusive |
|
91 * @return 16-bit code unit of text at given offset |
|
92 * @stable ICU 1.8 |
|
93 */ |
|
94 inline UChar charAt(int32_t offset) const; |
|
95 |
|
96 /** |
|
97 * Returns the 32-bit code point at the given 16-bit offset into |
|
98 * the text. This assumes the text is stored as 16-bit code units |
|
99 * with surrogate pairs intermixed. If the offset of a leading or |
|
100 * trailing code unit of a surrogate pair is given, return the |
|
101 * code point of the surrogate pair. |
|
102 * |
|
103 * @param offset an integer between 0 and <code>length()</code>-1 |
|
104 * inclusive |
|
105 * @return 32-bit code point of text at given offset |
|
106 * @stable ICU 1.8 |
|
107 */ |
|
108 inline UChar32 char32At(int32_t offset) const; |
|
109 |
|
110 /** |
|
111 * Copies characters in the range [<tt>start</tt>, <tt>limit</tt>) |
|
112 * into the UnicodeString <tt>target</tt>. |
|
113 * @param start offset of first character which will be copied |
|
114 * @param limit offset immediately following the last character to |
|
115 * be copied |
|
116 * @param target UnicodeString into which to copy characters. |
|
117 * @return A reference to <TT>target</TT> |
|
118 * @stable ICU 2.1 |
|
119 */ |
|
120 virtual void extractBetween(int32_t start, |
|
121 int32_t limit, |
|
122 UnicodeString& target) const = 0; |
|
123 |
|
124 /** |
|
125 * Replaces a substring of this object with the given text. If the |
|
126 * characters being replaced have metadata, the new characters |
|
127 * that replace them should be given the same metadata. |
|
128 * |
|
129 * <p>Subclasses must ensure that if the text between start and |
|
130 * limit is equal to the replacement text, that replace has no |
|
131 * effect. That is, any metadata |
|
132 * should be unaffected. In addition, subclasses are encouraged to |
|
133 * check for initial and trailing identical characters, and make a |
|
134 * smaller replacement if possible. This will preserve as much |
|
135 * metadata as possible. |
|
136 * @param start the beginning index, inclusive; <code>0 <= start |
|
137 * <= limit</code>. |
|
138 * @param limit the ending index, exclusive; <code>start <= limit |
|
139 * <= length()</code>. |
|
140 * @param text the text to replace characters <code>start</code> |
|
141 * to <code>limit - 1</code> |
|
142 * @stable ICU 2.0 |
|
143 */ |
|
144 virtual void handleReplaceBetween(int32_t start, |
|
145 int32_t limit, |
|
146 const UnicodeString& text) = 0; |
|
147 // Note: All other methods in this class take the names of |
|
148 // existing UnicodeString methods. This method is the exception. |
|
149 // It is named differently because all replace methods of |
|
150 // UnicodeString return a UnicodeString&. The 'between' is |
|
151 // required in order to conform to the UnicodeString naming |
|
152 // convention; API taking start/length are named <operation>, and |
|
153 // those taking start/limit are named <operationBetween>. The |
|
154 // 'handle' is added because 'replaceBetween' and |
|
155 // 'doReplaceBetween' are already taken. |
|
156 |
|
157 /** |
|
158 * Copies a substring of this object, retaining metadata. |
|
159 * This method is used to duplicate or reorder substrings. |
|
160 * The destination index must not overlap the source range. |
|
161 * |
|
162 * @param start the beginning index, inclusive; <code>0 <= start <= |
|
163 * limit</code>. |
|
164 * @param limit the ending index, exclusive; <code>start <= limit <= |
|
165 * length()</code>. |
|
166 * @param dest the destination index. The characters from |
|
167 * <code>start..limit-1</code> will be copied to <code>dest</code>. |
|
168 * Implementations of this method may assume that <code>dest <= start || |
|
169 * dest >= limit</code>. |
|
170 * @stable ICU 2.0 |
|
171 */ |
|
172 virtual void copy(int32_t start, int32_t limit, int32_t dest) = 0; |
|
173 |
|
174 /** |
|
175 * Returns true if this object contains metadata. If a |
|
176 * Replaceable object has metadata, calls to the Replaceable API |
|
177 * must be made so as to preserve metadata. If it does not, calls |
|
178 * to the Replaceable API may be optimized to improve performance. |
|
179 * The default implementation returns true. |
|
180 * @return true if this object contains metadata |
|
181 * @stable ICU 2.2 |
|
182 */ |
|
183 virtual UBool hasMetaData() const; |
|
184 |
|
185 /** |
|
186 * Clone this object, an instance of a subclass of Replaceable. |
|
187 * Clones can be used concurrently in multiple threads. |
|
188 * If a subclass does not implement clone(), or if an error occurs, |
|
189 * then NULL is returned. |
|
190 * The clone functions in all subclasses return a pointer to a Replaceable |
|
191 * because some compilers do not support covariant (same-as-this) |
|
192 * return types; cast to the appropriate subclass if necessary. |
|
193 * The caller must delete the clone. |
|
194 * |
|
195 * @return a clone of this object |
|
196 * |
|
197 * @see getDynamicClassID |
|
198 * @stable ICU 2.6 |
|
199 */ |
|
200 virtual Replaceable *clone() const; |
|
201 |
|
202 protected: |
|
203 |
|
204 /** |
|
205 * Default constructor. |
|
206 * @stable ICU 2.4 |
|
207 */ |
|
208 Replaceable(); |
|
209 |
|
210 /* |
|
211 * Assignment operator not declared. The compiler will provide one |
|
212 * which does nothing since this class does not contain any data members. |
|
213 * API/code coverage may show the assignment operator as present and |
|
214 * untested - ignore. |
|
215 * Subclasses need this assignment operator if they use compiler-provided |
|
216 * assignment operators of their own. An alternative to not declaring one |
|
217 * here would be to declare and empty-implement a protected or public one. |
|
218 Replaceable &Replaceable::operator=(const Replaceable &); |
|
219 */ |
|
220 |
|
221 /** |
|
222 * Virtual version of length(). |
|
223 * @stable ICU 2.4 |
|
224 */ |
|
225 virtual int32_t getLength() const = 0; |
|
226 |
|
227 /** |
|
228 * Virtual version of charAt(). |
|
229 * @stable ICU 2.4 |
|
230 */ |
|
231 virtual UChar getCharAt(int32_t offset) const = 0; |
|
232 |
|
233 /** |
|
234 * Virtual version of char32At(). |
|
235 * @stable ICU 2.4 |
|
236 */ |
|
237 virtual UChar32 getChar32At(int32_t offset) const = 0; |
|
238 }; |
|
239 |
|
240 inline int32_t |
|
241 Replaceable::length() const { |
|
242 return getLength(); |
|
243 } |
|
244 |
|
245 inline UChar |
|
246 Replaceable::charAt(int32_t offset) const { |
|
247 return getCharAt(offset); |
|
248 } |
|
249 |
|
250 inline UChar32 |
|
251 Replaceable::char32At(int32_t offset) const { |
|
252 return getChar32At(offset); |
|
253 } |
|
254 |
|
255 // There is no rep.cpp, see unistr.cpp for Replaceable function implementations. |
|
256 |
|
257 U_NAMESPACE_END |
|
258 |
|
259 #endif |