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