| /* |
| ******************************************************************************* |
| * Copyright (C) 1997-2009, International Business Machines |
| * Corporation and others. All Rights Reserved. |
| ******************************************************************************* |
| * Date Name Description |
| * 06/21/00 aliu Creation. |
| ******************************************************************************* |
| */ |
| |
| #ifndef UTRANS_H |
| #define UTRANS_H |
| |
| #include "unicode/utypes.h" |
| |
| #if !UCONFIG_NO_TRANSLITERATION |
| |
| #include "unicode/localpointer.h" |
| #include "unicode/urep.h" |
| #include "unicode/parseerr.h" |
| #include "unicode/uenum.h" |
| |
| /******************************************************************** |
| * General Notes |
| ******************************************************************** |
| */ |
| /** |
| * \file |
| * \brief C API: Transliterator |
| * |
| * <h2> Transliteration </h2> |
| * The data structures and functions described in this header provide |
| * transliteration services. Transliteration services are implemented |
| * as C++ classes. The comments and documentation in this header |
| * assume the reader is familiar with the C++ headers translit.h and |
| * associated documentation. |
| * |
| * A significant but incomplete subset of the C++ transliteration |
| * services are available to C code through this header. In order to |
| * access more complex transliteration services, refer to the C++ |
| * headers and documentation. |
| * |
| * There are two sets of functions for working with transliterator IDs: |
| * |
| * An old, deprecated set uses char * IDs, which works for true and pure |
| * identifiers that these APIs were designed for, |
| * for example "Cyrillic-Latin". |
| * It does not work when the ID contains filters ("[:Script=Cyrl:]") |
| * or even a complete set of rules because then the ID string contains more |
| * than just "invariant" characters (see utypes.h). |
| * |
| * A new set of functions replaces the old ones and uses UChar * IDs, |
| * paralleling the UnicodeString IDs in the C++ API. (New in ICU 2.8.) |
| */ |
| |
| /******************************************************************** |
| * Data Structures |
| ********************************************************************/ |
| |
| /** |
| * An opaque transliterator for use in C. Open with utrans_openxxx() |
| * and close with utrans_close() when done. Equivalent to the C++ class |
| * Transliterator and its subclasses. |
| * @see Transliterator |
| * @stable ICU 2.0 |
| */ |
| typedef void* UTransliterator; |
| |
| /** |
| * Direction constant indicating the direction in a transliterator, |
| * e.g., the forward or reverse rules of a RuleBasedTransliterator. |
| * Specified when a transliterator is opened. An "A-B" transliterator |
| * transliterates A to B when operating in the forward direction, and |
| * B to A when operating in the reverse direction. |
| * @stable ICU 2.0 |
| */ |
| typedef enum UTransDirection { |
| |
| /** |
| * UTRANS_FORWARD means from <source> to <target> for a |
| * transliterator with ID <source>-<target>. For a transliterator |
| * opened using a rule, it means forward direction rules, e.g., |
| * "A > B". |
| */ |
| UTRANS_FORWARD, |
| |
| /** |
| * UTRANS_REVERSE means from <target> to <source> for a |
| * transliterator with ID <source>-<target>. For a transliterator |
| * opened using a rule, it means reverse direction rules, e.g., |
| * "A < B". |
| */ |
| UTRANS_REVERSE |
| |
| } UTransDirection; |
| |
| /** |
| * Position structure for utrans_transIncremental() incremental |
| * transliteration. This structure defines two substrings of the text |
| * being transliterated. The first region, [contextStart, |
| * contextLimit), defines what characters the transliterator will read |
| * as context. The second region, [start, limit), defines what |
| * characters will actually be transliterated. The second region |
| * should be a subset of the first. |
| * |
| * <p>After a transliteration operation, some of the indices in this |
| * structure will be modified. See the field descriptions for |
| * details. |
| * |
| * <p>contextStart <= start <= limit <= contextLimit |
| * |
| * <p>Note: All index values in this structure must be at code point |
| * boundaries. That is, none of them may occur between two code units |
| * of a surrogate pair. If any index does split a surrogate pair, |
| * results are unspecified. |
| * |
| * @stable ICU 2.0 |
| */ |
| typedef struct UTransPosition { |
| |
| /** |
| * Beginning index, inclusive, of the context to be considered for |
| * a transliteration operation. The transliterator will ignore |
| * anything before this index. INPUT/OUTPUT parameter: This parameter |
| * is updated by a transliteration operation to reflect the maximum |
| * amount of antecontext needed by a transliterator. |
| * @stable ICU 2.4 |
| */ |
| int32_t contextStart; |
| |
| /** |
| * Ending index, exclusive, of the context to be considered for a |
| * transliteration operation. The transliterator will ignore |
| * anything at or after this index. INPUT/OUTPUT parameter: This |
| * parameter is updated to reflect changes in the length of the |
| * text, but points to the same logical position in the text. |
| * @stable ICU 2.4 |
| */ |
| int32_t contextLimit; |
| |
| /** |
| * Beginning index, inclusive, of the text to be transliteratd. |
| * INPUT/OUTPUT parameter: This parameter is advanced past |
| * characters that have already been transliterated by a |
| * transliteration operation. |
| * @stable ICU 2.4 |
| */ |
| int32_t start; |
| |
| /** |
| * Ending index, exclusive, of the text to be transliteratd. |
| * INPUT/OUTPUT parameter: This parameter is updated to reflect |
| * changes in the length of the text, but points to the same |
| * logical position in the text. |
| * @stable ICU 2.4 |
| */ |
| int32_t limit; |
| |
| } UTransPosition; |
| |
| /******************************************************************** |
| * General API |
| ********************************************************************/ |
| |
| /** |
| * Open a custom transliterator, given a custom rules string |
| * OR |
| * a system transliterator, given its ID. |
| * Any non-NULL result from this function should later be closed with |
| * utrans_close(). |
| * |
| * @param id a valid transliterator ID |
| * @param idLength the length of the ID string, or -1 if NUL-terminated |
| * @param dir the desired direction |
| * @param rules the transliterator rules. See the C++ header rbt.h for |
| * rules syntax. If NULL then a system transliterator matching |
| * the ID is returned. |
| * @param rulesLength the length of the rules, or -1 if the rules |
| * are NUL-terminated. |
| * @param parseError a pointer to a UParseError struct to receive the details |
| * of any parsing errors. This parameter may be NULL if no |
| * parsing error details are desired. |
| * @param pErrorCode a pointer to the UErrorCode |
| * @return a transliterator pointer that may be passed to other |
| * utrans_xxx() functions, or NULL if the open call fails. |
| * @stable ICU 2.8 |
| */ |
| U_STABLE UTransliterator* U_EXPORT2 |
| utrans_openU(const UChar *id, |
| int32_t idLength, |
| UTransDirection dir, |
| const UChar *rules, |
| int32_t rulesLength, |
| UParseError *parseError, |
| UErrorCode *pErrorCode); |
| |
| /** |
| * Open an inverse of an existing transliterator. For this to work, |
| * the inverse must be registered with the system. For example, if |
| * the Transliterator "A-B" is opened, and then its inverse is opened, |
| * the result is the Transliterator "B-A", if such a transliterator is |
| * registered with the system. Otherwise the result is NULL and a |
| * failing UErrorCode is set. Any non-NULL result from this function |
| * should later be closed with utrans_close(). |
| * |
| * @param trans the transliterator to open the inverse of. |
| * @param status a pointer to the UErrorCode |
| * @return a pointer to a newly-opened transliterator that is the |
| * inverse of trans, or NULL if the open call fails. |
| * @stable ICU 2.0 |
| */ |
| U_STABLE UTransliterator* U_EXPORT2 |
| utrans_openInverse(const UTransliterator* trans, |
| UErrorCode* status); |
| |
| /** |
| * Create a copy of a transliterator. Any non-NULL result from this |
| * function should later be closed with utrans_close(). |
| * |
| * @param trans the transliterator to be copied. |
| * @param status a pointer to the UErrorCode |
| * @return a transliterator pointer that may be passed to other |
| * utrans_xxx() functions, or NULL if the clone call fails. |
| * @stable ICU 2.0 |
| */ |
| U_STABLE UTransliterator* U_EXPORT2 |
| utrans_clone(const UTransliterator* trans, |
| UErrorCode* status); |
| |
| /** |
| * Close a transliterator. Any non-NULL pointer returned by |
| * utrans_openXxx() or utrans_clone() should eventually be closed. |
| * @param trans the transliterator to be closed. |
| * @stable ICU 2.0 |
| */ |
| U_STABLE void U_EXPORT2 |
| utrans_close(UTransliterator* trans); |
| |
| #if U_SHOW_CPLUSPLUS_API |
| |
| U_NAMESPACE_BEGIN |
| |
| /** |
| * \class LocalUTransliteratorPointer |
| * "Smart pointer" class, closes a UTransliterator via utrans_close(). |
| * For most methods see the LocalPointerBase base class. |
| * |
| * @see LocalPointerBase |
| * @see LocalPointer |
| * @draft ICU 4.4 |
| */ |
| U_DEFINE_LOCAL_OPEN_POINTER(LocalUTransliteratorPointer, UTransliterator, utrans_close); |
| |
| U_NAMESPACE_END |
| |
| #endif |
| |
| /** |
| * Return the programmatic identifier for this transliterator. |
| * If this identifier is passed to utrans_openU(), it will open |
| * a transliterator equivalent to this one, if the ID has been |
| * registered. |
| * |
| * @param trans the transliterator to return the ID of. |
| * @param resultLength pointer to an output variable receiving the length |
| * of the ID string; can be NULL |
| * @return the NUL-terminated ID string. This pointer remains |
| * valid until utrans_close() is called on this transliterator. |
| * |
| * @stable ICU 2.8 |
| */ |
| U_STABLE const UChar * U_EXPORT2 |
| utrans_getUnicodeID(const UTransliterator *trans, |
| int32_t *resultLength); |
| |
| /** |
| * Register an open transliterator with the system. When |
| * utrans_open() is called with an ID string that is equal to that |
| * returned by utrans_getID(adoptedTrans,...), then |
| * utrans_clone(adoptedTrans,...) is returned. |
| * |
| * <p>NOTE: After this call the system owns the adoptedTrans and will |
| * close it. The user must not call utrans_close() on adoptedTrans. |
| * |
| * @param adoptedTrans a transliterator, typically the result of |
| * utrans_openRules(), to be registered with the system. |
| * @param status a pointer to the UErrorCode |
| * @stable ICU 2.0 |
| */ |
| U_STABLE void U_EXPORT2 |
| utrans_register(UTransliterator* adoptedTrans, |
| UErrorCode* status); |
| |
| /** |
| * Unregister a transliterator from the system. After this call the |
| * system will no longer recognize the given ID when passed to |
| * utrans_open(). If the ID is invalid then nothing is done. |
| * |
| * @param id an ID to unregister |
| * @param idLength the length of id, or -1 if id is zero-terminated |
| * @stable ICU 2.8 |
| */ |
| U_STABLE void U_EXPORT2 |
| utrans_unregisterID(const UChar* id, int32_t idLength); |
| |
| /** |
| * Set the filter used by a transliterator. A filter can be used to |
| * make the transliterator pass certain characters through untouched. |
| * The filter is expressed using a UnicodeSet pattern. If the |
| * filterPattern is NULL or the empty string, then the transliterator |
| * will be reset to use no filter. |
| * |
| * @param trans the transliterator |
| * @param filterPattern a pattern string, in the form accepted by |
| * UnicodeSet, specifying which characters to apply the |
| * transliteration to. May be NULL or the empty string to indicate no |
| * filter. |
| * @param filterPatternLen the length of filterPattern, or -1 if |
| * filterPattern is zero-terminated |
| * @param status a pointer to the UErrorCode |
| * @see UnicodeSet |
| * @stable ICU 2.0 |
| */ |
| U_STABLE void U_EXPORT2 |
| utrans_setFilter(UTransliterator* trans, |
| const UChar* filterPattern, |
| int32_t filterPatternLen, |
| UErrorCode* status); |
| |
| /** |
| * Return the number of system transliterators. |
| * It is recommended to use utrans_openIDs() instead. |
| * |
| * @return the number of system transliterators. |
| * @stable ICU 2.0 |
| */ |
| U_STABLE int32_t U_EXPORT2 |
| utrans_countAvailableIDs(void); |
| |
| /** |
| * Return a UEnumeration for the available transliterators. |
| * |
| * @param pErrorCode Pointer to the UErrorCode in/out parameter. |
| * @return UEnumeration for the available transliterators. |
| * Close with uenum_close(). |
| * |
| * @stable ICU 2.8 |
| */ |
| U_STABLE UEnumeration * U_EXPORT2 |
| utrans_openIDs(UErrorCode *pErrorCode); |
| |
| /******************************************************************** |
| * Transliteration API |
| ********************************************************************/ |
| |
| /** |
| * Transliterate a segment of a UReplaceable string. The string is |
| * passed in as a UReplaceable pointer rep and a UReplaceableCallbacks |
| * function pointer struct repFunc. Functions in the repFunc struct |
| * will be called in order to modify the rep string. |
| * |
| * @param trans the transliterator |
| * @param rep a pointer to the string. This will be passed to the |
| * repFunc functions. |
| * @param repFunc a set of function pointers that will be used to |
| * modify the string pointed to by rep. |
| * @param start the beginning index, inclusive; <code>0 <= start <= |
| * limit</code>. |
| * @param limit pointer to the ending index, exclusive; <code>start <= |
| * limit <= repFunc->length(rep)</code>. Upon return, *limit will |
| * contain the new limit index. The text previously occupying |
| * <code>[start, limit)</code> has been transliterated, possibly to a |
| * string of a different length, at <code>[start, |
| * </code><em>new-limit</em><code>)</code>, where <em>new-limit</em> |
| * is the return value. |
| * @param status a pointer to the UErrorCode |
| * @stable ICU 2.0 |
| */ |
| U_STABLE void U_EXPORT2 |
| utrans_trans(const UTransliterator* trans, |
| UReplaceable* rep, |
| UReplaceableCallbacks* repFunc, |
| int32_t start, |
| int32_t* limit, |
| UErrorCode* status); |
| |
| /** |
| * Transliterate the portion of the UReplaceable text buffer that can |
| * be transliterated unambiguosly. This method is typically called |
| * after new text has been inserted, e.g. as a result of a keyboard |
| * event. The transliterator will try to transliterate characters of |
| * <code>rep</code> between <code>index.cursor</code> and |
| * <code>index.limit</code>. Characters before |
| * <code>index.cursor</code> will not be changed. |
| * |
| * <p>Upon return, values in <code>index</code> will be updated. |
| * <code>index.start</code> will be advanced to the first |
| * character that future calls to this method will read. |
| * <code>index.cursor</code> and <code>index.limit</code> will |
| * be adjusted to delimit the range of text that future calls to |
| * this method may change. |
| * |
| * <p>Typical usage of this method begins with an initial call |
| * with <code>index.start</code> and <code>index.limit</code> |
| * set to indicate the portion of <code>text</code> to be |
| * transliterated, and <code>index.cursor == index.start</code>. |
| * Thereafter, <code>index</code> can be used without |
| * modification in future calls, provided that all changes to |
| * <code>text</code> are made via this method. |
| * |
| * <p>This method assumes that future calls may be made that will |
| * insert new text into the buffer. As a result, it only performs |
| * unambiguous transliterations. After the last call to this method, |
| * there may be untransliterated text that is waiting for more input |
| * to resolve an ambiguity. In order to perform these pending |
| * transliterations, clients should call utrans_trans() with a start |
| * of index.start and a limit of index.end after the last call to this |
| * method has been made. |
| * |
| * @param trans the transliterator |
| * @param rep a pointer to the string. This will be passed to the |
| * repFunc functions. |
| * @param repFunc a set of function pointers that will be used to |
| * modify the string pointed to by rep. |
| * @param pos a struct containing the start and limit indices of the |
| * text to be read and the text to be transliterated |
| * @param status a pointer to the UErrorCode |
| * @stable ICU 2.0 |
| */ |
| U_STABLE void U_EXPORT2 |
| utrans_transIncremental(const UTransliterator* trans, |
| UReplaceable* rep, |
| UReplaceableCallbacks* repFunc, |
| UTransPosition* pos, |
| UErrorCode* status); |
| |
| /** |
| * Transliterate a segment of a UChar* string. The string is passed |
| * in in a UChar* buffer. The string is modified in place. If the |
| * result is longer than textCapacity, it is truncated. The actual |
| * length of the result is returned in *textLength, if textLength is |
| * non-NULL. *textLength may be greater than textCapacity, but only |
| * textCapacity UChars will be written to *text, including the zero |
| * terminator. |
| * |
| * @param trans the transliterator |
| * @param text a pointer to a buffer containing the text to be |
| * transliterated on input and the result text on output. |
| * @param textLength a pointer to the length of the string in text. |
| * If the length is -1 then the string is assumed to be |
| * zero-terminated. Upon return, the new length is stored in |
| * *textLength. If textLength is NULL then the string is assumed to |
| * be zero-terminated. |
| * @param textCapacity a pointer to the length of the text buffer. |
| * Upon return, |
| * @param start the beginning index, inclusive; <code>0 <= start <= |
| * limit</code>. |
| * @param limit pointer to the ending index, exclusive; <code>start <= |
| * limit <= repFunc->length(rep)</code>. Upon return, *limit will |
| * contain the new limit index. The text previously occupying |
| * <code>[start, limit)</code> has been transliterated, possibly to a |
| * string of a different length, at <code>[start, |
| * </code><em>new-limit</em><code>)</code>, where <em>new-limit</em> |
| * is the return value. |
| * @param status a pointer to the UErrorCode |
| * @stable ICU 2.0 |
| */ |
| U_STABLE void U_EXPORT2 |
| utrans_transUChars(const UTransliterator* trans, |
| UChar* text, |
| int32_t* textLength, |
| int32_t textCapacity, |
| int32_t start, |
| int32_t* limit, |
| UErrorCode* status); |
| |
| /** |
| * Transliterate the portion of the UChar* text buffer that can be |
| * transliterated unambiguosly. See utrans_transIncremental(). The |
| * string is passed in in a UChar* buffer. The string is modified in |
| * place. If the result is longer than textCapacity, it is truncated. |
| * The actual length of the result is returned in *textLength, if |
| * textLength is non-NULL. *textLength may be greater than |
| * textCapacity, but only textCapacity UChars will be written to |
| * *text, including the zero terminator. See utrans_transIncremental() |
| * for usage details. |
| * |
| * @param trans the transliterator |
| * @param text a pointer to a buffer containing the text to be |
| * transliterated on input and the result text on output. |
| * @param textLength a pointer to the length of the string in text. |
| * If the length is -1 then the string is assumed to be |
| * zero-terminated. Upon return, the new length is stored in |
| * *textLength. If textLength is NULL then the string is assumed to |
| * be zero-terminated. |
| * @param textCapacity the length of the text buffer |
| * @param pos a struct containing the start and limit indices of the |
| * text to be read and the text to be transliterated |
| * @param status a pointer to the UErrorCode |
| * @see utrans_transIncremental |
| * @stable ICU 2.0 |
| */ |
| U_STABLE void U_EXPORT2 |
| utrans_transIncrementalUChars(const UTransliterator* trans, |
| UChar* text, |
| int32_t* textLength, |
| int32_t textCapacity, |
| UTransPosition* pos, |
| UErrorCode* status); |
| |
| /* deprecated API ----------------------------------------------------------- */ |
| |
| /* see utrans.h documentation for why these functions are deprecated */ |
| |
| /** |
| * Deprecated, use utrans_openU() instead. |
| * Open a custom transliterator, given a custom rules string |
| * OR |
| * a system transliterator, given its ID. |
| * Any non-NULL result from this function should later be closed with |
| * utrans_close(). |
| * |
| * @param id a valid ID, as returned by utrans_getAvailableID() |
| * @param dir the desired direction |
| * @param rules the transliterator rules. See the C++ header rbt.h |
| * for rules syntax. If NULL then a system transliterator matching |
| * the ID is returned. |
| * @param rulesLength the length of the rules, or -1 if the rules |
| * are zero-terminated. |
| * @param parseError a pointer to a UParseError struct to receive the |
| * details of any parsing errors. This parameter may be NULL if no |
| * parsing error details are desired. |
| * @param status a pointer to the UErrorCode |
| * @return a transliterator pointer that may be passed to other |
| * utrans_xxx() functions, or NULL if the open call fails. |
| * @deprecated ICU 2.8 Use utrans_openU() instead, see utrans.h |
| */ |
| U_DEPRECATED UTransliterator* U_EXPORT2 |
| utrans_open(const char* id, |
| UTransDirection dir, |
| const UChar* rules, /* may be Null */ |
| int32_t rulesLength, /* -1 if null-terminated */ |
| UParseError* parseError, /* may be Null */ |
| UErrorCode* status); |
| |
| /** |
| * Deprecated, use utrans_getUnicodeID() instead. |
| * Return the programmatic identifier for this transliterator. |
| * If this identifier is passed to utrans_open(), it will open |
| * a transliterator equivalent to this one, if the ID has been |
| * registered. |
| * @param trans the transliterator to return the ID of. |
| * @param buf the buffer in which to receive the ID. This may be |
| * NULL, in which case no characters are copied. |
| * @param bufCapacity the capacity of the buffer. Ignored if buf is |
| * NULL. |
| * @return the actual length of the ID, not including |
| * zero-termination. This may be greater than bufCapacity. |
| * @deprecated ICU 2.8 Use utrans_getUnicodeID() instead, see utrans.h |
| */ |
| U_DEPRECATED int32_t U_EXPORT2 |
| utrans_getID(const UTransliterator* trans, |
| char* buf, |
| int32_t bufCapacity); |
| |
| /** |
| * Deprecated, use utrans_unregisterID() instead. |
| * Unregister a transliterator from the system. After this call the |
| * system will no longer recognize the given ID when passed to |
| * utrans_open(). If the id is invalid then nothing is done. |
| * |
| * @param id a zero-terminated ID |
| * @deprecated ICU 2.8 Use utrans_unregisterID() instead, see utrans.h |
| */ |
| U_DEPRECATED void U_EXPORT2 |
| utrans_unregister(const char* id); |
| |
| /** |
| * Deprecated, use utrans_openIDs() instead. |
| * Return the ID of the index-th system transliterator. The result |
| * is placed in the given buffer. If the given buffer is too small, |
| * the initial substring is copied to buf. The result in buf is |
| * always zero-terminated. |
| * |
| * @param index the number of the transliterator to return. Must |
| * satisfy 0 <= index < utrans_countAvailableIDs(). If index is out |
| * of range then it is treated as if it were 0. |
| * @param buf the buffer in which to receive the ID. This may be |
| * NULL, in which case no characters are copied. |
| * @param bufCapacity the capacity of the buffer. Ignored if buf is |
| * NULL. |
| * @return the actual length of the index-th ID, not including |
| * zero-termination. This may be greater than bufCapacity. |
| * @deprecated ICU 2.8 Use utrans_openIDs() instead, see utrans.h |
| */ |
| U_DEPRECATED int32_t U_EXPORT2 |
| utrans_getAvailableID(int32_t index, |
| char* buf, |
| int32_t bufCapacity); |
| |
| #endif /* #if !UCONFIG_NO_TRANSLITERATION */ |
| |
| #endif |