icuSources/i18n/unicode/utrans.h

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