jpayne@69: // © 2016 and later: Unicode, Inc. and others. jpayne@69: // License & terms of use: http://www.unicode.org/copyright.html jpayne@69: /* jpayne@69: ******************************************************************************* jpayne@69: * Copyright (C) 1997-2011,2014-2015 International Business Machines jpayne@69: * Corporation and others. All Rights Reserved. jpayne@69: ******************************************************************************* jpayne@69: * Date Name Description jpayne@69: * 06/21/00 aliu Creation. jpayne@69: ******************************************************************************* jpayne@69: */ jpayne@69: jpayne@69: #ifndef UTRANS_H jpayne@69: #define UTRANS_H jpayne@69: jpayne@69: #include "unicode/utypes.h" jpayne@69: jpayne@69: #if !UCONFIG_NO_TRANSLITERATION jpayne@69: jpayne@69: #include "unicode/localpointer.h" jpayne@69: #include "unicode/urep.h" jpayne@69: #include "unicode/parseerr.h" jpayne@69: #include "unicode/uenum.h" jpayne@69: #include "unicode/uset.h" jpayne@69: jpayne@69: /******************************************************************** jpayne@69: * General Notes jpayne@69: ******************************************************************** jpayne@69: */ jpayne@69: /** jpayne@69: * \file jpayne@69: * \brief C API: Transliterator jpayne@69: * jpayne@69: *

Transliteration

jpayne@69: * The data structures and functions described in this header provide jpayne@69: * transliteration services. Transliteration services are implemented jpayne@69: * as C++ classes. The comments and documentation in this header jpayne@69: * assume the reader is familiar with the C++ headers translit.h and jpayne@69: * associated documentation. jpayne@69: * jpayne@69: * A significant but incomplete subset of the C++ transliteration jpayne@69: * services are available to C code through this header. In order to jpayne@69: * access more complex transliteration services, refer to the C++ jpayne@69: * headers and documentation. jpayne@69: * jpayne@69: * There are two sets of functions for working with transliterator IDs: jpayne@69: * jpayne@69: * An old, deprecated set uses char * IDs, which works for true and pure jpayne@69: * identifiers that these APIs were designed for, jpayne@69: * for example "Cyrillic-Latin". jpayne@69: * It does not work when the ID contains filters ("[:Script=Cyrl:]") jpayne@69: * or even a complete set of rules because then the ID string contains more jpayne@69: * than just "invariant" characters (see utypes.h). jpayne@69: * jpayne@69: * A new set of functions replaces the old ones and uses UChar * IDs, jpayne@69: * paralleling the UnicodeString IDs in the C++ API. (New in ICU 2.8.) jpayne@69: */ jpayne@69: jpayne@69: /******************************************************************** jpayne@69: * Data Structures jpayne@69: ********************************************************************/ jpayne@69: jpayne@69: /** jpayne@69: * An opaque transliterator for use in C. Open with utrans_openxxx() jpayne@69: * and close with utrans_close() when done. Equivalent to the C++ class jpayne@69: * Transliterator and its subclasses. jpayne@69: * @see Transliterator jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: typedef void* UTransliterator; jpayne@69: jpayne@69: /** jpayne@69: * Direction constant indicating the direction in a transliterator, jpayne@69: * e.g., the forward or reverse rules of a RuleBasedTransliterator. jpayne@69: * Specified when a transliterator is opened. An "A-B" transliterator jpayne@69: * transliterates A to B when operating in the forward direction, and jpayne@69: * B to A when operating in the reverse direction. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: typedef enum UTransDirection { jpayne@69: jpayne@69: /** jpayne@69: * UTRANS_FORWARD means from <source> to <target> for a jpayne@69: * transliterator with ID <source>-<target>. For a transliterator jpayne@69: * opened using a rule, it means forward direction rules, e.g., jpayne@69: * "A > B". jpayne@69: */ jpayne@69: UTRANS_FORWARD, jpayne@69: jpayne@69: /** jpayne@69: * UTRANS_REVERSE means from <target> to <source> for a jpayne@69: * transliterator with ID <source>-<target>. For a transliterator jpayne@69: * opened using a rule, it means reverse direction rules, e.g., jpayne@69: * "A < B". jpayne@69: */ jpayne@69: UTRANS_REVERSE jpayne@69: jpayne@69: } UTransDirection; jpayne@69: jpayne@69: /** jpayne@69: * Position structure for utrans_transIncremental() incremental jpayne@69: * transliteration. This structure defines two substrings of the text jpayne@69: * being transliterated. The first region, [contextStart, jpayne@69: * contextLimit), defines what characters the transliterator will read jpayne@69: * as context. The second region, [start, limit), defines what jpayne@69: * characters will actually be transliterated. The second region jpayne@69: * should be a subset of the first. jpayne@69: * jpayne@69: *

After a transliteration operation, some of the indices in this jpayne@69: * structure will be modified. See the field descriptions for jpayne@69: * details. jpayne@69: * jpayne@69: *

contextStart <= start <= limit <= contextLimit jpayne@69: * jpayne@69: *

Note: All index values in this structure must be at code point jpayne@69: * boundaries. That is, none of them may occur between two code units jpayne@69: * of a surrogate pair. If any index does split a surrogate pair, jpayne@69: * results are unspecified. jpayne@69: * jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: typedef struct UTransPosition { jpayne@69: jpayne@69: /** jpayne@69: * Beginning index, inclusive, of the context to be considered for jpayne@69: * a transliteration operation. The transliterator will ignore jpayne@69: * anything before this index. INPUT/OUTPUT parameter: This parameter jpayne@69: * is updated by a transliteration operation to reflect the maximum jpayne@69: * amount of antecontext needed by a transliterator. jpayne@69: * @stable ICU 2.4 jpayne@69: */ jpayne@69: int32_t contextStart; jpayne@69: jpayne@69: /** jpayne@69: * Ending index, exclusive, of the context to be considered for a jpayne@69: * transliteration operation. The transliterator will ignore jpayne@69: * anything at or after this index. INPUT/OUTPUT parameter: This jpayne@69: * parameter is updated to reflect changes in the length of the jpayne@69: * text, but points to the same logical position in the text. jpayne@69: * @stable ICU 2.4 jpayne@69: */ jpayne@69: int32_t contextLimit; jpayne@69: jpayne@69: /** jpayne@69: * Beginning index, inclusive, of the text to be transliterated. jpayne@69: * INPUT/OUTPUT parameter: This parameter is advanced past jpayne@69: * characters that have already been transliterated by a jpayne@69: * transliteration operation. jpayne@69: * @stable ICU 2.4 jpayne@69: */ jpayne@69: int32_t start; jpayne@69: jpayne@69: /** jpayne@69: * Ending index, exclusive, of the text to be transliterated. jpayne@69: * INPUT/OUTPUT parameter: This parameter is updated to reflect jpayne@69: * changes in the length of the text, but points to the same jpayne@69: * logical position in the text. jpayne@69: * @stable ICU 2.4 jpayne@69: */ jpayne@69: int32_t limit; jpayne@69: jpayne@69: } UTransPosition; jpayne@69: jpayne@69: /******************************************************************** jpayne@69: * General API jpayne@69: ********************************************************************/ jpayne@69: jpayne@69: /** jpayne@69: * Open a custom transliterator, given a custom rules string jpayne@69: * OR jpayne@69: * a system transliterator, given its ID. jpayne@69: * Any non-NULL result from this function should later be closed with jpayne@69: * utrans_close(). jpayne@69: * jpayne@69: * @param id a valid transliterator ID jpayne@69: * @param idLength the length of the ID string, or -1 if NUL-terminated jpayne@69: * @param dir the desired direction jpayne@69: * @param rules the transliterator rules. See the C++ header rbt.h for jpayne@69: * rules syntax. If NULL then a system transliterator matching jpayne@69: * the ID is returned. jpayne@69: * @param rulesLength the length of the rules, or -1 if the rules jpayne@69: * are NUL-terminated. jpayne@69: * @param parseError a pointer to a UParseError struct to receive the details jpayne@69: * of any parsing errors. This parameter may be NULL if no jpayne@69: * parsing error details are desired. jpayne@69: * @param pErrorCode a pointer to the UErrorCode jpayne@69: * @return a transliterator pointer that may be passed to other jpayne@69: * utrans_xxx() functions, or NULL if the open call fails. jpayne@69: * @stable ICU 2.8 jpayne@69: */ jpayne@69: U_STABLE UTransliterator* U_EXPORT2 jpayne@69: utrans_openU(const UChar *id, jpayne@69: int32_t idLength, jpayne@69: UTransDirection dir, jpayne@69: const UChar *rules, jpayne@69: int32_t rulesLength, jpayne@69: UParseError *parseError, jpayne@69: UErrorCode *pErrorCode); jpayne@69: jpayne@69: /** jpayne@69: * Open an inverse of an existing transliterator. For this to work, jpayne@69: * the inverse must be registered with the system. For example, if jpayne@69: * the Transliterator "A-B" is opened, and then its inverse is opened, jpayne@69: * the result is the Transliterator "B-A", if such a transliterator is jpayne@69: * registered with the system. Otherwise the result is NULL and a jpayne@69: * failing UErrorCode is set. Any non-NULL result from this function jpayne@69: * should later be closed with utrans_close(). jpayne@69: * jpayne@69: * @param trans the transliterator to open the inverse of. jpayne@69: * @param status a pointer to the UErrorCode jpayne@69: * @return a pointer to a newly-opened transliterator that is the jpayne@69: * inverse of trans, or NULL if the open call fails. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE UTransliterator* U_EXPORT2 jpayne@69: utrans_openInverse(const UTransliterator* trans, jpayne@69: UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Create a copy of a transliterator. Any non-NULL result from this jpayne@69: * function should later be closed with utrans_close(). jpayne@69: * jpayne@69: * @param trans the transliterator to be copied. jpayne@69: * @param status a pointer to the UErrorCode jpayne@69: * @return a transliterator pointer that may be passed to other jpayne@69: * utrans_xxx() functions, or NULL if the clone call fails. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE UTransliterator* U_EXPORT2 jpayne@69: utrans_clone(const UTransliterator* trans, jpayne@69: UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Close a transliterator. Any non-NULL pointer returned by jpayne@69: * utrans_openXxx() or utrans_clone() should eventually be closed. jpayne@69: * @param trans the transliterator to be closed. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: utrans_close(UTransliterator* trans); jpayne@69: jpayne@69: #if U_SHOW_CPLUSPLUS_API jpayne@69: jpayne@69: U_NAMESPACE_BEGIN jpayne@69: jpayne@69: /** jpayne@69: * \class LocalUTransliteratorPointer jpayne@69: * "Smart pointer" class, closes a UTransliterator via utrans_close(). jpayne@69: * For most methods see the LocalPointerBase base class. jpayne@69: * jpayne@69: * @see LocalPointerBase jpayne@69: * @see LocalPointer jpayne@69: * @stable ICU 4.4 jpayne@69: */ jpayne@69: U_DEFINE_LOCAL_OPEN_POINTER(LocalUTransliteratorPointer, UTransliterator, utrans_close); jpayne@69: jpayne@69: U_NAMESPACE_END jpayne@69: jpayne@69: #endif jpayne@69: jpayne@69: /** jpayne@69: * Return the programmatic identifier for this transliterator. jpayne@69: * If this identifier is passed to utrans_openU(), it will open jpayne@69: * a transliterator equivalent to this one, if the ID has been jpayne@69: * registered. jpayne@69: * jpayne@69: * @param trans the transliterator to return the ID of. jpayne@69: * @param resultLength pointer to an output variable receiving the length jpayne@69: * of the ID string; can be NULL jpayne@69: * @return the NUL-terminated ID string. This pointer remains jpayne@69: * valid until utrans_close() is called on this transliterator. jpayne@69: * jpayne@69: * @stable ICU 2.8 jpayne@69: */ jpayne@69: U_STABLE const UChar * U_EXPORT2 jpayne@69: utrans_getUnicodeID(const UTransliterator *trans, jpayne@69: int32_t *resultLength); jpayne@69: jpayne@69: /** jpayne@69: * Register an open transliterator with the system. When jpayne@69: * utrans_open() is called with an ID string that is equal to that jpayne@69: * returned by utrans_getID(adoptedTrans,...), then jpayne@69: * utrans_clone(adoptedTrans,...) is returned. jpayne@69: * jpayne@69: *

NOTE: After this call the system owns the adoptedTrans and will jpayne@69: * close it. The user must not call utrans_close() on adoptedTrans. jpayne@69: * jpayne@69: * @param adoptedTrans a transliterator, typically the result of jpayne@69: * utrans_openRules(), to be registered with the system. jpayne@69: * @param status a pointer to the UErrorCode jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: utrans_register(UTransliterator* adoptedTrans, jpayne@69: UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Unregister a transliterator from the system. After this call the jpayne@69: * system will no longer recognize the given ID when passed to jpayne@69: * utrans_open(). If the ID is invalid then nothing is done. jpayne@69: * jpayne@69: * @param id an ID to unregister jpayne@69: * @param idLength the length of id, or -1 if id is zero-terminated jpayne@69: * @stable ICU 2.8 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: utrans_unregisterID(const UChar* id, int32_t idLength); jpayne@69: jpayne@69: /** jpayne@69: * Set the filter used by a transliterator. A filter can be used to jpayne@69: * make the transliterator pass certain characters through untouched. jpayne@69: * The filter is expressed using a UnicodeSet pattern. If the jpayne@69: * filterPattern is NULL or the empty string, then the transliterator jpayne@69: * will be reset to use no filter. jpayne@69: * jpayne@69: * @param trans the transliterator jpayne@69: * @param filterPattern a pattern string, in the form accepted by jpayne@69: * UnicodeSet, specifying which characters to apply the jpayne@69: * transliteration to. May be NULL or the empty string to indicate no jpayne@69: * filter. jpayne@69: * @param filterPatternLen the length of filterPattern, or -1 if jpayne@69: * filterPattern is zero-terminated jpayne@69: * @param status a pointer to the UErrorCode jpayne@69: * @see UnicodeSet jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: utrans_setFilter(UTransliterator* trans, jpayne@69: const UChar* filterPattern, jpayne@69: int32_t filterPatternLen, jpayne@69: UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Return the number of system transliterators. jpayne@69: * It is recommended to use utrans_openIDs() instead. jpayne@69: * jpayne@69: * @return the number of system transliterators. jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: utrans_countAvailableIDs(void); jpayne@69: jpayne@69: /** jpayne@69: * Return a UEnumeration for the available transliterators. jpayne@69: * jpayne@69: * @param pErrorCode Pointer to the UErrorCode in/out parameter. jpayne@69: * @return UEnumeration for the available transliterators. jpayne@69: * Close with uenum_close(). jpayne@69: * jpayne@69: * @stable ICU 2.8 jpayne@69: */ jpayne@69: U_STABLE UEnumeration * U_EXPORT2 jpayne@69: utrans_openIDs(UErrorCode *pErrorCode); jpayne@69: jpayne@69: /******************************************************************** jpayne@69: * Transliteration API jpayne@69: ********************************************************************/ jpayne@69: jpayne@69: /** jpayne@69: * Transliterate a segment of a UReplaceable string. The string is jpayne@69: * passed in as a UReplaceable pointer rep and a UReplaceableCallbacks jpayne@69: * function pointer struct repFunc. Functions in the repFunc struct jpayne@69: * will be called in order to modify the rep string. jpayne@69: * jpayne@69: * @param trans the transliterator jpayne@69: * @param rep a pointer to the string. This will be passed to the jpayne@69: * repFunc functions. jpayne@69: * @param repFunc a set of function pointers that will be used to jpayne@69: * modify the string pointed to by rep. jpayne@69: * @param start the beginning index, inclusive; 0 <= start <= jpayne@69: * limit. jpayne@69: * @param limit pointer to the ending index, exclusive; start <= jpayne@69: * limit <= repFunc->length(rep). Upon return, *limit will jpayne@69: * contain the new limit index. The text previously occupying jpayne@69: * [start, limit) has been transliterated, possibly to a jpayne@69: * string of a different length, at [start, jpayne@69: * new-limit), where new-limit jpayne@69: * is the return value. jpayne@69: * @param status a pointer to the UErrorCode jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: utrans_trans(const UTransliterator* trans, jpayne@69: UReplaceable* rep, jpayne@69: const UReplaceableCallbacks* repFunc, jpayne@69: int32_t start, jpayne@69: int32_t* limit, jpayne@69: UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Transliterate the portion of the UReplaceable text buffer that can jpayne@69: * be transliterated unambiguously. This method is typically called jpayne@69: * after new text has been inserted, e.g. as a result of a keyboard jpayne@69: * event. The transliterator will try to transliterate characters of jpayne@69: * rep between index.cursor and jpayne@69: * index.limit. Characters before jpayne@69: * index.cursor will not be changed. jpayne@69: * jpayne@69: *

Upon return, values in index will be updated. jpayne@69: * index.start will be advanced to the first jpayne@69: * character that future calls to this method will read. jpayne@69: * index.cursor and index.limit will jpayne@69: * be adjusted to delimit the range of text that future calls to jpayne@69: * this method may change. jpayne@69: * jpayne@69: *

Typical usage of this method begins with an initial call jpayne@69: * with index.start and index.limit jpayne@69: * set to indicate the portion of text to be jpayne@69: * transliterated, and index.cursor == index.start. jpayne@69: * Thereafter, index can be used without jpayne@69: * modification in future calls, provided that all changes to jpayne@69: * text are made via this method. jpayne@69: * jpayne@69: *

This method assumes that future calls may be made that will jpayne@69: * insert new text into the buffer. As a result, it only performs jpayne@69: * unambiguous transliterations. After the last call to this method, jpayne@69: * there may be untransliterated text that is waiting for more input jpayne@69: * to resolve an ambiguity. In order to perform these pending jpayne@69: * transliterations, clients should call utrans_trans() with a start jpayne@69: * of index.start and a limit of index.end after the last call to this jpayne@69: * method has been made. jpayne@69: * jpayne@69: * @param trans the transliterator jpayne@69: * @param rep a pointer to the string. This will be passed to the jpayne@69: * repFunc functions. jpayne@69: * @param repFunc a set of function pointers that will be used to jpayne@69: * modify the string pointed to by rep. jpayne@69: * @param pos a struct containing the start and limit indices of the jpayne@69: * text to be read and the text to be transliterated jpayne@69: * @param status a pointer to the UErrorCode jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: utrans_transIncremental(const UTransliterator* trans, jpayne@69: UReplaceable* rep, jpayne@69: const UReplaceableCallbacks* repFunc, jpayne@69: UTransPosition* pos, jpayne@69: UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Transliterate a segment of a UChar* string. The string is passed jpayne@69: * in in a UChar* buffer. The string is modified in place. If the jpayne@69: * result is longer than textCapacity, it is truncated. The actual jpayne@69: * length of the result is returned in *textLength, if textLength is jpayne@69: * non-NULL. *textLength may be greater than textCapacity, but only jpayne@69: * textCapacity UChars will be written to *text, including the zero jpayne@69: * terminator. jpayne@69: * jpayne@69: * @param trans the transliterator jpayne@69: * @param text a pointer to a buffer containing the text to be jpayne@69: * transliterated on input and the result text on output. jpayne@69: * @param textLength a pointer to the length of the string in text. jpayne@69: * If the length is -1 then the string is assumed to be jpayne@69: * zero-terminated. Upon return, the new length is stored in jpayne@69: * *textLength. If textLength is NULL then the string is assumed to jpayne@69: * be zero-terminated. jpayne@69: * @param textCapacity the length of the text buffer jpayne@69: * @param start the beginning index, inclusive; 0 <= start <= jpayne@69: * limit. jpayne@69: * @param limit pointer to the ending index, exclusive; start <= jpayne@69: * limit <= repFunc->length(rep). Upon return, *limit will jpayne@69: * contain the new limit index. The text previously occupying jpayne@69: * [start, limit) has been transliterated, possibly to a jpayne@69: * string of a different length, at [start, jpayne@69: * new-limit), where new-limit jpayne@69: * is the return value. jpayne@69: * @param status a pointer to the UErrorCode jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: utrans_transUChars(const UTransliterator* trans, jpayne@69: UChar* text, jpayne@69: int32_t* textLength, jpayne@69: int32_t textCapacity, jpayne@69: int32_t start, jpayne@69: int32_t* limit, jpayne@69: UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Transliterate the portion of the UChar* text buffer that can be jpayne@69: * transliterated unambiguously. See utrans_transIncremental(). The jpayne@69: * string is passed in in a UChar* buffer. The string is modified in jpayne@69: * place. If the result is longer than textCapacity, it is truncated. jpayne@69: * The actual length of the result is returned in *textLength, if jpayne@69: * textLength is non-NULL. *textLength may be greater than jpayne@69: * textCapacity, but only textCapacity UChars will be written to jpayne@69: * *text, including the zero terminator. See utrans_transIncremental() jpayne@69: * for usage details. jpayne@69: * jpayne@69: * @param trans the transliterator jpayne@69: * @param text a pointer to a buffer containing the text to be jpayne@69: * transliterated on input and the result text on output. jpayne@69: * @param textLength a pointer to the length of the string in text. jpayne@69: * If the length is -1 then the string is assumed to be jpayne@69: * zero-terminated. Upon return, the new length is stored in jpayne@69: * *textLength. If textLength is NULL then the string is assumed to jpayne@69: * be zero-terminated. jpayne@69: * @param textCapacity the length of the text buffer jpayne@69: * @param pos a struct containing the start and limit indices of the jpayne@69: * text to be read and the text to be transliterated jpayne@69: * @param status a pointer to the UErrorCode jpayne@69: * @see utrans_transIncremental jpayne@69: * @stable ICU 2.0 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: utrans_transIncrementalUChars(const UTransliterator* trans, jpayne@69: UChar* text, jpayne@69: int32_t* textLength, jpayne@69: int32_t textCapacity, jpayne@69: UTransPosition* pos, jpayne@69: UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Create a rule string that can be passed to utrans_openU to recreate this jpayne@69: * transliterator. jpayne@69: * jpayne@69: * @param trans The transliterator jpayne@69: * @param escapeUnprintable if TRUE then convert unprintable characters to their jpayne@69: * hex escape representations, \\uxxxx or \\Uxxxxxxxx. jpayne@69: * Unprintable characters are those other than jpayne@69: * U+000A, U+0020..U+007E. jpayne@69: * @param result A pointer to a buffer to receive the rules. jpayne@69: * @param resultLength The maximum size of result. jpayne@69: * @param status A pointer to the UErrorCode. In case of error status, the jpayne@69: * contents of result are undefined. jpayne@69: * @return int32_t The length of the rule string (may be greater than resultLength, jpayne@69: * in which case an error is returned). jpayne@69: * @stable ICU 53 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: utrans_toRules( const UTransliterator* trans, jpayne@69: UBool escapeUnprintable, jpayne@69: UChar* result, int32_t resultLength, jpayne@69: UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Returns the set of all characters that may be modified in the input text by jpayne@69: * this UTransliterator, optionally ignoring the transliterator's current filter. jpayne@69: * @param trans The transliterator. jpayne@69: * @param ignoreFilter If FALSE, the returned set incorporates the jpayne@69: * UTransliterator's current filter; if the filter is changed, jpayne@69: * the return value of this function will change. If TRUE, the jpayne@69: * returned set ignores the effect of the UTransliterator's jpayne@69: * current filter. jpayne@69: * @param fillIn Pointer to a USet object to receive the modifiable characters jpayne@69: * set. Previous contents of fillIn are lost. If fillIn is jpayne@69: * NULL, then a new USet is created and returned. The caller jpayne@69: * owns the result and must dispose of it by calling uset_close. jpayne@69: * @param status A pointer to the UErrorCode. jpayne@69: * @return USet* Either fillIn, or if fillIn is NULL, a pointer to a jpayne@69: * newly-allocated USet that the user must close. In case of jpayne@69: * error, NULL is returned. jpayne@69: * @stable ICU 53 jpayne@69: */ jpayne@69: U_STABLE USet* U_EXPORT2 jpayne@69: utrans_getSourceSet(const UTransliterator* trans, jpayne@69: UBool ignoreFilter, jpayne@69: USet* fillIn, jpayne@69: UErrorCode* status); jpayne@69: jpayne@69: /* deprecated API ----------------------------------------------------------- */ jpayne@69: jpayne@69: #ifndef U_HIDE_DEPRECATED_API jpayne@69: jpayne@69: /* see utrans.h documentation for why these functions are deprecated */ jpayne@69: jpayne@69: /** jpayne@69: * Deprecated, use utrans_openU() instead. jpayne@69: * Open a custom transliterator, given a custom rules string jpayne@69: * OR jpayne@69: * a system transliterator, given its ID. jpayne@69: * Any non-NULL result from this function should later be closed with jpayne@69: * utrans_close(). jpayne@69: * jpayne@69: * @param id a valid ID, as returned by utrans_getAvailableID() jpayne@69: * @param dir the desired direction jpayne@69: * @param rules the transliterator rules. See the C++ header rbt.h jpayne@69: * for rules syntax. If NULL then a system transliterator matching jpayne@69: * the ID is returned. jpayne@69: * @param rulesLength the length of the rules, or -1 if the rules jpayne@69: * are zero-terminated. jpayne@69: * @param parseError a pointer to a UParseError struct to receive the jpayne@69: * details of any parsing errors. This parameter may be NULL if no jpayne@69: * parsing error details are desired. jpayne@69: * @param status a pointer to the UErrorCode jpayne@69: * @return a transliterator pointer that may be passed to other jpayne@69: * utrans_xxx() functions, or NULL if the open call fails. jpayne@69: * @deprecated ICU 2.8 Use utrans_openU() instead, see utrans.h jpayne@69: */ jpayne@69: U_DEPRECATED UTransliterator* U_EXPORT2 jpayne@69: utrans_open(const char* id, jpayne@69: UTransDirection dir, jpayne@69: const UChar* rules, /* may be Null */ jpayne@69: int32_t rulesLength, /* -1 if null-terminated */ jpayne@69: UParseError* parseError, /* may be Null */ jpayne@69: UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Deprecated, use utrans_getUnicodeID() instead. jpayne@69: * Return the programmatic identifier for this transliterator. jpayne@69: * If this identifier is passed to utrans_open(), it will open jpayne@69: * a transliterator equivalent to this one, if the ID has been jpayne@69: * registered. jpayne@69: * @param trans the transliterator to return the ID of. jpayne@69: * @param buf the buffer in which to receive the ID. This may be jpayne@69: * NULL, in which case no characters are copied. jpayne@69: * @param bufCapacity the capacity of the buffer. Ignored if buf is jpayne@69: * NULL. jpayne@69: * @return the actual length of the ID, not including jpayne@69: * zero-termination. This may be greater than bufCapacity. jpayne@69: * @deprecated ICU 2.8 Use utrans_getUnicodeID() instead, see utrans.h jpayne@69: */ jpayne@69: U_DEPRECATED int32_t U_EXPORT2 jpayne@69: utrans_getID(const UTransliterator* trans, jpayne@69: char* buf, jpayne@69: int32_t bufCapacity); jpayne@69: jpayne@69: /** jpayne@69: * Deprecated, use utrans_unregisterID() instead. jpayne@69: * Unregister a transliterator from the system. After this call the jpayne@69: * system will no longer recognize the given ID when passed to jpayne@69: * utrans_open(). If the id is invalid then nothing is done. jpayne@69: * jpayne@69: * @param id a zero-terminated ID jpayne@69: * @deprecated ICU 2.8 Use utrans_unregisterID() instead, see utrans.h jpayne@69: */ jpayne@69: U_DEPRECATED void U_EXPORT2 jpayne@69: utrans_unregister(const char* id); jpayne@69: jpayne@69: /** jpayne@69: * Deprecated, use utrans_openIDs() instead. jpayne@69: * Return the ID of the index-th system transliterator. The result jpayne@69: * is placed in the given buffer. If the given buffer is too small, jpayne@69: * the initial substring is copied to buf. The result in buf is jpayne@69: * always zero-terminated. jpayne@69: * jpayne@69: * @param index the number of the transliterator to return. Must jpayne@69: * satisfy 0 <= index < utrans_countAvailableIDs(). If index is out jpayne@69: * of range then it is treated as if it were 0. jpayne@69: * @param buf the buffer in which to receive the ID. This may be jpayne@69: * NULL, in which case no characters are copied. jpayne@69: * @param bufCapacity the capacity of the buffer. Ignored if buf is jpayne@69: * NULL. jpayne@69: * @return the actual length of the index-th ID, not including jpayne@69: * zero-termination. This may be greater than bufCapacity. jpayne@69: * @deprecated ICU 2.8 Use utrans_openIDs() instead, see utrans.h jpayne@69: */ jpayne@69: U_DEPRECATED int32_t U_EXPORT2 jpayne@69: utrans_getAvailableID(int32_t index, jpayne@69: char* buf, jpayne@69: int32_t bufCapacity); jpayne@69: jpayne@69: #endif /* U_HIDE_DEPRECATED_API */ jpayne@69: jpayne@69: #endif /* #if !UCONFIG_NO_TRANSLITERATION */ jpayne@69: jpayne@69: #endif