Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/utext.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 *
jpayne@69 6 * Copyright (C) 2004-2012, International Business Machines
jpayne@69 7 * Corporation and others. All Rights Reserved.
jpayne@69 8 *
jpayne@69 9 *******************************************************************************
jpayne@69 10 * file name: utext.h
jpayne@69 11 * encoding: UTF-8
jpayne@69 12 * tab size: 8 (not used)
jpayne@69 13 * indentation:4
jpayne@69 14 *
jpayne@69 15 * created on: 2004oct06
jpayne@69 16 * created by: Markus W. Scherer
jpayne@69 17 */
jpayne@69 18
jpayne@69 19 #ifndef __UTEXT_H__
jpayne@69 20 #define __UTEXT_H__
jpayne@69 21
jpayne@69 22 /**
jpayne@69 23 * \file
jpayne@69 24 * \brief C API: Abstract Unicode Text API
jpayne@69 25 *
jpayne@69 26 * The Text Access API provides a means to allow text that is stored in alternative
jpayne@69 27 * formats to work with ICU services. ICU normally operates on text that is
jpayne@69 28 * stored in UTF-16 format, in (UChar *) arrays for the C APIs or as type
jpayne@69 29 * UnicodeString for C++ APIs.
jpayne@69 30 *
jpayne@69 31 * ICU Text Access allows other formats, such as UTF-8 or non-contiguous
jpayne@69 32 * UTF-16 strings, to be placed in a UText wrapper and then passed to ICU services.
jpayne@69 33 *
jpayne@69 34 * There are three general classes of usage for UText:
jpayne@69 35 *
jpayne@69 36 * Application Level Use. This is the simplest usage - applications would
jpayne@69 37 * use one of the utext_open() functions on their input text, and pass
jpayne@69 38 * the resulting UText to the desired ICU service.
jpayne@69 39 *
jpayne@69 40 * Second is usage in ICU Services, such as break iteration, that will need to
jpayne@69 41 * operate on input presented to them as a UText. These implementations
jpayne@69 42 * will need to use the iteration and related UText functions to gain
jpayne@69 43 * access to the actual text.
jpayne@69 44 *
jpayne@69 45 * The third class of UText users are "text providers." These are the
jpayne@69 46 * UText implementations for the various text storage formats. An application
jpayne@69 47 * or system with a unique text storage format can implement a set of
jpayne@69 48 * UText provider functions for that format, which will then allow
jpayne@69 49 * ICU services to operate on that format.
jpayne@69 50 *
jpayne@69 51 *
jpayne@69 52 * <em>Iterating over text</em>
jpayne@69 53 *
jpayne@69 54 * Here is sample code for a forward iteration over the contents of a UText
jpayne@69 55 *
jpayne@69 56 * \code
jpayne@69 57 * UChar32 c;
jpayne@69 58 * UText *ut = whatever();
jpayne@69 59 *
jpayne@69 60 * for (c=utext_next32From(ut, 0); c>=0; c=utext_next32(ut)) {
jpayne@69 61 * // do whatever with the codepoint c here.
jpayne@69 62 * }
jpayne@69 63 * \endcode
jpayne@69 64 *
jpayne@69 65 * And here is similar code to iterate in the reverse direction, from the end
jpayne@69 66 * of the text towards the beginning.
jpayne@69 67 *
jpayne@69 68 * \code
jpayne@69 69 * UChar32 c;
jpayne@69 70 * UText *ut = whatever();
jpayne@69 71 * int textLength = utext_nativeLength(ut);
jpayne@69 72 * for (c=utext_previous32From(ut, textLength); c>=0; c=utext_previous32(ut)) {
jpayne@69 73 * // do whatever with the codepoint c here.
jpayne@69 74 * }
jpayne@69 75 * \endcode
jpayne@69 76 *
jpayne@69 77 * <em>Characters and Indexing</em>
jpayne@69 78 *
jpayne@69 79 * Indexing into text by UText functions is nearly always in terms of the native
jpayne@69 80 * indexing of the underlying text storage. The storage format could be UTF-8
jpayne@69 81 * or UTF-32, for example. When coding to the UText access API, no assumptions
jpayne@69 82 * can be made regarding the size of characters, or how far an index
jpayne@69 83 * may move when iterating between characters.
jpayne@69 84 *
jpayne@69 85 * All indices supplied to UText functions are pinned to the length of the
jpayne@69 86 * text. An out-of-bounds index is not considered to be an error, but is
jpayne@69 87 * adjusted to be in the range 0 <= index <= length of input text.
jpayne@69 88 *
jpayne@69 89 *
jpayne@69 90 * When an index position is returned from a UText function, it will be
jpayne@69 91 * a native index to the underlying text. In the case of multi-unit characters,
jpayne@69 92 * it will always refer to the first position of the character,
jpayne@69 93 * never to the interior. This is essentially the same thing as saying that
jpayne@69 94 * a returned index will always point to a boundary between characters.
jpayne@69 95 *
jpayne@69 96 * When a native index is supplied to a UText function, all indices that
jpayne@69 97 * refer to any part of a multi-unit character representation are considered
jpayne@69 98 * to be equivalent. In the case of multi-unit characters, an incoming index
jpayne@69 99 * will be logically normalized to refer to the start of the character.
jpayne@69 100 *
jpayne@69 101 * It is possible to test whether a native index is on a code point boundary
jpayne@69 102 * by doing a utext_setNativeIndex() followed by a utext_getNativeIndex().
jpayne@69 103 * If the index is returned unchanged, it was on a code point boundary. If
jpayne@69 104 * an adjusted index is returned, the original index referred to the
jpayne@69 105 * interior of a character.
jpayne@69 106 *
jpayne@69 107 * <em>Conventions for calling UText functions</em>
jpayne@69 108 *
jpayne@69 109 * Most UText access functions have as their first parameter a (UText *) pointer,
jpayne@69 110 * which specifies the UText to be used. Unless otherwise noted, the
jpayne@69 111 * pointer must refer to a valid, open UText. Attempting to
jpayne@69 112 * use a closed UText or passing a NULL pointer is a programming error and
jpayne@69 113 * will produce undefined results or NULL pointer exceptions.
jpayne@69 114 *
jpayne@69 115 * The UText_Open family of functions can either open an existing (closed)
jpayne@69 116 * UText, or heap allocate a new UText. Here is sample code for creating
jpayne@69 117 * a stack-allocated UText.
jpayne@69 118 *
jpayne@69 119 * \code
jpayne@69 120 * char *s = whatever(); // A utf-8 string
jpayne@69 121 * U_ErrorCode status = U_ZERO_ERROR;
jpayne@69 122 * UText ut = UTEXT_INITIALIZER;
jpayne@69 123 * utext_openUTF8(ut, s, -1, &status);
jpayne@69 124 * if (U_FAILURE(status)) {
jpayne@69 125 * // error handling
jpayne@69 126 * } else {
jpayne@69 127 * // work with the UText
jpayne@69 128 * }
jpayne@69 129 * \endcode
jpayne@69 130 *
jpayne@69 131 * Any existing UText passed to an open function _must_ have been initialized,
jpayne@69 132 * either by the UTEXT_INITIALIZER, or by having been originally heap-allocated
jpayne@69 133 * by an open function. Passing NULL will cause the open function to
jpayne@69 134 * heap-allocate and fully initialize a new UText.
jpayne@69 135 *
jpayne@69 136 */
jpayne@69 137
jpayne@69 138
jpayne@69 139
jpayne@69 140 #include "unicode/utypes.h"
jpayne@69 141 #include "unicode/uchar.h"
jpayne@69 142 #if U_SHOW_CPLUSPLUS_API
jpayne@69 143 #include "unicode/localpointer.h"
jpayne@69 144 #include "unicode/rep.h"
jpayne@69 145 #include "unicode/unistr.h"
jpayne@69 146 #include "unicode/chariter.h"
jpayne@69 147 #endif
jpayne@69 148
jpayne@69 149
jpayne@69 150 U_CDECL_BEGIN
jpayne@69 151
jpayne@69 152 struct UText;
jpayne@69 153 typedef struct UText UText; /**< C typedef for struct UText. @stable ICU 3.6 */
jpayne@69 154
jpayne@69 155
jpayne@69 156 /***************************************************************************************
jpayne@69 157 *
jpayne@69 158 * C Functions for creating UText wrappers around various kinds of text strings.
jpayne@69 159 *
jpayne@69 160 ****************************************************************************************/
jpayne@69 161
jpayne@69 162
jpayne@69 163 /**
jpayne@69 164 * Close function for UText instances.
jpayne@69 165 * Cleans up, releases any resources being held by an open UText.
jpayne@69 166 * <p>
jpayne@69 167 * If the UText was originally allocated by one of the utext_open functions,
jpayne@69 168 * the storage associated with the utext will also be freed.
jpayne@69 169 * If the UText storage originated with the application, as it would with
jpayne@69 170 * a local or static instance, the storage will not be deleted.
jpayne@69 171 *
jpayne@69 172 * An open UText can be reset to refer to new string by using one of the utext_open()
jpayne@69 173 * functions without first closing the UText.
jpayne@69 174 *
jpayne@69 175 * @param ut The UText to be closed.
jpayne@69 176 * @return NULL if the UText struct was deleted by the close. If the UText struct
jpayne@69 177 * was originally provided by the caller to the open function, it is
jpayne@69 178 * returned by this function, and may be safely used again in
jpayne@69 179 * a subsequent utext_open.
jpayne@69 180 *
jpayne@69 181 * @stable ICU 3.4
jpayne@69 182 */
jpayne@69 183 U_STABLE UText * U_EXPORT2
jpayne@69 184 utext_close(UText *ut);
jpayne@69 185
jpayne@69 186 /**
jpayne@69 187 * Open a read-only UText implementation for UTF-8 strings.
jpayne@69 188 *
jpayne@69 189 * \htmlonly
jpayne@69 190 * Any invalid UTF-8 in the input will be handled in this way:
jpayne@69 191 * a sequence of bytes that has the form of a truncated, but otherwise valid,
jpayne@69 192 * UTF-8 sequence will be replaced by a single unicode replacement character, \uFFFD.
jpayne@69 193 * Any other illegal bytes will each be replaced by a \uFFFD.
jpayne@69 194 * \endhtmlonly
jpayne@69 195 *
jpayne@69 196 * @param ut Pointer to a UText struct. If NULL, a new UText will be created.
jpayne@69 197 * If non-NULL, must refer to an initialized UText struct, which will then
jpayne@69 198 * be reset to reference the specified UTF-8 string.
jpayne@69 199 * @param s A UTF-8 string. Must not be NULL.
jpayne@69 200 * @param length The length of the UTF-8 string in bytes, or -1 if the string is
jpayne@69 201 * zero terminated.
jpayne@69 202 * @param status Errors are returned here.
jpayne@69 203 * @return A pointer to the UText. If a pre-allocated UText was provided, it
jpayne@69 204 * will always be used and returned.
jpayne@69 205 * @stable ICU 3.4
jpayne@69 206 */
jpayne@69 207 U_STABLE UText * U_EXPORT2
jpayne@69 208 utext_openUTF8(UText *ut, const char *s, int64_t length, UErrorCode *status);
jpayne@69 209
jpayne@69 210
jpayne@69 211 /**
jpayne@69 212 * Open a read-only UText for UChar * string.
jpayne@69 213 *
jpayne@69 214 * @param ut Pointer to a UText struct. If NULL, a new UText will be created.
jpayne@69 215 * If non-NULL, must refer to an initialized UText struct, which will then
jpayne@69 216 * be reset to reference the specified UChar string.
jpayne@69 217 * @param s A UChar (UTF-16) string
jpayne@69 218 * @param length The number of UChars in the input string, or -1 if the string is
jpayne@69 219 * zero terminated.
jpayne@69 220 * @param status Errors are returned here.
jpayne@69 221 * @return A pointer to the UText. If a pre-allocated UText was provided, it
jpayne@69 222 * will always be used and returned.
jpayne@69 223 * @stable ICU 3.4
jpayne@69 224 */
jpayne@69 225 U_STABLE UText * U_EXPORT2
jpayne@69 226 utext_openUChars(UText *ut, const UChar *s, int64_t length, UErrorCode *status);
jpayne@69 227
jpayne@69 228
jpayne@69 229 #if U_SHOW_CPLUSPLUS_API
jpayne@69 230 /**
jpayne@69 231 * Open a writable UText for a non-const UnicodeString.
jpayne@69 232 *
jpayne@69 233 * @param ut Pointer to a UText struct. If NULL, a new UText will be created.
jpayne@69 234 * If non-NULL, must refer to an initialized UText struct, which will then
jpayne@69 235 * be reset to reference the specified input string.
jpayne@69 236 * @param s A UnicodeString.
jpayne@69 237 * @param status Errors are returned here.
jpayne@69 238 * @return Pointer to the UText. If a UText was supplied as input, this
jpayne@69 239 * will always be used and returned.
jpayne@69 240 * @stable ICU 3.4
jpayne@69 241 */
jpayne@69 242 U_STABLE UText * U_EXPORT2
jpayne@69 243 utext_openUnicodeString(UText *ut, icu::UnicodeString *s, UErrorCode *status);
jpayne@69 244
jpayne@69 245
jpayne@69 246 /**
jpayne@69 247 * Open a UText for a const UnicodeString. The resulting UText will not be writable.
jpayne@69 248 *
jpayne@69 249 * @param ut Pointer to a UText struct. If NULL, a new UText will be created.
jpayne@69 250 * If non-NULL, must refer to an initialized UText struct, which will then
jpayne@69 251 * be reset to reference the specified input string.
jpayne@69 252 * @param s A const UnicodeString to be wrapped.
jpayne@69 253 * @param status Errors are returned here.
jpayne@69 254 * @return Pointer to the UText. If a UText was supplied as input, this
jpayne@69 255 * will always be used and returned.
jpayne@69 256 * @stable ICU 3.4
jpayne@69 257 */
jpayne@69 258 U_STABLE UText * U_EXPORT2
jpayne@69 259 utext_openConstUnicodeString(UText *ut, const icu::UnicodeString *s, UErrorCode *status);
jpayne@69 260
jpayne@69 261
jpayne@69 262 /**
jpayne@69 263 * Open a writable UText implementation for an ICU Replaceable object.
jpayne@69 264 * @param ut Pointer to a UText struct. If NULL, a new UText will be created.
jpayne@69 265 * If non-NULL, must refer to an already existing UText, which will then
jpayne@69 266 * be reset to reference the specified replaceable text.
jpayne@69 267 * @param rep A Replaceable text object.
jpayne@69 268 * @param status Errors are returned here.
jpayne@69 269 * @return Pointer to the UText. If a UText was supplied as input, this
jpayne@69 270 * will always be used and returned.
jpayne@69 271 * @see Replaceable
jpayne@69 272 * @stable ICU 3.4
jpayne@69 273 */
jpayne@69 274 U_STABLE UText * U_EXPORT2
jpayne@69 275 utext_openReplaceable(UText *ut, icu::Replaceable *rep, UErrorCode *status);
jpayne@69 276
jpayne@69 277 /**
jpayne@69 278 * Open a UText implementation over an ICU CharacterIterator.
jpayne@69 279 * @param ut Pointer to a UText struct. If NULL, a new UText will be created.
jpayne@69 280 * If non-NULL, must refer to an already existing UText, which will then
jpayne@69 281 * be reset to reference the specified replaceable text.
jpayne@69 282 * @param ci A Character Iterator.
jpayne@69 283 * @param status Errors are returned here.
jpayne@69 284 * @return Pointer to the UText. If a UText was supplied as input, this
jpayne@69 285 * will always be used and returned.
jpayne@69 286 * @see Replaceable
jpayne@69 287 * @stable ICU 3.4
jpayne@69 288 */
jpayne@69 289 U_STABLE UText * U_EXPORT2
jpayne@69 290 utext_openCharacterIterator(UText *ut, icu::CharacterIterator *ci, UErrorCode *status);
jpayne@69 291
jpayne@69 292 #endif
jpayne@69 293
jpayne@69 294
jpayne@69 295 /**
jpayne@69 296 * Clone a UText. This is much like opening a UText where the source text is itself
jpayne@69 297 * another UText.
jpayne@69 298 *
jpayne@69 299 * A deep clone will copy both the UText data structures and the underlying text.
jpayne@69 300 * The original and cloned UText will operate completely independently; modifications
jpayne@69 301 * made to the text in one will not affect the other. Text providers are not
jpayne@69 302 * required to support deep clones. The user of clone() must check the status return
jpayne@69 303 * and be prepared to handle failures.
jpayne@69 304 *
jpayne@69 305 * The standard UText implementations for UTF8, UChar *, UnicodeString and
jpayne@69 306 * Replaceable all support deep cloning.
jpayne@69 307 *
jpayne@69 308 * The UText returned from a deep clone will be writable, assuming that the text
jpayne@69 309 * provider is able to support writing, even if the source UText had been made
jpayne@69 310 * non-writable by means of UText_freeze().
jpayne@69 311 *
jpayne@69 312 * A shallow clone replicates only the UText data structures; it does not make
jpayne@69 313 * a copy of the underlying text. Shallow clones can be used as an efficient way to
jpayne@69 314 * have multiple iterators active in a single text string that is not being
jpayne@69 315 * modified.
jpayne@69 316 *
jpayne@69 317 * A shallow clone operation will not fail, barring truly exceptional conditions such
jpayne@69 318 * as memory allocation failures.
jpayne@69 319 *
jpayne@69 320 * Shallow UText clones should be avoided if the UText functions that modify the
jpayne@69 321 * text are expected to be used, either on the original or the cloned UText.
jpayne@69 322 * Any such modifications can cause unpredictable behavior. Read Only
jpayne@69 323 * shallow clones provide some protection against errors of this type by
jpayne@69 324 * disabling text modification via the cloned UText.
jpayne@69 325 *
jpayne@69 326 * A shallow clone made with the readOnly parameter == FALSE will preserve the
jpayne@69 327 * utext_isWritable() state of the source object. Note, however, that
jpayne@69 328 * write operations must be avoided while more than one UText exists that refer
jpayne@69 329 * to the same underlying text.
jpayne@69 330 *
jpayne@69 331 * A UText and its clone may be safely concurrently accessed by separate threads.
jpayne@69 332 * This is true for read access only with shallow clones, and for both read and
jpayne@69 333 * write access with deep clones.
jpayne@69 334 * It is the responsibility of the Text Provider to ensure that this thread safety
jpayne@69 335 * constraint is met.
jpayne@69 336 *
jpayne@69 337 * @param dest A UText struct to be filled in with the result of the clone operation,
jpayne@69 338 * or NULL if the clone function should heap-allocate a new UText struct.
jpayne@69 339 * If non-NULL, must refer to an already existing UText, which will then
jpayne@69 340 * be reset to become the clone.
jpayne@69 341 * @param src The UText to be cloned.
jpayne@69 342 * @param deep TRUE to request a deep clone, FALSE for a shallow clone.
jpayne@69 343 * @param readOnly TRUE to request that the cloned UText have read only access to the
jpayne@69 344 * underlying text.
jpayne@69 345
jpayne@69 346 * @param status Errors are returned here. For deep clones, U_UNSUPPORTED_ERROR
jpayne@69 347 * will be returned if the text provider is unable to clone the
jpayne@69 348 * original text.
jpayne@69 349 * @return The newly created clone, or NULL if the clone operation failed.
jpayne@69 350 * @stable ICU 3.4
jpayne@69 351 */
jpayne@69 352 U_STABLE UText * U_EXPORT2
jpayne@69 353 utext_clone(UText *dest, const UText *src, UBool deep, UBool readOnly, UErrorCode *status);
jpayne@69 354
jpayne@69 355
jpayne@69 356 /**
jpayne@69 357 * Compare two UText objects for equality.
jpayne@69 358 * UTexts are equal if they are iterating over the same text, and
jpayne@69 359 * have the same iteration position within the text.
jpayne@69 360 * If either or both of the parameters are NULL, the comparison is FALSE.
jpayne@69 361 *
jpayne@69 362 * @param a The first of the two UTexts to compare.
jpayne@69 363 * @param b The other UText to be compared.
jpayne@69 364 * @return TRUE if the two UTexts are equal.
jpayne@69 365 * @stable ICU 3.6
jpayne@69 366 */
jpayne@69 367 U_STABLE UBool U_EXPORT2
jpayne@69 368 utext_equals(const UText *a, const UText *b);
jpayne@69 369
jpayne@69 370
jpayne@69 371 /*****************************************************************************
jpayne@69 372 *
jpayne@69 373 * Functions to work with the text represented by a UText wrapper
jpayne@69 374 *
jpayne@69 375 *****************************************************************************/
jpayne@69 376
jpayne@69 377 /**
jpayne@69 378 * Get the length of the text. Depending on the characteristics
jpayne@69 379 * of the underlying text representation, this may be expensive.
jpayne@69 380 * @see utext_isLengthExpensive()
jpayne@69 381 *
jpayne@69 382 *
jpayne@69 383 * @param ut the text to be accessed.
jpayne@69 384 * @return the length of the text, expressed in native units.
jpayne@69 385 *
jpayne@69 386 * @stable ICU 3.4
jpayne@69 387 */
jpayne@69 388 U_STABLE int64_t U_EXPORT2
jpayne@69 389 utext_nativeLength(UText *ut);
jpayne@69 390
jpayne@69 391 /**
jpayne@69 392 * Return TRUE if calculating the length of the text could be expensive.
jpayne@69 393 * Finding the length of NUL terminated strings is considered to be expensive.
jpayne@69 394 *
jpayne@69 395 * Note that the value of this function may change
jpayne@69 396 * as the result of other operations on a UText.
jpayne@69 397 * Once the length of a string has been discovered, it will no longer
jpayne@69 398 * be expensive to report it.
jpayne@69 399 *
jpayne@69 400 * @param ut the text to be accessed.
jpayne@69 401 * @return TRUE if determining the length of the text could be time consuming.
jpayne@69 402 * @stable ICU 3.4
jpayne@69 403 */
jpayne@69 404 U_STABLE UBool U_EXPORT2
jpayne@69 405 utext_isLengthExpensive(const UText *ut);
jpayne@69 406
jpayne@69 407 /**
jpayne@69 408 * Returns the code point at the requested index,
jpayne@69 409 * or U_SENTINEL (-1) if it is out of bounds.
jpayne@69 410 *
jpayne@69 411 * If the specified index points to the interior of a multi-unit
jpayne@69 412 * character - one of the trail bytes of a UTF-8 sequence, for example -
jpayne@69 413 * the complete code point will be returned.
jpayne@69 414 *
jpayne@69 415 * The iteration position will be set to the start of the returned code point.
jpayne@69 416 *
jpayne@69 417 * This function is roughly equivalent to the sequence
jpayne@69 418 * utext_setNativeIndex(index);
jpayne@69 419 * utext_current32();
jpayne@69 420 * (There is a subtle difference if the index is out of bounds by being less than zero -
jpayne@69 421 * utext_setNativeIndex(negative value) sets the index to zero, after which utext_current()
jpayne@69 422 * will return the char at zero. utext_char32At(negative index), on the other hand, will
jpayne@69 423 * return the U_SENTINEL value of -1.)
jpayne@69 424 *
jpayne@69 425 * @param ut the text to be accessed
jpayne@69 426 * @param nativeIndex the native index of the character to be accessed. If the index points
jpayne@69 427 * to other than the first unit of a multi-unit character, it will be adjusted
jpayne@69 428 * to the start of the character.
jpayne@69 429 * @return the code point at the specified index.
jpayne@69 430 * @stable ICU 3.4
jpayne@69 431 */
jpayne@69 432 U_STABLE UChar32 U_EXPORT2
jpayne@69 433 utext_char32At(UText *ut, int64_t nativeIndex);
jpayne@69 434
jpayne@69 435
jpayne@69 436 /**
jpayne@69 437 *
jpayne@69 438 * Get the code point at the current iteration position,
jpayne@69 439 * or U_SENTINEL (-1) if the iteration has reached the end of
jpayne@69 440 * the input text.
jpayne@69 441 *
jpayne@69 442 * @param ut the text to be accessed.
jpayne@69 443 * @return the Unicode code point at the current iterator position.
jpayne@69 444 * @stable ICU 3.4
jpayne@69 445 */
jpayne@69 446 U_STABLE UChar32 U_EXPORT2
jpayne@69 447 utext_current32(UText *ut);
jpayne@69 448
jpayne@69 449
jpayne@69 450 /**
jpayne@69 451 * Get the code point at the current iteration position of the UText, and
jpayne@69 452 * advance the position to the first index following the character.
jpayne@69 453 *
jpayne@69 454 * If the position is at the end of the text (the index following
jpayne@69 455 * the last character, which is also the length of the text),
jpayne@69 456 * return U_SENTINEL (-1) and do not advance the index.
jpayne@69 457 *
jpayne@69 458 * This is a post-increment operation.
jpayne@69 459 *
jpayne@69 460 * An inline macro version of this function, UTEXT_NEXT32(),
jpayne@69 461 * is available for performance critical use.
jpayne@69 462 *
jpayne@69 463 * @param ut the text to be accessed.
jpayne@69 464 * @return the Unicode code point at the iteration position.
jpayne@69 465 * @see UTEXT_NEXT32
jpayne@69 466 * @stable ICU 3.4
jpayne@69 467 */
jpayne@69 468 U_STABLE UChar32 U_EXPORT2
jpayne@69 469 utext_next32(UText *ut);
jpayne@69 470
jpayne@69 471
jpayne@69 472 /**
jpayne@69 473 * Move the iterator position to the character (code point) whose
jpayne@69 474 * index precedes the current position, and return that character.
jpayne@69 475 * This is a pre-decrement operation.
jpayne@69 476 *
jpayne@69 477 * If the initial position is at the start of the text (index of 0)
jpayne@69 478 * return U_SENTINEL (-1), and leave the position unchanged.
jpayne@69 479 *
jpayne@69 480 * An inline macro version of this function, UTEXT_PREVIOUS32(),
jpayne@69 481 * is available for performance critical use.
jpayne@69 482 *
jpayne@69 483 * @param ut the text to be accessed.
jpayne@69 484 * @return the previous UChar32 code point, or U_SENTINEL (-1)
jpayne@69 485 * if the iteration has reached the start of the text.
jpayne@69 486 * @see UTEXT_PREVIOUS32
jpayne@69 487 * @stable ICU 3.4
jpayne@69 488 */
jpayne@69 489 U_STABLE UChar32 U_EXPORT2
jpayne@69 490 utext_previous32(UText *ut);
jpayne@69 491
jpayne@69 492
jpayne@69 493 /**
jpayne@69 494 * Set the iteration index and return the code point at that index.
jpayne@69 495 * Leave the iteration index at the start of the following code point.
jpayne@69 496 *
jpayne@69 497 * This function is the most efficient and convenient way to
jpayne@69 498 * begin a forward iteration. The results are identical to the those
jpayne@69 499 * from the sequence
jpayne@69 500 * \code
jpayne@69 501 * utext_setIndex();
jpayne@69 502 * utext_next32();
jpayne@69 503 * \endcode
jpayne@69 504 *
jpayne@69 505 * @param ut the text to be accessed.
jpayne@69 506 * @param nativeIndex Iteration index, in the native units of the text provider.
jpayne@69 507 * @return Code point which starts at or before index,
jpayne@69 508 * or U_SENTINEL (-1) if it is out of bounds.
jpayne@69 509 * @stable ICU 3.4
jpayne@69 510 */
jpayne@69 511 U_STABLE UChar32 U_EXPORT2
jpayne@69 512 utext_next32From(UText *ut, int64_t nativeIndex);
jpayne@69 513
jpayne@69 514
jpayne@69 515
jpayne@69 516 /**
jpayne@69 517 * Set the iteration index, and return the code point preceding the
jpayne@69 518 * one specified by the initial index. Leave the iteration position
jpayne@69 519 * at the start of the returned code point.
jpayne@69 520 *
jpayne@69 521 * This function is the most efficient and convenient way to
jpayne@69 522 * begin a backwards iteration.
jpayne@69 523 *
jpayne@69 524 * @param ut the text to be accessed.
jpayne@69 525 * @param nativeIndex Iteration index in the native units of the text provider.
jpayne@69 526 * @return Code point preceding the one at the initial index,
jpayne@69 527 * or U_SENTINEL (-1) if it is out of bounds.
jpayne@69 528 *
jpayne@69 529 * @stable ICU 3.4
jpayne@69 530 */
jpayne@69 531 U_STABLE UChar32 U_EXPORT2
jpayne@69 532 utext_previous32From(UText *ut, int64_t nativeIndex);
jpayne@69 533
jpayne@69 534 /**
jpayne@69 535 * Get the current iterator position, which can range from 0 to
jpayne@69 536 * the length of the text.
jpayne@69 537 * The position is a native index into the input text, in whatever format it
jpayne@69 538 * may have (possibly UTF-8 for example), and may not always be the same as
jpayne@69 539 * the corresponding UChar (UTF-16) index.
jpayne@69 540 * The returned position will always be aligned to a code point boundary.
jpayne@69 541 *
jpayne@69 542 * @param ut the text to be accessed.
jpayne@69 543 * @return the current index position, in the native units of the text provider.
jpayne@69 544 * @stable ICU 3.4
jpayne@69 545 */
jpayne@69 546 U_STABLE int64_t U_EXPORT2
jpayne@69 547 utext_getNativeIndex(const UText *ut);
jpayne@69 548
jpayne@69 549 /**
jpayne@69 550 * Set the current iteration position to the nearest code point
jpayne@69 551 * boundary at or preceding the specified index.
jpayne@69 552 * The index is in the native units of the original input text.
jpayne@69 553 * If the index is out of range, it will be pinned to be within
jpayne@69 554 * the range of the input text.
jpayne@69 555 * <p>
jpayne@69 556 * It will usually be more efficient to begin an iteration
jpayne@69 557 * using the functions utext_next32From() or utext_previous32From()
jpayne@69 558 * rather than setIndex().
jpayne@69 559 * <p>
jpayne@69 560 * Moving the index position to an adjacent character is best done
jpayne@69 561 * with utext_next32(), utext_previous32() or utext_moveIndex32().
jpayne@69 562 * Attempting to do direct arithmetic on the index position is
jpayne@69 563 * complicated by the fact that the size (in native units) of a
jpayne@69 564 * character depends on the underlying representation of the character
jpayne@69 565 * (UTF-8, UTF-16, UTF-32, arbitrary codepage), and is not
jpayne@69 566 * easily knowable.
jpayne@69 567 *
jpayne@69 568 * @param ut the text to be accessed.
jpayne@69 569 * @param nativeIndex the native unit index of the new iteration position.
jpayne@69 570 * @stable ICU 3.4
jpayne@69 571 */
jpayne@69 572 U_STABLE void U_EXPORT2
jpayne@69 573 utext_setNativeIndex(UText *ut, int64_t nativeIndex);
jpayne@69 574
jpayne@69 575 /**
jpayne@69 576 * Move the iterator position by delta code points. The number of code points
jpayne@69 577 * is a signed number; a negative delta will move the iterator backwards,
jpayne@69 578 * towards the start of the text.
jpayne@69 579 * <p>
jpayne@69 580 * The index is moved by <code>delta</code> code points
jpayne@69 581 * forward or backward, but no further backward than to 0 and
jpayne@69 582 * no further forward than to utext_nativeLength().
jpayne@69 583 * The resulting index value will be in between 0 and length, inclusive.
jpayne@69 584 *
jpayne@69 585 * @param ut the text to be accessed.
jpayne@69 586 * @param delta the signed number of code points to move the iteration position.
jpayne@69 587 * @return TRUE if the position could be moved the requested number of positions while
jpayne@69 588 * staying within the range [0 - text length].
jpayne@69 589 * @stable ICU 3.4
jpayne@69 590 */
jpayne@69 591 U_STABLE UBool U_EXPORT2
jpayne@69 592 utext_moveIndex32(UText *ut, int32_t delta);
jpayne@69 593
jpayne@69 594 /**
jpayne@69 595 * Get the native index of the character preceding the current position.
jpayne@69 596 * If the iteration position is already at the start of the text, zero
jpayne@69 597 * is returned.
jpayne@69 598 * The value returned is the same as that obtained from the following sequence,
jpayne@69 599 * but without the side effect of changing the iteration position.
jpayne@69 600 *
jpayne@69 601 * \code
jpayne@69 602 * UText *ut = whatever;
jpayne@69 603 * ...
jpayne@69 604 * utext_previous(ut)
jpayne@69 605 * utext_getNativeIndex(ut);
jpayne@69 606 * \endcode
jpayne@69 607 *
jpayne@69 608 * This function is most useful during forwards iteration, where it will get the
jpayne@69 609 * native index of the character most recently returned from utext_next().
jpayne@69 610 *
jpayne@69 611 * @param ut the text to be accessed
jpayne@69 612 * @return the native index of the character preceding the current index position,
jpayne@69 613 * or zero if the current position is at the start of the text.
jpayne@69 614 * @stable ICU 3.6
jpayne@69 615 */
jpayne@69 616 U_STABLE int64_t U_EXPORT2
jpayne@69 617 utext_getPreviousNativeIndex(UText *ut);
jpayne@69 618
jpayne@69 619
jpayne@69 620 /**
jpayne@69 621 *
jpayne@69 622 * Extract text from a UText into a UChar buffer. The range of text to be extracted
jpayne@69 623 * is specified in the native indices of the UText provider. These may not necessarily
jpayne@69 624 * be UTF-16 indices.
jpayne@69 625 * <p>
jpayne@69 626 * The size (number of 16 bit UChars) of the data to be extracted is returned. The
jpayne@69 627 * full number of UChars is returned, even when the extracted text is truncated
jpayne@69 628 * because the specified buffer size is too small.
jpayne@69 629 * <p>
jpayne@69 630 * The extracted string will (if you are a user) / must (if you are a text provider)
jpayne@69 631 * be NUL-terminated if there is sufficient space in the destination buffer. This
jpayne@69 632 * terminating NUL is not included in the returned length.
jpayne@69 633 * <p>
jpayne@69 634 * The iteration index is left at the position following the last extracted character.
jpayne@69 635 *
jpayne@69 636 * @param ut the UText from which to extract data.
jpayne@69 637 * @param nativeStart the native index of the first character to extract.\
jpayne@69 638 * If the specified index is out of range,
jpayne@69 639 * it will be pinned to be within 0 <= index <= textLength
jpayne@69 640 * @param nativeLimit the native string index of the position following the last
jpayne@69 641 * character to extract. If the specified index is out of range,
jpayne@69 642 * it will be pinned to be within 0 <= index <= textLength.
jpayne@69 643 * nativeLimit must be >= nativeStart.
jpayne@69 644 * @param dest the UChar (UTF-16) buffer into which the extracted text is placed
jpayne@69 645 * @param destCapacity The size, in UChars, of the destination buffer. May be zero
jpayne@69 646 * for precomputing the required size.
jpayne@69 647 * @param status receives any error status.
jpayne@69 648 * U_BUFFER_OVERFLOW_ERROR: the extracted text was truncated because the
jpayne@69 649 * buffer was too small. Returns number of UChars for preflighting.
jpayne@69 650 * @return Number of UChars in the data to be extracted. Does not include a trailing NUL.
jpayne@69 651 *
jpayne@69 652 * @stable ICU 3.4
jpayne@69 653 */
jpayne@69 654 U_STABLE int32_t U_EXPORT2
jpayne@69 655 utext_extract(UText *ut,
jpayne@69 656 int64_t nativeStart, int64_t nativeLimit,
jpayne@69 657 UChar *dest, int32_t destCapacity,
jpayne@69 658 UErrorCode *status);
jpayne@69 659
jpayne@69 660
jpayne@69 661
jpayne@69 662 /************************************************************************************
jpayne@69 663 *
jpayne@69 664 * #define inline versions of selected performance-critical text access functions
jpayne@69 665 * Caution: do not use auto increment++ or decrement-- expressions
jpayne@69 666 * as parameters to these macros.
jpayne@69 667 *
jpayne@69 668 * For most use, where there is no extreme performance constraint, the
jpayne@69 669 * normal, non-inline functions are a better choice. The resulting code
jpayne@69 670 * will be smaller, and, if the need ever arises, easier to debug.
jpayne@69 671 *
jpayne@69 672 * These are implemented as #defines rather than real functions
jpayne@69 673 * because there is no fully portable way to do inline functions in plain C.
jpayne@69 674 *
jpayne@69 675 ************************************************************************************/
jpayne@69 676
jpayne@69 677 #ifndef U_HIDE_INTERNAL_API
jpayne@69 678 /**
jpayne@69 679 * inline version of utext_current32(), for performance-critical situations.
jpayne@69 680 *
jpayne@69 681 * Get the code point at the current iteration position of the UText.
jpayne@69 682 * Returns U_SENTINEL (-1) if the position is at the end of the
jpayne@69 683 * text.
jpayne@69 684 *
jpayne@69 685 * @internal ICU 4.4 technology preview
jpayne@69 686 */
jpayne@69 687 #define UTEXT_CURRENT32(ut) \
jpayne@69 688 ((ut)->chunkOffset < (ut)->chunkLength && ((ut)->chunkContents)[(ut)->chunkOffset]<0xd800 ? \
jpayne@69 689 ((ut)->chunkContents)[((ut)->chunkOffset)] : utext_current32(ut))
jpayne@69 690 #endif /* U_HIDE_INTERNAL_API */
jpayne@69 691
jpayne@69 692 /**
jpayne@69 693 * inline version of utext_next32(), for performance-critical situations.
jpayne@69 694 *
jpayne@69 695 * Get the code point at the current iteration position of the UText, and
jpayne@69 696 * advance the position to the first index following the character.
jpayne@69 697 * This is a post-increment operation.
jpayne@69 698 * Returns U_SENTINEL (-1) if the position is at the end of the
jpayne@69 699 * text.
jpayne@69 700 *
jpayne@69 701 * @stable ICU 3.4
jpayne@69 702 */
jpayne@69 703 #define UTEXT_NEXT32(ut) \
jpayne@69 704 ((ut)->chunkOffset < (ut)->chunkLength && ((ut)->chunkContents)[(ut)->chunkOffset]<0xd800 ? \
jpayne@69 705 ((ut)->chunkContents)[((ut)->chunkOffset)++] : utext_next32(ut))
jpayne@69 706
jpayne@69 707 /**
jpayne@69 708 * inline version of utext_previous32(), for performance-critical situations.
jpayne@69 709 *
jpayne@69 710 * Move the iterator position to the character (code point) whose
jpayne@69 711 * index precedes the current position, and return that character.
jpayne@69 712 * This is a pre-decrement operation.
jpayne@69 713 * Returns U_SENTINEL (-1) if the position is at the start of the text.
jpayne@69 714 *
jpayne@69 715 * @stable ICU 3.4
jpayne@69 716 */
jpayne@69 717 #define UTEXT_PREVIOUS32(ut) \
jpayne@69 718 ((ut)->chunkOffset > 0 && \
jpayne@69 719 (ut)->chunkContents[(ut)->chunkOffset-1] < 0xd800 ? \
jpayne@69 720 (ut)->chunkContents[--((ut)->chunkOffset)] : utext_previous32(ut))
jpayne@69 721
jpayne@69 722 /**
jpayne@69 723 * inline version of utext_getNativeIndex(), for performance-critical situations.
jpayne@69 724 *
jpayne@69 725 * Get the current iterator position, which can range from 0 to
jpayne@69 726 * the length of the text.
jpayne@69 727 * The position is a native index into the input text, in whatever format it
jpayne@69 728 * may have (possibly UTF-8 for example), and may not always be the same as
jpayne@69 729 * the corresponding UChar (UTF-16) index.
jpayne@69 730 * The returned position will always be aligned to a code point boundary.
jpayne@69 731 *
jpayne@69 732 * @stable ICU 3.6
jpayne@69 733 */
jpayne@69 734 #define UTEXT_GETNATIVEINDEX(ut) \
jpayne@69 735 ((ut)->chunkOffset <= (ut)->nativeIndexingLimit? \
jpayne@69 736 (ut)->chunkNativeStart+(ut)->chunkOffset : \
jpayne@69 737 (ut)->pFuncs->mapOffsetToNative(ut))
jpayne@69 738
jpayne@69 739 /**
jpayne@69 740 * inline version of utext_setNativeIndex(), for performance-critical situations.
jpayne@69 741 *
jpayne@69 742 * Set the current iteration position to the nearest code point
jpayne@69 743 * boundary at or preceding the specified index.
jpayne@69 744 * The index is in the native units of the original input text.
jpayne@69 745 * If the index is out of range, it will be pinned to be within
jpayne@69 746 * the range of the input text.
jpayne@69 747 *
jpayne@69 748 * @stable ICU 3.8
jpayne@69 749 */
jpayne@69 750 #define UTEXT_SETNATIVEINDEX(ut, ix) UPRV_BLOCK_MACRO_BEGIN { \
jpayne@69 751 int64_t __offset = (ix) - (ut)->chunkNativeStart; \
jpayne@69 752 if (__offset>=0 && __offset<(int64_t)(ut)->nativeIndexingLimit && (ut)->chunkContents[__offset]<0xdc00) { \
jpayne@69 753 (ut)->chunkOffset=(int32_t)__offset; \
jpayne@69 754 } else { \
jpayne@69 755 utext_setNativeIndex((ut), (ix)); \
jpayne@69 756 } \
jpayne@69 757 } UPRV_BLOCK_MACRO_END
jpayne@69 758
jpayne@69 759
jpayne@69 760
jpayne@69 761 /************************************************************************************
jpayne@69 762 *
jpayne@69 763 * Functions related to writing or modifying the text.
jpayne@69 764 * These will work only with modifiable UTexts. Attempting to
jpayne@69 765 * modify a read-only UText will return an error status.
jpayne@69 766 *
jpayne@69 767 ************************************************************************************/
jpayne@69 768
jpayne@69 769
jpayne@69 770 /**
jpayne@69 771 * Return TRUE if the text can be written (modified) with utext_replace() or
jpayne@69 772 * utext_copy(). For the text to be writable, the text provider must
jpayne@69 773 * be of a type that supports writing and the UText must not be frozen.
jpayne@69 774 *
jpayne@69 775 * Attempting to modify text when utext_isWriteable() is FALSE will fail -
jpayne@69 776 * the text will not be modified, and an error will be returned from the function
jpayne@69 777 * that attempted the modification.
jpayne@69 778 *
jpayne@69 779 * @param ut the UText to be tested.
jpayne@69 780 * @return TRUE if the text is modifiable.
jpayne@69 781 *
jpayne@69 782 * @see utext_freeze()
jpayne@69 783 * @see utext_replace()
jpayne@69 784 * @see utext_copy()
jpayne@69 785 * @stable ICU 3.4
jpayne@69 786 *
jpayne@69 787 */
jpayne@69 788 U_STABLE UBool U_EXPORT2
jpayne@69 789 utext_isWritable(const UText *ut);
jpayne@69 790
jpayne@69 791
jpayne@69 792 /**
jpayne@69 793 * Test whether there is meta data associated with the text.
jpayne@69 794 * @see Replaceable::hasMetaData()
jpayne@69 795 *
jpayne@69 796 * @param ut The UText to be tested
jpayne@69 797 * @return TRUE if the underlying text includes meta data.
jpayne@69 798 * @stable ICU 3.4
jpayne@69 799 */
jpayne@69 800 U_STABLE UBool U_EXPORT2
jpayne@69 801 utext_hasMetaData(const UText *ut);
jpayne@69 802
jpayne@69 803
jpayne@69 804 /**
jpayne@69 805 * Replace a range of the original text with a replacement text.
jpayne@69 806 *
jpayne@69 807 * Leaves the current iteration position at the position following the
jpayne@69 808 * newly inserted replacement text.
jpayne@69 809 *
jpayne@69 810 * This function is only available on UText types that support writing,
jpayne@69 811 * that is, ones where utext_isWritable() returns TRUE.
jpayne@69 812 *
jpayne@69 813 * When using this function, there should be only a single UText opened onto the
jpayne@69 814 * underlying native text string. Behavior after a replace operation
jpayne@69 815 * on a UText is undefined for any other additional UTexts that refer to the
jpayne@69 816 * modified string.
jpayne@69 817 *
jpayne@69 818 * @param ut the UText representing the text to be operated on.
jpayne@69 819 * @param nativeStart the native index of the start of the region to be replaced
jpayne@69 820 * @param nativeLimit the native index of the character following the region to be replaced.
jpayne@69 821 * @param replacementText pointer to the replacement text
jpayne@69 822 * @param replacementLength length of the replacement text, or -1 if the text is NUL terminated.
jpayne@69 823 * @param status receives any error status. Possible errors include
jpayne@69 824 * U_NO_WRITE_PERMISSION
jpayne@69 825 *
jpayne@69 826 * @return The signed number of (native) storage units by which
jpayne@69 827 * the length of the text expanded or contracted.
jpayne@69 828 *
jpayne@69 829 * @stable ICU 3.4
jpayne@69 830 */
jpayne@69 831 U_STABLE int32_t U_EXPORT2
jpayne@69 832 utext_replace(UText *ut,
jpayne@69 833 int64_t nativeStart, int64_t nativeLimit,
jpayne@69 834 const UChar *replacementText, int32_t replacementLength,
jpayne@69 835 UErrorCode *status);
jpayne@69 836
jpayne@69 837
jpayne@69 838
jpayne@69 839 /**
jpayne@69 840 *
jpayne@69 841 * Copy or move a substring from one position to another within the text,
jpayne@69 842 * while retaining any metadata associated with the text.
jpayne@69 843 * This function is used to duplicate or reorder substrings.
jpayne@69 844 * The destination index must not overlap the source range.
jpayne@69 845 *
jpayne@69 846 * The text to be copied or moved is inserted at destIndex;
jpayne@69 847 * it does not replace or overwrite any existing text.
jpayne@69 848 *
jpayne@69 849 * The iteration position is left following the newly inserted text
jpayne@69 850 * at the destination position.
jpayne@69 851 *
jpayne@69 852 * This function is only available on UText types that support writing,
jpayne@69 853 * that is, ones where utext_isWritable() returns TRUE.
jpayne@69 854 *
jpayne@69 855 * When using this function, there should be only a single UText opened onto the
jpayne@69 856 * underlying native text string. Behavior after a copy operation
jpayne@69 857 * on a UText is undefined in any other additional UTexts that refer to the
jpayne@69 858 * modified string.
jpayne@69 859 *
jpayne@69 860 * @param ut The UText representing the text to be operated on.
jpayne@69 861 * @param nativeStart The native index of the start of the region to be copied or moved
jpayne@69 862 * @param nativeLimit The native index of the character position following the region
jpayne@69 863 * to be copied.
jpayne@69 864 * @param destIndex The native destination index to which the source substring is
jpayne@69 865 * copied or moved.
jpayne@69 866 * @param move If TRUE, then the substring is moved, not copied/duplicated.
jpayne@69 867 * @param status receives any error status. Possible errors include U_NO_WRITE_PERMISSION
jpayne@69 868 *
jpayne@69 869 * @stable ICU 3.4
jpayne@69 870 */
jpayne@69 871 U_STABLE void U_EXPORT2
jpayne@69 872 utext_copy(UText *ut,
jpayne@69 873 int64_t nativeStart, int64_t nativeLimit,
jpayne@69 874 int64_t destIndex,
jpayne@69 875 UBool move,
jpayne@69 876 UErrorCode *status);
jpayne@69 877
jpayne@69 878
jpayne@69 879 /**
jpayne@69 880 * <p>
jpayne@69 881 * Freeze a UText. This prevents any modification to the underlying text itself
jpayne@69 882 * by means of functions operating on this UText.
jpayne@69 883 * </p>
jpayne@69 884 * <p>
jpayne@69 885 * Once frozen, a UText can not be unfrozen. The intent is to ensure
jpayne@69 886 * that a the text underlying a frozen UText wrapper cannot be modified via that UText.
jpayne@69 887 * </p>
jpayne@69 888 * <p>
jpayne@69 889 * Caution: freezing a UText will disable changes made via the specific
jpayne@69 890 * frozen UText wrapper only; it will not have any effect on the ability to
jpayne@69 891 * directly modify the text by bypassing the UText. Any such backdoor modifications
jpayne@69 892 * are always an error while UText access is occurring because the underlying
jpayne@69 893 * text can get out of sync with UText's buffering.
jpayne@69 894 * </p>
jpayne@69 895 *
jpayne@69 896 * @param ut The UText to be frozen.
jpayne@69 897 * @see utext_isWritable()
jpayne@69 898 * @stable ICU 3.6
jpayne@69 899 */
jpayne@69 900 U_STABLE void U_EXPORT2
jpayne@69 901 utext_freeze(UText *ut);
jpayne@69 902
jpayne@69 903
jpayne@69 904 /**
jpayne@69 905 * UText provider properties (bit field indexes).
jpayne@69 906 *
jpayne@69 907 * @see UText
jpayne@69 908 * @stable ICU 3.4
jpayne@69 909 */
jpayne@69 910 enum {
jpayne@69 911 /**
jpayne@69 912 * It is potentially time consuming for the provider to determine the length of the text.
jpayne@69 913 * @stable ICU 3.4
jpayne@69 914 */
jpayne@69 915 UTEXT_PROVIDER_LENGTH_IS_EXPENSIVE = 1,
jpayne@69 916 /**
jpayne@69 917 * Text chunks remain valid and usable until the text object is modified or
jpayne@69 918 * deleted, not just until the next time the access() function is called
jpayne@69 919 * (which is the default).
jpayne@69 920 * @stable ICU 3.4
jpayne@69 921 */
jpayne@69 922 UTEXT_PROVIDER_STABLE_CHUNKS = 2,
jpayne@69 923 /**
jpayne@69 924 * The provider supports modifying the text via the replace() and copy()
jpayne@69 925 * functions.
jpayne@69 926 * @see Replaceable
jpayne@69 927 * @stable ICU 3.4
jpayne@69 928 */
jpayne@69 929 UTEXT_PROVIDER_WRITABLE = 3,
jpayne@69 930 /**
jpayne@69 931 * There is meta data associated with the text.
jpayne@69 932 * @see Replaceable::hasMetaData()
jpayne@69 933 * @stable ICU 3.4
jpayne@69 934 */
jpayne@69 935 UTEXT_PROVIDER_HAS_META_DATA = 4,
jpayne@69 936 /**
jpayne@69 937 * Text provider owns the text storage.
jpayne@69 938 * Generally occurs as the result of a deep clone of the UText.
jpayne@69 939 * When closing the UText, the associated text must
jpayne@69 940 * also be closed/deleted/freed/ whatever is appropriate.
jpayne@69 941 * @stable ICU 3.6
jpayne@69 942 */
jpayne@69 943 UTEXT_PROVIDER_OWNS_TEXT = 5
jpayne@69 944 };
jpayne@69 945
jpayne@69 946 /**
jpayne@69 947 * Function type declaration for UText.clone().
jpayne@69 948 *
jpayne@69 949 * clone a UText. Much like opening a UText where the source text is itself
jpayne@69 950 * another UText.
jpayne@69 951 *
jpayne@69 952 * A deep clone will copy both the UText data structures and the underlying text.
jpayne@69 953 * The original and cloned UText will operate completely independently; modifications
jpayne@69 954 * made to the text in one will not effect the other. Text providers are not
jpayne@69 955 * required to support deep clones. The user of clone() must check the status return
jpayne@69 956 * and be prepared to handle failures.
jpayne@69 957 *
jpayne@69 958 * A shallow clone replicates only the UText data structures; it does not make
jpayne@69 959 * a copy of the underlying text. Shallow clones can be used as an efficient way to
jpayne@69 960 * have multiple iterators active in a single text string that is not being
jpayne@69 961 * modified.
jpayne@69 962 *
jpayne@69 963 * A shallow clone operation must not fail except for truly exceptional conditions such
jpayne@69 964 * as memory allocation failures.
jpayne@69 965 *
jpayne@69 966 * A UText and its clone may be safely concurrently accessed by separate threads.
jpayne@69 967 * This is true for both shallow and deep clones.
jpayne@69 968 * It is the responsibility of the Text Provider to ensure that this thread safety
jpayne@69 969 * constraint is met.
jpayne@69 970
jpayne@69 971 *
jpayne@69 972 * @param dest A UText struct to be filled in with the result of the clone operation,
jpayne@69 973 * or NULL if the clone function should heap-allocate a new UText struct.
jpayne@69 974 * @param src The UText to be cloned.
jpayne@69 975 * @param deep TRUE to request a deep clone, FALSE for a shallow clone.
jpayne@69 976 * @param status Errors are returned here. For deep clones, U_UNSUPPORTED_ERROR
jpayne@69 977 * should be returned if the text provider is unable to clone the
jpayne@69 978 * original text.
jpayne@69 979 * @return The newly created clone, or NULL if the clone operation failed.
jpayne@69 980 *
jpayne@69 981 * @stable ICU 3.4
jpayne@69 982 */
jpayne@69 983 typedef UText * U_CALLCONV
jpayne@69 984 UTextClone(UText *dest, const UText *src, UBool deep, UErrorCode *status);
jpayne@69 985
jpayne@69 986
jpayne@69 987 /**
jpayne@69 988 * Function type declaration for UText.nativeLength().
jpayne@69 989 *
jpayne@69 990 * @param ut the UText to get the length of.
jpayne@69 991 * @return the length, in the native units of the original text string.
jpayne@69 992 * @see UText
jpayne@69 993 * @stable ICU 3.4
jpayne@69 994 */
jpayne@69 995 typedef int64_t U_CALLCONV
jpayne@69 996 UTextNativeLength(UText *ut);
jpayne@69 997
jpayne@69 998 /**
jpayne@69 999 * Function type declaration for UText.access(). Get the description of the text chunk
jpayne@69 1000 * containing the text at a requested native index. The UText's iteration
jpayne@69 1001 * position will be left at the requested index. If the index is out
jpayne@69 1002 * of bounds, the iteration position will be left at the start or end
jpayne@69 1003 * of the string, as appropriate.
jpayne@69 1004 *
jpayne@69 1005 * Chunks must begin and end on code point boundaries. A single code point
jpayne@69 1006 * comprised of multiple storage units must never span a chunk boundary.
jpayne@69 1007 *
jpayne@69 1008 *
jpayne@69 1009 * @param ut the UText being accessed.
jpayne@69 1010 * @param nativeIndex Requested index of the text to be accessed.
jpayne@69 1011 * @param forward If TRUE, then the returned chunk must contain text
jpayne@69 1012 * starting from the index, so that start<=index<limit.
jpayne@69 1013 * If FALSE, then the returned chunk must contain text
jpayne@69 1014 * before the index, so that start<index<=limit.
jpayne@69 1015 * @return True if the requested index could be accessed. The chunk
jpayne@69 1016 * will contain the requested text.
jpayne@69 1017 * False value if a chunk cannot be accessed
jpayne@69 1018 * (the requested index is out of bounds).
jpayne@69 1019 *
jpayne@69 1020 * @see UText
jpayne@69 1021 * @stable ICU 3.4
jpayne@69 1022 */
jpayne@69 1023 typedef UBool U_CALLCONV
jpayne@69 1024 UTextAccess(UText *ut, int64_t nativeIndex, UBool forward);
jpayne@69 1025
jpayne@69 1026 /**
jpayne@69 1027 * Function type declaration for UText.extract().
jpayne@69 1028 *
jpayne@69 1029 * Extract text from a UText into a UChar buffer. The range of text to be extracted
jpayne@69 1030 * is specified in the native indices of the UText provider. These may not necessarily
jpayne@69 1031 * be UTF-16 indices.
jpayne@69 1032 * <p>
jpayne@69 1033 * The size (number of 16 bit UChars) in the data to be extracted is returned. The
jpayne@69 1034 * full amount is returned, even when the specified buffer size is smaller.
jpayne@69 1035 * <p>
jpayne@69 1036 * The extracted string will (if you are a user) / must (if you are a text provider)
jpayne@69 1037 * be NUL-terminated if there is sufficient space in the destination buffer.
jpayne@69 1038 *
jpayne@69 1039 * @param ut the UText from which to extract data.
jpayne@69 1040 * @param nativeStart the native index of the first character to extract.
jpayne@69 1041 * @param nativeLimit the native string index of the position following the last
jpayne@69 1042 * character to extract.
jpayne@69 1043 * @param dest the UChar (UTF-16) buffer into which the extracted text is placed
jpayne@69 1044 * @param destCapacity The size, in UChars, of the destination buffer. May be zero
jpayne@69 1045 * for precomputing the required size.
jpayne@69 1046 * @param status receives any error status.
jpayne@69 1047 * If U_BUFFER_OVERFLOW_ERROR: Returns number of UChars for
jpayne@69 1048 * preflighting.
jpayne@69 1049 * @return Number of UChars in the data. Does not include a trailing NUL.
jpayne@69 1050 *
jpayne@69 1051 * @stable ICU 3.4
jpayne@69 1052 */
jpayne@69 1053 typedef int32_t U_CALLCONV
jpayne@69 1054 UTextExtract(UText *ut,
jpayne@69 1055 int64_t nativeStart, int64_t nativeLimit,
jpayne@69 1056 UChar *dest, int32_t destCapacity,
jpayne@69 1057 UErrorCode *status);
jpayne@69 1058
jpayne@69 1059 /**
jpayne@69 1060 * Function type declaration for UText.replace().
jpayne@69 1061 *
jpayne@69 1062 * Replace a range of the original text with a replacement text.
jpayne@69 1063 *
jpayne@69 1064 * Leaves the current iteration position at the position following the
jpayne@69 1065 * newly inserted replacement text.
jpayne@69 1066 *
jpayne@69 1067 * This function need only be implemented on UText types that support writing.
jpayne@69 1068 *
jpayne@69 1069 * When using this function, there should be only a single UText opened onto the
jpayne@69 1070 * underlying native text string. The function is responsible for updating the
jpayne@69 1071 * text chunk within the UText to reflect the updated iteration position,
jpayne@69 1072 * taking into account any changes to the underlying string's structure caused
jpayne@69 1073 * by the replace operation.
jpayne@69 1074 *
jpayne@69 1075 * @param ut the UText representing the text to be operated on.
jpayne@69 1076 * @param nativeStart the index of the start of the region to be replaced
jpayne@69 1077 * @param nativeLimit the index of the character following the region to be replaced.
jpayne@69 1078 * @param replacementText pointer to the replacement text
jpayne@69 1079 * @param replacmentLength length of the replacement text in UChars, or -1 if the text is NUL terminated.
jpayne@69 1080 * @param status receives any error status. Possible errors include
jpayne@69 1081 * U_NO_WRITE_PERMISSION
jpayne@69 1082 *
jpayne@69 1083 * @return The signed number of (native) storage units by which
jpayne@69 1084 * the length of the text expanded or contracted.
jpayne@69 1085 *
jpayne@69 1086 * @stable ICU 3.4
jpayne@69 1087 */
jpayne@69 1088 typedef int32_t U_CALLCONV
jpayne@69 1089 UTextReplace(UText *ut,
jpayne@69 1090 int64_t nativeStart, int64_t nativeLimit,
jpayne@69 1091 const UChar *replacementText, int32_t replacmentLength,
jpayne@69 1092 UErrorCode *status);
jpayne@69 1093
jpayne@69 1094 /**
jpayne@69 1095 * Function type declaration for UText.copy().
jpayne@69 1096 *
jpayne@69 1097 * Copy or move a substring from one position to another within the text,
jpayne@69 1098 * while retaining any metadata associated with the text.
jpayne@69 1099 * This function is used to duplicate or reorder substrings.
jpayne@69 1100 * The destination index must not overlap the source range.
jpayne@69 1101 *
jpayne@69 1102 * The text to be copied or moved is inserted at destIndex;
jpayne@69 1103 * it does not replace or overwrite any existing text.
jpayne@69 1104 *
jpayne@69 1105 * This function need only be implemented for UText types that support writing.
jpayne@69 1106 *
jpayne@69 1107 * When using this function, there should be only a single UText opened onto the
jpayne@69 1108 * underlying native text string. The function is responsible for updating the
jpayne@69 1109 * text chunk within the UText to reflect the updated iteration position,
jpayne@69 1110 * taking into account any changes to the underlying string's structure caused
jpayne@69 1111 * by the replace operation.
jpayne@69 1112 *
jpayne@69 1113 * @param ut The UText representing the text to be operated on.
jpayne@69 1114 * @param nativeStart The index of the start of the region to be copied or moved
jpayne@69 1115 * @param nativeLimit The index of the character following the region to be replaced.
jpayne@69 1116 * @param nativeDest The destination index to which the source substring is copied or moved.
jpayne@69 1117 * @param move If TRUE, then the substring is moved, not copied/duplicated.
jpayne@69 1118 * @param status receives any error status. Possible errors include U_NO_WRITE_PERMISSION
jpayne@69 1119 *
jpayne@69 1120 * @stable ICU 3.4
jpayne@69 1121 */
jpayne@69 1122 typedef void U_CALLCONV
jpayne@69 1123 UTextCopy(UText *ut,
jpayne@69 1124 int64_t nativeStart, int64_t nativeLimit,
jpayne@69 1125 int64_t nativeDest,
jpayne@69 1126 UBool move,
jpayne@69 1127 UErrorCode *status);
jpayne@69 1128
jpayne@69 1129 /**
jpayne@69 1130 * Function type declaration for UText.mapOffsetToNative().
jpayne@69 1131 * Map from the current UChar offset within the current text chunk to
jpayne@69 1132 * the corresponding native index in the original source text.
jpayne@69 1133 *
jpayne@69 1134 * This is required only for text providers that do not use native UTF-16 indexes.
jpayne@69 1135 *
jpayne@69 1136 * @param ut the UText.
jpayne@69 1137 * @return Absolute (native) index corresponding to chunkOffset in the current chunk.
jpayne@69 1138 * The returned native index should always be to a code point boundary.
jpayne@69 1139 *
jpayne@69 1140 * @stable ICU 3.4
jpayne@69 1141 */
jpayne@69 1142 typedef int64_t U_CALLCONV
jpayne@69 1143 UTextMapOffsetToNative(const UText *ut);
jpayne@69 1144
jpayne@69 1145 /**
jpayne@69 1146 * Function type declaration for UText.mapIndexToUTF16().
jpayne@69 1147 * Map from a native index to a UChar offset within a text chunk.
jpayne@69 1148 * Behavior is undefined if the native index does not fall within the
jpayne@69 1149 * current chunk.
jpayne@69 1150 *
jpayne@69 1151 * This function is required only for text providers that do not use native UTF-16 indexes.
jpayne@69 1152 *
jpayne@69 1153 * @param ut The UText containing the text chunk.
jpayne@69 1154 * @param nativeIndex Absolute (native) text index, chunk->start<=index<=chunk->limit.
jpayne@69 1155 * @return Chunk-relative UTF-16 offset corresponding to the specified native
jpayne@69 1156 * index.
jpayne@69 1157 *
jpayne@69 1158 * @stable ICU 3.4
jpayne@69 1159 */
jpayne@69 1160 typedef int32_t U_CALLCONV
jpayne@69 1161 UTextMapNativeIndexToUTF16(const UText *ut, int64_t nativeIndex);
jpayne@69 1162
jpayne@69 1163
jpayne@69 1164 /**
jpayne@69 1165 * Function type declaration for UText.utextClose().
jpayne@69 1166 *
jpayne@69 1167 * A Text Provider close function is only required for provider types that make
jpayne@69 1168 * allocations in their open function (or other functions) that must be
jpayne@69 1169 * cleaned when the UText is closed.
jpayne@69 1170 *
jpayne@69 1171 * The allocation of the UText struct itself and any "extra" storage
jpayne@69 1172 * associated with the UText is handled by the common UText implementation
jpayne@69 1173 * and does not require provider specific cleanup in a close function.
jpayne@69 1174 *
jpayne@69 1175 * Most UText provider implementations do not need to implement this function.
jpayne@69 1176 *
jpayne@69 1177 * @param ut A UText object to be closed.
jpayne@69 1178 *
jpayne@69 1179 * @stable ICU 3.4
jpayne@69 1180 */
jpayne@69 1181 typedef void U_CALLCONV
jpayne@69 1182 UTextClose(UText *ut);
jpayne@69 1183
jpayne@69 1184
jpayne@69 1185 /**
jpayne@69 1186 * (public) Function dispatch table for UText.
jpayne@69 1187 * Conceptually very much like a C++ Virtual Function Table.
jpayne@69 1188 * This struct defines the organization of the table.
jpayne@69 1189 * Each text provider implementation must provide an
jpayne@69 1190 * actual table that is initialized with the appropriate functions
jpayne@69 1191 * for the type of text being handled.
jpayne@69 1192 * @stable ICU 3.6
jpayne@69 1193 */
jpayne@69 1194 struct UTextFuncs {
jpayne@69 1195 /**
jpayne@69 1196 * (public) Function table size, sizeof(UTextFuncs)
jpayne@69 1197 * Intended for use should the table grow to accommodate added
jpayne@69 1198 * functions in the future, to allow tests for older format
jpayne@69 1199 * function tables that do not contain the extensions.
jpayne@69 1200 *
jpayne@69 1201 * Fields are placed for optimal alignment on
jpayne@69 1202 * 32/64/128-bit-pointer machines, by normally grouping together
jpayne@69 1203 * 4 32-bit fields,
jpayne@69 1204 * 4 pointers,
jpayne@69 1205 * 2 64-bit fields
jpayne@69 1206 * in sequence.
jpayne@69 1207 * @stable ICU 3.6
jpayne@69 1208 */
jpayne@69 1209 int32_t tableSize;
jpayne@69 1210
jpayne@69 1211 /**
jpayne@69 1212 * (private) Alignment padding.
jpayne@69 1213 * Do not use, reserved for use by the UText framework only.
jpayne@69 1214 * @internal
jpayne@69 1215 */
jpayne@69 1216 int32_t reserved1, /** @internal */ reserved2, /** @internal */ reserved3;
jpayne@69 1217
jpayne@69 1218
jpayne@69 1219 /**
jpayne@69 1220 * (public) Function pointer for UTextClone
jpayne@69 1221 *
jpayne@69 1222 * @see UTextClone
jpayne@69 1223 * @stable ICU 3.6
jpayne@69 1224 */
jpayne@69 1225 UTextClone *clone;
jpayne@69 1226
jpayne@69 1227 /**
jpayne@69 1228 * (public) function pointer for UTextLength
jpayne@69 1229 * May be expensive to compute!
jpayne@69 1230 *
jpayne@69 1231 * @see UTextLength
jpayne@69 1232 * @stable ICU 3.6
jpayne@69 1233 */
jpayne@69 1234 UTextNativeLength *nativeLength;
jpayne@69 1235
jpayne@69 1236 /**
jpayne@69 1237 * (public) Function pointer for UTextAccess.
jpayne@69 1238 *
jpayne@69 1239 * @see UTextAccess
jpayne@69 1240 * @stable ICU 3.6
jpayne@69 1241 */
jpayne@69 1242 UTextAccess *access;
jpayne@69 1243
jpayne@69 1244 /**
jpayne@69 1245 * (public) Function pointer for UTextExtract.
jpayne@69 1246 *
jpayne@69 1247 * @see UTextExtract
jpayne@69 1248 * @stable ICU 3.6
jpayne@69 1249 */
jpayne@69 1250 UTextExtract *extract;
jpayne@69 1251
jpayne@69 1252 /**
jpayne@69 1253 * (public) Function pointer for UTextReplace.
jpayne@69 1254 *
jpayne@69 1255 * @see UTextReplace
jpayne@69 1256 * @stable ICU 3.6
jpayne@69 1257 */
jpayne@69 1258 UTextReplace *replace;
jpayne@69 1259
jpayne@69 1260 /**
jpayne@69 1261 * (public) Function pointer for UTextCopy.
jpayne@69 1262 *
jpayne@69 1263 * @see UTextCopy
jpayne@69 1264 * @stable ICU 3.6
jpayne@69 1265 */
jpayne@69 1266 UTextCopy *copy;
jpayne@69 1267
jpayne@69 1268 /**
jpayne@69 1269 * (public) Function pointer for UTextMapOffsetToNative.
jpayne@69 1270 *
jpayne@69 1271 * @see UTextMapOffsetToNative
jpayne@69 1272 * @stable ICU 3.6
jpayne@69 1273 */
jpayne@69 1274 UTextMapOffsetToNative *mapOffsetToNative;
jpayne@69 1275
jpayne@69 1276 /**
jpayne@69 1277 * (public) Function pointer for UTextMapNativeIndexToUTF16.
jpayne@69 1278 *
jpayne@69 1279 * @see UTextMapNativeIndexToUTF16
jpayne@69 1280 * @stable ICU 3.6
jpayne@69 1281 */
jpayne@69 1282 UTextMapNativeIndexToUTF16 *mapNativeIndexToUTF16;
jpayne@69 1283
jpayne@69 1284 /**
jpayne@69 1285 * (public) Function pointer for UTextClose.
jpayne@69 1286 *
jpayne@69 1287 * @see UTextClose
jpayne@69 1288 * @stable ICU 3.6
jpayne@69 1289 */
jpayne@69 1290 UTextClose *close;
jpayne@69 1291
jpayne@69 1292 /**
jpayne@69 1293 * (private) Spare function pointer
jpayne@69 1294 * @internal
jpayne@69 1295 */
jpayne@69 1296 UTextClose *spare1;
jpayne@69 1297
jpayne@69 1298 /**
jpayne@69 1299 * (private) Spare function pointer
jpayne@69 1300 * @internal
jpayne@69 1301 */
jpayne@69 1302 UTextClose *spare2;
jpayne@69 1303
jpayne@69 1304 /**
jpayne@69 1305 * (private) Spare function pointer
jpayne@69 1306 * @internal
jpayne@69 1307 */
jpayne@69 1308 UTextClose *spare3;
jpayne@69 1309
jpayne@69 1310 };
jpayne@69 1311 /**
jpayne@69 1312 * Function dispatch table for UText
jpayne@69 1313 * @see UTextFuncs
jpayne@69 1314 */
jpayne@69 1315 typedef struct UTextFuncs UTextFuncs;
jpayne@69 1316
jpayne@69 1317 /**
jpayne@69 1318 * UText struct. Provides the interface between the generic UText access code
jpayne@69 1319 * and the UText provider code that works on specific kinds of
jpayne@69 1320 * text (UTF-8, noncontiguous UTF-16, whatever.)
jpayne@69 1321 *
jpayne@69 1322 * Applications that are using predefined types of text providers
jpayne@69 1323 * to pass text data to ICU services will have no need to view the
jpayne@69 1324 * internals of the UText structs that they open.
jpayne@69 1325 *
jpayne@69 1326 * @stable ICU 3.6
jpayne@69 1327 */
jpayne@69 1328 struct UText {
jpayne@69 1329 /**
jpayne@69 1330 * (private) Magic. Used to help detect when UText functions are handed
jpayne@69 1331 * invalid or uninitialized UText structs.
jpayne@69 1332 * utext_openXYZ() functions take an initialized,
jpayne@69 1333 * but not necessarily open, UText struct as an
jpayne@69 1334 * optional fill-in parameter. This magic field
jpayne@69 1335 * is used to check for that initialization.
jpayne@69 1336 * Text provider close functions must NOT clear
jpayne@69 1337 * the magic field because that would prevent
jpayne@69 1338 * reuse of the UText struct.
jpayne@69 1339 * @internal
jpayne@69 1340 */
jpayne@69 1341 uint32_t magic;
jpayne@69 1342
jpayne@69 1343
jpayne@69 1344 /**
jpayne@69 1345 * (private) Flags for managing the allocation and freeing of
jpayne@69 1346 * memory associated with this UText.
jpayne@69 1347 * @internal
jpayne@69 1348 */
jpayne@69 1349 int32_t flags;
jpayne@69 1350
jpayne@69 1351
jpayne@69 1352 /**
jpayne@69 1353 * Text provider properties. This set of flags is maintained by the
jpayne@69 1354 * text provider implementation.
jpayne@69 1355 * @stable ICU 3.4
jpayne@69 1356 */
jpayne@69 1357 int32_t providerProperties;
jpayne@69 1358
jpayne@69 1359 /**
jpayne@69 1360 * (public) sizeOfStruct=sizeof(UText)
jpayne@69 1361 * Allows possible backward compatible extension.
jpayne@69 1362 *
jpayne@69 1363 * @stable ICU 3.4
jpayne@69 1364 */
jpayne@69 1365 int32_t sizeOfStruct;
jpayne@69 1366
jpayne@69 1367 /* ------ 16 byte alignment boundary ----------- */
jpayne@69 1368
jpayne@69 1369
jpayne@69 1370 /**
jpayne@69 1371 * (protected) Native index of the first character position following
jpayne@69 1372 * the current chunk.
jpayne@69 1373 * @stable ICU 3.6
jpayne@69 1374 */
jpayne@69 1375 int64_t chunkNativeLimit;
jpayne@69 1376
jpayne@69 1377 /**
jpayne@69 1378 * (protected) Size in bytes of the extra space (pExtra).
jpayne@69 1379 * @stable ICU 3.4
jpayne@69 1380 */
jpayne@69 1381 int32_t extraSize;
jpayne@69 1382
jpayne@69 1383 /**
jpayne@69 1384 * (protected) The highest chunk offset where native indexing and
jpayne@69 1385 * chunk (UTF-16) indexing correspond. For UTF-16 sources, value
jpayne@69 1386 * will be equal to chunkLength.
jpayne@69 1387 *
jpayne@69 1388 * @stable ICU 3.6
jpayne@69 1389 */
jpayne@69 1390 int32_t nativeIndexingLimit;
jpayne@69 1391
jpayne@69 1392 /* ---- 16 byte alignment boundary------ */
jpayne@69 1393
jpayne@69 1394 /**
jpayne@69 1395 * (protected) Native index of the first character in the text chunk.
jpayne@69 1396 * @stable ICU 3.6
jpayne@69 1397 */
jpayne@69 1398 int64_t chunkNativeStart;
jpayne@69 1399
jpayne@69 1400 /**
jpayne@69 1401 * (protected) Current iteration position within the text chunk (UTF-16 buffer).
jpayne@69 1402 * This is the index to the character that will be returned by utext_next32().
jpayne@69 1403 * @stable ICU 3.6
jpayne@69 1404 */
jpayne@69 1405 int32_t chunkOffset;
jpayne@69 1406
jpayne@69 1407 /**
jpayne@69 1408 * (protected) Length the text chunk (UTF-16 buffer), in UChars.
jpayne@69 1409 * @stable ICU 3.6
jpayne@69 1410 */
jpayne@69 1411 int32_t chunkLength;
jpayne@69 1412
jpayne@69 1413 /* ---- 16 byte alignment boundary-- */
jpayne@69 1414
jpayne@69 1415
jpayne@69 1416 /**
jpayne@69 1417 * (protected) pointer to a chunk of text in UTF-16 format.
jpayne@69 1418 * May refer either to original storage of the source of the text, or
jpayne@69 1419 * if conversion was required, to a buffer owned by the UText.
jpayne@69 1420 * @stable ICU 3.6
jpayne@69 1421 */
jpayne@69 1422 const UChar *chunkContents;
jpayne@69 1423
jpayne@69 1424 /**
jpayne@69 1425 * (public) Pointer to Dispatch table for accessing functions for this UText.
jpayne@69 1426 * @stable ICU 3.6
jpayne@69 1427 */
jpayne@69 1428 const UTextFuncs *pFuncs;
jpayne@69 1429
jpayne@69 1430 /**
jpayne@69 1431 * (protected) Pointer to additional space requested by the
jpayne@69 1432 * text provider during the utext_open operation.
jpayne@69 1433 * @stable ICU 3.4
jpayne@69 1434 */
jpayne@69 1435 void *pExtra;
jpayne@69 1436
jpayne@69 1437 /**
jpayne@69 1438 * (protected) Pointer to string or text-containing object or similar.
jpayne@69 1439 * This is the source of the text that this UText is wrapping, in a format
jpayne@69 1440 * that is known to the text provider functions.
jpayne@69 1441 * @stable ICU 3.4
jpayne@69 1442 */
jpayne@69 1443 const void *context;
jpayne@69 1444
jpayne@69 1445 /* --- 16 byte alignment boundary--- */
jpayne@69 1446
jpayne@69 1447 /**
jpayne@69 1448 * (protected) Pointer fields available for use by the text provider.
jpayne@69 1449 * Not used by UText common code.
jpayne@69 1450 * @stable ICU 3.6
jpayne@69 1451 */
jpayne@69 1452 const void *p;
jpayne@69 1453 /**
jpayne@69 1454 * (protected) Pointer fields available for use by the text provider.
jpayne@69 1455 * Not used by UText common code.
jpayne@69 1456 * @stable ICU 3.6
jpayne@69 1457 */
jpayne@69 1458 const void *q;
jpayne@69 1459 /**
jpayne@69 1460 * (protected) Pointer fields available for use by the text provider.
jpayne@69 1461 * Not used by UText common code.
jpayne@69 1462 * @stable ICU 3.6
jpayne@69 1463 */
jpayne@69 1464 const void *r;
jpayne@69 1465
jpayne@69 1466 /**
jpayne@69 1467 * Private field reserved for future use by the UText framework
jpayne@69 1468 * itself. This is not to be touched by the text providers.
jpayne@69 1469 * @internal ICU 3.4
jpayne@69 1470 */
jpayne@69 1471 void *privP;
jpayne@69 1472
jpayne@69 1473
jpayne@69 1474 /* --- 16 byte alignment boundary--- */
jpayne@69 1475
jpayne@69 1476
jpayne@69 1477 /**
jpayne@69 1478 * (protected) Integer field reserved for use by the text provider.
jpayne@69 1479 * Not used by the UText framework, or by the client (user) of the UText.
jpayne@69 1480 * @stable ICU 3.4
jpayne@69 1481 */
jpayne@69 1482 int64_t a;
jpayne@69 1483
jpayne@69 1484 /**
jpayne@69 1485 * (protected) Integer field reserved for use by the text provider.
jpayne@69 1486 * Not used by the UText framework, or by the client (user) of the UText.
jpayne@69 1487 * @stable ICU 3.4
jpayne@69 1488 */
jpayne@69 1489 int32_t b;
jpayne@69 1490
jpayne@69 1491 /**
jpayne@69 1492 * (protected) Integer field reserved for use by the text provider.
jpayne@69 1493 * Not used by the UText framework, or by the client (user) of the UText.
jpayne@69 1494 * @stable ICU 3.4
jpayne@69 1495 */
jpayne@69 1496 int32_t c;
jpayne@69 1497
jpayne@69 1498 /* ---- 16 byte alignment boundary---- */
jpayne@69 1499
jpayne@69 1500
jpayne@69 1501 /**
jpayne@69 1502 * Private field reserved for future use by the UText framework
jpayne@69 1503 * itself. This is not to be touched by the text providers.
jpayne@69 1504 * @internal ICU 3.4
jpayne@69 1505 */
jpayne@69 1506 int64_t privA;
jpayne@69 1507 /**
jpayne@69 1508 * Private field reserved for future use by the UText framework
jpayne@69 1509 * itself. This is not to be touched by the text providers.
jpayne@69 1510 * @internal ICU 3.4
jpayne@69 1511 */
jpayne@69 1512 int32_t privB;
jpayne@69 1513 /**
jpayne@69 1514 * Private field reserved for future use by the UText framework
jpayne@69 1515 * itself. This is not to be touched by the text providers.
jpayne@69 1516 * @internal ICU 3.4
jpayne@69 1517 */
jpayne@69 1518 int32_t privC;
jpayne@69 1519 };
jpayne@69 1520
jpayne@69 1521
jpayne@69 1522 /**
jpayne@69 1523 * Common function for use by Text Provider implementations to allocate and/or initialize
jpayne@69 1524 * a new UText struct. To be called in the implementation of utext_open() functions.
jpayne@69 1525 * If the supplied UText parameter is null, a new UText struct will be allocated on the heap.
jpayne@69 1526 * If the supplied UText is already open, the provider's close function will be called
jpayne@69 1527 * so that the struct can be reused by the open that is in progress.
jpayne@69 1528 *
jpayne@69 1529 * @param ut pointer to a UText struct to be re-used, or null if a new UText
jpayne@69 1530 * should be allocated.
jpayne@69 1531 * @param extraSpace The amount of additional space to be allocated as part
jpayne@69 1532 * of this UText, for use by types of providers that require
jpayne@69 1533 * additional storage.
jpayne@69 1534 * @param status Errors are returned here.
jpayne@69 1535 * @return pointer to the UText, allocated if necessary, with extra space set up if requested.
jpayne@69 1536 * @stable ICU 3.4
jpayne@69 1537 */
jpayne@69 1538 U_STABLE UText * U_EXPORT2
jpayne@69 1539 utext_setup(UText *ut, int32_t extraSpace, UErrorCode *status);
jpayne@69 1540
jpayne@69 1541 // do not use #ifndef U_HIDE_INTERNAL_API around the following!
jpayne@69 1542 /**
jpayne@69 1543 * @internal
jpayne@69 1544 * Value used to help identify correctly initialized UText structs.
jpayne@69 1545 * Note: must be publicly visible so that UTEXT_INITIALIZER can access it.
jpayne@69 1546 */
jpayne@69 1547 enum {
jpayne@69 1548 UTEXT_MAGIC = 0x345ad82c
jpayne@69 1549 };
jpayne@69 1550
jpayne@69 1551 /**
jpayne@69 1552 * initializer to be used with local (stack) instances of a UText
jpayne@69 1553 * struct. UText structs must be initialized before passing
jpayne@69 1554 * them to one of the utext_open functions.
jpayne@69 1555 *
jpayne@69 1556 * @stable ICU 3.6
jpayne@69 1557 */
jpayne@69 1558 #define UTEXT_INITIALIZER { \
jpayne@69 1559 UTEXT_MAGIC, /* magic */ \
jpayne@69 1560 0, /* flags */ \
jpayne@69 1561 0, /* providerProps */ \
jpayne@69 1562 sizeof(UText), /* sizeOfStruct */ \
jpayne@69 1563 0, /* chunkNativeLimit */ \
jpayne@69 1564 0, /* extraSize */ \
jpayne@69 1565 0, /* nativeIndexingLimit */ \
jpayne@69 1566 0, /* chunkNativeStart */ \
jpayne@69 1567 0, /* chunkOffset */ \
jpayne@69 1568 0, /* chunkLength */ \
jpayne@69 1569 NULL, /* chunkContents */ \
jpayne@69 1570 NULL, /* pFuncs */ \
jpayne@69 1571 NULL, /* pExtra */ \
jpayne@69 1572 NULL, /* context */ \
jpayne@69 1573 NULL, NULL, NULL, /* p, q, r */ \
jpayne@69 1574 NULL, /* privP */ \
jpayne@69 1575 0, 0, 0, /* a, b, c */ \
jpayne@69 1576 0, 0, 0 /* privA,B,C, */ \
jpayne@69 1577 }
jpayne@69 1578
jpayne@69 1579
jpayne@69 1580 U_CDECL_END
jpayne@69 1581
jpayne@69 1582
jpayne@69 1583 #if U_SHOW_CPLUSPLUS_API
jpayne@69 1584
jpayne@69 1585 U_NAMESPACE_BEGIN
jpayne@69 1586
jpayne@69 1587 /**
jpayne@69 1588 * \class LocalUTextPointer
jpayne@69 1589 * "Smart pointer" class, closes a UText via utext_close().
jpayne@69 1590 * For most methods see the LocalPointerBase base class.
jpayne@69 1591 *
jpayne@69 1592 * @see LocalPointerBase
jpayne@69 1593 * @see LocalPointer
jpayne@69 1594 * @stable ICU 4.4
jpayne@69 1595 */
jpayne@69 1596 U_DEFINE_LOCAL_OPEN_POINTER(LocalUTextPointer, UText, utext_close);
jpayne@69 1597
jpayne@69 1598 U_NAMESPACE_END
jpayne@69 1599
jpayne@69 1600 #endif
jpayne@69 1601
jpayne@69 1602
jpayne@69 1603 #endif