// © 2016 and later: Unicode, Inc. and others. // License & terms of use: http://www.unicode.org/copyright.html /* ******************************************************************************* * Copyright (C) 1997-2011,2014-2015 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/parseerr.h" #include "unicode/uenum.h" #include "unicode/uset.h" #if U_SHOW_CPLUSPLUS_API #include "unicode/localpointer.h" #endif // U_SHOW_CPLUSPLUS_API /******************************************************************** * General Notes ******************************************************************** */ /** * \file * \brief C API: Transliterator * *
After a transliteration operation, some of the indices in this * structure will be modified. See the field descriptions for * details. * *
contextStart <= start <= limit <= contextLimit * *
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 transliterated. * 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 transliterated. * 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_CAPI 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_CAPI 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_CAPI 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_CAPI 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 * @stable 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_CAPI 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. * *
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_CAPI 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_CAPI 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_CAPI 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_CAPI 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_CAPI UEnumeration * U_EXPORT2
utrans_openIDs(UErrorCode *pErrorCode);
/********************************************************************
* Transliteration API
********************************************************************/
/**
* 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 the length of the text buffer
* @param start the beginning index, inclusive; 0 <= start <=
* limit
.
* @param limit pointer to the ending index, exclusive; start <=
* limit <= repFunc->length(rep)
. Upon return, *limit will
* contain the new limit index. The text previously occupying
* [start, limit)
has been transliterated, possibly to a
* string of a different length, at [start,
*
new-limit)
, where new-limit
* is the return value.
* @param status a pointer to the UErrorCode
* @stable ICU 2.0
*/
U_CAPI 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 unambiguously. 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_CAPI void U_EXPORT2
utrans_transIncrementalUChars(const UTransliterator* trans,
UChar* text,
int32_t* textLength,
int32_t textCapacity,
UTransPosition* pos,
UErrorCode* status);
/**
* Create a rule string that can be passed to utrans_openU to recreate this
* transliterator.
*
* @param trans The transliterator
* @param escapeUnprintable if true then convert unprintable characters to their
* hex escape representations, \\uxxxx or \\Uxxxxxxxx.
* Unprintable characters are those other than
* U+000A, U+0020..U+007E.
* @param result A pointer to a buffer to receive the rules.
* @param resultLength The maximum size of result.
* @param status A pointer to the UErrorCode. In case of error status, the
* contents of result are undefined.
* @return int32_t The length of the rule string (may be greater than resultLength,
* in which case an error is returned).
* @stable ICU 53
*/
U_CAPI int32_t U_EXPORT2
utrans_toRules( const UTransliterator* trans,
UBool escapeUnprintable,
UChar* result, int32_t resultLength,
UErrorCode* status);
/**
* Returns the set of all characters that may be modified in the input text by
* this UTransliterator, optionally ignoring the transliterator's current filter.
* @param trans The transliterator.
* @param ignoreFilter If false, the returned set incorporates the
* UTransliterator's current filter; if the filter is changed,
* the return value of this function will change. If true, the
* returned set ignores the effect of the UTransliterator's
* current filter.
* @param fillIn Pointer to a USet object to receive the modifiable characters
* set. Previous contents of fillIn are lost. If fillIn is
* NULL, then a new USet is created and returned. The caller
* owns the result and must dispose of it by calling uset_close.
* @param status A pointer to the UErrorCode.
* @return USet* Either fillIn, or if fillIn is NULL, a pointer to a
* newly-allocated USet that the user must close. In case of
* error, NULL is returned.
* @stable ICU 53
*/
U_CAPI USet* U_EXPORT2
utrans_getSourceSet(const UTransliterator* trans,
UBool ignoreFilter,
USet* fillIn,
UErrorCode* status);
/* deprecated API ----------------------------------------------------------- */
#ifndef U_HIDE_DEPRECATED_API
/* see utrans.h documentation for why these functions are deprecated */
#endif /* U_HIDE_DEPRECATED_API */
#endif /* #if !UCONFIG_NO_TRANSLITERATION */
#endif