← Back to branch summary

~alinuxninja/nginx-edge/trunk

« back to all changes in this revision

Viewing changes to debian/modules/ngx_pagespeed/psol/include/third_party/icu/source/i18n/unicode/translit.h

  • Committer: Vivian
  • Date: 2015-12-04 18:20:11 UTC
  • Revision ID: git-v1:a36f2bc32e884f7473b3a47040e5411306144d7d
* Do not extract psol.tar.gz

Show diffs side-by-side

added added

removed removed

Lines of Context:
debian/modules/ngx_pagespeed/psol/include/third_party/icu/source/i18n/unicode/translit.h
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&gt;{theta}<br>
103
 
 * t&gt;{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&gt;|{tau}<br>
113
 
 * {tau}h&gt;{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 factory.
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 different
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 bounds,
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&, UErrorCode&) 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&, UErrorCode&) 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