source/i18n/unicode/utrans.h

   1 // Copyright (C) 2016 and later: Unicode, Inc. and others.
   2 // License & terms of use: http://www.unicode.org/copyright.html
   3 /*
   4 *******************************************************************************
   5 *   Copyright (C) 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