Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/utrans.h @ 69:33d812a61356

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