← Back to branch summary

~ubuntu-branches/ubuntu/raring/qtwebkit-source/raring-proposed

« back to all changes in this revision

Viewing changes to Source/WebCore/icu/unicode/rep.h

  • Committer: Package Import Robot
  • Author(s): Jonathan Riddell
  • Date: 2013-02-18 14:24:18 UTC
  • Revision ID: package-import@ubuntu.com-20130218142418-eon0jmjg3nj438uy
Tags: upstream-2.3
Import upstream version 2.3

Show diffs side-by-side

added added

removed removed

Lines of Context:
Source/WebCore/icu/unicode/rep.h
 
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