michael@0: * If the UText was originally allocated by one of the utext_open functions, michael@0: * the storage associated with the utext will also be freed. michael@0: * If the UText storage originated with the application, as it would with michael@0: * a local or static instance, the storage will not be deleted. michael@0: * michael@0: * An open UText can be reset to refer to new string by using one of the utext_open() michael@0: * functions without first closing the UText. michael@0: * michael@0: * @param ut The UText to be closed. michael@0: * @return NULL if the UText struct was deleted by the close. If the UText struct michael@0: * was originally provided by the caller to the open function, it is michael@0: * returned by this function, and may be safely used again in michael@0: * a subsequent utext_open. michael@0: * michael@0: * @stable ICU 3.4 michael@0: */ michael@0: U_STABLE UText * U_EXPORT2 michael@0: utext_close(UText *ut); michael@0: michael@0: #if U_SHOW_CPLUSPLUS_API michael@0: michael@0: U_NAMESPACE_BEGIN michael@0: michael@0: /** michael@0: * \class LocalUTextPointer michael@0: * "Smart pointer" class, closes a UText via utext_close(). michael@0: * For most methods see the LocalPointerBase base class. michael@0: * michael@0: * @see LocalPointerBase michael@0: * @see LocalPointer michael@0: * @stable ICU 4.4 michael@0: */ michael@0: U_DEFINE_LOCAL_OPEN_POINTER(LocalUTextPointer, UText, utext_close); michael@0: michael@0: U_NAMESPACE_END michael@0: michael@0: #endif michael@0: michael@0: /** michael@0: * Open a read-only UText implementation for UTF-8 strings. michael@0: * michael@0: * \htmlonly michael@0: * Any invalid UTF-8 in the input will be handled in this way: michael@0: * a sequence of bytes that has the form of a truncated, but otherwise valid, michael@0: * UTF-8 sequence will be replaced by a single unicode replacement character, \uFFFD. michael@0: * Any other illegal bytes will each be replaced by a \uFFFD. michael@0: * \endhtmlonly michael@0: * michael@0: * @param ut Pointer to a UText struct. If NULL, a new UText will be created. michael@0: * If non-NULL, must refer to an initialized UText struct, which will then michael@0: * be reset to reference the specified UTF-8 string. michael@0: * @param s A UTF-8 string. Must not be NULL. michael@0: * @param length The length of the UTF-8 string in bytes, or -1 if the string is michael@0: * zero terminated. michael@0: * @param status Errors are returned here. michael@0: * @return A pointer to the UText. If a pre-allocated UText was provided, it michael@0: * will always be used and returned. michael@0: * @stable ICU 3.4 michael@0: */ michael@0: U_STABLE UText * U_EXPORT2 michael@0: utext_openUTF8(UText *ut, const char *s, int64_t length, UErrorCode *status); michael@0: michael@0: michael@0: /** michael@0: * Open a read-only UText for UChar * string. michael@0: * michael@0: * @param ut Pointer to a UText struct. If NULL, a new UText will be created. michael@0: * If non-NULL, must refer to an initialized UText struct, which will then michael@0: * be reset to reference the specified UChar string. michael@0: * @param s A UChar (UTF-16) string michael@0: * @param length The number of UChars in the input string, or -1 if the string is michael@0: * zero terminated. michael@0: * @param status Errors are returned here. michael@0: * @return A pointer to the UText. If a pre-allocated UText was provided, it michael@0: * will always be used and returned. michael@0: * @stable ICU 3.4 michael@0: */ michael@0: U_STABLE UText * U_EXPORT2 michael@0: utext_openUChars(UText *ut, const UChar *s, int64_t length, UErrorCode *status); michael@0: michael@0: michael@0: #if U_SHOW_CPLUSPLUS_API michael@0: /** michael@0: * Open a writable UText for a non-const UnicodeString. michael@0: * michael@0: * @param ut Pointer to a UText struct. If NULL, a new UText will be created. michael@0: * If non-NULL, must refer to an initialized UText struct, which will then michael@0: * be reset to reference the specified input string. michael@0: * @param s A UnicodeString. michael@0: * @param status Errors are returned here. michael@0: * @return Pointer to the UText. If a UText was supplied as input, this michael@0: * will always be used and returned. michael@0: * @stable ICU 3.4 michael@0: */ michael@0: U_STABLE UText * U_EXPORT2 michael@0: utext_openUnicodeString(UText *ut, icu::UnicodeString *s, UErrorCode *status); michael@0: michael@0: michael@0: /** michael@0: * Open a UText for a const UnicodeString. The resulting UText will not be writable. michael@0: * michael@0: * @param ut Pointer to a UText struct. If NULL, a new UText will be created. michael@0: * If non-NULL, must refer to an initialized UText struct, which will then michael@0: * be reset to reference the specified input string. michael@0: * @param s A const UnicodeString to be wrapped. michael@0: * @param status Errors are returned here. michael@0: * @return Pointer to the UText. If a UText was supplied as input, this michael@0: * will always be used and returned. michael@0: * @stable ICU 3.4 michael@0: */ michael@0: U_STABLE UText * U_EXPORT2 michael@0: utext_openConstUnicodeString(UText *ut, const icu::UnicodeString *s, UErrorCode *status); michael@0: michael@0: michael@0: /** michael@0: * Open a writable UText implementation for an ICU Replaceable object. michael@0: * @param ut Pointer to a UText struct. If NULL, a new UText will be created. michael@0: * If non-NULL, must refer to an already existing UText, which will then michael@0: * be reset to reference the specified replaceable text. michael@0: * @param rep A Replaceable text object. michael@0: * @param status Errors are returned here. michael@0: * @return Pointer to the UText. If a UText was supplied as input, this michael@0: * will always be used and returned. michael@0: * @see Replaceable michael@0: * @stable ICU 3.4 michael@0: */ michael@0: U_STABLE UText * U_EXPORT2 michael@0: utext_openReplaceable(UText *ut, icu::Replaceable *rep, UErrorCode *status); michael@0: michael@0: /** michael@0: * Open a UText implementation over an ICU CharacterIterator. michael@0: * @param ut Pointer to a UText struct. If NULL, a new UText will be created. michael@0: * If non-NULL, must refer to an already existing UText, which will then michael@0: * be reset to reference the specified replaceable text. michael@0: * @param ci A Character Iterator. michael@0: * @param status Errors are returned here. michael@0: * @return Pointer to the UText. If a UText was supplied as input, this michael@0: * will always be used and returned. michael@0: * @see Replaceable michael@0: * @stable ICU 3.4 michael@0: */ michael@0: U_STABLE UText * U_EXPORT2 michael@0: utext_openCharacterIterator(UText *ut, icu::CharacterIterator *ci, UErrorCode *status); michael@0: michael@0: #endif michael@0: michael@0: michael@0: /** michael@0: * Clone a UText. This is much like opening a UText where the source text is itself michael@0: * another UText. michael@0: * michael@0: * A deep clone will copy both the UText data structures and the underlying text. michael@0: * The original and cloned UText will operate completely independently; modifications michael@0: * made to the text in one will not affect the other. Text providers are not michael@0: * required to support deep clones. The user of clone() must check the status return michael@0: * and be prepared to handle failures. michael@0: * michael@0: * The standard UText implementations for UTF8, UChar *, UnicodeString and michael@0: * Replaceable all support deep cloning. michael@0: * michael@0: * The UText returned from a deep clone will be writable, assuming that the text michael@0: * provider is able to support writing, even if the source UText had been made michael@0: * non-writable by means of UText_freeze(). michael@0: * michael@0: * A shallow clone replicates only the UText data structures; it does not make michael@0: * a copy of the underlying text. Shallow clones can be used as an efficient way to michael@0: * have multiple iterators active in a single text string that is not being michael@0: * modified. michael@0: * michael@0: * A shallow clone operation will not fail, barring truly exceptional conditions such michael@0: * as memory allocation failures. michael@0: * michael@0: * Shallow UText clones should be avoided if the UText functions that modify the michael@0: * text are expected to be used, either on the original or the cloned UText. michael@0: * Any such modifications can cause unpredictable behavior. Read Only michael@0: * shallow clones provide some protection against errors of this type by michael@0: * disabling text modification via the cloned UText. michael@0: * michael@0: * A shallow clone made with the readOnly parameter == FALSE will preserve the michael@0: * utext_isWritable() state of the source object. Note, however, that michael@0: * write operations must be avoided while more than one UText exists that refer michael@0: * to the same underlying text. michael@0: * michael@0: * A UText and its clone may be safely concurrently accessed by separate threads. michael@0: * This is true for read access only with shallow clones, and for both read and michael@0: * write access with deep clones. michael@0: * It is the responsibility of the Text Provider to ensure that this thread safety michael@0: * constraint is met. michael@0: * michael@0: * @param dest A UText struct to be filled in with the result of the clone operation, michael@0: * or NULL if the clone function should heap-allocate a new UText struct. michael@0: * If non-NULL, must refer to an already existing UText, which will then michael@0: * be reset to become the clone. michael@0: * @param src The UText to be cloned. michael@0: * @param deep TRUE to request a deep clone, FALSE for a shallow clone. michael@0: * @param readOnly TRUE to request that the cloned UText have read only access to the michael@0: * underlying text. michael@0: michael@0: * @param status Errors are returned here. For deep clones, U_UNSUPPORTED_ERROR michael@0: * will be returned if the text provider is unable to clone the michael@0: * original text. michael@0: * @return The newly created clone, or NULL if the clone operation failed. michael@0: * @stable ICU 3.4 michael@0: */ michael@0: U_STABLE UText * U_EXPORT2 michael@0: utext_clone(UText *dest, const UText *src, UBool deep, UBool readOnly, UErrorCode *status); michael@0: michael@0: michael@0: /** michael@0: * Compare two UText objects for equality. michael@0: * UTexts are equal if they are iterating over the same text, and michael@0: * have the same iteration position within the text. michael@0: * If either or both of the parameters are NULL, the comparison is FALSE. michael@0: * michael@0: * @param a The first of the two UTexts to compare. michael@0: * @param b The other UText to be compared. michael@0: * @return TRUE if the two UTexts are equal. michael@0: * @stable ICU 3.6 michael@0: */ michael@0: U_STABLE UBool U_EXPORT2 michael@0: utext_equals(const UText *a, const UText *b); michael@0: michael@0: michael@0: /***************************************************************************** michael@0: * michael@0: * Functions to work with the text represeted by a UText wrapper michael@0: * michael@0: *****************************************************************************/ michael@0: michael@0: /** michael@0: * Get the length of the text. Depending on the characteristics michael@0: * of the underlying text representation, this may be expensive. michael@0: * @see utext_isLengthExpensive() michael@0: * michael@0: * michael@0: * @param ut the text to be accessed. michael@0: * @return the length of the text, expressed in native units. michael@0: * michael@0: * @stable ICU 3.4 michael@0: */ michael@0: U_STABLE int64_t U_EXPORT2 michael@0: utext_nativeLength(UText *ut); michael@0: michael@0: /** michael@0: * Return TRUE if calculating the length of the text could be expensive. michael@0: * Finding the length of NUL terminated strings is considered to be expensive. michael@0: * michael@0: * Note that the value of this function may change michael@0: * as the result of other operations on a UText. michael@0: * Once the length of a string has been discovered, it will no longer michael@0: * be expensive to report it. michael@0: * michael@0: * @param ut the text to be accessed. michael@0: * @return TRUE if determining the length of the text could be time consuming. michael@0: * @stable ICU 3.4 michael@0: */ michael@0: U_STABLE UBool U_EXPORT2 michael@0: utext_isLengthExpensive(const UText *ut); michael@0: michael@0: /** michael@0: * Returns the code point at the requested index, michael@0: * or U_SENTINEL (-1) if it is out of bounds. michael@0: * michael@0: * If the specified index points to the interior of a multi-unit michael@0: * character - one of the trail bytes of a UTF-8 sequence, for example - michael@0: * the complete code point will be returned. michael@0: * michael@0: * The iteration position will be set to the start of the returned code point. michael@0: * michael@0: * This function is roughly equivalent to the the sequence michael@0: * utext_setNativeIndex(index); michael@0: * utext_current32(); michael@0: * (There is a subtle difference if the index is out of bounds by being less than zero - michael@0: * utext_setNativeIndex(negative value) sets the index to zero, after which utext_current() michael@0: * will return the char at zero. utext_char32At(negative index), on the other hand, will michael@0: * return the U_SENTINEL value of -1.) michael@0: * michael@0: * @param ut the text to be accessed michael@0: * @param nativeIndex the native index of the character to be accessed. If the index points michael@0: * to other than the first unit of a multi-unit character, it will be adjusted michael@0: * to the start of the character. michael@0: * @return the code point at the specified index. michael@0: * @stable ICU 3.4 michael@0: */ michael@0: U_STABLE UChar32 U_EXPORT2 michael@0: utext_char32At(UText *ut, int64_t nativeIndex); michael@0: michael@0: michael@0: /** michael@0: * michael@0: * Get the code point at the current iteration position, michael@0: * or U_SENTINEL (-1) if the iteration has reached the end of michael@0: * the input text. michael@0: * michael@0: * @param ut the text to be accessed. michael@0: * @return the Unicode code point at the current iterator position. michael@0: * @stable ICU 3.4 michael@0: */ michael@0: U_STABLE UChar32 U_EXPORT2 michael@0: utext_current32(UText *ut); michael@0: michael@0: michael@0: /** michael@0: * Get the code point at the current iteration position of the UText, and michael@0: * advance the position to the first index following the character. michael@0: * michael@0: * If the position is at the end of the text (the index following michael@0: * the last character, which is also the length of the text), michael@0: * return U_SENTINEL (-1) and do not advance the index. michael@0: * michael@0: * This is a post-increment operation. michael@0: * michael@0: * An inline macro version of this function, UTEXT_NEXT32(), michael@0: * is available for performance critical use. michael@0: * michael@0: * @param ut the text to be accessed. michael@0: * @return the Unicode code point at the iteration position. michael@0: * @see UTEXT_NEXT32 michael@0: * @stable ICU 3.4 michael@0: */ michael@0: U_STABLE UChar32 U_EXPORT2 michael@0: utext_next32(UText *ut); michael@0: michael@0: michael@0: /** michael@0: * Move the iterator position to the character (code point) whose michael@0: * index precedes the current position, and return that character. michael@0: * This is a pre-decrement operation. michael@0: * michael@0: * If the initial position is at the start of the text (index of 0) michael@0: * return U_SENTINEL (-1), and leave the position unchanged. michael@0: * michael@0: * An inline macro version of this function, UTEXT_PREVIOUS32(), michael@0: * is available for performance critical use. michael@0: * michael@0: * @param ut the text to be accessed. michael@0: * @return the previous UChar32 code point, or U_SENTINEL (-1) michael@0: * if the iteration has reached the start of the text. michael@0: * @see UTEXT_PREVIOUS32 michael@0: * @stable ICU 3.4 michael@0: */ michael@0: U_STABLE UChar32 U_EXPORT2 michael@0: utext_previous32(UText *ut); michael@0: michael@0: michael@0: /** michael@0: * Set the iteration index and return the code point at that index. michael@0: * Leave the iteration index at the start of the following code point. michael@0: * michael@0: * This function is the most efficient and convenient way to michael@0: * begin a forward iteration. The results are identical to the those michael@0: * from the sequence michael@0: * \code michael@0: * utext_setIndex(); michael@0: * utext_next32(); michael@0: * \endcode michael@0: * michael@0: * @param ut the text to be accessed. michael@0: * @param nativeIndex Iteration index, in the native units of the text provider. michael@0: * @return Code point which starts at or before index, michael@0: * or U_SENTINEL (-1) if it is out of bounds. michael@0: * @stable ICU 3.4 michael@0: */ michael@0: U_STABLE UChar32 U_EXPORT2 michael@0: utext_next32From(UText *ut, int64_t nativeIndex); michael@0: michael@0: michael@0: michael@0: /** michael@0: * Set the iteration index, and return the code point preceding the michael@0: * one specified by the initial index. Leave the iteration position michael@0: * at the start of the returned code point. michael@0: * michael@0: * This function is the most efficient and convenient way to michael@0: * begin a backwards iteration. michael@0: * michael@0: * @param ut the text to be accessed. michael@0: * @param nativeIndex Iteration index in the native units of the text provider. michael@0: * @return Code point preceding the one at the initial index, michael@0: * or U_SENTINEL (-1) if it is out of bounds. michael@0: * michael@0: * @stable ICU 3.4 michael@0: */ michael@0: U_STABLE UChar32 U_EXPORT2 michael@0: utext_previous32From(UText *ut, int64_t nativeIndex); michael@0: michael@0: /** michael@0: * Get the current iterator position, which can range from 0 to michael@0: * the length of the text. michael@0: * The position is a native index into the input text, in whatever format it michael@0: * may have (possibly UTF-8 for example), and may not always be the same as michael@0: * the corresponding UChar (UTF-16) index. michael@0: * The returned position will always be aligned to a code point boundary. michael@0: * michael@0: * @param ut the text to be accessed. michael@0: * @return the current index position, in the native units of the text provider. michael@0: * @stable ICU 3.4 michael@0: */ michael@0: U_STABLE int64_t U_EXPORT2 michael@0: utext_getNativeIndex(const UText *ut); michael@0: michael@0: /** michael@0: * Set the current iteration position to the nearest code point michael@0: * boundary at or preceding the specified index. michael@0: * The index is in the native units of the original input text. michael@0: * If the index is out of range, it will be pinned to be within michael@0: * the range of the input text. michael@0: *
michael@0: * It will usually be more efficient to begin an iteration michael@0: * using the functions utext_next32From() or utext_previous32From() michael@0: * rather than setIndex(). michael@0: *
michael@0: * Moving the index position to an adjacent character is best done michael@0: * with utext_next32(), utext_previous32() or utext_moveIndex32(). michael@0: * Attempting to do direct arithmetic on the index position is michael@0: * complicated by the fact that the size (in native units) of a michael@0: * character depends on the underlying representation of the character michael@0: * (UTF-8, UTF-16, UTF-32, arbitrary codepage), and is not michael@0: * easily knowable. michael@0: * michael@0: * @param ut the text to be accessed. michael@0: * @param nativeIndex the native unit index of the new iteration position. michael@0: * @stable ICU 3.4 michael@0: */ michael@0: U_STABLE void U_EXPORT2 michael@0: utext_setNativeIndex(UText *ut, int64_t nativeIndex); michael@0: michael@0: /** michael@0: * Move the iterator postion by delta code points. The number of code points michael@0: * is a signed number; a negative delta will move the iterator backwards, michael@0: * towards the start of the text. michael@0: *
michael@0: * The index is moved by delta code points
michael@0: * forward or backward, but no further backward than to 0 and
michael@0: * no further forward than to utext_nativeLength().
michael@0: * The resulting index value will be in between 0 and length, inclusive.
michael@0: *
michael@0: * @param ut the text to be accessed.
michael@0: * @param delta the signed number of code points to move the iteration position.
michael@0: * @return TRUE if the position could be moved the requested number of positions while
michael@0: * staying within the range [0 - text length].
michael@0: * @stable ICU 3.4
michael@0: */
michael@0: U_STABLE UBool U_EXPORT2
michael@0: utext_moveIndex32(UText *ut, int32_t delta);
michael@0:
michael@0: /**
michael@0: * Get the native index of the character preceeding the current position.
michael@0: * If the iteration position is already at the start of the text, zero
michael@0: * is returned.
michael@0: * The value returned is the same as that obtained from the following sequence,
michael@0: * but without the side effect of changing the iteration position.
michael@0: *
michael@0: * \code
michael@0: * UText *ut = whatever;
michael@0: * ...
michael@0: * utext_previous(ut)
michael@0: * utext_getNativeIndex(ut);
michael@0: * \endcode
michael@0: *
michael@0: * This function is most useful during forwards iteration, where it will get the
michael@0: * native index of the character most recently returned from utext_next().
michael@0: *
michael@0: * @param ut the text to be accessed
michael@0: * @return the native index of the character preceeding the current index position,
michael@0: * or zero if the current position is at the start of the text.
michael@0: * @stable ICU 3.6
michael@0: */
michael@0: U_STABLE int64_t U_EXPORT2
michael@0: utext_getPreviousNativeIndex(UText *ut);
michael@0:
michael@0:
michael@0: /**
michael@0: *
michael@0: * Extract text from a UText into a UChar buffer. The range of text to be extracted
michael@0: * is specified in the native indices of the UText provider. These may not necessarily
michael@0: * be UTF-16 indices.
michael@0: *
michael@0: * The size (number of 16 bit UChars) of the data to be extracted is returned. The michael@0: * full number of UChars is returned, even when the extracted text is truncated michael@0: * because the specified buffer size is too small. michael@0: *
michael@0: * The extracted string will (if you are a user) / must (if you are a text provider) michael@0: * be NUL-terminated if there is sufficient space in the destination buffer. This michael@0: * terminating NUL is not included in the returned length. michael@0: *
michael@0: * The iteration index is left at the position following the last extracted character. michael@0: * michael@0: * @param ut the UText from which to extract data. michael@0: * @param nativeStart the native index of the first character to extract.\ michael@0: * If the specified index is out of range, michael@0: * it will be pinned to to be within 0 <= index <= textLength michael@0: * @param nativeLimit the native string index of the position following the last michael@0: * character to extract. If the specified index is out of range, michael@0: * it will be pinned to to be within 0 <= index <= textLength. michael@0: * nativeLimit must be >= nativeStart. michael@0: * @param dest the UChar (UTF-16) buffer into which the extracted text is placed michael@0: * @param destCapacity The size, in UChars, of the destination buffer. May be zero michael@0: * for precomputing the required size. michael@0: * @param status receives any error status. michael@0: * U_BUFFER_OVERFLOW_ERROR: the extracted text was truncated because the michael@0: * buffer was too small. Returns number of UChars for preflighting. michael@0: * @return Number of UChars in the data to be extracted. Does not include a trailing NUL. michael@0: * michael@0: * @stable ICU 3.4 michael@0: */ michael@0: U_STABLE int32_t U_EXPORT2 michael@0: utext_extract(UText *ut, michael@0: int64_t nativeStart, int64_t nativeLimit, michael@0: UChar *dest, int32_t destCapacity, michael@0: UErrorCode *status); michael@0: michael@0: michael@0: michael@0: /************************************************************************************ michael@0: * michael@0: * #define inline versions of selected performance-critical text access functions michael@0: * Caution: do not use auto increment++ or decrement-- expressions michael@0: * as parameters to these macros. michael@0: * michael@0: * For most use, where there is no extreme performance constraint, the michael@0: * normal, non-inline functions are a better choice. The resulting code michael@0: * will be smaller, and, if the need ever arises, easier to debug. michael@0: * michael@0: * These are implemented as #defines rather than real functions michael@0: * because there is no fully portable way to do inline functions in plain C. michael@0: * michael@0: ************************************************************************************/ michael@0: michael@0: #ifndef U_HIDE_INTERNAL_API michael@0: /** michael@0: * inline version of utext_current32(), for performance-critical situations. michael@0: * michael@0: * Get the code point at the current iteration position of the UText. michael@0: * Returns U_SENTINEL (-1) if the position is at the end of the michael@0: * text. michael@0: * michael@0: * @internal ICU 4.4 technology preview michael@0: */ michael@0: #define UTEXT_CURRENT32(ut) \ michael@0: ((ut)->chunkOffset < (ut)->chunkLength && ((ut)->chunkContents)[(ut)->chunkOffset]<0xd800 ? \ michael@0: ((ut)->chunkContents)[((ut)->chunkOffset)] : utext_current32(ut)) michael@0: #endif /* U_HIDE_INTERNAL_API */ michael@0: michael@0: /** michael@0: * inline version of utext_next32(), for performance-critical situations. michael@0: * michael@0: * Get the code point at the current iteration position of the UText, and michael@0: * advance the position to the first index following the character. michael@0: * This is a post-increment operation. michael@0: * Returns U_SENTINEL (-1) if the position is at the end of the michael@0: * text. michael@0: * michael@0: * @stable ICU 3.4 michael@0: */ michael@0: #define UTEXT_NEXT32(ut) \ michael@0: ((ut)->chunkOffset < (ut)->chunkLength && ((ut)->chunkContents)[(ut)->chunkOffset]<0xd800 ? \ michael@0: ((ut)->chunkContents)[((ut)->chunkOffset)++] : utext_next32(ut)) michael@0: michael@0: /** michael@0: * inline version of utext_previous32(), for performance-critical situations. michael@0: * michael@0: * Move the iterator position to the character (code point) whose michael@0: * index precedes the current position, and return that character. michael@0: * This is a pre-decrement operation. michael@0: * Returns U_SENTINEL (-1) if the position is at the start of the text. michael@0: * michael@0: * @stable ICU 3.4 michael@0: */ michael@0: #define UTEXT_PREVIOUS32(ut) \ michael@0: ((ut)->chunkOffset > 0 && \ michael@0: (ut)->chunkContents[(ut)->chunkOffset-1] < 0xd800 ? \ michael@0: (ut)->chunkContents[--((ut)->chunkOffset)] : utext_previous32(ut)) michael@0: michael@0: /** michael@0: * inline version of utext_getNativeIndex(), for performance-critical situations. michael@0: * michael@0: * Get the current iterator position, which can range from 0 to michael@0: * the length of the text. michael@0: * The position is a native index into the input text, in whatever format it michael@0: * may have (possibly UTF-8 for example), and may not always be the same as michael@0: * the corresponding UChar (UTF-16) index. michael@0: * The returned position will always be aligned to a code point boundary. michael@0: * michael@0: * @stable ICU 3.6 michael@0: */ michael@0: #define UTEXT_GETNATIVEINDEX(ut) \ michael@0: ((ut)->chunkOffset <= (ut)->nativeIndexingLimit? \ michael@0: (ut)->chunkNativeStart+(ut)->chunkOffset : \ michael@0: (ut)->pFuncs->mapOffsetToNative(ut)) michael@0: michael@0: /** michael@0: * inline version of utext_setNativeIndex(), for performance-critical situations. michael@0: * michael@0: * Set the current iteration position to the nearest code point michael@0: * boundary at or preceding the specified index. michael@0: * The index is in the native units of the original input text. michael@0: * If the index is out of range, it will be pinned to be within michael@0: * the range of the input text. michael@0: * michael@0: * @stable ICU 3.8 michael@0: */ michael@0: #define UTEXT_SETNATIVEINDEX(ut, ix) \ michael@0: { int64_t __offset = (ix) - (ut)->chunkNativeStart; \ michael@0: if (__offset>=0 && __offset<=(int64_t)(ut)->nativeIndexingLimit) { \ michael@0: (ut)->chunkOffset=(int32_t)__offset; \ michael@0: } else { \ michael@0: utext_setNativeIndex((ut), (ix)); } } michael@0: michael@0: michael@0: michael@0: /************************************************************************************ michael@0: * michael@0: * Functions related to writing or modifying the text. michael@0: * These will work only with modifiable UTexts. Attempting to michael@0: * modify a read-only UText will return an error status. michael@0: * michael@0: ************************************************************************************/ michael@0: michael@0: michael@0: /** michael@0: * Return TRUE if the text can be written (modified) with utext_replace() or michael@0: * utext_copy(). For the text to be writable, the text provider must michael@0: * be of a type that supports writing and the UText must not be frozen. michael@0: * michael@0: * Attempting to modify text when utext_isWriteable() is FALSE will fail - michael@0: * the text will not be modified, and an error will be returned from the function michael@0: * that attempted the modification. michael@0: * michael@0: * @param ut the UText to be tested. michael@0: * @return TRUE if the text is modifiable. michael@0: * michael@0: * @see utext_freeze() michael@0: * @see utext_replace() michael@0: * @see utext_copy() michael@0: * @stable ICU 3.4 michael@0: * michael@0: */ michael@0: U_STABLE UBool U_EXPORT2 michael@0: utext_isWritable(const UText *ut); michael@0: michael@0: michael@0: /** michael@0: * Test whether there is meta data associated with the text. michael@0: * @see Replaceable::hasMetaData() michael@0: * michael@0: * @param ut The UText to be tested michael@0: * @return TRUE if the underlying text includes meta data. michael@0: * @stable ICU 3.4 michael@0: */ michael@0: U_STABLE UBool U_EXPORT2 michael@0: utext_hasMetaData(const UText *ut); michael@0: michael@0: michael@0: /** michael@0: * Replace a range of the original text with a replacement text. michael@0: * michael@0: * Leaves the current iteration position at the position following the michael@0: * newly inserted replacement text. michael@0: * michael@0: * This function is only available on UText types that support writing, michael@0: * that is, ones where utext_isWritable() returns TRUE. michael@0: * michael@0: * When using this function, there should be only a single UText opened onto the michael@0: * underlying native text string. Behavior after a replace operation michael@0: * on a UText is undefined for any other additional UTexts that refer to the michael@0: * modified string. michael@0: * michael@0: * @param ut the UText representing the text to be operated on. michael@0: * @param nativeStart the native index of the start of the region to be replaced michael@0: * @param nativeLimit the native index of the character following the region to be replaced. michael@0: * @param replacementText pointer to the replacement text michael@0: * @param replacementLength length of the replacement text, or -1 if the text is NUL terminated. michael@0: * @param status receives any error status. Possible errors include michael@0: * U_NO_WRITE_PERMISSION michael@0: * michael@0: * @return The signed number of (native) storage units by which michael@0: * the length of the text expanded or contracted. michael@0: * michael@0: * @stable ICU 3.4 michael@0: */ michael@0: U_STABLE int32_t U_EXPORT2 michael@0: utext_replace(UText *ut, michael@0: int64_t nativeStart, int64_t nativeLimit, michael@0: const UChar *replacementText, int32_t replacementLength, michael@0: UErrorCode *status); michael@0: michael@0: michael@0: michael@0: /** michael@0: * michael@0: * Copy or move a substring from one position to another within the text, michael@0: * while retaining any metadata associated with the text. michael@0: * This function is used to duplicate or reorder substrings. michael@0: * The destination index must not overlap the source range. michael@0: * michael@0: * The text to be copied or moved is inserted at destIndex; michael@0: * it does not replace or overwrite any existing text. michael@0: * michael@0: * The iteration position is left following the newly inserted text michael@0: * at the destination position. michael@0: * michael@0: * This function is only available on UText types that support writing, michael@0: * that is, ones where utext_isWritable() returns TRUE. michael@0: * michael@0: * When using this function, there should be only a single UText opened onto the michael@0: * underlying native text string. Behavior after a copy operation michael@0: * on a UText is undefined in any other additional UTexts that refer to the michael@0: * modified string. michael@0: * michael@0: * @param ut The UText representing the text to be operated on. michael@0: * @param nativeStart The native index of the start of the region to be copied or moved michael@0: * @param nativeLimit The native index of the character position following the region michael@0: * to be copied. michael@0: * @param destIndex The native destination index to which the source substring is michael@0: * copied or moved. michael@0: * @param move If TRUE, then the substring is moved, not copied/duplicated. michael@0: * @param status receives any error status. Possible errors include U_NO_WRITE_PERMISSION michael@0: * michael@0: * @stable ICU 3.4 michael@0: */ michael@0: U_STABLE void U_EXPORT2 michael@0: utext_copy(UText *ut, michael@0: int64_t nativeStart, int64_t nativeLimit, michael@0: int64_t destIndex, michael@0: UBool move, michael@0: UErrorCode *status); michael@0: michael@0: michael@0: /** michael@0: *
michael@0: * Freeze a UText. This prevents any modification to the underlying text itself michael@0: * by means of functions operating on this UText. michael@0: *
michael@0: *michael@0: * Once frozen, a UText can not be unfrozen. The intent is to ensure michael@0: * that a the text underlying a frozen UText wrapper cannot be modified via that UText. michael@0: *
michael@0: *michael@0: * Caution: freezing a UText will disable changes made via the specific michael@0: * frozen UText wrapper only; it will not have any effect on the ability to michael@0: * directly modify the text by bypassing the UText. Any such backdoor modifications michael@0: * are always an error while UText access is occuring because the underlying michael@0: * text can get out of sync with UText's buffering. michael@0: *
michael@0: * michael@0: * @param ut The UText to be frozen. michael@0: * @see utext_isWritable() michael@0: * @stable ICU 3.6 michael@0: */ michael@0: U_STABLE void U_EXPORT2 michael@0: utext_freeze(UText *ut); michael@0: michael@0: michael@0: /** michael@0: * UText provider properties (bit field indexes). michael@0: * michael@0: * @see UText michael@0: * @stable ICU 3.4 michael@0: */ michael@0: enum { michael@0: /** michael@0: * It is potentially time consuming for the provider to determine the length of the text. michael@0: * @stable ICU 3.4 michael@0: */ michael@0: UTEXT_PROVIDER_LENGTH_IS_EXPENSIVE = 1, michael@0: /** michael@0: * Text chunks remain valid and usable until the text object is modified or michael@0: * deleted, not just until the next time the access() function is called michael@0: * (which is the default). michael@0: * @stable ICU 3.4 michael@0: */ michael@0: UTEXT_PROVIDER_STABLE_CHUNKS = 2, michael@0: /** michael@0: * The provider supports modifying the text via the replace() and copy() michael@0: * functions. michael@0: * @see Replaceable michael@0: * @stable ICU 3.4 michael@0: */ michael@0: UTEXT_PROVIDER_WRITABLE = 3, michael@0: /** michael@0: * There is meta data associated with the text. michael@0: * @see Replaceable::hasMetaData() michael@0: * @stable ICU 3.4 michael@0: */ michael@0: UTEXT_PROVIDER_HAS_META_DATA = 4, michael@0: /** michael@0: * Text provider owns the text storage. michael@0: * Generally occurs as the result of a deep clone of the UText. michael@0: * When closing the UText, the associated text must michael@0: * also be closed/deleted/freed/ whatever is appropriate. michael@0: * @stable ICU 3.6 michael@0: */ michael@0: UTEXT_PROVIDER_OWNS_TEXT = 5 michael@0: }; michael@0: michael@0: /** michael@0: * Function type declaration for UText.clone(). michael@0: * michael@0: * clone a UText. Much like opening a UText where the source text is itself michael@0: * another UText. michael@0: * michael@0: * A deep clone will copy both the UText data structures and the underlying text. michael@0: * The original and cloned UText will operate completely independently; modifications michael@0: * made to the text in one will not effect the other. Text providers are not michael@0: * required to support deep clones. The user of clone() must check the status return michael@0: * and be prepared to handle failures. michael@0: * michael@0: * A shallow clone replicates only the UText data structures; it does not make michael@0: * a copy of the underlying text. Shallow clones can be used as an efficient way to michael@0: * have multiple iterators active in a single text string that is not being michael@0: * modified. michael@0: * michael@0: * A shallow clone operation must not fail except for truly exceptional conditions such michael@0: * as memory allocation failures. michael@0: * michael@0: * A UText and its clone may be safely concurrently accessed by separate threads. michael@0: * This is true for both shallow and deep clones. michael@0: * It is the responsibility of the Text Provider to ensure that this thread safety michael@0: * constraint is met. michael@0: michael@0: * michael@0: * @param dest A UText struct to be filled in with the result of the clone operation, michael@0: * or NULL if the clone function should heap-allocate a new UText struct. michael@0: * @param src The UText to be cloned. michael@0: * @param deep TRUE to request a deep clone, FALSE for a shallow clone. michael@0: * @param status Errors are returned here. For deep clones, U_UNSUPPORTED_ERROR michael@0: * should be returned if the text provider is unable to clone the michael@0: * original text. michael@0: * @return The newly created clone, or NULL if the clone operation failed. michael@0: * michael@0: * @stable ICU 3.4 michael@0: */ michael@0: typedef UText * U_CALLCONV michael@0: UTextClone(UText *dest, const UText *src, UBool deep, UErrorCode *status); michael@0: michael@0: michael@0: /** michael@0: * Function type declaration for UText.nativeLength(). michael@0: * michael@0: * @param ut the UText to get the length of. michael@0: * @return the length, in the native units of the original text string. michael@0: * @see UText michael@0: * @stable ICU 3.4 michael@0: */ michael@0: typedef int64_t U_CALLCONV michael@0: UTextNativeLength(UText *ut); michael@0: michael@0: /** michael@0: * Function type declaration for UText.access(). Get the description of the text chunk michael@0: * containing the text at a requested native index. The UText's iteration michael@0: * position will be left at the requested index. If the index is out michael@0: * of bounds, the iteration position will be left at the start or end michael@0: * of the string, as appropriate. michael@0: * michael@0: * Chunks must begin and end on code point boundaries. A single code point michael@0: * comprised of multiple storage units must never span a chunk boundary. michael@0: * michael@0: * michael@0: * @param ut the UText being accessed. michael@0: * @param nativeIndex Requested index of the text to be accessed. michael@0: * @param forward If TRUE, then the returned chunk must contain text michael@0: * starting from the index, so that start<=indexmichael@0: * The extracted string will (if you are a user) / must (if you are a text provider) michael@0: * be NUL-terminated if there is sufficient space in the destination buffer. michael@0: * michael@0: * @param ut the UText from which to extract data. michael@0: * @param nativeStart the native index of the first characer to extract. michael@0: * @param nativeLimit the native string index of the position following the last michael@0: * character to extract. michael@0: * @param dest the UChar (UTF-16) buffer into which the extracted text is placed michael@0: * @param destCapacity The size, in UChars, of the destination buffer. May be zero michael@0: * for precomputing the required size. michael@0: * @param status receives any error status. michael@0: * If U_BUFFER_OVERFLOW_ERROR: Returns number of UChars for michael@0: * preflighting. michael@0: * @return Number of UChars in the data. Does not include a trailing NUL. michael@0: * michael@0: * @stable ICU 3.4 michael@0: */ michael@0: typedef int32_t U_CALLCONV michael@0: UTextExtract(UText *ut, michael@0: int64_t nativeStart, int64_t nativeLimit, michael@0: UChar *dest, int32_t destCapacity, michael@0: UErrorCode *status); michael@0: michael@0: /** michael@0: * Function type declaration for UText.replace(). michael@0: * michael@0: * Replace a range of the original text with a replacement text. michael@0: * michael@0: * Leaves the current iteration position at the position following the michael@0: * newly inserted replacement text. michael@0: * michael@0: * This function need only be implemented on UText types that support writing. michael@0: * michael@0: * When using this function, there should be only a single UText opened onto the michael@0: * underlying native text string. The function is responsible for updating the michael@0: * text chunk within the UText to reflect the updated iteration position, michael@0: * taking into account any changes to the underlying string's structure caused michael@0: * by the replace operation. michael@0: * michael@0: * @param ut the UText representing the text to be operated on. michael@0: * @param nativeStart the index of the start of the region to be replaced michael@0: * @param nativeLimit the index of the character following the region to be replaced. michael@0: * @param replacementText pointer to the replacement text michael@0: * @param replacmentLength length of the replacement text in UChars, or -1 if the text is NUL terminated. michael@0: * @param status receives any error status. Possible errors include michael@0: * U_NO_WRITE_PERMISSION michael@0: * michael@0: * @return The signed number of (native) storage units by which michael@0: * the length of the text expanded or contracted. michael@0: * michael@0: * @stable ICU 3.4 michael@0: */ michael@0: typedef int32_t U_CALLCONV michael@0: UTextReplace(UText *ut, michael@0: int64_t nativeStart, int64_t nativeLimit, michael@0: const UChar *replacementText, int32_t replacmentLength, michael@0: UErrorCode *status); michael@0: michael@0: /** michael@0: * Function type declaration for UText.copy(). michael@0: * michael@0: * Copy or move a substring from one position to another within the text, michael@0: * while retaining any metadata associated with the text. michael@0: * This function is used to duplicate or reorder substrings. michael@0: * The destination index must not overlap the source range. michael@0: * michael@0: * The text to be copied or moved is inserted at destIndex; michael@0: * it does not replace or overwrite any existing text. michael@0: * michael@0: * This function need only be implemented for UText types that support writing. michael@0: * michael@0: * When using this function, there should be only a single UText opened onto the michael@0: * underlying native text string. The function is responsible for updating the michael@0: * text chunk within the UText to reflect the updated iteration position, michael@0: * taking into account any changes to the underlying string's structure caused michael@0: * by the replace operation. michael@0: * michael@0: * @param ut The UText representing the text to be operated on. michael@0: * @param nativeStart The index of the start of the region to be copied or moved michael@0: * @param nativeLimit The index of the character following the region to be replaced. michael@0: * @param nativeDest The destination index to which the source substring is copied or moved. michael@0: * @param move If TRUE, then the substring is moved, not copied/duplicated. michael@0: * @param status receives any error status. Possible errors include U_NO_WRITE_PERMISSION michael@0: * michael@0: * @stable ICU 3.4 michael@0: */ michael@0: typedef void U_CALLCONV michael@0: UTextCopy(UText *ut, michael@0: int64_t nativeStart, int64_t nativeLimit, michael@0: int64_t nativeDest, michael@0: UBool move, michael@0: UErrorCode *status); michael@0: michael@0: /** michael@0: * Function type declaration for UText.mapOffsetToNative(). michael@0: * Map from the current UChar offset within the current text chunk to michael@0: * the corresponding native index in the original source text. michael@0: * michael@0: * This is required only for text providers that do not use native UTF-16 indexes. michael@0: * michael@0: * @param ut the UText. michael@0: * @return Absolute (native) index corresponding to chunkOffset in the current chunk. michael@0: * The returned native index should always be to a code point boundary. michael@0: * michael@0: * @stable ICU 3.4 michael@0: */ michael@0: typedef int64_t U_CALLCONV michael@0: UTextMapOffsetToNative(const UText *ut); michael@0: michael@0: /** michael@0: * Function type declaration for UText.mapIndexToUTF16(). michael@0: * Map from a native index to a UChar offset within a text chunk. michael@0: * Behavior is undefined if the native index does not fall within the michael@0: * current chunk. michael@0: * michael@0: * This function is required only for text providers that do not use native UTF-16 indexes. michael@0: * michael@0: * @param ut The UText containing the text chunk. michael@0: * @param nativeIndex Absolute (native) text index, chunk->start<=index<=chunk->limit. michael@0: * @return Chunk-relative UTF-16 offset corresponding to the specified native michael@0: * index. michael@0: * michael@0: * @stable ICU 3.4 michael@0: */ michael@0: typedef int32_t U_CALLCONV michael@0: UTextMapNativeIndexToUTF16(const UText *ut, int64_t nativeIndex); michael@0: michael@0: michael@0: /** michael@0: * Function type declaration for UText.utextClose(). michael@0: * michael@0: * A Text Provider close function is only required for provider types that make michael@0: * allocations in their open function (or other functions) that must be michael@0: * cleaned when the UText is closed. michael@0: * michael@0: * The allocation of the UText struct itself and any "extra" storage michael@0: * associated with the UText is handled by the common UText implementation michael@0: * and does not require provider specific cleanup in a close function. michael@0: * michael@0: * Most UText provider implementations do not need to implement this function. michael@0: * michael@0: * @param ut A UText object to be closed. michael@0: * michael@0: * @stable ICU 3.4 michael@0: */ michael@0: typedef void U_CALLCONV michael@0: UTextClose(UText *ut); michael@0: michael@0: michael@0: /** michael@0: * (public) Function dispatch table for UText. michael@0: * Conceptually very much like a C++ Virtual Function Table. michael@0: * This struct defines the organization of the table. michael@0: * Each text provider implementation must provide an michael@0: * actual table that is initialized with the appropriate functions michael@0: * for the type of text being handled. michael@0: * @stable ICU 3.6 michael@0: */ michael@0: struct UTextFuncs { michael@0: /** michael@0: * (public) Function table size, sizeof(UTextFuncs) michael@0: * Intended for use should the table grow to accomodate added michael@0: * functions in the future, to allow tests for older format michael@0: * function tables that do not contain the extensions. michael@0: * michael@0: * Fields are placed for optimal alignment on michael@0: * 32/64/128-bit-pointer machines, by normally grouping together michael@0: * 4 32-bit fields, michael@0: * 4 pointers, michael@0: * 2 64-bit fields michael@0: * in sequence. michael@0: * @stable ICU 3.6 michael@0: */ michael@0: int32_t tableSize; michael@0: michael@0: /** michael@0: * (private) Alignment padding. michael@0: * Do not use, reserved for use by the UText framework only. michael@0: * @internal michael@0: */ michael@0: int32_t reserved1, /** @internal */ reserved2, /** @internal */ reserved3; michael@0: michael@0: michael@0: /** michael@0: * (public) Function pointer for UTextClone michael@0: * michael@0: * @see UTextClone michael@0: * @stable ICU 3.6 michael@0: */ michael@0: UTextClone *clone; michael@0: michael@0: /** michael@0: * (public) function pointer for UTextLength michael@0: * May be expensive to compute! michael@0: * michael@0: * @see UTextLength michael@0: * @stable ICU 3.6 michael@0: */ michael@0: UTextNativeLength *nativeLength; michael@0: michael@0: /** michael@0: * (public) Function pointer for UTextAccess. michael@0: * michael@0: * @see UTextAccess michael@0: * @stable ICU 3.6 michael@0: */ michael@0: UTextAccess *access; michael@0: michael@0: /** michael@0: * (public) Function pointer for UTextExtract. michael@0: * michael@0: * @see UTextExtract michael@0: * @stable ICU 3.6 michael@0: */ michael@0: UTextExtract *extract; michael@0: michael@0: /** michael@0: * (public) Function pointer for UTextReplace. michael@0: * michael@0: * @see UTextReplace michael@0: * @stable ICU 3.6 michael@0: */ michael@0: UTextReplace *replace; michael@0: michael@0: /** michael@0: * (public) Function pointer for UTextCopy. michael@0: * michael@0: * @see UTextCopy michael@0: * @stable ICU 3.6 michael@0: */ michael@0: UTextCopy *copy; michael@0: michael@0: /** michael@0: * (public) Function pointer for UTextMapOffsetToNative. michael@0: * michael@0: * @see UTextMapOffsetToNative michael@0: * @stable ICU 3.6 michael@0: */ michael@0: UTextMapOffsetToNative *mapOffsetToNative; michael@0: michael@0: /** michael@0: * (public) Function pointer for UTextMapNativeIndexToUTF16. michael@0: * michael@0: * @see UTextMapNativeIndexToUTF16 michael@0: * @stable ICU 3.6 michael@0: */ michael@0: UTextMapNativeIndexToUTF16 *mapNativeIndexToUTF16; michael@0: michael@0: /** michael@0: * (public) Function pointer for UTextClose. michael@0: * michael@0: * @see UTextClose michael@0: * @stable ICU 3.6 michael@0: */ michael@0: UTextClose *close; michael@0: michael@0: /** michael@0: * (private) Spare function pointer michael@0: * @internal michael@0: */ michael@0: UTextClose *spare1; michael@0: michael@0: /** michael@0: * (private) Spare function pointer michael@0: * @internal michael@0: */ michael@0: UTextClose *spare2; michael@0: michael@0: /** michael@0: * (private) Spare function pointer michael@0: * @internal michael@0: */ michael@0: UTextClose *spare3; michael@0: michael@0: }; michael@0: /** michael@0: * Function dispatch table for UText michael@0: * @see UTextFuncs michael@0: */ michael@0: typedef struct UTextFuncs UTextFuncs; michael@0: michael@0: /** michael@0: * UText struct. Provides the interface between the generic UText access code michael@0: * and the UText provider code that works on specific kinds of michael@0: * text (UTF-8, noncontiguous UTF-16, whatever.) michael@0: * michael@0: * Applications that are using predefined types of text providers michael@0: * to pass text data to ICU services will have no need to view the michael@0: * internals of the UText structs that they open. michael@0: * michael@0: * @stable ICU 3.6 michael@0: */ michael@0: struct UText { michael@0: /** michael@0: * (private) Magic. Used to help detect when UText functions are handed michael@0: * invalid or unitialized UText structs. michael@0: * utext_openXYZ() functions take an initialized, michael@0: * but not necessarily open, UText struct as an michael@0: * optional fill-in parameter. This magic field michael@0: * is used to check for that initialization. michael@0: * Text provider close functions must NOT clear michael@0: * the magic field because that would prevent michael@0: * reuse of the UText struct. michael@0: * @internal michael@0: */ michael@0: uint32_t magic; michael@0: michael@0: michael@0: /** michael@0: * (private) Flags for managing the allocation and freeing of michael@0: * memory associated with this UText. michael@0: * @internal michael@0: */ michael@0: int32_t flags; michael@0: michael@0: michael@0: /** michael@0: * Text provider properties. This set of flags is maintainted by the michael@0: * text provider implementation. michael@0: * @stable ICU 3.4 michael@0: */ michael@0: int32_t providerProperties; michael@0: michael@0: /** michael@0: * (public) sizeOfStruct=sizeof(UText) michael@0: * Allows possible backward compatible extension. michael@0: * michael@0: * @stable ICU 3.4 michael@0: */ michael@0: int32_t sizeOfStruct; michael@0: michael@0: /* ------ 16 byte alignment boundary ----------- */ michael@0: michael@0: michael@0: /** michael@0: * (protected) Native index of the first character position following michael@0: * the current chunk. michael@0: * @stable ICU 3.6 michael@0: */ michael@0: int64_t chunkNativeLimit; michael@0: michael@0: /** michael@0: * (protected) Size in bytes of the extra space (pExtra). michael@0: * @stable ICU 3.4 michael@0: */ michael@0: int32_t extraSize; michael@0: michael@0: /** michael@0: * (protected) The highest chunk offset where native indexing and michael@0: * chunk (UTF-16) indexing correspond. For UTF-16 sources, value michael@0: * will be equal to chunkLength. michael@0: * michael@0: * @stable ICU 3.6 michael@0: */ michael@0: int32_t nativeIndexingLimit; michael@0: michael@0: /* ---- 16 byte alignment boundary------ */ michael@0: michael@0: /** michael@0: * (protected) Native index of the first character in the text chunk. michael@0: * @stable ICU 3.6 michael@0: */ michael@0: int64_t chunkNativeStart; michael@0: michael@0: /** michael@0: * (protected) Current iteration position within the text chunk (UTF-16 buffer). michael@0: * This is the index to the character that will be returned by utext_next32(). michael@0: * @stable ICU 3.6 michael@0: */ michael@0: int32_t chunkOffset; michael@0: michael@0: /** michael@0: * (protected) Length the text chunk (UTF-16 buffer), in UChars. michael@0: * @stable ICU 3.6 michael@0: */ michael@0: int32_t chunkLength; michael@0: michael@0: /* ---- 16 byte alignment boundary-- */ michael@0: michael@0: michael@0: /** michael@0: * (protected) pointer to a chunk of text in UTF-16 format. michael@0: * May refer either to original storage of the source of the text, or michael@0: * if conversion was required, to a buffer owned by the UText. michael@0: * @stable ICU 3.6 michael@0: */ michael@0: const UChar *chunkContents; michael@0: michael@0: /** michael@0: * (public) Pointer to Dispatch table for accessing functions for this UText. michael@0: * @stable ICU 3.6 michael@0: */ michael@0: const UTextFuncs *pFuncs; michael@0: michael@0: /** michael@0: * (protected) Pointer to additional space requested by the michael@0: * text provider during the utext_open operation. michael@0: * @stable ICU 3.4 michael@0: */ michael@0: void *pExtra; michael@0: michael@0: /** michael@0: * (protected) Pointer to string or text-containin object or similar. michael@0: * This is the source of the text that this UText is wrapping, in a format michael@0: * that is known to the text provider functions. michael@0: * @stable ICU 3.4 michael@0: */ michael@0: const void *context; michael@0: michael@0: /* --- 16 byte alignment boundary--- */ michael@0: michael@0: /** michael@0: * (protected) Pointer fields available for use by the text provider. michael@0: * Not used by UText common code. michael@0: * @stable ICU 3.6 michael@0: */ michael@0: const void *p; michael@0: /** michael@0: * (protected) Pointer fields available for use by the text provider. michael@0: * Not used by UText common code. michael@0: * @stable ICU 3.6 michael@0: */ michael@0: const void *q; michael@0: /** michael@0: * (protected) Pointer fields available for use by the text provider. michael@0: * Not used by UText common code. michael@0: * @stable ICU 3.6 michael@0: */ michael@0: const void *r; michael@0: michael@0: /** michael@0: * Private field reserved for future use by the UText framework michael@0: * itself. This is not to be touched by the text providers. michael@0: * @internal ICU 3.4 michael@0: */ michael@0: void *privP; michael@0: michael@0: michael@0: /* --- 16 byte alignment boundary--- */ michael@0: michael@0: michael@0: /** michael@0: * (protected) Integer field reserved for use by the text provider. michael@0: * Not used by the UText framework, or by the client (user) of the UText. michael@0: * @stable ICU 3.4 michael@0: */ michael@0: int64_t a; michael@0: michael@0: /** michael@0: * (protected) Integer field reserved for use by the text provider. michael@0: * Not used by the UText framework, or by the client (user) of the UText. michael@0: * @stable ICU 3.4 michael@0: */ michael@0: int32_t b; michael@0: michael@0: /** michael@0: * (protected) Integer field reserved for use by the text provider. michael@0: * Not used by the UText framework, or by the client (user) of the UText. michael@0: * @stable ICU 3.4 michael@0: */ michael@0: int32_t c; michael@0: michael@0: /* ---- 16 byte alignment boundary---- */ michael@0: michael@0: michael@0: /** michael@0: * Private field reserved for future use by the UText framework michael@0: * itself. This is not to be touched by the text providers. michael@0: * @internal ICU 3.4 michael@0: */ michael@0: int64_t privA; michael@0: /** michael@0: * Private field reserved for future use by the UText framework michael@0: * itself. This is not to be touched by the text providers. michael@0: * @internal ICU 3.4 michael@0: */ michael@0: int32_t privB; michael@0: /** michael@0: * Private field reserved for future use by the UText framework michael@0: * itself. This is not to be touched by the text providers. michael@0: * @internal ICU 3.4 michael@0: */ michael@0: int32_t privC; michael@0: }; michael@0: michael@0: michael@0: /** michael@0: * Common function for use by Text Provider implementations to allocate and/or initialize michael@0: * a new UText struct. To be called in the implementation of utext_open() functions. michael@0: * If the supplied UText parameter is null, a new UText struct will be allocated on the heap. michael@0: * If the supplied UText is already open, the provider's close function will be called michael@0: * so that the struct can be reused by the open that is in progress. michael@0: * michael@0: * @param ut pointer to a UText struct to be re-used, or null if a new UText michael@0: * should be allocated. michael@0: * @param extraSpace The amount of additional space to be allocated as part michael@0: * of this UText, for use by types of providers that require michael@0: * additional storage. michael@0: * @param status Errors are returned here. michael@0: * @return pointer to the UText, allocated if necessary, with extra space set up if requested. michael@0: * @stable ICU 3.4 michael@0: */ michael@0: U_STABLE UText * U_EXPORT2 michael@0: utext_setup(UText *ut, int32_t extraSpace, UErrorCode *status); michael@0: michael@0: #ifndef U_HIDE_INTERNAL_API michael@0: /** michael@0: * @internal michael@0: * Value used to help identify correctly initialized UText structs. michael@0: * Note: must be publicly visible so that UTEXT_INITIALIZER can access it. michael@0: */ michael@0: enum { michael@0: UTEXT_MAGIC = 0x345ad82c michael@0: }; michael@0: #endif /* U_HIDE_INTERNAL_API */ michael@0: michael@0: /** michael@0: * initializer to be used with local (stack) instances of a UText michael@0: * struct. UText structs must be initialized before passing michael@0: * them to one of the utext_open functions. michael@0: * michael@0: * @stable ICU 3.6 michael@0: */ michael@0: #define UTEXT_INITIALIZER { \ michael@0: UTEXT_MAGIC, /* magic */ \ michael@0: 0, /* flags */ \ michael@0: 0, /* providerProps */ \ michael@0: sizeof(UText), /* sizeOfStruct */ \ michael@0: 0, /* chunkNativeLimit */ \ michael@0: 0, /* extraSize */ \ michael@0: 0, /* nativeIndexingLimit */ \ michael@0: 0, /* chunkNativeStart */ \ michael@0: 0, /* chunkOffset */ \ michael@0: 0, /* chunkLength */ \ michael@0: NULL, /* chunkContents */ \ michael@0: NULL, /* pFuncs */ \ michael@0: NULL, /* pExtra */ \ michael@0: NULL, /* context */ \ michael@0: NULL, NULL, NULL, /* p, q, r */ \ michael@0: NULL, /* privP */ \ michael@0: 0, 0, 0, /* a, b, c */ \ michael@0: 0, 0, 0 /* privA,B,C, */ \ michael@0: } michael@0: michael@0: michael@0: U_CDECL_END michael@0: michael@0: michael@0: michael@0: #endif