/*
*******************************************************************************
-* Copyright (C) 1997-2003, International Business Machines
+* Copyright (C) 1997-2011,2014 International Business Machines
* Corporation and others. All Rights Reserved.
*******************************************************************************
* Date Name Description
#if !UCONFIG_NO_TRANSLITERATION
+#include "unicode/localpointer.h"
#include "unicode/urep.h"
#include "unicode/parseerr.h"
+#include "unicode/uenum.h"
+#include "unicode/uset.h"
/********************************************************************
* General Notes
* 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.)
*/
/********************************************************************
typedef enum UTransDirection {
/**
- * UTRANS_FORWARD means from <source> to <target> for a
- * transliterator with ID <source>-<target>. For a transliterator
+ * 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
+ * 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".
*/
* 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.
- * @draft ICU 2.4
+ * @stable ICU 2.4
*/
int32_t contextStart;
* 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.
- * @draft ICU 2.4
+ * @stable ICU 2.4
*/
int32_t contextLimit;
* INPUT/OUTPUT parameter: This parameter is advanced past
* characters that have already been transliterated by a
* transliteration operation.
- * @draft ICU 2.4
+ * @stable ICU 2.4
*/
int32_t start;
* 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.
- * @draft ICU 2.4
+ * @stable ICU 2.4
*/
int32_t limit;
* 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 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 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 dir the desired direction
- * @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
+ * 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.0
+ * utrans_xxx() functions, or NULL if the open call fails.
+ * @stable ICU 2.8
*/
-U_CAPI 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);
+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,
* inverse of trans, or NULL if the open call fails.
* @stable ICU 2.0
*/
-U_CAPI UTransliterator* U_EXPORT2
+U_STABLE UTransliterator* U_EXPORT2
utrans_openInverse(const UTransliterator* trans,
UErrorCode* status);
* utrans_xxx() functions, or NULL if the clone call fails.
* @stable ICU 2.0
*/
-U_CAPI UTransliterator* U_EXPORT2
+U_STABLE UTransliterator* U_EXPORT2
utrans_clone(const UTransliterator* trans,
UErrorCode* status);
* @param trans the transliterator to be closed.
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+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
+ * @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_open(), it will open
+ * 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 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.
- * @stable ICU 2.0
+ * @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 int32_t U_EXPORT2
-utrans_getID(const UTransliterator* trans,
- char* buf,
- int32_t bufCapacity);
+U_STABLE const UChar * U_EXPORT2
+utrans_getUnicodeID(const UTransliterator *trans,
+ int32_t *resultLength);
/**
* Register an open transliterator with the system. When
* @param status a pointer to the UErrorCode
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+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.
+ * utrans_open(). If the ID is invalid then nothing is done.
*
- * @param id a zero-terminated ID
- * @stable ICU 2.0
+ * @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_unregister(const char* id);
+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
* @see UnicodeSet
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
utrans_setFilter(UTransliterator* trans,
const UChar* filterPattern,
int32_t filterPatternLen,
/**
* 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
+U_STABLE int32_t U_EXPORT2
utrans_countAvailableIDs(void);
/**
- * 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.
+ * Return a UEnumeration for the available transliterators.
*
- * @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.
- * @stable ICU 2.0
+ * @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 int32_t U_EXPORT2
-utrans_getAvailableID(int32_t index,
- char* buf,
- int32_t bufCapacity);
+U_STABLE UEnumeration * U_EXPORT2
+utrans_openIDs(UErrorCode *pErrorCode);
/********************************************************************
* Transliteration API
* @param status a pointer to the UErrorCode
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
utrans_trans(const UTransliterator* trans,
UReplaceable* rep,
UReplaceableCallbacks* repFunc,
* @param status a pointer to the UErrorCode
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
utrans_transIncremental(const UTransliterator* trans,
UReplaceable* rep,
UReplaceableCallbacks* repFunc,
* @param status a pointer to the UErrorCode
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
utrans_transUChars(const UTransliterator* trans,
UChar* text,
int32_t* textLength,
* @see utrans_transIncremental
* @stable ICU 2.0
*/
-U_CAPI void U_EXPORT2
+U_STABLE void U_EXPORT2
utrans_transIncrementalUChars(const UTransliterator* trans,
UChar* text,
int32_t* textLength,
UTransPosition* pos,
UErrorCode* status);
+#ifndef U_HIDE_DRAFT_API
+/**
+ * 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).
+ * @draft ICU 53
+ */
+U_DRAFT int32_t U_EXPORT2
+utrans_toRules( const UTransliterator* trans,
+ UBool escapeUnprintable,
+ UChar* result, int32_t resultLength,
+ UErrorCode* status);
-/********************* Obsolete API ************************************/
/**
- * TODO: Remove after Aug 2002
+ * 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. <em>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.</em>
+ * @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.
+ * @draft ICU 53
*/
+U_DRAFT USet* U_EXPORT2
+utrans_getSourceSet(const UTransliterator* trans,
+ UBool ignoreFilter,
+ USet* fillIn,
+ UErrorCode* status);
+#endif /* U_HIDE_DRAFT_API */
-#ifdef U_USE_DEPRECATED_FORMAT_API
+/* deprecated API ----------------------------------------------------------- */
-#if ((U_ICU_VERSION_MAJOR_NUM != 2) || (U_ICU_VERSION_MINOR_NUM != 2))
-# error "ICU version has changed. Please redefine the macros under U_USE_DEPRECATED_FORMAT_API pre-processor definition"
-#else
- U_CAPI UTransliterator* U_EXPORT2
- utrans_openRules(const char* id,
- const UChar* rules,
- int32_t rulesLength, /* -1 if null-terminated */
- UTransDirection dir,
- UParseError* parseErr, /* may be NULL */
- UErrorCode* status){
- return utrans_open(id,dir,rules,rulesLength,parseErr,status);
- }
+#ifndef U_HIDE_DEPRECATED_API
-# define utrans_open_2_2(id,dir,status) utrans_open(id,dir,NULL,0,NULL,status)
+/* see utrans.h documentation for why these functions are deprecated */
-#endif
-#endif
-/********************* End **********************************************/
+/**
+ * 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 /* U_HIDE_DEPRECATED_API */
#endif /* #if !UCONFIG_NO_TRANSLITERATION */
projects / apple / icu.git / blobdiff