| OLD | NEW |
|---|
| (Empty) |
| 1 /* | |
| 2 ********************************************************************** | |
| 3 * Copyright (C) 1999-2008, International Business Machines | |
| 4 * Corporation and others. All Rights Reserved. | |
| 5 ********************************************************************** | |
| 6 * Date Name Description | |
| 7 * 11/17/99 aliu Creation. | |
| 8 ********************************************************************** | |
| 9 */ | |
| 10 #ifndef TRANSLIT_H | |
| 11 #define TRANSLIT_H | |
| 12 | |
| 13 #include "unicode/utypes.h" | |
| 14 | |
| 15 /** | |
| 16 * \file | |
| 17 * \brief C++ API: Tranforms text from one format to another. | |
| 18 */ | |
| 19 | |
| 20 #if !UCONFIG_NO_TRANSLITERATION | |
| 21 | |
| 22 #include "unicode/uobject.h" | |
| 23 #include "unicode/unistr.h" | |
| 24 #include "unicode/parseerr.h" | |
| 25 #include "unicode/utrans.h" // UTransPosition, UTransDirection | |
| 26 #include "unicode/strenum.h" | |
| 27 | |
| 28 U_NAMESPACE_BEGIN | |
| 29 | |
| 30 class UnicodeFilter; | |
| 31 class UnicodeSet; | |
| 32 class CompoundTransliterator; | |
| 33 class TransliteratorParser; | |
| 34 class NormalizationTransliterator; | |
| 35 class TransliteratorIDParser; | |
| 36 | |
| 37 /** | |
| 38 * | |
| 39 * <code>Transliterator</code> is an abstract class that | |
| 40 * transliterates text from one format to another. The most common | |
| 41 * kind of transliterator is a script, or alphabet, transliterator. | |
| 42 * For example, a Russian to Latin transliterator changes Russian text | |
| 43 * written in Cyrillic characters to phonetically equivalent Latin | |
| 44 * characters. It does not <em>translate</em> Russian to English! | |
| 45 * Transliteration, unlike translation, operates on characters, without | |
| 46 * reference to the meanings of words and sentences. | |
| 47 * | |
| 48 * <p>Although script conversion is its most common use, a | |
| 49 * transliterator can actually perform a more general class of tasks. | |
| 50 * In fact, <code>Transliterator</code> defines a very general API | |
| 51 * which specifies only that a segment of the input text is replaced | |
| 52 * by new text. The particulars of this conversion are determined | |
| 53 * entirely by subclasses of <code>Transliterator</code>. | |
| 54 * | |
| 55 * <p><b>Transliterators are stateless</b> | |
| 56 * | |
| 57 * <p><code>Transliterator</code> objects are <em>stateless</em>; they | |
| 58 * retain no information between calls to | |
| 59 * <code>transliterate()</code>. (However, this does <em>not</em> | |
| 60 * mean that threads may share transliterators without synchronizing | |
| 61 * them. Transliterators are not immutable, so they must be | |
| 62 * synchronized when shared between threads.) This might seem to | |
| 63 * limit the complexity of the transliteration operation. In | |
| 64 * practice, subclasses perform complex transliterations by delaying | |
| 65 * the replacement of text until it is known that no other | |
| 66 * replacements are possible. In other words, although the | |
| 67 * <code>Transliterator</code> objects are stateless, the source text | |
| 68 * itself embodies all the needed information, and delayed operation | |
| 69 * allows arbitrary complexity. | |
| 70 * | |
| 71 * <p><b>Batch transliteration</b> | |
| 72 * | |
| 73 * <p>The simplest way to perform transliteration is all at once, on a | |
| 74 * string of existing text. This is referred to as <em>batch</em> | |
| 75 * transliteration. For example, given a string <code>input</code> | |
| 76 * and a transliterator <code>t</code>, the call | |
| 77 * | |
| 78 * \htmlonly<blockquote>\endhtmlonly<code>String result = t.transliterate(input)
; | |
| 79 * </code>\htmlonly</blockquote>\endhtmlonly | |
| 80 * | |
| 81 * will transliterate it and return the result. Other methods allow | |
| 82 * the client to specify a substring to be transliterated and to use | |
| 83 * {@link Replaceable } objects instead of strings, in order to | |
| 84 * preserve out-of-band information (such as text styles). | |
| 85 * | |
| 86 * <p><b>Keyboard transliteration</b> | |
| 87 * | |
| 88 * <p>Somewhat more involved is <em>keyboard</em>, or incremental | |
| 89 * transliteration. This is the transliteration of text that is | |
| 90 * arriving from some source (typically the user's keyboard) one | |
| 91 * character at a time, or in some other piecemeal fashion. | |
| 92 * | |
| 93 * <p>In keyboard transliteration, a <code>Replaceable</code> buffer | |
| 94 * stores the text. As text is inserted, as much as possible is | |
| 95 * transliterated on the fly. This means a GUI that displays the | |
| 96 * contents of the buffer may show text being modified as each new | |
| 97 * character arrives. | |
| 98 * | |
| 99 * <p>Consider the simple <code>RuleBasedTransliterator</code>: | |
| 100 * | |
| 101 * \htmlonly<blockquote>\endhtmlonly<code> | |
| 102 * th>{theta}<br> | |
| 103 * t>{tau} | |
| 104 * </code>\htmlonly</blockquote>\endhtmlonly | |
| 105 * | |
| 106 * When the user types 't', nothing will happen, since the | |
| 107 * transliterator is waiting to see if the next character is 'h'. To | |
| 108 * remedy this, we introduce the notion of a cursor, marked by a '|' | |
| 109 * in the output string: | |
| 110 * | |
| 111 * \htmlonly<blockquote>\endhtmlonly<code> | |
| 112 * t>|{tau}<br> | |
| 113 * {tau}h>{theta} | |
| 114 * </code>\htmlonly</blockquote>\endhtmlonly | |
| 115 * | |
| 116 * Now when the user types 't', tau appears, and if the next character | |
| 117 * is 'h', the tau changes to a theta. This is accomplished by | |
| 118 * maintaining a cursor position (independent of the insertion point, | |
| 119 * and invisible in the GUI) across calls to | |
| 120 * <code>transliterate()</code>. Typically, the cursor will | |
| 121 * be coincident with the insertion point, but in a case like the one | |
| 122 * above, it will precede the insertion point. | |
| 123 * | |
| 124 * <p>Keyboard transliteration methods maintain a set of three indices | |
| 125 * that are updated with each call to | |
| 126 * <code>transliterate()</code>, including the cursor, start, | |
| 127 * and limit. Since these indices are changed by the method, they are | |
| 128 * passed in an <code>int[]</code> array. The <code>START</code> index | |
| 129 * marks the beginning of the substring that the transliterator will | |
| 130 * look at. It is advanced as text becomes committed (but it is not | |
| 131 * the committed index; that's the <code>CURSOR</code>). The | |
| 132 * <code>CURSOR</code> index, described above, marks the point at | |
| 133 * which the transliterator last stopped, either because it reached | |
| 134 * the end, or because it required more characters to disambiguate | |
| 135 * between possible inputs. The <code>CURSOR</code> can also be | |
| 136 * explicitly set by rules in a <code>RuleBasedTransliterator</code>. | |
| 137 * Any characters before the <code>CURSOR</code> index are frozen; | |
| 138 * future keyboard transliteration calls within this input sequence | |
| 139 * will not change them. New text is inserted at the | |
| 140 * <code>LIMIT</code> index, which marks the end of the substring that | |
| 141 * the transliterator looks at. | |
| 142 * | |
| 143 * <p>Because keyboard transliteration assumes that more characters | |
| 144 * are to arrive, it is conservative in its operation. It only | |
| 145 * transliterates when it can do so unambiguously. Otherwise it waits | |
| 146 * for more characters to arrive. When the client code knows that no | |
| 147 * more characters are forthcoming, perhaps because the user has | |
| 148 * performed some input termination operation, then it should call | |
| 149 * <code>finishTransliteration()</code> to complete any | |
| 150 * pending transliterations. | |
| 151 * | |
| 152 * <p><b>Inverses</b> | |
| 153 * | |
| 154 * <p>Pairs of transliterators may be inverses of one another. For | |
| 155 * example, if transliterator <b>A</b> transliterates characters by | |
| 156 * incrementing their Unicode value (so "abc" -> "def"), and | |
| 157 * transliterator <b>B</b> decrements character values, then <b>A</b> | |
| 158 * is an inverse of <b>B</b> and vice versa. If we compose <b>A</b> | |
| 159 * with <b>B</b> in a compound transliterator, the result is the | |
| 160 * indentity transliterator, that is, a transliterator that does not | |
| 161 * change its input text. | |
| 162 * | |
| 163 * The <code>Transliterator</code> method <code>getInverse()</code> | |
| 164 * returns a transliterator's inverse, if one exists, or | |
| 165 * <code>null</code> otherwise. However, the result of | |
| 166 * <code>getInverse()</code> usually will <em>not</em> be a true | |
| 167 * mathematical inverse. This is because true inverse transliterators | |
| 168 * are difficult to formulate. For example, consider two | |
| 169 * transliterators: <b>AB</b>, which transliterates the character 'A' | |
| 170 * to 'B', and <b>BA</b>, which transliterates 'B' to 'A'. It might | |
| 171 * seem that these are exact inverses, since | |
| 172 * | |
| 173 * \htmlonly<blockquote>\endhtmlonly"A" x <b>AB</b> -> "B"<br> | |
| 174 * "B" x <b>BA</b> -> "A"\htmlonly</blockquote>\endhtmlonly | |
| 175 * | |
| 176 * where 'x' represents transliteration. However, | |
| 177 * | |
| 178 * \htmlonly<blockquote>\endhtmlonly"ABCD" x <b>AB</b> -> "BBCD"<br> | |
| 179 * "BBCD" x <b>BA</b> -> "AACD"\htmlonly</blockquote>\endhtmlonly | |
| 180 * | |
| 181 * so <b>AB</b> composed with <b>BA</b> is not the | |
| 182 * identity. Nonetheless, <b>BA</b> may be usefully considered to be | |
| 183 * <b>AB</b>'s inverse, and it is on this basis that | |
| 184 * <b>AB</b><code>.getInverse()</code> could legitimately return | |
| 185 * <b>BA</b>. | |
| 186 * | |
| 187 * <p><b>IDs and display names</b> | |
| 188 * | |
| 189 * <p>A transliterator is designated by a short identifier string or | |
| 190 * <em>ID</em>. IDs follow the format <em>source-destination</em>, | |
| 191 * where <em>source</em> describes the entity being replaced, and | |
| 192 * <em>destination</em> describes the entity replacing | |
| 193 * <em>source</em>. The entities may be the names of scripts, | |
| 194 * particular sequences of characters, or whatever else it is that the | |
| 195 * transliterator converts to or from. For example, a transliterator | |
| 196 * from Russian to Latin might be named "Russian-Latin". A | |
| 197 * transliterator from keyboard escape sequences to Latin-1 characters | |
| 198 * might be named "KeyboardEscape-Latin1". By convention, system | |
| 199 * entity names are in English, with the initial letters of words | |
| 200 * capitalized; user entity names may follow any format so long as | |
| 201 * they do not contain dashes. | |
| 202 * | |
| 203 * <p>In addition to programmatic IDs, transliterator objects have | |
| 204 * display names for presentation in user interfaces, returned by | |
| 205 * {@link #getDisplayName }. | |
| 206 * | |
| 207 * <p><b>Factory methods and registration</b> | |
| 208 * | |
| 209 * <p>In general, client code should use the factory method | |
| 210 * {@link #createInstance } to obtain an instance of a | |
| 211 * transliterator given its ID. Valid IDs may be enumerated using | |
| 212 * <code>getAvailableIDs()</code>. Since transliterators are mutable, | |
| 213 * multiple calls to {@link #createInstance } with the same ID will | |
| 214 * return distinct objects. | |
| 215 * | |
| 216 * <p>In addition to the system transliterators registered at startup, | |
| 217 * user transliterators may be registered by calling | |
| 218 * <code>registerInstance()</code> at run time. A registered instance | |
| 219 * acts a template; future calls to {@link #createInstance } with the ID | |
| 220 * of the registered object return clones of that object. Thus any | |
| 221 * object passed to <tt>registerInstance()</tt> must implement | |
| 222 * <tt>clone()</tt> propertly. To register a transliterator subclass | |
| 223 * without instantiating it (until it is needed), users may call | |
| 224 * {@link #registerFactory }. In this case, the objects are | |
| 225 * instantiated by invoking the zero-argument public constructor of | |
| 226 * the class. | |
| 227 * | |
| 228 * <p><b>Subclassing</b> | |
| 229 * | |
| 230 * Subclasses must implement the abstract method | |
| 231 * <code>handleTransliterate()</code>. <p>Subclasses should override | |
| 232 * the <code>transliterate()</code> method taking a | |
| 233 * <code>Replaceable</code> and the <code>transliterate()</code> | |
| 234 * method taking a <code>String</code> and <code>StringBuffer</code> | |
| 235 * if the performance of these methods can be improved over the | |
| 236 * performance obtained by the default implementations in this class. | |
| 237 * | |
| 238 * @author Alan Liu | |
| 239 * @stable ICU 2.0 | |
| 240 */ | |
| 241 class U_I18N_API Transliterator : public UObject { | |
| 242 | |
| 243 private: | |
| 244 | |
| 245 /** | |
| 246 * Programmatic name, e.g., "Latin-Arabic". | |
| 247 */ | |
| 248 UnicodeString ID; | |
| 249 | |
| 250 /** | |
| 251 * This transliterator's filter. Any character for which | |
| 252 * <tt>filter.contains()</tt> returns <tt>false</tt> will not be | |
| 253 * altered by this transliterator. If <tt>filter</tt> is | |
| 254 * <tt>null</tt> then no filtering is applied. | |
| 255 */ | |
| 256 UnicodeFilter* filter; | |
| 257 | |
| 258 int32_t maximumContextLength; | |
| 259 | |
| 260 public: | |
| 261 | |
| 262 /** | |
| 263 * A context integer or pointer for a factory function, passed by | |
| 264 * value. | |
| 265 * @stable ICU 2.4 | |
| 266 */ | |
| 267 union Token { | |
| 268 /** | |
| 269 * This token, interpreted as a 32-bit integer. | |
| 270 * @stable ICU 2.4 | |
| 271 */ | |
| 272 int32_t integer; | |
| 273 /** | |
| 274 * This token, interpreted as a native pointer. | |
| 275 * @stable ICU 2.4 | |
| 276 */ | |
| 277 void* pointer; | |
| 278 }; | |
| 279 | |
| 280 /** | |
| 281 * Return a token containing an integer. | |
| 282 * @return a token containing an integer. | |
| 283 * @internal | |
| 284 */ | |
| 285 inline static Token integerToken(int32_t); | |
| 286 | |
| 287 /** | |
| 288 * Return a token containing a pointer. | |
| 289 * @return a token containing a pointer. | |
| 290 * @internal | |
| 291 */ | |
| 292 inline static Token pointerToken(void*); | |
| 293 | |
| 294 /** | |
| 295 * A function that creates and returns a Transliterator. When | |
| 296 * invoked, it will be passed the ID string that is being | |
| 297 * instantiated, together with the context pointer that was passed | |
| 298 * in when the factory function was first registered. Many | |
| 299 * factory functions will ignore both parameters, however, | |
| 300 * functions that are registered to more than one ID may use the | |
| 301 * ID or the context parameter to parameterize the transliterator | |
| 302 * they create. | |
| 303 * @param ID the string identifier for this transliterator | |
| 304 * @param context a context pointer that will be stored and | |
| 305 * later passed to the factory function when an ID matching | |
| 306 * the registration ID is being instantiated with this factor
y. | |
| 307 * @stable ICU 2.4 | |
| 308 */ | |
| 309 typedef Transliterator* (U_EXPORT2 *Factory)(const UnicodeString& ID, Token
context); | |
| 310 | |
| 311 protected: | |
| 312 | |
| 313 /** | |
| 314 * Default constructor. | |
| 315 * @param ID the string identifier for this transliterator | |
| 316 * @param adoptedFilter the filter. Any character for which | |
| 317 * <tt>filter.contains()</tt> returns <tt>false</tt> will not be | |
| 318 * altered by this transliterator. If <tt>filter</tt> is | |
| 319 * <tt>null</tt> then no filtering is applied. | |
| 320 * @stable ICU 2.4 | |
| 321 */ | |
| 322 Transliterator(const UnicodeString& ID, UnicodeFilter* adoptedFilter); | |
| 323 | |
| 324 /** | |
| 325 * Copy constructor. | |
| 326 * @stable ICU 2.4 | |
| 327 */ | |
| 328 Transliterator(const Transliterator&); | |
| 329 | |
| 330 /** | |
| 331 * Assignment operator. | |
| 332 * @stable ICU 2.4 | |
| 333 */ | |
| 334 Transliterator& operator=(const Transliterator&); | |
| 335 | |
| 336 /** | |
| 337 * Create a transliterator from a basic ID. This is an ID | |
| 338 * containing only the forward direction source, target, and | |
| 339 * variant. | |
| 340 * @param id a basic ID of the form S-T or S-T/V. | |
| 341 * @param canon canonical ID to assign to the object, or | |
| 342 * NULL to leave the ID unchanged | |
| 343 * @return a newly created Transliterator or null if the ID is | |
| 344 * invalid. | |
| 345 * @stable ICU 2.4 | |
| 346 */ | |
| 347 static Transliterator* createBasicInstance(const UnicodeString& id, | |
| 348 const UnicodeString* canon); | |
| 349 | |
| 350 friend class TransliteratorParser; // for parseID() | |
| 351 friend class TransliteratorIDParser; // for createBasicInstance() | |
| 352 friend class TransliteratorAlias; // for setID() | |
| 353 | |
| 354 public: | |
| 355 | |
| 356 /** | |
| 357 * Destructor. | |
| 358 * @stable ICU 2.0 | |
| 359 */ | |
| 360 virtual ~Transliterator(); | |
| 361 | |
| 362 /** | |
| 363 * Implements Cloneable. | |
| 364 * All subclasses are encouraged to implement this method if it is | |
| 365 * possible and reasonable to do so. Subclasses that are to be | |
| 366 * registered with the system using <tt>registerInstance()</tt> | |
| 367 * are required to implement this method. If a subclass does not | |
| 368 * implement clone() properly and is registered with the system | |
| 369 * using registerInstance(), then the default clone() implementation | |
| 370 * will return null, and calls to createInstance() will fail. | |
| 371 * | |
| 372 * @return a copy of the object. | |
| 373 * @see #registerInstance | |
| 374 * @stable ICU 2.0 | |
| 375 */ | |
| 376 virtual Transliterator* clone() const; | |
| 377 | |
| 378 /** | |
| 379 * Transliterates a segment of a string, with optional filtering. | |
| 380 * | |
| 381 * @param text the string to be transliterated | |
| 382 * @param start the beginning index, inclusive; <code>0 <= start | |
| 383 * <= limit</code>. | |
| 384 * @param limit the ending index, exclusive; <code>start <= limit | |
| 385 * <= text.length()</code>. | |
| 386 * @return The new limit index. The text previously occupying <code>[start, | |
| 387 * limit)</code> has been transliterated, possibly to a string of a differen
t | |
| 388 * length, at <code>[start, </code><em>new-limit</em><code>)</code>, where | |
| 389 * <em>new-limit</em> is the return value. If the input offsets are out of b
ounds, | |
| 390 * the returned value is -1 and the input string remains unchanged. | |
| 391 * @stable ICU 2.0 | |
| 392 */ | |
| 393 virtual int32_t transliterate(Replaceable& text, | |
| 394 int32_t start, int32_t limit) const; | |
| 395 | |
| 396 /** | |
| 397 * Transliterates an entire string in place. Convenience method. | |
| 398 * @param text the string to be transliterated | |
| 399 * @stable ICU 2.0 | |
| 400 */ | |
| 401 virtual void transliterate(Replaceable& text) const; | |
| 402 | |
| 403 /** | |
| 404 * Transliterates the portion of the text buffer that can be | |
| 405 * transliterated unambiguosly after new text has been inserted, | |
| 406 * typically as a result of a keyboard event. The new text in | |
| 407 * <code>insertion</code> will be inserted into <code>text</code> | |
| 408 * at <code>index.limit</code>, advancing | |
| 409 * <code>index.limit</code> by <code>insertion.length()</code>. | |
| 410 * Then the transliterator will try to transliterate characters of | |
| 411 * <code>text</code> between <code>index.cursor</code> and | |
| 412 * <code>index.limit</code>. Characters before | |
| 413 * <code>index.cursor</code> will not be changed. | |
| 414 * | |
| 415 * <p>Upon return, values in <code>index</code> will be updated. | |
| 416 * <code>index.start</code> will be advanced to the first | |
| 417 * character that future calls to this method will read. | |
| 418 * <code>index.cursor</code> and <code>index.limit</code> will | |
| 419 * be adjusted to delimit the range of text that future calls to | |
| 420 * this method may change. | |
| 421 * | |
| 422 * <p>Typical usage of this method begins with an initial call | |
| 423 * with <code>index.start</code> and <code>index.limit</code> | |
| 424 * set to indicate the portion of <code>text</code> to be | |
| 425 * transliterated, and <code>index.cursor == index.start</code>. | |
| 426 * Thereafter, <code>index</code> can be used without | |
| 427 * modification in future calls, provided that all changes to | |
| 428 * <code>text</code> are made via this method. | |
| 429 * | |
| 430 * <p>This method assumes that future calls may be made that will | |
| 431 * insert new text into the buffer. As a result, it only performs | |
| 432 * unambiguous transliterations. After the last call to this | |
| 433 * method, there may be untransliterated text that is waiting for | |
| 434 * more input to resolve an ambiguity. In order to perform these | |
| 435 * pending transliterations, clients should call {@link | |
| 436 * #finishTransliteration } after the last call to this | |
| 437 * method has been made. | |
| 438 * | |
| 439 * @param text the buffer holding transliterated and untransliterated text | |
| 440 * @param index an array of three integers. | |
| 441 * | |
| 442 * <ul><li><code>index.start</code>: the beginning index, | |
| 443 * inclusive; <code>0 <= index.start <= index.limit</code>. | |
| 444 * | |
| 445 * <li><code>index.limit</code>: the ending index, exclusive; | |
| 446 * <code>index.start <= index.limit <= text.length()</code>. | |
| 447 * <code>insertion</code> is inserted at | |
| 448 * <code>index.limit</code>. | |
| 449 * | |
| 450 * <li><code>index.cursor</code>: the next character to be | |
| 451 * considered for transliteration; <code>index.start <= | |
| 452 * index.cursor <= index.limit</code>. Characters before | |
| 453 * <code>index.cursor</code> will not be changed by future calls | |
| 454 * to this method.</ul> | |
| 455 * | |
| 456 * @param insertion text to be inserted and possibly | |
| 457 * transliterated into the translation buffer at | |
| 458 * <code>index.limit</code>. If <code>null</code> then no text | |
| 459 * is inserted. | |
| 460 * @param status Output param to filled in with a success or an error. | |
| 461 * @see #handleTransliterate | |
| 462 * @exception IllegalArgumentException if <code>index</code> | |
| 463 * is invalid | |
| 464 * @see UTransPosition | |
| 465 * @stable ICU 2.0 | |
| 466 */ | |
| 467 virtual void transliterate(Replaceable& text, UTransPosition& index, | |
| 468 const UnicodeString& insertion, | |
| 469 UErrorCode& status) const; | |
| 470 | |
| 471 /** | |
| 472 * Transliterates the portion of the text buffer that can be | |
| 473 * transliterated unambiguosly after a new character has been | |
| 474 * inserted, typically as a result of a keyboard event. This is a | |
| 475 * convenience method. | |
| 476 * @param text the buffer holding transliterated and | |
| 477 * untransliterated text | |
| 478 * @param index an array of three integers. | |
| 479 * @param insertion text to be inserted and possibly | |
| 480 * transliterated into the translation buffer at | |
| 481 * <code>index.limit</code>. | |
| 482 * @param status Output param to filled in with a success or an error. | |
| 483 * @see #transliterate(Replaceable&, UTransPosition&, const UnicodeString&,
UErrorCode&) const | |
| 484 * @stable ICU 2.0 | |
| 485 */ | |
| 486 virtual void transliterate(Replaceable& text, UTransPosition& index, | |
| 487 UChar32 insertion, | |
| 488 UErrorCode& status) const; | |
| 489 | |
| 490 /** | |
| 491 * Transliterates the portion of the text buffer that can be | |
| 492 * transliterated unambiguosly. This is a convenience method; see | |
| 493 * {@link | |
| 494 * #transliterate(Replaceable&, UTransPosition&, const UnicodeString&, UErro
rCode&) const } | |
| 495 * for details. | |
| 496 * @param text the buffer holding transliterated and | |
| 497 * untransliterated text | |
| 498 * @param index an array of three integers. See {@link | |
| 499 * #transliterate(Replaceable&, UTransPosition&, const UnicodeString&, UErro
rCode&) const }. | |
| 500 * @param status Output param to filled in with a success or an error. | |
| 501 * @see #transliterate(Replaceable, int[], String) | |
| 502 * @stable ICU 2.0 | |
| 503 */ | |
| 504 virtual void transliterate(Replaceable& text, UTransPosition& index, | |
| 505 UErrorCode& status) const; | |
| 506 | |
| 507 /** | |
| 508 * Finishes any pending transliterations that were waiting for | |
| 509 * more characters. Clients should call this method as the last | |
| 510 * call after a sequence of one or more calls to | |
| 511 * <code>transliterate()</code>. | |
| 512 * @param text the buffer holding transliterated and | |
| 513 * untransliterated text. | |
| 514 * @param index the array of indices previously passed to {@link | |
| 515 * #transliterate } | |
| 516 * @stable ICU 2.0 | |
| 517 */ | |
| 518 virtual void finishTransliteration(Replaceable& text, | |
| 519 UTransPosition& index) const; | |
| 520 | |
| 521 private: | |
| 522 | |
| 523 /** | |
| 524 * This internal method does incremental transliteration. If the | |
| 525 * 'insertion' is non-null then we append it to 'text' before | |
| 526 * proceeding. This method calls through to the pure virtual | |
| 527 * framework method handleTransliterate() to do the actual | |
| 528 * work. | |
| 529 * @param text the buffer holding transliterated and | |
| 530 * untransliterated text | |
| 531 * @param index an array of three integers. See {@link | |
| 532 * #transliterate(Replaceable, int[], String)}. | |
| 533 * @param insertion text to be inserted and possibly | |
| 534 * transliterated into the translation buffer at | |
| 535 * <code>index.limit</code>. | |
| 536 * @param status Output param to filled in with a success or an error. | |
| 537 */ | |
| 538 void _transliterate(Replaceable& text, | |
| 539 UTransPosition& index, | |
| 540 const UnicodeString* insertion, | |
| 541 UErrorCode &status) const; | |
| 542 | |
| 543 protected: | |
| 544 | |
| 545 /** | |
| 546 * Abstract method that concrete subclasses define to implement | |
| 547 * their transliteration algorithm. This method handles both | |
| 548 * incremental and non-incremental transliteration. Let | |
| 549 * <code>originalStart</code> refer to the value of | |
| 550 * <code>pos.start</code> upon entry. | |
| 551 * | |
| 552 * <ul> | |
| 553 * <li>If <code>incremental</code> is false, then this method | |
| 554 * should transliterate all characters between | |
| 555 * <code>pos.start</code> and <code>pos.limit</code>. Upon return | |
| 556 * <code>pos.start</code> must == <code> pos.limit</code>.</li> | |
| 557 * | |
| 558 * <li>If <code>incremental</code> is true, then this method | |
| 559 * should transliterate all characters between | |
| 560 * <code>pos.start</code> and <code>pos.limit</code> that can be | |
| 561 * unambiguously transliterated, regardless of future insertions | |
| 562 * of text at <code>pos.limit</code>. Upon return, | |
| 563 * <code>pos.start</code> should be in the range | |
| 564 * [<code>originalStart</code>, <code>pos.limit</code>). | |
| 565 * <code>pos.start</code> should be positioned such that | |
| 566 * characters [<code>originalStart</code>, <code> | |
| 567 * pos.start</code>) will not be changed in the future by this | |
| 568 * transliterator and characters [<code>pos.start</code>, | |
| 569 * <code>pos.limit</code>) are unchanged.</li> | |
| 570 * </ul> | |
| 571 * | |
| 572 * <p>Implementations of this method should also obey the | |
| 573 * following invariants:</p> | |
| 574 * | |
| 575 * <ul> | |
| 576 * <li> <code>pos.limit</code> and <code>pos.contextLimit</code> | |
| 577 * should be updated to reflect changes in length of the text | |
| 578 * between <code>pos.start</code> and <code>pos.limit</code>. The | |
| 579 * difference <code> pos.contextLimit - pos.limit</code> should | |
| 580 * not change.</li> | |
| 581 * | |
| 582 * <li><code>pos.contextStart</code> should not change.</li> | |
| 583 * | |
| 584 * <li>Upon return, neither <code>pos.start</code> nor | |
| 585 * <code>pos.limit</code> should be less than | |
| 586 * <code>originalStart</code>.</li> | |
| 587 * | |
| 588 * <li>Text before <code>originalStart</code> and text after | |
| 589 * <code>pos.limit</code> should not change.</li> | |
| 590 * | |
| 591 * <li>Text before <code>pos.contextStart</code> and text after | |
| 592 * <code> pos.contextLimit</code> should be ignored.</li> | |
| 593 * </ul> | |
| 594 * | |
| 595 * <p>Subclasses may safely assume that all characters in | |
| 596 * [<code>pos.start</code>, <code>pos.limit</code>) are filtered. | |
| 597 * In other words, the filter has already been applied by the time | |
| 598 * this method is called. See | |
| 599 * <code>filteredTransliterate()</code>. | |
| 600 * | |
| 601 * <p>This method is <b>not</b> for public consumption. Calling | |
| 602 * this method directly will transliterate | |
| 603 * [<code>pos.start</code>, <code>pos.limit</code>) without | |
| 604 * applying the filter. End user code should call <code> | |
| 605 * transliterate()</code> instead of this method. Subclass code | |
| 606 * and wrapping transliterators should call | |
| 607 * <code>filteredTransliterate()</code> instead of this method.<p> | |
| 608 * | |
| 609 * @param text the buffer holding transliterated and | |
| 610 * untransliterated text | |
| 611 * | |
| 612 * @param pos the indices indicating the start, limit, context | |
| 613 * start, and context limit of the text. | |
| 614 * | |
| 615 * @param incremental if true, assume more text may be inserted at | |
| 616 * <code>pos.limit</code> and act accordingly. Otherwise, | |
| 617 * transliterate all text between <code>pos.start</code> and | |
| 618 * <code>pos.limit</code> and move <code>pos.start</code> up to | |
| 619 * <code>pos.limit</code>. | |
| 620 * | |
| 621 * @see #transliterate | |
| 622 * @stable ICU 2.4 | |
| 623 */ | |
| 624 virtual void handleTransliterate(Replaceable& text, | |
| 625 UTransPosition& pos, | |
| 626 UBool incremental) const = 0; | |
| 627 | |
| 628 public: | |
| 629 /** | |
| 630 * Transliterate a substring of text, as specified by index, taking filters | |
| 631 * into account. This method is for subclasses that need to delegate to | |
| 632 * another transliterator, such as CompoundTransliterator. | |
| 633 * @param text the text to be transliterated | |
| 634 * @param index the position indices | |
| 635 * @param incremental if TRUE, then assume more characters may be inserted | |
| 636 * at index.limit, and postpone processing to accomodate future incoming | |
| 637 * characters | |
| 638 * @stable ICU 2.4 | |
| 639 */ | |
| 640 virtual void filteredTransliterate(Replaceable& text, | |
| 641 UTransPosition& index, | |
| 642 UBool incremental) const; | |
| 643 | |
| 644 private: | |
| 645 | |
| 646 /** | |
| 647 * Top-level transliteration method, handling filtering, incremental and | |
| 648 * non-incremental transliteration, and rollback. All transliteration | |
| 649 * public API methods eventually call this method with a rollback argument | |
| 650 * of TRUE. Other entities may call this method but rollback should be | |
| 651 * FALSE. | |
| 652 * | |
| 653 * <p>If this transliterator has a filter, break up the input text into runs | |
| 654 * of unfiltered characters. Pass each run to | |
| 655 * <subclass>.handleTransliterate(). | |
| 656 * | |
| 657 * <p>In incremental mode, if rollback is TRUE, perform a special | |
| 658 * incremental procedure in which several passes are made over the input | |
| 659 * text, adding one character at a time, and committing successful | |
| 660 * transliterations as they occur. Unsuccessful transliterations are rolled | |
| 661 * back and retried with additional characters to give correct results. | |
| 662 * | |
| 663 * @param text the text to be transliterated | |
| 664 * @param index the position indices | |
| 665 * @param incremental if TRUE, then assume more characters may be inserted | |
| 666 * at index.limit, and postpone processing to accomodate future incoming | |
| 667 * characters | |
| 668 * @param rollback if TRUE and if incremental is TRUE, then perform special | |
| 669 * incremental processing, as described above, and undo partial | |
| 670 * transliterations where necessary. If incremental is FALSE then this | |
| 671 * parameter is ignored. | |
| 672 */ | |
| 673 virtual void filteredTransliterate(Replaceable& text, | |
| 674 UTransPosition& index, | |
| 675 UBool incremental, | |
| 676 UBool rollback) const; | |
| 677 | |
| 678 public: | |
| 679 | |
| 680 /** | |
| 681 * Returns the length of the longest context required by this transliterator
. | |
| 682 * This is <em>preceding</em> context. The default implementation supplied | |
| 683 * by <code>Transliterator</code> returns zero; subclasses | |
| 684 * that use preceding context should override this method to return the | |
| 685 * correct value. For example, if a transliterator translates "ddd" (where | |
| 686 * d is any digit) to "555" when preceded by "(ddd)", then the preceding | |
| 687 * context length is 5, the length of "(ddd)". | |
| 688 * | |
| 689 * @return The maximum number of preceding context characters this | |
| 690 * transliterator needs to examine | |
| 691 * @stable ICU 2.0 | |
| 692 */ | |
| 693 int32_t getMaximumContextLength(void) const; | |
| 694 | |
| 695 protected: | |
| 696 | |
| 697 /** | |
| 698 * Method for subclasses to use to set the maximum context length. | |
| 699 * @param maxContextLength the new value to be set. | |
| 700 * @see #getMaximumContextLength | |
| 701 * @stable ICU 2.4 | |
| 702 */ | |
| 703 void setMaximumContextLength(int32_t maxContextLength); | |
| 704 | |
| 705 public: | |
| 706 | |
| 707 /** | |
| 708 * Returns a programmatic identifier for this transliterator. | |
| 709 * If this identifier is passed to <code>createInstance()</code>, it | |
| 710 * will return this object, if it has been registered. | |
| 711 * @return a programmatic identifier for this transliterator. | |
| 712 * @see #registerInstance | |
| 713 * @see #registerFactory | |
| 714 * @see #getAvailableIDs | |
| 715 * @stable ICU 2.0 | |
| 716 */ | |
| 717 virtual const UnicodeString& getID(void) const; | |
| 718 | |
| 719 /** | |
| 720 * Returns a name for this transliterator that is appropriate for | |
| 721 * display to the user in the default locale. See {@link | |
| 722 * #getDisplayName } for details. | |
| 723 * @param ID the string identifier for this transliterator | |
| 724 * @param result Output param to receive the display name | |
| 725 * @return A reference to 'result'. | |
| 726 * @stable ICU 2.0 | |
| 727 */ | |
| 728 static UnicodeString& U_EXPORT2 getDisplayName(const UnicodeString& ID, | |
| 729 UnicodeString& result); | |
| 730 | |
| 731 /** | |
| 732 * Returns a name for this transliterator that is appropriate for | |
| 733 * display to the user in the given locale. This name is taken | |
| 734 * from the locale resource data in the standard manner of the | |
| 735 * <code>java.text</code> package. | |
| 736 * | |
| 737 * <p>If no localized names exist in the system resource bundles, | |
| 738 * a name is synthesized using a localized | |
| 739 * <code>MessageFormat</code> pattern from the resource data. The | |
| 740 * arguments to this pattern are an integer followed by one or two | |
| 741 * strings. The integer is the number of strings, either 1 or 2. | |
| 742 * The strings are formed by splitting the ID for this | |
| 743 * transliterator at the first '-'. If there is no '-', then the | |
| 744 * entire ID forms the only string. | |
| 745 * @param ID the string identifier for this transliterator | |
| 746 * @param inLocale the Locale in which the display name should be | |
| 747 * localized. | |
| 748 * @param result Output param to receive the display name | |
| 749 * @return A reference to 'result'. | |
| 750 * @stable ICU 2.0 | |
| 751 */ | |
| 752 static UnicodeString& U_EXPORT2 getDisplayName(const UnicodeString& ID, | |
| 753 const Locale& inLocale, | |
| 754 UnicodeString& result); | |
| 755 | |
| 756 /** | |
| 757 * Returns the filter used by this transliterator, or <tt>NULL</tt> | |
| 758 * if this transliterator uses no filter. | |
| 759 * @return the filter used by this transliterator, or <tt>NULL</tt> | |
| 760 * if this transliterator uses no filter. | |
| 761 * @stable ICU 2.0 | |
| 762 */ | |
| 763 const UnicodeFilter* getFilter(void) const; | |
| 764 | |
| 765 /** | |
| 766 * Returns the filter used by this transliterator, or <tt>NULL</tt> if this | |
| 767 * transliterator uses no filter. The caller must eventually delete the | |
| 768 * result. After this call, this transliterator's filter is set to | |
| 769 * <tt>NULL</tt>. | |
| 770 * @return the filter used by this transliterator, or <tt>NULL</tt> if this | |
| 771 * transliterator uses no filter. | |
| 772 * @stable ICU 2.4 | |
| 773 */ | |
| 774 UnicodeFilter* orphanFilter(void); | |
| 775 | |
| 776 /** | |
| 777 * Changes the filter used by this transliterator. If the filter | |
| 778 * is set to <tt>null</tt> then no filtering will occur. | |
| 779 * | |
| 780 * <p>Callers must take care if a transliterator is in use by | |
| 781 * multiple threads. The filter should not be changed by one | |
| 782 * thread while another thread may be transliterating. | |
| 783 * @param adoptedFilter the new filter to be adopted. | |
| 784 * @stable ICU 2.0 | |
| 785 */ | |
| 786 void adoptFilter(UnicodeFilter* adoptedFilter); | |
| 787 | |
| 788 /** | |
| 789 * Returns this transliterator's inverse. See the class | |
| 790 * documentation for details. This implementation simply inverts | |
| 791 * the two entities in the ID and attempts to retrieve the | |
| 792 * resulting transliterator. That is, if <code>getID()</code> | |
| 793 * returns "A-B", then this method will return the result of | |
| 794 * <code>createInstance("B-A")</code>, or <code>null</code> if that | |
| 795 * call fails. | |
| 796 * | |
| 797 * <p>Subclasses with knowledge of their inverse may wish to | |
| 798 * override this method. | |
| 799 * | |
| 800 * @param status Output param to filled in with a success or an error. | |
| 801 * @return a transliterator that is an inverse, not necessarily | |
| 802 * exact, of this transliterator, or <code>null</code> if no such | |
| 803 * transliterator is registered. | |
| 804 * @see #registerInstance | |
| 805 * @stable ICU 2.0 | |
| 806 */ | |
| 807 Transliterator* createInverse(UErrorCode& status) const; | |
| 808 | |
| 809 /** | |
| 810 * Returns a <code>Transliterator</code> object given its ID. | |
| 811 * The ID must be either a system transliterator ID or a ID registered | |
| 812 * using <code>registerInstance()</code>. | |
| 813 * | |
| 814 * @param ID a valid ID, as enumerated by <code>getAvailableIDs()</code> | |
| 815 * @param dir either FORWARD or REVERSE. | |
| 816 * @param parseError Struct to recieve information on position | |
| 817 * of error if an error is encountered | |
| 818 * @param status Output param to filled in with a success or an error. | |
| 819 * @return A <code>Transliterator</code> object with the given ID | |
| 820 * @see #registerInstance | |
| 821 * @see #getAvailableIDs | |
| 822 * @see #getID | |
| 823 * @stable ICU 2.0 | |
| 824 */ | |
| 825 static Transliterator* U_EXPORT2 createInstance(const UnicodeString& ID, | |
| 826 UTransDirection dir, | |
| 827 UParseError& parseError, | |
| 828 UErrorCode& status); | |
| 829 | |
| 830 /** | |
| 831 * Returns a <code>Transliterator</code> object given its ID. | |
| 832 * The ID must be either a system transliterator ID or a ID registered | |
| 833 * using <code>registerInstance()</code>. | |
| 834 * @param ID a valid ID, as enumerated by <code>getAvailableIDs()</code> | |
| 835 * @param dir either FORWARD or REVERSE. | |
| 836 * @param status Output param to filled in with a success or an error. | |
| 837 * @return A <code>Transliterator</code> object with the given ID | |
| 838 * @stable ICU 2.0 | |
| 839 */ | |
| 840 static Transliterator* U_EXPORT2 createInstance(const UnicodeString& ID, | |
| 841 UTransDirection dir, | |
| 842 UErrorCode& status); | |
| 843 | |
| 844 /** | |
| 845 * Returns a <code>Transliterator</code> object constructed from | |
| 846 * the given rule string. This will be a RuleBasedTransliterator, | |
| 847 * if the rule string contains only rules, or a | |
| 848 * CompoundTransliterator, if it contains ID blocks, or a | |
| 849 * NullTransliterator, if it contains ID blocks which parse as | |
| 850 * empty for the given direction. | |
| 851 * @param ID the id for the transliterator. | |
| 852 * @param rules rules, separated by ';' | |
| 853 * @param dir either FORWARD or REVERSE. | |
| 854 * @param parseError Struct to recieve information on position | |
| 855 * of error if an error is encountered | |
| 856 * @param status Output param set to success/failure code. | |
| 857 * @stable ICU 2.0 | |
| 858 */ | |
| 859 static Transliterator* U_EXPORT2 createFromRules(const UnicodeString& ID, | |
| 860 const UnicodeString& rules, | |
| 861 UTransDirection dir, | |
| 862 UParseError& parseError, | |
| 863 UErrorCode& status); | |
| 864 | |
| 865 /** | |
| 866 * Create a rule string that can be passed to createFromRules() | |
| 867 * to recreate this transliterator. | |
| 868 * @param result the string to receive the rules. Previous | |
| 869 * contents will be deleted. | |
| 870 * @param escapeUnprintable if TRUE then convert unprintable | |
| 871 * character to their hex escape representations, \\uxxxx or | |
| 872 * \\Uxxxxxxxx. Unprintable characters are those other than | |
| 873 * U+000A, U+0020..U+007E. | |
| 874 * @stable ICU 2.0 | |
| 875 */ | |
| 876 virtual UnicodeString& toRules(UnicodeString& result, | |
| 877 UBool escapeUnprintable) const; | |
| 878 | |
| 879 /** | |
| 880 * Return the number of elements that make up this transliterator. | |
| 881 * For example, if the transliterator "NFD;Jamo-Latin;Latin-Greek" | |
| 882 * were created, the return value of this method would be 3. | |
| 883 * | |
| 884 * <p>If this transliterator is not composed of other | |
| 885 * transliterators, then this method returns 1. | |
| 886 * @return the number of transliterators that compose this | |
| 887 * transliterator, or 1 if this transliterator is not composed of | |
| 888 * multiple transliterators | |
| 889 * @stable ICU 3.0 | |
| 890 */ | |
| 891 int32_t countElements() const; | |
| 892 | |
| 893 /** | |
| 894 * Return an element that makes up this transliterator. For | |
| 895 * example, if the transliterator "NFD;Jamo-Latin;Latin-Greek" | |
| 896 * were created, the return value of this method would be one | |
| 897 * of the three transliterator objects that make up that | |
| 898 * transliterator: [NFD, Jamo-Latin, Latin-Greek]. | |
| 899 * | |
| 900 * <p>If this transliterator is not composed of other | |
| 901 * transliterators, then this method will return a reference to | |
| 902 * this transliterator when given the index 0. | |
| 903 * @param index a value from 0..countElements()-1 indicating the | |
| 904 * transliterator to return | |
| 905 * @param ec input-output error code | |
| 906 * @return one of the transliterators that makes up this | |
| 907 * transliterator, if this transliterator is made up of multiple | |
| 908 * transliterators, otherwise a reference to this object if given | |
| 909 * an index of 0 | |
| 910 * @stable ICU 3.0 | |
| 911 */ | |
| 912 const Transliterator& getElement(int32_t index, UErrorCode& ec) const; | |
| 913 | |
| 914 /** | |
| 915 * Returns the set of all characters that may be modified in the | |
| 916 * input text by this Transliterator. This incorporates this | |
| 917 * object's current filter; if the filter is changed, the return | |
| 918 * value of this function will change. The default implementation | |
| 919 * returns an empty set. Some subclasses may override {@link | |
| 920 * #handleGetSourceSet } to return a more precise result. The | |
| 921 * return result is approximate in any case and is intended for | |
| 922 * use by tests, tools, or utilities. | |
| 923 * @param result receives result set; previous contents lost | |
| 924 * @return a reference to result | |
| 925 * @see #getTargetSet | |
| 926 * @see #handleGetSourceSet | |
| 927 * @stable ICU 2.4 | |
| 928 */ | |
| 929 UnicodeSet& getSourceSet(UnicodeSet& result) const; | |
| 930 | |
| 931 /** | |
| 932 * Framework method that returns the set of all characters that | |
| 933 * may be modified in the input text by this Transliterator, | |
| 934 * ignoring the effect of this object's filter. The base class | |
| 935 * implementation returns the empty set. Subclasses that wish to | |
| 936 * implement this should override this method. | |
| 937 * @return the set of characters that this transliterator may | |
| 938 * modify. The set may be modified, so subclasses should return a | |
| 939 * newly-created object. | |
| 940 * @param result receives result set; previous contents lost | |
| 941 * @see #getSourceSet | |
| 942 * @see #getTargetSet | |
| 943 * @stable ICU 2.4 | |
| 944 */ | |
| 945 virtual void handleGetSourceSet(UnicodeSet& result) const; | |
| 946 | |
| 947 /** | |
| 948 * Returns the set of all characters that may be generated as | |
| 949 * replacement text by this transliterator. The default | |
| 950 * implementation returns the empty set. Some subclasses may | |
| 951 * override this method to return a more precise result. The | |
| 952 * return result is approximate in any case and is intended for | |
| 953 * use by tests, tools, or utilities requiring such | |
| 954 * meta-information. | |
| 955 * @param result receives result set; previous contents lost | |
| 956 * @return a reference to result | |
| 957 * @see #getTargetSet | |
| 958 * @stable ICU 2.4 | |
| 959 */ | |
| 960 virtual UnicodeSet& getTargetSet(UnicodeSet& result) const; | |
| 961 | |
| 962 public: | |
| 963 | |
| 964 /** | |
| 965 * Registers a factory function that creates transliterators of | |
| 966 * a given ID. | |
| 967 * @param id the ID being registered | |
| 968 * @param factory a function pointer that will be copied and | |
| 969 * called later when the given ID is passed to createInstance() | |
| 970 * @param context a context pointer that will be stored and | |
| 971 * later passed to the factory function when an ID matching | |
| 972 * the registration ID is being instantiated with this factory. | |
| 973 * @stable ICU 2.0 | |
| 974 */ | |
| 975 static void U_EXPORT2 registerFactory(const UnicodeString& id, | |
| 976 Factory factory, | |
| 977 Token context); | |
| 978 | |
| 979 /** | |
| 980 * Registers an instance <tt>obj</tt> of a subclass of | |
| 981 * <code>Transliterator</code> with the system. When | |
| 982 * <tt>createInstance()</tt> is called with an ID string that is | |
| 983 * equal to <tt>obj->getID()</tt>, then <tt>obj->clone()</tt> is | |
| 984 * returned. | |
| 985 * | |
| 986 * After this call the Transliterator class owns the adoptedObj | |
| 987 * and will delete it. | |
| 988 * | |
| 989 * @param adoptedObj an instance of subclass of | |
| 990 * <code>Transliterator</code> that defines <tt>clone()</tt> | |
| 991 * @see #createInstance | |
| 992 * @see #registerFactory | |
| 993 * @see #unregister | |
| 994 * @stable ICU 2.0 | |
| 995 */ | |
| 996 static void U_EXPORT2 registerInstance(Transliterator* adoptedObj); | |
| 997 | |
| 998 /** | |
| 999 * Registers an ID string as an alias of another ID string. | |
| 1000 * That is, after calling this function, <tt>createInstance(aliasID)</tt> | |
| 1001 * will return the same thing as <tt>createInstance(realID)</tt>. | |
| 1002 * This is generally used to create shorter, more mnemonic aliases | |
| 1003 * for long compound IDs. | |
| 1004 * | |
| 1005 * @param aliasID The new ID being registered. | |
| 1006 * @param realID The ID that the new ID is to be an alias for. | |
| 1007 * This can be a compound ID and can include filters and should | |
| 1008 * refer to transliterators that have already been registered with | |
| 1009 * the framework, although this isn't checked. | |
| 1010 * @stable ICU 3.6 | |
| 1011 */ | |
| 1012 static void U_EXPORT2 registerAlias(const UnicodeString& aliasID, | |
| 1013 const UnicodeString& realID); | |
| 1014 | |
| 1015 protected: | |
| 1016 | |
| 1017 /** | |
| 1018 * @internal | |
| 1019 * @param id the ID being registered | |
| 1020 * @param factory a function pointer that will be copied and | |
| 1021 * called later when the given ID is passed to createInstance() | |
| 1022 * @param context a context pointer that will be stored and | |
| 1023 * later passed to the factory function when an ID matching | |
| 1024 * the registration ID is being instantiated with this factory. | |
| 1025 */ | |
| 1026 static void _registerFactory(const UnicodeString& id, | |
| 1027 Factory factory, | |
| 1028 Token context); | |
| 1029 | |
| 1030 /** | |
| 1031 * @internal | |
| 1032 */ | |
| 1033 static void _registerInstance(Transliterator* adoptedObj); | |
| 1034 | |
| 1035 /** | |
| 1036 * @internal | |
| 1037 */ | |
| 1038 static void _registerAlias(const UnicodeString& aliasID, const UnicodeString
& realID); | |
| 1039 | |
| 1040 /** | |
| 1041 * Register two targets as being inverses of one another. For | |
| 1042 * example, calling registerSpecialInverse("NFC", "NFD", true) causes | |
| 1043 * Transliterator to form the following inverse relationships: | |
| 1044 * | |
| 1045 * <pre>NFC => NFD | |
| 1046 * Any-NFC => Any-NFD | |
| 1047 * NFD => NFC | |
| 1048 * Any-NFD => Any-NFC</pre> | |
| 1049 * | |
| 1050 * (Without the special inverse registration, the inverse of NFC | |
| 1051 * would be NFC-Any.) Note that NFD is shorthand for Any-NFD, but | |
| 1052 * that the presence or absence of "Any-" is preserved. | |
| 1053 * | |
| 1054 * <p>The relationship is symmetrical; registering (a, b) is | |
| 1055 * equivalent to registering (b, a). | |
| 1056 * | |
| 1057 * <p>The relevant IDs must still be registered separately as | |
| 1058 * factories or classes. | |
| 1059 * | |
| 1060 * <p>Only the targets are specified. Special inverses always | |
| 1061 * have the form Any-Target1 <=> Any-Target2. The target should | |
| 1062 * have canonical casing (the casing desired to be produced when | |
| 1063 * an inverse is formed) and should contain no whitespace or other | |
| 1064 * extraneous characters. | |
| 1065 * | |
| 1066 * @param target the target against which to register the inverse | |
| 1067 * @param inverseTarget the inverse of target, that is | |
| 1068 * Any-target.getInverse() => Any-inverseTarget | |
| 1069 * @param bidirectional if true, register the reverse relation | |
| 1070 * as well, that is, Any-inverseTarget.getInverse() => Any-target | |
| 1071 * @internal | |
| 1072 */ | |
| 1073 static void _registerSpecialInverse(const UnicodeString& target, | |
| 1074 const UnicodeString& inverseTarget, | |
| 1075 UBool bidirectional); | |
| 1076 | |
| 1077 public: | |
| 1078 | |
| 1079 /** | |
| 1080 * Unregisters a transliterator or class. This may be either | |
| 1081 * a system transliterator or a user transliterator or class. | |
| 1082 * Any attempt to construct an unregistered transliterator based | |
| 1083 * on its ID will fail. | |
| 1084 * | |
| 1085 * @param ID the ID of the transliterator or class | |
| 1086 * @return the <code>Object</code> that was registered with | |
| 1087 * <code>ID</code>, or <code>null</code> if none was | |
| 1088 * @see #registerInstance | |
| 1089 * @see #registerFactory | |
| 1090 * @stable ICU 2.0 | |
| 1091 */ | |
| 1092 static void U_EXPORT2 unregister(const UnicodeString& ID); | |
| 1093 | |
| 1094 public: | |
| 1095 | |
| 1096 /** | |
| 1097 * Return a StringEnumeration over the IDs available at the time of the | |
| 1098 * call, including user-registered IDs. | |
| 1099 * @param ec input-output error code | |
| 1100 * @return a newly-created StringEnumeration over the transliterators | |
| 1101 * available at the time of the call. The caller should delete this object | |
| 1102 * when done using it. | |
| 1103 * @stable ICU 3.0 | |
| 1104 */ | |
| 1105 static StringEnumeration* U_EXPORT2 getAvailableIDs(UErrorCode& ec); | |
| 1106 | |
| 1107 /** | |
| 1108 * Return the number of registered source specifiers. | |
| 1109 * @return the number of registered source specifiers. | |
| 1110 * @stable ICU 2.0 | |
| 1111 */ | |
| 1112 static int32_t U_EXPORT2 countAvailableSources(void); | |
| 1113 | |
| 1114 /** | |
| 1115 * Return a registered source specifier. | |
| 1116 * @param index which specifier to return, from 0 to n-1, where | |
| 1117 * n = countAvailableSources() | |
| 1118 * @param result fill-in paramter to receive the source specifier. | |
| 1119 * If index is out of range, result will be empty. | |
| 1120 * @return reference to result | |
| 1121 * @stable ICU 2.0 | |
| 1122 */ | |
| 1123 static UnicodeString& U_EXPORT2 getAvailableSource(int32_t index, | |
| 1124 UnicodeString& result); | |
| 1125 | |
| 1126 /** | |
| 1127 * Return the number of registered target specifiers for a given | |
| 1128 * source specifier. | |
| 1129 * @param source the given source specifier. | |
| 1130 * @return the number of registered target specifiers for a given | |
| 1131 * source specifier. | |
| 1132 * @stable ICU 2.0 | |
| 1133 */ | |
| 1134 static int32_t U_EXPORT2 countAvailableTargets(const UnicodeString& source); | |
| 1135 | |
| 1136 /** | |
| 1137 * Return a registered target specifier for a given source. | |
| 1138 * @param index which specifier to return, from 0 to n-1, where | |
| 1139 * n = countAvailableTargets(source) | |
| 1140 * @param source the source specifier | |
| 1141 * @param result fill-in paramter to receive the target specifier. | |
| 1142 * If source is invalid or if index is out of range, result will | |
| 1143 * be empty. | |
| 1144 * @return reference to result | |
| 1145 * @stable ICU 2.0 | |
| 1146 */ | |
| 1147 static UnicodeString& U_EXPORT2 getAvailableTarget(int32_t index, | |
| 1148 const UnicodeString& source, | |
| 1149 UnicodeString& result); | |
| 1150 | |
| 1151 /** | |
| 1152 * Return the number of registered variant specifiers for a given | |
| 1153 * source-target pair. | |
| 1154 * @param source the source specifiers. | |
| 1155 * @param target the target specifiers. | |
| 1156 * @stable ICU 2.0 | |
| 1157 */ | |
| 1158 static int32_t U_EXPORT2 countAvailableVariants(const UnicodeString& source, | |
| 1159 const UnicodeString& target); | |
| 1160 | |
| 1161 /** | |
| 1162 * Return a registered variant specifier for a given source-target | |
| 1163 * pair. | |
| 1164 * @param index which specifier to return, from 0 to n-1, where | |
| 1165 * n = countAvailableVariants(source, target) | |
| 1166 * @param source the source specifier | |
| 1167 * @param target the target specifier | |
| 1168 * @param result fill-in paramter to receive the variant | |
| 1169 * specifier. If source is invalid or if target is invalid or if | |
| 1170 * index is out of range, result will be empty. | |
| 1171 * @return reference to result | |
| 1172 * @stable ICU 2.0 | |
| 1173 */ | |
| 1174 static UnicodeString& U_EXPORT2 getAvailableVariant(int32_t index, | |
| 1175 const UnicodeString& source, | |
| 1176 const UnicodeString& target, | |
| 1177 UnicodeString& result); | |
| 1178 | |
| 1179 protected: | |
| 1180 | |
| 1181 /** | |
| 1182 * Non-mutexed internal method | |
| 1183 * @internal | |
| 1184 */ | |
| 1185 static int32_t _countAvailableSources(void); | |
| 1186 | |
| 1187 /** | |
| 1188 * Non-mutexed internal method | |
| 1189 * @internal | |
| 1190 */ | |
| 1191 static UnicodeString& _getAvailableSource(int32_t index, | |
| 1192 UnicodeString& result); | |
| 1193 | |
| 1194 /** | |
| 1195 * Non-mutexed internal method | |
| 1196 * @internal | |
| 1197 */ | |
| 1198 static int32_t _countAvailableTargets(const UnicodeString& source); | |
| 1199 | |
| 1200 /** | |
| 1201 * Non-mutexed internal method | |
| 1202 * @internal | |
| 1203 */ | |
| 1204 static UnicodeString& _getAvailableTarget(int32_t index, | |
| 1205 const UnicodeString& source, | |
| 1206 UnicodeString& result); | |
| 1207 | |
| 1208 /** | |
| 1209 * Non-mutexed internal method | |
| 1210 * @internal | |
| 1211 */ | |
| 1212 static int32_t _countAvailableVariants(const UnicodeString& source, | |
| 1213 const UnicodeString& target); | |
| 1214 | |
| 1215 /** | |
| 1216 * Non-mutexed internal method | |
| 1217 * @internal | |
| 1218 */ | |
| 1219 static UnicodeString& _getAvailableVariant(int32_t index, | |
| 1220 const UnicodeString& source, | |
| 1221 const UnicodeString& target, | |
| 1222 UnicodeString& result); | |
| 1223 | |
| 1224 protected: | |
| 1225 | |
| 1226 /** | |
| 1227 * Set the ID of this transliterators. Subclasses shouldn't do | |
| 1228 * this, unless the underlying script behavior has changed. | |
| 1229 * @param id the new id t to be set. | |
| 1230 * @stable ICU 2.4 | |
| 1231 */ | |
| 1232 void setID(const UnicodeString& id); | |
| 1233 | |
| 1234 public: | |
| 1235 | |
| 1236 /** | |
| 1237 * Return the class ID for this class. This is useful only for | |
| 1238 * comparing to a return value from getDynamicClassID(). | |
| 1239 * Note that Transliterator is an abstract base class, and therefor | |
| 1240 * no fully constructed object will have a dynamic | |
| 1241 * UCLassID that equals the UClassID returned from | |
| 1242 * TRansliterator::getStaticClassID(). | |
| 1243 * @return The class ID for class Transliterator. | |
| 1244 * @stable ICU 2.0 | |
| 1245 */ | |
| 1246 static UClassID U_EXPORT2 getStaticClassID(void); | |
| 1247 | |
| 1248 /** | |
| 1249 * Returns a unique class ID <b>polymorphically</b>. This method | |
| 1250 * is to implement a simple version of RTTI, since not all C++ | |
| 1251 * compilers support genuine RTTI. Polymorphic operator==() and | |
| 1252 * clone() methods call this method. | |
| 1253 * | |
| 1254 * <p>Concrete subclasses of Transliterator must use the | |
| 1255 * UOBJECT_DEFINE_RTTI_IMPLEMENTATION macro from | |
| 1256 * uobject.h to provide the RTTI functions. | |
| 1257 * | |
| 1258 * @return The class ID for this object. All objects of a given | |
| 1259 * class have the same class ID. Objects of other classes have | |
| 1260 * different class IDs. | |
| 1261 * @stable ICU 2.0 | |
| 1262 */ | |
| 1263 virtual UClassID getDynamicClassID(void) const = 0; | |
| 1264 | |
| 1265 private: | |
| 1266 static UBool initializeRegistry(UErrorCode &status); | |
| 1267 | |
| 1268 public: | |
| 1269 /** | |
| 1270 * Return the number of IDs currently registered with the system. | |
| 1271 * To retrieve the actual IDs, call getAvailableID(i) with | |
| 1272 * i from 0 to countAvailableIDs() - 1. | |
| 1273 * @return the number of IDs currently registered with the system. | |
| 1274 * @obsolete ICU 3.4 use getAvailableIDs() instead | |
| 1275 */ | |
| 1276 static int32_t U_EXPORT2 countAvailableIDs(void); | |
| 1277 | |
| 1278 /** | |
| 1279 * Return the index-th available ID. index must be between 0 | |
| 1280 * and countAvailableIDs() - 1, inclusive. If index is out of | |
| 1281 * range, the result of getAvailableID(0) is returned. | |
| 1282 * @param index the given ID index. | |
| 1283 * @return the index-th available ID. index must be between 0 | |
| 1284 * and countAvailableIDs() - 1, inclusive. If index is out of | |
| 1285 * range, the result of getAvailableID(0) is returned. | |
| 1286 * @obsolete ICU 3.4 use getAvailableIDs() instead; this function | |
| 1287 * is not thread safe, since it returns a reference to storage that | |
| 1288 * may become invalid if another thread calls unregister | |
| 1289 */ | |
| 1290 static const UnicodeString& U_EXPORT2 getAvailableID(int32_t index); | |
| 1291 }; | |
| 1292 | |
| 1293 inline int32_t Transliterator::getMaximumContextLength(void) const { | |
| 1294 return maximumContextLength; | |
| 1295 } | |
| 1296 | |
| 1297 inline void Transliterator::setID(const UnicodeString& id) { | |
| 1298 ID = id; | |
| 1299 // NUL-terminate the ID string, which is a non-aliased copy. | |
| 1300 ID.append((UChar)0); | |
| 1301 ID.truncate(ID.length()-1); | |
| 1302 } | |
| 1303 | |
| 1304 inline Transliterator::Token Transliterator::integerToken(int32_t i) { | |
| 1305 Token t; | |
| 1306 t.integer = i; | |
| 1307 return t; | |
| 1308 } | |
| 1309 | |
| 1310 inline Transliterator::Token Transliterator::pointerToken(void* p) { | |
| 1311 Token t; | |
| 1312 t.pointer = p; | |
| 1313 return t; | |
| 1314 } | |
| 1315 | |
| 1316 U_NAMESPACE_END | |
| 1317 | |
| 1318 #endif /* #if !UCONFIG_NO_TRANSLITERATION */ | |
| 1319 | |
| 1320 #endif | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 19417002:
Move ICU header part 2 (Closed)
Base URL: svn://chrome-svn/chrome/trunk/deps/third_party/icu46/