util/X86MAC64/include/unicode/utrans.h

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