• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 // © 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
3 /*
4 *******************************************************************************
5 *   Copyright (C) 1997-2011,2014-2015 International Business Machines
6 *   Corporation and others.  All Rights Reserved.
7 *******************************************************************************
8 *   Date        Name        Description
9 *   06/21/00    aliu        Creation.
10 *******************************************************************************
11 */
12 
13 #ifndef UTRANS_H
14 #define UTRANS_H
15 
16 #include "unicode/utypes.h"
17 
18 #if !UCONFIG_NO_TRANSLITERATION
19 
20 #include "unicode/localpointer.h"
21 #include "unicode/urep.h"
22 #include "unicode/parseerr.h"
23 #include "unicode/uenum.h"
24 #include "unicode/uset.h"
25 
26 /********************************************************************
27  * General Notes
28  ********************************************************************
29  */
30 /**
31  * \file
32  * \brief C API: Transliterator
33  *
34  * <h2> Transliteration </h2>
35  * The data structures and functions described in this header provide
36  * transliteration services.  Transliteration services are implemented
37  * as C++ classes.  The comments and documentation in this header
38  * assume the reader is familiar with the C++ headers translit.h and
39  * associated documentation.
40  *
41  * A significant but incomplete subset of the C++ transliteration
42  * services are available to C code through this header.  In order to
43  * access more complex transliteration services, refer to the C++
44  * headers and documentation.
45  *
46  * There are two sets of functions for working with transliterator IDs:
47  *
48  * An old, deprecated set uses char * IDs, which works for true and pure
49  * identifiers that these APIs were designed for,
50  * for example "Cyrillic-Latin".
51  * It does not work when the ID contains filters ("[:Script=Cyrl:]")
52  * or even a complete set of rules because then the ID string contains more
53  * than just "invariant" characters (see utypes.h).
54  *
55  * A new set of functions replaces the old ones and uses UChar * IDs,
56  * paralleling the UnicodeString IDs in the C++ API. (New in ICU 2.8.)
57  */
58 
59 /********************************************************************
60  * Data Structures
61  ********************************************************************/
62 
63 /**
64  * An opaque transliterator for use in C.  Open with utrans_openxxx()
65  * and close with utrans_close() when done.  Equivalent to the C++ class
66  * Transliterator and its subclasses.
67  * @see Transliterator
68  * @stable ICU 2.0
69  */
70 typedef void* UTransliterator;
71 
72 /**
73  * Direction constant indicating the direction in a transliterator,
74  * e.g., the forward or reverse rules of a RuleBasedTransliterator.
75  * Specified when a transliterator is opened.  An "A-B" transliterator
76  * transliterates A to B when operating in the forward direction, and
77  * B to A when operating in the reverse direction.
78  * @stable ICU 2.0
79  */
80 typedef enum UTransDirection {
81 
82     /**
83      * UTRANS_FORWARD means from &lt;source&gt; to &lt;target&gt; for a
84      * transliterator with ID &lt;source&gt;-&lt;target&gt;.  For a transliterator
85      * opened using a rule, it means forward direction rules, e.g.,
86      * "A > B".
87      */
88     UTRANS_FORWARD,
89 
90     /**
91      * UTRANS_REVERSE means from &lt;target&gt; to &lt;source&gt; for a
92      * transliterator with ID &lt;source&gt;-&lt;target&gt;.  For a transliterator
93      * opened using a rule, it means reverse direction rules, e.g.,
94      * "A < B".
95      */
96     UTRANS_REVERSE
97 
98 } UTransDirection;
99 
100 /**
101  * Position structure for utrans_transIncremental() incremental
102  * transliteration.  This structure defines two substrings of the text
103  * being transliterated.  The first region, [contextStart,
104  * contextLimit), defines what characters the transliterator will read
105  * as context.  The second region, [start, limit), defines what
106  * characters will actually be transliterated.  The second region
107  * should be a subset of the first.
108  *
109  * <p>After a transliteration operation, some of the indices in this
110  * structure will be modified.  See the field descriptions for
111  * details.
112  *
113  * <p>contextStart <= start <= limit <= contextLimit
114  *
115  * <p>Note: All index values in this structure must be at code point
116  * boundaries.  That is, none of them may occur between two code units
117  * of a surrogate pair.  If any index does split a surrogate pair,
118  * results are unspecified.
119  *
120  * @stable ICU 2.0
121  */
122 typedef struct UTransPosition {
123 
124     /**
125      * Beginning index, inclusive, of the context to be considered for
126      * a transliteration operation.  The transliterator will ignore
127      * anything before this index.  INPUT/OUTPUT parameter: This parameter
128      * is updated by a transliteration operation to reflect the maximum
129      * amount of antecontext needed by a transliterator.
130      * @stable ICU 2.4
131      */
132     int32_t contextStart;
133 
134     /**
135      * Ending index, exclusive, of the context to be considered for a
136      * transliteration operation.  The transliterator will ignore
137      * anything at or after this index.  INPUT/OUTPUT parameter: This
138      * parameter is updated to reflect changes in the length of the
139      * text, but points to the same logical position in the text.
140      * @stable ICU 2.4
141      */
142     int32_t contextLimit;
143 
144     /**
145      * Beginning index, inclusive, of the text to be transliteratd.
146      * INPUT/OUTPUT parameter: This parameter is advanced past
147      * characters that have already been transliterated by a
148      * transliteration operation.
149      * @stable ICU 2.4
150      */
151     int32_t start;
152 
153     /**
154      * Ending index, exclusive, of the text to be transliteratd.
155      * INPUT/OUTPUT parameter: This parameter is updated to reflect
156      * changes in the length of the text, but points to the same
157      * logical position in the text.
158      * @stable ICU 2.4
159      */
160     int32_t limit;
161 
162 } UTransPosition;
163 
164 /********************************************************************
165  * General API
166  ********************************************************************/
167 
168 /**
169  * Open a custom transliterator, given a custom rules string
170  * OR
171  * a system transliterator, given its ID.
172  * Any non-NULL result from this function should later be closed with
173  * utrans_close().
174  *
175  * @param id a valid transliterator ID
176  * @param idLength the length of the ID string, or -1 if NUL-terminated
177  * @param dir the desired direction
178  * @param rules the transliterator rules.  See the C++ header rbt.h for
179  *              rules syntax. If NULL then a system transliterator matching
180  *              the ID is returned.
181  * @param rulesLength the length of the rules, or -1 if the rules
182  *                    are NUL-terminated.
183  * @param parseError a pointer to a UParseError struct to receive the details
184  *                   of any parsing errors. This parameter may be NULL if no
185  *                   parsing error details are desired.
186  * @param pErrorCode a pointer to the UErrorCode
187  * @return a transliterator pointer that may be passed to other
188  *         utrans_xxx() functions, or NULL if the open call fails.
189  * @stable ICU 2.8
190  */
191 U_STABLE UTransliterator* U_EXPORT2
192 utrans_openU(const UChar *id,
193              int32_t idLength,
194              UTransDirection dir,
195              const UChar *rules,
196              int32_t rulesLength,
197              UParseError *parseError,
198              UErrorCode *pErrorCode);
199 
200 /**
201  * Open an inverse of an existing transliterator.  For this to work,
202  * the inverse must be registered with the system.  For example, if
203  * the Transliterator "A-B" is opened, and then its inverse is opened,
204  * the result is the Transliterator "B-A", if such a transliterator is
205  * registered with the system.  Otherwise the result is NULL and a
206  * failing UErrorCode is set.  Any non-NULL result from this function
207  * should later be closed with utrans_close().
208  *
209  * @param trans the transliterator to open the inverse of.
210  * @param status a pointer to the UErrorCode
211  * @return a pointer to a newly-opened transliterator that is the
212  * inverse of trans, or NULL if the open call fails.
213  * @stable ICU 2.0
214  */
215 U_STABLE UTransliterator* U_EXPORT2
216 utrans_openInverse(const UTransliterator* trans,
217                    UErrorCode* status);
218 
219 /**
220  * Create a copy of a transliterator.  Any non-NULL result from this
221  * function should later be closed with utrans_close().
222  *
223  * @param trans the transliterator to be copied.
224  * @param status a pointer to the UErrorCode
225  * @return a transliterator pointer that may be passed to other
226  * utrans_xxx() functions, or NULL if the clone call fails.
227  * @stable ICU 2.0
228  */
229 U_STABLE UTransliterator* U_EXPORT2
230 utrans_clone(const UTransliterator* trans,
231              UErrorCode* status);
232 
233 /**
234  * Close a transliterator.  Any non-NULL pointer returned by
235  * utrans_openXxx() or utrans_clone() should eventually be closed.
236  * @param trans the transliterator to be closed.
237  * @stable ICU 2.0
238  */
239 U_STABLE void U_EXPORT2
240 utrans_close(UTransliterator* trans);
241 
242 #if U_SHOW_CPLUSPLUS_API
243 
244 U_NAMESPACE_BEGIN
245 
246 /**
247  * \class LocalUTransliteratorPointer
248  * "Smart pointer" class, closes a UTransliterator via utrans_close().
249  * For most methods see the LocalPointerBase base class.
250  *
251  * @see LocalPointerBase
252  * @see LocalPointer
253  * @stable ICU 4.4
254  */
255 U_DEFINE_LOCAL_OPEN_POINTER(LocalUTransliteratorPointer, UTransliterator, utrans_close);
256 
257 U_NAMESPACE_END
258 
259 #endif
260 
261 /**
262  * Return the programmatic identifier for this transliterator.
263  * If this identifier is passed to utrans_openU(), it will open
264  * a transliterator equivalent to this one, if the ID has been
265  * registered.
266  *
267  * @param trans the transliterator to return the ID of.
268  * @param resultLength pointer to an output variable receiving the length
269  *        of the ID string; can be NULL
270  * @return the NUL-terminated ID string. This pointer remains
271  * valid until utrans_close() is called on this transliterator.
272  *
273  * @stable ICU 2.8
274  */
275 U_STABLE const UChar * U_EXPORT2
276 utrans_getUnicodeID(const UTransliterator *trans,
277                     int32_t *resultLength);
278 
279 /**
280  * Register an open transliterator with the system.  When
281  * utrans_open() is called with an ID string that is equal to that
282  * returned by utrans_getID(adoptedTrans,...), then
283  * utrans_clone(adoptedTrans,...) is returned.
284  *
285  * <p>NOTE: After this call the system owns the adoptedTrans and will
286  * close it.  The user must not call utrans_close() on adoptedTrans.
287  *
288  * @param adoptedTrans a transliterator, typically the result of
289  * utrans_openRules(), to be registered with the system.
290  * @param status a pointer to the UErrorCode
291  * @stable ICU 2.0
292  */
293 U_STABLE void U_EXPORT2
294 utrans_register(UTransliterator* adoptedTrans,
295                 UErrorCode* status);
296 
297 /**
298  * Unregister a transliterator from the system.  After this call the
299  * system will no longer recognize the given ID when passed to
300  * utrans_open(). If the ID is invalid then nothing is done.
301  *
302  * @param id an ID to unregister
303  * @param idLength the length of id, or -1 if id is zero-terminated
304  * @stable ICU 2.8
305  */
306 U_STABLE void U_EXPORT2
307 utrans_unregisterID(const UChar* id, int32_t idLength);
308 
309 /**
310  * Set the filter used by a transliterator.  A filter can be used to
311  * make the transliterator pass certain characters through untouched.
312  * The filter is expressed using a UnicodeSet pattern.  If the
313  * filterPattern is NULL or the empty string, then the transliterator
314  * will be reset to use no filter.
315  *
316  * @param trans the transliterator
317  * @param filterPattern a pattern string, in the form accepted by
318  * UnicodeSet, specifying which characters to apply the
319  * transliteration to.  May be NULL or the empty string to indicate no
320  * filter.
321  * @param filterPatternLen the length of filterPattern, or -1 if
322  * filterPattern is zero-terminated
323  * @param status a pointer to the UErrorCode
324  * @see UnicodeSet
325  * @stable ICU 2.0
326  */
327 U_STABLE void U_EXPORT2
328 utrans_setFilter(UTransliterator* trans,
329                  const UChar* filterPattern,
330                  int32_t filterPatternLen,
331                  UErrorCode* status);
332 
333 /**
334  * Return the number of system transliterators.
335  * It is recommended to use utrans_openIDs() instead.
336  *
337  * @return the number of system transliterators.
338  * @stable ICU 2.0
339  */
340 U_STABLE int32_t U_EXPORT2
341 utrans_countAvailableIDs(void);
342 
343 /**
344  * Return a UEnumeration for the available transliterators.
345  *
346  * @param pErrorCode Pointer to the UErrorCode in/out parameter.
347  * @return UEnumeration for the available transliterators.
348  *         Close with uenum_close().
349  *
350  * @stable ICU 2.8
351  */
352 U_STABLE UEnumeration * U_EXPORT2
353 utrans_openIDs(UErrorCode *pErrorCode);
354 
355 /********************************************************************
356  * Transliteration API
357  ********************************************************************/
358 
359 /**
360  * Transliterate a segment of a UReplaceable string.  The string is
361  * passed in as a UReplaceable pointer rep and a UReplaceableCallbacks
362  * function pointer struct repFunc.  Functions in the repFunc struct
363  * will be called in order to modify the rep string.
364  *
365  * @param trans the transliterator
366  * @param rep a pointer to the string.  This will be passed to the
367  * repFunc functions.
368  * @param repFunc a set of function pointers that will be used to
369  * modify the string pointed to by rep.
370  * @param start the beginning index, inclusive; <code>0 <= start <=
371  * limit</code>.
372  * @param limit pointer to the ending index, exclusive; <code>start <=
373  * limit <= repFunc->length(rep)</code>.  Upon return, *limit will
374  * contain the new limit index.  The text previously occupying
375  * <code>[start, limit)</code> has been transliterated, possibly to a
376  * string of a different length, at <code>[start,
377  * </code><em>new-limit</em><code>)</code>, where <em>new-limit</em>
378  * is the return value.
379  * @param status a pointer to the UErrorCode
380  * @stable ICU 2.0
381  */
382 U_STABLE void U_EXPORT2
383 utrans_trans(const UTransliterator* trans,
384              UReplaceable* rep,
385              UReplaceableCallbacks* repFunc,
386              int32_t start,
387              int32_t* limit,
388              UErrorCode* status);
389 
390 /**
391  * Transliterate the portion of the UReplaceable text buffer that can
392  * be transliterated unambiguosly.  This method is typically called
393  * after new text has been inserted, e.g. as a result of a keyboard
394  * event.  The transliterator will try to transliterate characters of
395  * <code>rep</code> between <code>index.cursor</code> and
396  * <code>index.limit</code>.  Characters before
397  * <code>index.cursor</code> will not be changed.
398  *
399  * <p>Upon return, values in <code>index</code> will be updated.
400  * <code>index.start</code> will be advanced to the first
401  * character that future calls to this method will read.
402  * <code>index.cursor</code> and <code>index.limit</code> will
403  * be adjusted to delimit the range of text that future calls to
404  * this method may change.
405  *
406  * <p>Typical usage of this method begins with an initial call
407  * with <code>index.start</code> and <code>index.limit</code>
408  * set to indicate the portion of <code>text</code> to be
409  * transliterated, and <code>index.cursor == index.start</code>.
410  * Thereafter, <code>index</code> can be used without
411  * modification in future calls, provided that all changes to
412  * <code>text</code> are made via this method.
413  *
414  * <p>This method assumes that future calls may be made that will
415  * insert new text into the buffer.  As a result, it only performs
416  * unambiguous transliterations.  After the last call to this method,
417  * there may be untransliterated text that is waiting for more input
418  * to resolve an ambiguity.  In order to perform these pending
419  * transliterations, clients should call utrans_trans() with a start
420  * of index.start and a limit of index.end after the last call to this
421  * method has been made.
422  *
423  * @param trans the transliterator
424  * @param rep a pointer to the string.  This will be passed to the
425  * repFunc functions.
426  * @param repFunc a set of function pointers that will be used to
427  * modify the string pointed to by rep.
428  * @param pos a struct containing the start and limit indices of the
429  * text to be read and the text to be transliterated
430  * @param status a pointer to the UErrorCode
431  * @stable ICU 2.0
432  */
433 U_STABLE void U_EXPORT2
434 utrans_transIncremental(const UTransliterator* trans,
435                         UReplaceable* rep,
436                         UReplaceableCallbacks* repFunc,
437                         UTransPosition* pos,
438                         UErrorCode* status);
439 
440 /**
441  * Transliterate a segment of a UChar* string.  The string is passed
442  * in in a UChar* buffer.  The string is modified in place.  If the
443  * result is longer than textCapacity, it is truncated.  The actual
444  * length of the result is returned in *textLength, if textLength is
445  * non-NULL. *textLength may be greater than textCapacity, but only
446  * textCapacity UChars will be written to *text, including the zero
447  * terminator.
448  *
449  * @param trans the transliterator
450  * @param text a pointer to a buffer containing the text to be
451  * transliterated on input and the result text on output.
452  * @param textLength a pointer to the length of the string in text.
453  * If the length is -1 then the string is assumed to be
454  * zero-terminated.  Upon return, the new length is stored in
455  * *textLength.  If textLength is NULL then the string is assumed to
456  * be zero-terminated.
457  * @param textCapacity a pointer to the length of the text buffer.
458  * Upon return,
459  * @param start the beginning index, inclusive; <code>0 <= start <=
460  * limit</code>.
461  * @param limit pointer to the ending index, exclusive; <code>start <=
462  * limit <= repFunc->length(rep)</code>.  Upon return, *limit will
463  * contain the new limit index.  The text previously occupying
464  * <code>[start, limit)</code> has been transliterated, possibly to a
465  * string of a different length, at <code>[start,
466  * </code><em>new-limit</em><code>)</code>, where <em>new-limit</em>
467  * is the return value.
468  * @param status a pointer to the UErrorCode
469  * @stable ICU 2.0
470  */
471 U_STABLE void U_EXPORT2
472 utrans_transUChars(const UTransliterator* trans,
473                    UChar* text,
474                    int32_t* textLength,
475                    int32_t textCapacity,
476                    int32_t start,
477                    int32_t* limit,
478                    UErrorCode* status);
479 
480 /**
481  * Transliterate the portion of the UChar* text buffer that can be
482  * transliterated unambiguosly.  See utrans_transIncremental().  The
483  * string is passed in in a UChar* buffer.  The string is modified in
484  * place.  If the result is longer than textCapacity, it is truncated.
485  * The actual length of the result is returned in *textLength, if
486  * textLength is non-NULL. *textLength may be greater than
487  * textCapacity, but only textCapacity UChars will be written to
488  * *text, including the zero terminator.  See utrans_transIncremental()
489  * for usage details.
490  *
491  * @param trans the transliterator
492  * @param text a pointer to a buffer containing the text to be
493  * transliterated on input and the result text on output.
494  * @param textLength a pointer to the length of the string in text.
495  * If the length is -1 then the string is assumed to be
496  * zero-terminated.  Upon return, the new length is stored in
497  * *textLength.  If textLength is NULL then the string is assumed to
498  * be zero-terminated.
499  * @param textCapacity the length of the text buffer
500  * @param pos a struct containing the start and limit indices of the
501  * text to be read and the text to be transliterated
502  * @param status a pointer to the UErrorCode
503  * @see utrans_transIncremental
504  * @stable ICU 2.0
505  */
506 U_STABLE void U_EXPORT2
507 utrans_transIncrementalUChars(const UTransliterator* trans,
508                               UChar* text,
509                               int32_t* textLength,
510                               int32_t textCapacity,
511                               UTransPosition* pos,
512                               UErrorCode* status);
513 
514 /**
515  * Create a rule string that can be passed to utrans_openU to recreate this
516  * transliterator.
517  *
518  * @param trans     The transliterator
519  * @param escapeUnprintable if TRUE then convert unprintable characters to their
520  *                  hex escape representations, \\uxxxx or \\Uxxxxxxxx.
521  *                  Unprintable characters are those other than
522  *                  U+000A, U+0020..U+007E.
523  * @param result    A pointer to a buffer to receive the rules.
524  * @param resultLength The maximum size of result.
525  * @param status    A pointer to the UErrorCode. In case of error status, the
526  *                  contents of result are undefined.
527  * @return int32_t   The length of the rule string (may be greater than resultLength,
528  *                  in which case an error is returned).
529  * @stable ICU 53
530  */
531 U_STABLE int32_t U_EXPORT2
532 utrans_toRules(     const UTransliterator* trans,
533                     UBool escapeUnprintable,
534                     UChar* result, int32_t resultLength,
535                     UErrorCode* status);
536 
537 /**
538  * Returns the set of all characters that may be modified in the input text by
539  * this UTransliterator, optionally ignoring the transliterator's current filter.
540  * @param trans     The transliterator.
541  * @param ignoreFilter If FALSE, the returned set incorporates the
542  *                  UTransliterator's current filter; if the filter is changed,
543  *                  the return value of this function will change. If TRUE, the
544  *                  returned set ignores the effect of the UTransliterator's
545  *                  current filter.
546  * @param fillIn    Pointer to a USet object to receive the modifiable characters
547  *                  set. Previous contents of fillIn are lost. <em>If fillIn is
548  *                  NULL, then a new USet is created and returned. The caller
549  *                  owns the result and must dispose of it by calling uset_close.</em>
550  * @param status    A pointer to the UErrorCode.
551  * @return USet*    Either fillIn, or if fillIn is NULL, a pointer to a
552  *                  newly-allocated USet that the user must close. In case of
553  *                  error, NULL is returned.
554  * @stable ICU 53
555  */
556 U_STABLE USet* U_EXPORT2
557 utrans_getSourceSet(const UTransliterator* trans,
558                     UBool ignoreFilter,
559                     USet* fillIn,
560                     UErrorCode* status);
561 
562 /* deprecated API ----------------------------------------------------------- */
563 
564 #ifndef U_HIDE_DEPRECATED_API
565 
566 /* see utrans.h documentation for why these functions are deprecated */
567 
568 /**
569  * Deprecated, use utrans_openU() instead.
570  * Open a custom transliterator, given a custom rules string
571  * OR
572  * a system transliterator, given its ID.
573  * Any non-NULL result from this function should later be closed with
574  * utrans_close().
575  *
576  * @param id a valid ID, as returned by utrans_getAvailableID()
577  * @param dir the desired direction
578  * @param rules the transliterator rules.  See the C++ header rbt.h
579  * for rules syntax. If NULL then a system transliterator matching
580  * the ID is returned.
581  * @param rulesLength the length of the rules, or -1 if the rules
582  * are zero-terminated.
583  * @param parseError a pointer to a UParseError struct to receive the
584  * details of any parsing errors. This parameter may be NULL if no
585  * parsing error details are desired.
586  * @param status a pointer to the UErrorCode
587  * @return a transliterator pointer that may be passed to other
588  * utrans_xxx() functions, or NULL if the open call fails.
589  * @deprecated ICU 2.8 Use utrans_openU() instead, see utrans.h
590  */
591 U_DEPRECATED UTransliterator* U_EXPORT2
592 utrans_open(const char* id,
593             UTransDirection dir,
594             const UChar* rules,         /* may be Null */
595             int32_t rulesLength,        /* -1 if null-terminated */
596             UParseError* parseError,    /* may be Null */
597             UErrorCode* status);
598 
599 /**
600  * Deprecated, use utrans_getUnicodeID() instead.
601  * Return the programmatic identifier for this transliterator.
602  * If this identifier is passed to utrans_open(), it will open
603  * a transliterator equivalent to this one, if the ID has been
604  * registered.
605  * @param trans the transliterator to return the ID of.
606  * @param buf the buffer in which to receive the ID.  This may be
607  * NULL, in which case no characters are copied.
608  * @param bufCapacity the capacity of the buffer.  Ignored if buf is
609  * NULL.
610  * @return the actual length of the ID, not including
611  * zero-termination.  This may be greater than bufCapacity.
612  * @deprecated ICU 2.8 Use utrans_getUnicodeID() instead, see utrans.h
613  */
614 U_DEPRECATED int32_t U_EXPORT2
615 utrans_getID(const UTransliterator* trans,
616              char* buf,
617              int32_t bufCapacity);
618 
619 /**
620  * Deprecated, use utrans_unregisterID() instead.
621  * Unregister a transliterator from the system.  After this call the
622  * system will no longer recognize the given ID when passed to
623  * utrans_open().  If the id is invalid then nothing is done.
624  *
625  * @param id a zero-terminated ID
626  * @deprecated ICU 2.8 Use utrans_unregisterID() instead, see utrans.h
627  */
628 U_DEPRECATED void U_EXPORT2
629 utrans_unregister(const char* id);
630 
631 /**
632  * Deprecated, use utrans_openIDs() instead.
633  * Return the ID of the index-th system transliterator.  The result
634  * is placed in the given buffer.  If the given buffer is too small,
635  * the initial substring is copied to buf.  The result in buf is
636  * always zero-terminated.
637  *
638  * @param index the number of the transliterator to return.  Must
639  * satisfy 0 <= index < utrans_countAvailableIDs().  If index is out
640  * of range then it is treated as if it were 0.
641  * @param buf the buffer in which to receive the ID.  This may be
642  * NULL, in which case no characters are copied.
643  * @param bufCapacity the capacity of the buffer.  Ignored if buf is
644  * NULL.
645  * @return the actual length of the index-th ID, not including
646  * zero-termination.  This may be greater than bufCapacity.
647  * @deprecated ICU 2.8 Use utrans_openIDs() instead, see utrans.h
648  */
649 U_DEPRECATED int32_t U_EXPORT2
650 utrans_getAvailableID(int32_t index,
651                       char* buf,
652                       int32_t bufCapacity);
653 
654 #endif  /* U_HIDE_DEPRECATED_API */
655 
656 #endif /* #if !UCONFIG_NO_TRANSLITERATION */
657 
658 #endif
659