sl@0: /*
sl@0: *******************************************************************************
sl@0: *
sl@0: * Copyright (C) 2004-2005, International Business Machines
sl@0: * Corporation and others. All Rights Reserved.
sl@0: *
sl@0: *******************************************************************************
sl@0: * file name: utext.h
sl@0: * encoding: US-ASCII
sl@0: * tab size: 8 (not used)
sl@0: * indentation:4
sl@0: *
sl@0: * created on: 2004oct06
sl@0: * created by: Markus W. Scherer
sl@0: */
sl@0:
sl@0: #ifndef __UTEXT_H__
sl@0: #define __UTEXT_H__
sl@0:
sl@0: /**
sl@0: * \file
sl@0: * \brief C API: Abstract Unicode Text API
sl@0: *
sl@0: * The Text Access API provides a means to allow text that is stored in alternative
sl@0: * formats to work with ICU services. ICU normally operates on text that is
sl@0: * stored UTF-16 format, in (UChar *) arrays for the C APIs or as type
sl@0: * UnicodeString for C++ APIs.
sl@0: *
sl@0: * ICU Text Access allows other formats, such as UTF-8 or non-contiguous
sl@0: * UTF-16 strings, to be placed in a UText wrapper and then passed to ICU services.
sl@0: *
sl@0: * There are three general classes of usage for UText:
sl@0: *
sl@0: * Application Level Use. This is the simplest usage - applications would
sl@0: * use one of the utext_open() functions on their input text, and pass
sl@0: * the resulting UText to the desired ICU service.
sl@0: *
sl@0: * Second is usage in ICU Services, such as break iteration, that will need to
sl@0: * operate on input presented to them as a UText. These implementations
sl@0: * will need to use the iteration and related UText functions to gain
sl@0: * access to the actual text.
sl@0: *
sl@0: * The third class of UText users are "text providers." These are the
sl@0: * UText implementations for the various text storage formats. An application
sl@0: * or system with a unique text storage format can implement a set of
sl@0: * UText provider functions for that format, which will then allow
sl@0: * ICU services to operate on that format.
sl@0: *
sl@0: *
sl@0: * Iterating over text
sl@0: *
sl@0: * Here is sample code for a forward iteration over the contents of a UText
sl@0: *
sl@0: * \code
sl@0: * UChar32 c;
sl@0: * UText *ut = whatever();
sl@0: *
sl@0: * for (c=utext_next32From(ut, 0); c>=0; c=utext_next32(ut)) {
sl@0: * // do whatever with the codepoint c here.
sl@0: * }
sl@0: * \endcode
sl@0: *
sl@0: * And here is similar code to iterate in the reverse direction, from the end
sl@0: * of the text towards the beginning.
sl@0: *
sl@0: * \code
sl@0: * UChar32 c;
sl@0: * UText *ut = whatever();
sl@0: * int textLength = utext_nativeLength(ut);
sl@0: * for (c=utext_previous32From(ut, textLength); c>=0; c=utext_previous32(ut)) {
sl@0: * // do whatever with the codepoint c here.
sl@0: * }
sl@0: * \endcode
sl@0: *
sl@0: * Characters and Indexing
sl@0: *
sl@0: * Indexing into text by UText functions is nearly always in terms of the native
sl@0: * indexing of the underlying text storage. The storage format could be UTF-8
sl@0: * or UTF-32, for example. When coding to the UText access API, no assumptions
sl@0: * can be made regarding the size of characters, or how far an index
sl@0: * may move when iterating between characters.
sl@0: *
sl@0: * All indices supplied to UText functions are pinned to the length of the
sl@0: * text. An out-of-bounds index is not considered to be an error, but is
sl@0: * adjusted to be in the range 0 <= index <= length of input text.
sl@0: *
sl@0: *
sl@0: * When an index position is returned from a UText function, it will be
sl@0: * a native index to the underlying text. In the case of multi-unit characters,
sl@0: * it will always refer to the first position of the character,
sl@0: * never to the interior. This is essentially the same thing as saying that
sl@0: * a returned index will always point to a boundary between characters.
sl@0: *
sl@0: * When a native index is supplied to a UText function, all indices that
sl@0: * refer to any part of a multi-unit character representation are considered
sl@0: * to be equivalent. In the case of multi-unit characters, an incoming index
sl@0: * will be logically normalized to refer to the start of the character.
sl@0: *
sl@0: * It is possible to test whether a native index is on a code point boundary
sl@0: * by doing a utext_setNativeIndex() followed by a utext_getNativeIndex().
sl@0: * If the index is returned unchanged, it was on a code point boundary. If
sl@0: * an adjusted index is returned, the original index referred to the
sl@0: * interior of a character.
sl@0: *
sl@0: */
sl@0:
sl@0:
sl@0:
sl@0: #include "unicode/utypes.h"
sl@0: #ifdef XP_CPLUSPLUS
sl@0: #include "unicode/rep.h"
sl@0: #include "unicode/unistr.h"
sl@0: #endif
sl@0:
sl@0: #ifndef U_HIDE_DRAFT_API
sl@0:
sl@0: U_CDECL_BEGIN
sl@0:
sl@0: struct UText;
sl@0: typedef struct UText UText; /**< C typedef for struct UText. @draft ICU 3.4 */
sl@0:
sl@0: struct UTextChunk;
sl@0: typedef struct UTextChunk UTextChunk; /**< C typedef for struct UTextChunk. @draft ICU 3.4 */
sl@0:
sl@0:
sl@0:
sl@0: /***************************************************************************************
sl@0: *
sl@0: * C Functions for creating UText wrappers around various kinds of text strings.
sl@0: *
sl@0: ****************************************************************************************/
sl@0:
sl@0:
sl@0: /**
sl@0: * utext_close Close function for UText instances.
sl@0: * Cleans up, releases any resources being held by an
sl@0: * open UText.
sl@0: *
sl@0: * If the UText was originally allocated by one of the utext_open functions,
sl@0: * the storage associated with the utext will also be freed.
sl@0: * If the UText storage originated with the application, as it would with
sl@0: * a local or static instance, the storage will not be deleted.
sl@0: *
sl@0: * An open UText can be reset to refer to new string by using one of the utext_open()
sl@0: * functions without first closing the UText.
sl@0: *
sl@0: * @param ut The UText to be closed.
sl@0: * @return NULL if the UText struct was deleted by the close. If the UText struct
sl@0: * was originally provided by the caller to the open function, it is
sl@0: * returned by this function, and may be safely used again in
sl@0: * a subsequent utext_open.
sl@0: *
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: U_DRAFT UText * U_EXPORT2
sl@0: utext_close(UText *ut);
sl@0:
sl@0:
sl@0: /**
sl@0: * Open a read-only UText implementation for UTF-8 strings.
sl@0: *
sl@0: * \htmlonly
sl@0: * Any invalid UTF-8 in the input will be handled in this way:
sl@0: * a sequence of bytes that has the form of a truncated, but otherwise valid,
sl@0: * UTF-8 sequence will be replaced by a single unicode replacement character, \uFFFD.
sl@0: * Any other illegal bytes will each be replaced by a \uFFFD.
sl@0: * \endhtmlonly
sl@0: *
sl@0: * @param ut Pointer to a UText struct. If NULL, a new UText will be created.
sl@0: * If non-NULL, must refer to an initialized UText struct, which will then
sl@0: * be reset to reference the specified UTF-8 string.
sl@0: * @param s A UTF-8 string
sl@0: * @param length The length of the UTF-8 string in bytes, or -1 if the string is
sl@0: * zero terminated.
sl@0: * @param status Errors are returned here.
sl@0: * @return A pointer to the UText. If a pre-allocated UText was provided, it
sl@0: * will always be used and returned.
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: U_DRAFT UText * U_EXPORT2
sl@0: utext_openUTF8(UText *ut, const char *s, int32_t length, UErrorCode *status);
sl@0:
sl@0:
sl@0: /**
sl@0: * Open a read-only UText for UChar * string.
sl@0: *
sl@0: * @param ut Pointer to a UText struct. If NULL, a new UText will be created.
sl@0: * If non-NULL, must refer to an initialized UText struct, which will then
sl@0: * be reset to reference the specified UChar string.
sl@0: * @param s A UChar (UTF-16) string
sl@0: * @param length The number of UChars in the input string, or -1 if the string is
sl@0: * zero terminated.
sl@0: * @param status Errors are returned here.
sl@0: * @return A pointer to the UText. If a pre-allocated UText was provided, it
sl@0: * will always be used and returned.
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: U_DRAFT UText * U_EXPORT2
sl@0: utext_openUChars(UText *ut, const UChar *s, int32_t length, UErrorCode *status);
sl@0:
sl@0:
sl@0: #ifdef XP_CPLUSPLUS
sl@0: /**
sl@0: * Open a writable UText for a non-const UnicodeString.
sl@0: *
sl@0: * @param ut Pointer to a UText struct. If NULL, a new UText will be created.
sl@0: * If non-NULL, must refer to an initialized UText struct, which will then
sl@0: * be reset to reference the specified input string.
sl@0: * @param s A UnicodeString.
sl@0: * @param status Errors are returned here.
sl@0: * @return Pointer to the UText. If a UText was supplied as input, this
sl@0: * will always be used and returned.
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: U_DRAFT UText * U_EXPORT2
sl@0: utext_openUnicodeString(UText *ut, UnicodeString *s, UErrorCode *status);
sl@0:
sl@0:
sl@0: /**
sl@0: * Open a UText for a const UnicodeString. The resulting UText will not be writable.
sl@0: *
sl@0: * @param ut Pointer to a UText struct. If NULL, a new UText will be created.
sl@0: * If non-NULL, must refer to an initialized UText struct, which will then
sl@0: * be reset to reference the specified input string.
sl@0: * @param s A const UnicodeString to be wrapped.
sl@0: * @param status Errors are returned here.
sl@0: * @return Pointer to the UText. If a UText was supplied as input, this
sl@0: * will always be used and returned.
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: U_DRAFT UText * U_EXPORT2
sl@0: utext_openConstUnicodeString(UText *ut, const UnicodeString *s, UErrorCode *status);
sl@0:
sl@0:
sl@0: /**
sl@0: * Open a writable UText implementation for an ICU Replaceable object.
sl@0: * @param ut Pointer to a UText struct. If NULL, a new UText will be created.
sl@0: * If non-NULL, must refer to an already existing UText, which will then
sl@0: * be reset to reference the specified replaceable text.
sl@0: * @param rep A Replaceable text object.
sl@0: * @param status Errors are returned here.
sl@0: * @return Pointer to the UText. If a UText was supplied as input, this
sl@0: * will always be used and returned.
sl@0: * @see Replaceable
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: U_DRAFT UText * U_EXPORT2
sl@0: utext_openReplaceable(UText *ut, Replaceable *rep, UErrorCode *status);
sl@0:
sl@0: #endif
sl@0:
sl@0:
sl@0: /**
sl@0: * clone a UText. Much like opening a UText where the source text is itself
sl@0: * another UText.
sl@0: *
sl@0: * A deep clone will copy both the UText data structures and the underlying text.
sl@0: * The original and cloned UText will operate completely independently; modifications
sl@0: * made to the text in one will not effect the other. Text providers are not
sl@0: * required to support deep clones. The user of clone() must check the status return
sl@0: * and be prepared to handle failures.
sl@0: *
sl@0: * A shallow clone replicates only the UText data structures; it does not make
sl@0: * a copy of the underlying text. Shallow clones can be used as an efficient way to
sl@0: * have multiple iterators active in a single text string that is not being
sl@0: * modified.
sl@0: *
sl@0: * A shallow clone operation will not fail, barring truly exceptional conditions such
sl@0: * as memory allocation failures.
sl@0: *
sl@0: * A UText and its clone may be safely concurrently accessed by separate threads.
sl@0: * This is true for both shallow and deep clones.
sl@0: * It is the responsibility of the Text Provider to ensure that this thread safety
sl@0: * constraint is met.
sl@0: *
sl@0: * @param dest A UText struct to be filled in with the result of the clone operation,
sl@0: * or NULL if the clone function should heap-allocate a new UText struct.
sl@0: * @param src The UText to be cloned.
sl@0: * @param deep TRUE to request a deep clone, FALSE for a shallow clone.
sl@0: * @param status Errors are returned here. For deep clones, U_UNSUPPORTED_ERROR
sl@0: * will be returned if the text provider is unable to clone the
sl@0: * original text.
sl@0: * @return The newly created clone, or NULL if the clone operation failed.
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: U_DRAFT UText * U_EXPORT2
sl@0: utext_clone(UText *dest, const UText *src, UBool deep, UErrorCode *status);
sl@0:
sl@0:
sl@0: /*****************************************************************************
sl@0: *
sl@0: * C Functions to work with the text represeted by a UText wrapper
sl@0: *
sl@0: *****************************************************************************/
sl@0:
sl@0: /**
sl@0: * Get the length of the text. Depending on the characteristics
sl@0: * of the underlying text representation, this may be expensive.
sl@0: * @see utext_isLengthExpensive()
sl@0: *
sl@0: *
sl@0: * @param ut the text to be accessed.
sl@0: * @return the length of the text, expressed in native units.
sl@0: *
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: U_DRAFT int32_t U_EXPORT2
sl@0: utext_nativeLength(UText *ut);
sl@0:
sl@0: /**
sl@0: * Return TRUE if calculating the length of the text could be expensive.
sl@0: * Finding the length of NUL terminated strings is considered to be expensive.
sl@0: *
sl@0: * Note that the value of this function may change
sl@0: * as the result of other operations on a UText.
sl@0: * Once the length of a string has been discovered, it will no longer
sl@0: * be expensive to report it.
sl@0: *
sl@0: * @param ut the text to be accessed.
sl@0: * @return TRUE if determining the length of the text could be time consuming.
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: U_DRAFT UBool U_EXPORT2
sl@0: utext_isLengthExpensive(const UText *ut);
sl@0:
sl@0: /**
sl@0: * Returns the code point at the requested index,
sl@0: * or U_SENTINEL (-1) if it is out of bounds.
sl@0: *
sl@0: * If the specified index points to the interior of a multi-unit
sl@0: * character - one of the trail bytes of a UTF-8 sequence, for example -
sl@0: * the complete code point will be returned.
sl@0: *
sl@0: * The iteration position will be set to the start of the returned code point.
sl@0: *
sl@0: * This function is roughly equivalent to the the sequence
sl@0: * utext_setNativeIndex(index);
sl@0: * utext_current32();
sl@0: * (There is a difference if the index is out of bounds by being less than zero)
sl@0: *
sl@0: * @param ut the text to be accessed
sl@0: * @param nativeIndex the native index of the character to be accessed. If the index points
sl@0: * to other than the first unit of a multi-unit character, it will be adjusted
sl@0: * to the start of the character.
sl@0: * @return the code point at the specified index.
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: U_DRAFT UChar32 U_EXPORT2
sl@0: utext_char32At(UText *ut, int32_t nativeIndex);
sl@0:
sl@0:
sl@0: /**
sl@0: *
sl@0: * Get the code point at the current iteration position,
sl@0: * or U_SENTINEL (-1) if the iteration has reached the end of
sl@0: * the input text.
sl@0: *
sl@0: * @param ut the text to be accessed.
sl@0: * @return the Unicode code point at the current iterator position.
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: U_DRAFT UChar32 U_EXPORT2
sl@0: utext_current32(UText *ut);
sl@0:
sl@0:
sl@0: /**
sl@0: * Get the code point at the current iteration position of the UText, and
sl@0: * advance the position to the first index following the character.
sl@0: * Returns U_SENTINEL (-1) if the position is at the end of the
sl@0: * text.
sl@0: * This is a post-increment operation
sl@0: *
sl@0: * An inline macro version of this function, UTEXT_NEXT32(),
sl@0: * is available for performance critical use.
sl@0: *
sl@0: * @param ut the text to be accessed.
sl@0: * @return the Unicode code point at the iteration position.
sl@0: * @see UTEXT_NEXT32
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: U_DRAFT UChar32 U_EXPORT2
sl@0: utext_next32(UText *ut);
sl@0:
sl@0:
sl@0: /**
sl@0: * Move the iterator position to the character (code point) whose
sl@0: * index precedes the current position, and return that character.
sl@0: * This is a pre-decrement operation.
sl@0: * Returns U_SENTINEL (-1) if the position is at the start of the text.
sl@0: * This is a pre-decrement operation.
sl@0: *
sl@0: * An inline macro version of this function, UTEXT_PREVIOUS32(),
sl@0: * is available for performance critical use.
sl@0: *
sl@0: * @param ut the text to be accessed.
sl@0: * @return the previous UChar32 code point, or U_SENTINEL (-1)
sl@0: * if the iteration has reached the start of the text.
sl@0: * @see UTEXT_PREVIOUS32
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: U_DRAFT UChar32 U_EXPORT2
sl@0: utext_previous32(UText *ut);
sl@0:
sl@0:
sl@0: /**
sl@0: * Set the iteration index, access the text for forward iteration,
sl@0: * and return the code point starting at or before that index.
sl@0: * Leave the iteration index at the start of the following code point.
sl@0: *
sl@0: * This function is the most efficient and convenient way to
sl@0: * begin a forward iteration.
sl@0: *
sl@0: * @param ut the text to be accessed.
sl@0: * @param nativeIndex Iteration index, in the native units of the text provider.
sl@0: * @return Code point which starts at or before index,
sl@0: * or U_SENTINEL (-1) if it is out of bounds.
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: U_DRAFT UChar32 U_EXPORT2
sl@0: utext_next32From(UText *ut, int32_t nativeIndex);
sl@0:
sl@0:
sl@0:
sl@0: /**
sl@0: * Set the iteration index, and return the code point preceding the
sl@0: * one specified by the initial index. Leave the iteration position
sl@0: * at the start of the returned code point.
sl@0: *
sl@0: * This function is the most efficient and convenient way to
sl@0: * begin a backwards iteration.
sl@0: *
sl@0: * @param ut the text to be accessed.
sl@0: * @param nativeIndex Iteration index in the native units of the text provider.
sl@0: * @return Code point preceding the one at the initial index,
sl@0: * or U_SENTINEL (-1) if it is out of bounds.
sl@0: *
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: U_DRAFT UChar32 U_EXPORT2
sl@0: utext_previous32From(UText *ut, int32_t nativeIndex);
sl@0:
sl@0: /**
sl@0: * Get the current iterator position, which can range from 0 to
sl@0: * the length of the text.
sl@0: * The position is a native index into the input text, in whatever format it
sl@0: * may have, and may not always correspond to a UChar (UTF-16) index
sl@0: * into the text. The returned position will always be aligned to a
sl@0: * code point boundary
sl@0: *
sl@0: * @param ut the text to be accessed.
sl@0: * @return the current index position, in the native units of the text provider.
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: U_DRAFT int32_t U_EXPORT2
sl@0: utext_getNativeIndex(UText *ut);
sl@0:
sl@0: /**
sl@0: * Set the current iteration position to the nearest code point
sl@0: * boundary at or preceding the specified index.
sl@0: * The index is in the native units of the original input text.
sl@0: * If the index is out of range, it will be trimmed to be within
sl@0: * the range of the input text.
sl@0: *
sl@0: * It will usually be more efficient to begin an iteration
sl@0: * using the functions utext_next32From() or utext_previous32From()
sl@0: * rather than setIndex().
sl@0: *
sl@0: * Moving the index position to an adjacent character is best done
sl@0: * with utext_next32(), utext_previous32() or utext_moveIndex32().
sl@0: * Attempting to do direct arithmetic on the index position is
sl@0: * complicated by the fact that the size (in native units) of a
sl@0: * character depends on the underlying representation of the character
sl@0: * (UTF-8, UTF-16, UTF-32, arbitrary codepage), and is not
sl@0: * easily knowable.
sl@0: *
sl@0: * @param ut the text to be accessed.
sl@0: * @param nativeIndex the native unit index of the new iteration position.
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: U_DRAFT void U_EXPORT2
sl@0: utext_setNativeIndex(UText *ut, int32_t nativeIndex);
sl@0:
sl@0: /**
sl@0: * Move the iterator postion by delta code points. The number of code points
sl@0: * is a signed number; a negative delta will move the iterator backwards,
sl@0: * towards the start of the text.
sl@0: *
sl@0: * The index is moved by delta code points
sl@0: * forward or backward, but no further backward than to 0 and
sl@0: * no further forward than to utext_nativeLength().
sl@0: * The resulting index value will be in between 0 and length, inclusive.
sl@0: *
sl@0: * Because the index is kept in the native units of the text provider, the
sl@0: * actual numeric amount by which the index moves depends on the
sl@0: * underlying text storage representation of the text provider.
sl@0: *
sl@0: * @param ut the text to be accessed.
sl@0: * @param delta the signed number of code points to move the iteration position.
sl@0: * @return TRUE if the position could be moved the requested number of positions while
sl@0: * staying within the range [0 - text length].
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: U_DRAFT UBool U_EXPORT2
sl@0: utext_moveIndex32(UText *ut, int32_t delta);
sl@0:
sl@0:
sl@0: /**
sl@0: *
sl@0: * Extract text from a UText into a UChar buffer. The range of text to be extracted
sl@0: * is specified in the native indices of the UText provider. These may not necessarily
sl@0: * be UTF-16 indices.
sl@0: *
sl@0: * The size (number of 16 bit UChars) in the data to be extracted is returned. The
sl@0: * full number of UChars is returned, even when the extracted text is truncated
sl@0: * because the specified buffer size is too small.
sl@0: *
sl@0: * The extracted string will (if you are a user) / must (if you are a text provider)
sl@0: * be NUL-terminated if there is sufficient space in the destination buffer. This
sl@0: * terminating NUL is not included in the returned length.
sl@0: *
sl@0: * @param ut the UText from which to extract data.
sl@0: * @param nativeStart the native index of the first character to extract.
sl@0: * @param nativeLimit the native string index of the position following the last
sl@0: * character to extract. If the specified limit is greater than the length
sl@0: * of the text, the limit will be trimmed back to the text length.
sl@0: * @param dest the UChar (UTF-16) buffer into which the extracted text is placed
sl@0: * @param destCapacity The size, in UChars, of the destination buffer. May be zero
sl@0: * for precomputing the required size.
sl@0: * @param status receives any error status.
sl@0: * U_BUFFER_OVERFLOW_ERROR: the extracted text was truncated because the
sl@0: * buffer was too small. Returns number of UChars for preflighting.
sl@0: * @return Number of UChars in the data to be extracted. Does not include a trailing NUL.
sl@0: *
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: U_DRAFT int32_t U_EXPORT2
sl@0: utext_extract(UText *ut,
sl@0: int32_t nativeStart, int32_t nativeLimit,
sl@0: UChar *dest, int32_t destCapacity,
sl@0: UErrorCode *status);
sl@0:
sl@0:
sl@0:
sl@0: /************************************************************************************
sl@0: *
sl@0: * #define inline versions of selected performance-critical text access functions
sl@0: * Caution: do not use auto increment++ or decrement-- expressions
sl@0: * as parameters to these macros.
sl@0: *
sl@0: * For most use, where there is no extreme performance constraint, the
sl@0: * normal, non-inline functions are a better choice. The resulting code
sl@0: * will be smaller, and, if the need ever arises, easier to debug.
sl@0: *
sl@0: * These are implemented as #defines rather than real functions
sl@0: * because there is no fully portable way to do inline functions in plain C.
sl@0: *
sl@0: ************************************************************************************/
sl@0:
sl@0: /**
sl@0: * inline version of utext_next32(), for performance-critical situations.
sl@0: *
sl@0: * Get the code point at the current iteration position of the UText, and
sl@0: * advance the position to the first index following the character.
sl@0: * This is a post-increment operation.
sl@0: * Returns U_SENTINEL (-1) if the position is at the end of the
sl@0: * text.
sl@0: *
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: #define UTEXT_NEXT32(ut) \
sl@0: ((ut)->chunk.offset < (ut)->chunk.length && ((ut)->chunk.contents)[(ut)->chunk.offset]<0xd800 ? \
sl@0: ((ut)->chunk.contents)[((ut)->chunk.offset)++] : utext_next32(ut))
sl@0:
sl@0: /**
sl@0: * inline version of utext_previous32(), for performance-critical situations.
sl@0: *
sl@0: * Move the iterator position to the character (code point) whose
sl@0: * index precedes the current position, and return that character.
sl@0: * This is a pre-decrement operation.
sl@0: * Returns U_SENTINEL (-1) if the position is at the start of the text.
sl@0: *
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: #define UTEXT_PREVIOUS32(ut) \
sl@0: ((ut)->chunk.offset > 0 && \
sl@0: (ut)->chunk.contents[(ut)->chunk.offset-1] < 0xd800 ? \
sl@0: (ut)->chunk.contents[--((ut)->chunk.offset)] : utext_previous32(ut))
sl@0:
sl@0:
sl@0:
sl@0:
sl@0: /************************************************************************************
sl@0: *
sl@0: * Functions related to writing or modifying the text.
sl@0: * These will work only with modifiable UTexts. Attempting to
sl@0: * modify a read-only UText will return an error status.
sl@0: *
sl@0: ************************************************************************************/
sl@0:
sl@0:
sl@0: /**
sl@0: * Return TRUE if the text can be written with utext_replace() or
sl@0: * utext_copy(). For the text to be writable, the text provider must
sl@0: * be of a type that supports writing.
sl@0: *
sl@0: * @param ut the UText to be tested.
sl@0: * @return TRUE if the text is modifiable.
sl@0: * @draft ICU 3.4
sl@0: *
sl@0: */
sl@0: U_DRAFT UBool U_EXPORT2
sl@0: utext_isWritable(const UText *ut);
sl@0:
sl@0:
sl@0: /**
sl@0: * Test whether there is meta data associated with the text.
sl@0: * @see Replaceable::hasMetaData()
sl@0: *
sl@0: * @param ut The UText to be tested
sl@0: * @return TRUE if the underlying text includes meta data.
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: U_DRAFT UBool U_EXPORT2
sl@0: utext_hasMetaData(const UText *ut);
sl@0:
sl@0:
sl@0: /**
sl@0: * Replace a range of the original text with a replacement text.
sl@0: *
sl@0: * Leaves the current iteration position at the position following the
sl@0: * newly inserted replacement text.
sl@0: *
sl@0: * This function is only available on UText types that support writing,
sl@0: * that is, ones where utext_isWritable() returns TRUE.
sl@0: *
sl@0: * When using this function, there should be only a single UText opened onto the
sl@0: * underlying native text string. Behavior after a replace operation
sl@0: * on a UText is undefined for any other additional UTexts that refer to the
sl@0: * modified string.
sl@0: *
sl@0: * @param ut the UText representing the text to be operated on.
sl@0: * @param nativeStart the native index of the start of the region to be replaced
sl@0: * @param nativeLimit the native index of the character following the region to be replaced.
sl@0: * @param replacementText pointer to the replacement text
sl@0: * @param replacementLength length of the replacement text, or -1 if the text is NUL terminated.
sl@0: * @param status receives any error status. Possible errors include
sl@0: * U_NO_WRITE_PERMISSION
sl@0: *
sl@0: * @return The signed number of (native) storage units by which
sl@0: * the length of the text expanded or contracted.
sl@0: *
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: U_DRAFT int32_t U_EXPORT2
sl@0: utext_replace(UText *ut,
sl@0: int32_t nativeStart, int32_t nativeLimit,
sl@0: const UChar *replacementText, int32_t replacementLength,
sl@0: UErrorCode *status);
sl@0:
sl@0:
sl@0:
sl@0: /**
sl@0: *
sl@0: * Copy or move a substring from one position to another within the text,
sl@0: * while retaining any metadata associated with the text.
sl@0: * This function is used to duplicate or reorder substrings.
sl@0: * The destination index must not overlap the source range.
sl@0: *
sl@0: * The text to be copied or moved is inserted at destIndex;
sl@0: * it does not replace or overwrite any existing text.
sl@0: *
sl@0: * This function is only available on UText types that support writing,
sl@0: * that is, ones where utext_isWritable() returns TRUE.
sl@0: *
sl@0: * When using this function, there should be only a single UText opened onto the
sl@0: * underlying native text string. Behavior after a copy operation
sl@0: * on a UText is undefined in any other additional UTexts that refer to the
sl@0: * modified string.
sl@0: *
sl@0: * @param ut The UText representing the text to be operated on.
sl@0: * @param nativeStart The native index of the start of the region to be copied or moved
sl@0: * @param nativeLimit The native index of the character position following the region to be copied.
sl@0: * @param destIndex The native destination index to which the source substring is copied or moved.
sl@0: * @param move If TRUE, then the substring is moved, not copied/duplicated.
sl@0: * @param status receives any error status. Possible errors include U_NO_WRITE_PERMISSION
sl@0: *
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: U_DRAFT void U_EXPORT2
sl@0: utext_copy(UText *ut,
sl@0: int32_t nativeStart, int32_t nativeLimit,
sl@0: int32_t destIndex,
sl@0: UBool move,
sl@0: UErrorCode *status);
sl@0:
sl@0:
sl@0:
sl@0:
sl@0:
sl@0: /****************************************************************************************
sl@0: *
sl@0: * The following items are required by text providers implementations -
sl@0: * by packages that are writing UText wrappers for additional types of text strings.
sl@0: * These declarations are not needed by applications that use already existing
sl@0: * UText functions for wrapping strings or accessing text data that has been
sl@0: * wrapped in a UText.
sl@0: *
sl@0: *****************************************************************************************/
sl@0:
sl@0:
sl@0: /**
sl@0: * Descriptor of a chunk, or segment of text in UChar format.
sl@0: *
sl@0: * UText provider implementations surface their text in the form of UTextChunks.
sl@0: *
sl@0: * If the native form of the text if UTF-16, a chunk will typically refer back to the
sl@0: * original native text storage. If the native format is something else, chunks
sl@0: * will typically refer to a buffer maintained by the provider that contains
sl@0: * some amount input that has been converted to UTF-16 (UChar) form.
sl@0: *
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: struct UTextChunk {
sl@0: /** Pointer to contents of text chunk. UChar format. */
sl@0: const UChar *contents;
sl@0:
sl@0: /** Index within the contents of the current iteration position. */
sl@0: int32_t offset;
sl@0:
sl@0: /** Number of UChars in the chunk. */
sl@0: int32_t length;
sl@0:
sl@0: /** (Native) text index corresponding to the start of the chunk. */
sl@0: int32_t nativeStart;
sl@0:
sl@0: /** (Native) text index corresponding to the end of the chunk (contents+length). */
sl@0: int32_t nativeLimit;
sl@0:
sl@0: /** If TRUE, then non-UTF-16 indexes are used in this chunk. */
sl@0: UBool nonUTF16Indexes;
sl@0:
sl@0: /** Unused. */
sl@0: UBool padding1, padding2, padding3;
sl@0:
sl@0: /** Unused. */
sl@0: int32_t padInt1, padInt2;
sl@0:
sl@0: /** Contains sizeof(UTextChunk) and allows the future addition of fields. */
sl@0: int32_t sizeOfStruct;
sl@0: };
sl@0:
sl@0:
sl@0: /**
sl@0: * UText provider properties (bit field indexes).
sl@0: *
sl@0: * @see UText
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: enum {
sl@0: /**
sl@0: * The provider works with non-UTF-16 ("native") text indexes.
sl@0: * For example, byte indexes into UTF-8 text or UTF-32 indexes into UTF-32 text.
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: UTEXT_PROVIDER_NON_UTF16_INDEXES = 0,
sl@0: /**
sl@0: * It is potentially time consuming for the provider to determine the length of the text.
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: UTEXT_PROVIDER_LENGTH_IS_EXPENSIVE = 1,
sl@0: /**
sl@0: * Text chunks remain valid and usable until the text object is modified or
sl@0: * deleted, not just until the next time the access() function is called
sl@0: * (which is the default).
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: UTEXT_PROVIDER_STABLE_CHUNKS = 2,
sl@0: /**
sl@0: * The provider supports modifying the text via the replace() and copy()
sl@0: * functions.
sl@0: * @see Replaceable
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: UTEXT_PROVIDER_WRITABLE = 3,
sl@0: /**
sl@0: * There is meta data associated with the text.
sl@0: * @see Replaceable::hasMetaData()
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: UTEXT_PROVIDER_HAS_META_DATA = 4
sl@0: };
sl@0:
sl@0: /**
sl@0: * Function type declaration for UText.clone().
sl@0: *
sl@0: * clone a UText. Much like opening a UText where the source text is itself
sl@0: * another UText.
sl@0: *
sl@0: * A deep clone will copy both the UText data structures and the underlying text.
sl@0: * The original and cloned UText will operate completely independently; modifications
sl@0: * made to the text in one will not effect the other. Text providers are not
sl@0: * required to support deep clones. The user of clone() must check the status return
sl@0: * and be prepared to handle failures.
sl@0: *
sl@0: * A shallow clone replicates only the UText data structures; it does not make
sl@0: * a copy of the underlying text. Shallow clones can be used as an efficient way to
sl@0: * have multiple iterators active in a single text string that is not being
sl@0: * modified.
sl@0: *
sl@0: * A shallow clone operation must not fail except for truly exceptional conditions such
sl@0: * as memory allocation failures.
sl@0: *
sl@0: * A UText and its clone may be safely concurrently accessed by separate threads.
sl@0: * This is true for both shallow and deep clones.
sl@0: * It is the responsibility of the Text Provider to ensure that this thread safety
sl@0: * constraint is met.
sl@0:
sl@0: *
sl@0: * @param dest A UText struct to be filled in with the result of the clone operation,
sl@0: * or NULL if the clone function should heap-allocate a new UText struct.
sl@0: * @param src The UText to be cloned.
sl@0: * @param deep TRUE to request a deep clone, FALSE for a shallow clone.
sl@0: * @param status Errors are returned here. For deep clones, U_UNSUPPORTED_ERROR
sl@0: * should be returned if the text provider is unable to clone the
sl@0: * original text.
sl@0: * @return The newly created clone, or NULL if the clone operation failed.
sl@0: *
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: typedef UText * U_CALLCONV
sl@0: UTextClone(UText *dest, const UText *src, UBool deep, UErrorCode *status);
sl@0:
sl@0:
sl@0: /**
sl@0: * Function type declaration for UText.nativeLength().
sl@0: *
sl@0: * @param ut the UText to get the length of.
sl@0: * @return the length, in the native units of the original text string.
sl@0: * @see UText
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: typedef int32_t U_CALLCONV
sl@0: UTextNativeLength(UText *ut);
sl@0:
sl@0: /**
sl@0: * Function type declaration for UText.access(). Get the description of the text chunk
sl@0: * containing the text at a requested native index. The UText's iteration
sl@0: * position will be left at the requested index. If the index is out
sl@0: * of bounds, the iteration position will be left at the start or end
sl@0: * of the string, as appropriate.
sl@0: *
sl@0: * Chunks must begin and end on code point boundaries. A single code point
sl@0: * comprised of multiple storage units must never span a chunk boundary.
sl@0: *
sl@0: *
sl@0: * @param ut the UText being accessed.
sl@0: * @param nativeIndex Requested index of the text to be accessed.
sl@0: * @param forward If TRUE, then the returned chunk must contain text
sl@0: * starting from the index, so that start<=index
sl@0: * The size (number of 16 bit UChars) in the data to be extracted is returned. The
sl@0: * full amount is returned, even when the specified buffer size is smaller.
sl@0: *
sl@0: * The extracted string will (if you are a user) / must (if you are a text provider)
sl@0: * be NUL-terminated if there is sufficient space in the destination buffer.
sl@0: *
sl@0: * @param ut the UText from which to extract data.
sl@0: * @param nativeStart the native index of the first characer to extract.
sl@0: * @param nativeLimit the native string index of the position following the last
sl@0: * character to extract.
sl@0: * @param dest the UChar (UTF-16) buffer into which the extracted text is placed
sl@0: * @param destCapacity The size, in UChars, of the destination buffer. May be zero
sl@0: * for precomputing the required size.
sl@0: * @param status receives any error status.
sl@0: * If U_BUFFER_OVERFLOW_ERROR: Returns number of UChars for
sl@0: * preflighting.
sl@0: * @return Number of UChars in the data. Does not include a trailing NUL.
sl@0: *
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: typedef int32_t U_CALLCONV
sl@0: UTextExtract(UText *ut,
sl@0: int32_t nativeStart, int32_t nativeLimit,
sl@0: UChar *dest, int32_t destCapacity,
sl@0: UErrorCode *status);
sl@0:
sl@0: /**
sl@0: * Function type declaration for UText.replace().
sl@0: *
sl@0: * Replace a range of the original text with a replacement text.
sl@0: *
sl@0: * Leaves the current iteration position at the position following the
sl@0: * newly inserted replacement text.
sl@0: *
sl@0: * This function need only be implemented on UText types that support writing.
sl@0: *
sl@0: * When using this function, there should be only a single UText opened onto the
sl@0: * underlying native text string. The function is responsible for updating the
sl@0: * text chunk within the UText to reflect the updated iteration position,
sl@0: * taking into account any changes to the underlying string's structure caused
sl@0: * by the replace operation.
sl@0: *
sl@0: * @param ut the UText representing the text to be operated on.
sl@0: * @param nativeStart the index of the start of the region to be replaced
sl@0: * @param nativeLimit the index of the character following the region to be replaced.
sl@0: * @param replacementText pointer to the replacement text
sl@0: * @param replacmentLength length of the replacement text in UChars, or -1 if the text is NUL terminated.
sl@0: * @param status receives any error status. Possible errors include
sl@0: * U_NO_WRITE_PERMISSION
sl@0: *
sl@0: * @return The signed number of (native) storage units by which
sl@0: * the length of the text expanded or contracted.
sl@0: *
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: typedef int32_t U_CALLCONV
sl@0: UTextReplace(UText *ut,
sl@0: int32_t nativeStart, int32_t nativeLimit,
sl@0: const UChar *replacementText, int32_t replacmentLength,
sl@0: UErrorCode *status);
sl@0:
sl@0: /**
sl@0: * Function type declaration for UText.copy().
sl@0: *
sl@0: * Copy or move a substring from one position to another within the text,
sl@0: * while retaining any metadata associated with the text.
sl@0: * This function is used to duplicate or reorder substrings.
sl@0: * The destination index must not overlap the source range.
sl@0: *
sl@0: * The text to be copied or moved is inserted at destIndex;
sl@0: * it does not replace or overwrite any existing text.
sl@0: *
sl@0: * This function need only be implemented for UText types that support writing.
sl@0: *
sl@0: * When using this function, there should be only a single UText opened onto the
sl@0: * underlying native text string. The function is responsible for updating the
sl@0: * text chunk within the UText to reflect the updated iteration position,
sl@0: * taking into account any changes to the underlying string's structure caused
sl@0: * by the replace operation.
sl@0: *
sl@0: * @param ut The UText representing the text to be operated on.
sl@0: * @param nativeStart The index of the start of the region to be copied or moved
sl@0: * @param nativeLimit The index of the character following the region to be replaced.
sl@0: * @param nativeDest The destination index to which the source substring is copied or moved.
sl@0: * @param move If TRUE, then the substring is moved, not copied/duplicated.
sl@0: * @param status receives any error status. Possible errors include U_NO_WRITE_PERMISSION
sl@0: *
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: typedef void U_CALLCONV
sl@0: UTextCopy(UText *ut,
sl@0: int32_t nativeStart, int32_t nativeLimit,
sl@0: int32_t nativeDest,
sl@0: UBool move,
sl@0: UErrorCode *status);
sl@0:
sl@0: /**
sl@0: * Function type declaration for UText.mapOffsetToNative().
sl@0: * Map from a UChar offset within the current text chunk within the UText to
sl@0: * the corresponding native index in the original source text.
sl@0: *
sl@0: * This is required only for text providers that do not use native UTF-16 indexes.
sl@0: *
sl@0: * TODO: specify behavior with out-of-bounds offset? Shouldn't ever occur.
sl@0: *
sl@0: * @param ut the UText.
sl@0: * @param offset UTF-16 offset within text chunk
sl@0: * 0<=offset<=chunk->length.
sl@0: * @return Absolute (native) index corresponding to the specified chunk offset.
sl@0: * The returned native index should always be to a code point boundary.
sl@0: *
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: typedef int32_t U_CALLCONV
sl@0: UTextMapOffsetToNative(UText *ut, int32_t offset);
sl@0:
sl@0: /**
sl@0: * Function type declaration for UText.mapIndexToUTF16().
sl@0: * Map from a native index to a UChar offset within a text chunk
sl@0: *
sl@0: * This function is required only for text providers that do not use native UTF-16 indexes.
sl@0: *
sl@0: * @param ut The UText containing the text chunk.
sl@0: * @param nativeIndex Absolute (native) text index, chunk->start<=index<=chunk->limit.
sl@0: * @return Chunk-relative UTF-16 offset corresponding to the specified native
sl@0: * index.
sl@0: *
sl@0: * TODO: specify behavior with out-of-bounds index? Shouldn't ever occur.
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: typedef int32_t U_CALLCONV
sl@0: UTextMapNativeIndexToUTF16(UText *ut, int32_t nativeIndex);
sl@0:
sl@0:
sl@0: /**
sl@0: * Function type declaration for UText.utextClose().
sl@0: *
sl@0: * A Text Provider close function is only required for provider types that make
sl@0: * allocations in their open function (or other functions) that must be
sl@0: * cleaned when the UText is closed.
sl@0: *
sl@0: * The allocation of the UText struct itself and any "extra" storage
sl@0: * associated with the UText is handled by the common UText implementation
sl@0: * and does not require provider specific cleanup in a close function.
sl@0: *
sl@0: * Most UText provider implementations do not need to implement this function.
sl@0: *
sl@0: * @param ut A UText object to be closed.
sl@0: *
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: typedef void U_CALLCONV
sl@0: UTextClose(UText *ut);
sl@0:
sl@0:
sl@0: /**
sl@0: * UText struct. Provides the interface between the generic UText access code
sl@0: * and the UText provider code that works on specific kinds of
sl@0: * text (UTF-8, noncontiguous UTF-16, whatever.)
sl@0: *
sl@0: * Applications that are using predefined types of text providers
sl@0: * to pass text data to ICU services will have no need to view the
sl@0: * internals of the UText structs that they open.
sl@0: *
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: struct UText {
sl@0: /**
sl@0: * (protected) Pointer to string or wrapped object or similar.
sl@0: * Not used by caller.
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: const void *context;
sl@0:
sl@0: /**
sl@0: * (protected) Pointer fields available for use by the text provider.
sl@0: * Not used by UText common code.
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: const void *p, *q, *r;
sl@0:
sl@0: /**
sl@0: * (protected) Pointer to additional space requested by the
sl@0: * text provider during the utext_open operation.
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: void *pExtra;
sl@0:
sl@0: /**
sl@0: * (protected) Size in bytes of the extra space (pExtra).
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: int32_t extraSize;
sl@0:
sl@0: /**
sl@0: * (private) Flags for managing the allocation and freeing of
sl@0: * memory associated with this UText.
sl@0: * @internal
sl@0: */
sl@0: int32_t flags;
sl@0:
sl@0: /**
sl@0: * (private) Magic. Try to detect when we are handed junk.
sl@0: * utext_openXYZ() functions take an initialized,
sl@0: * but not necessarily open, UText struct as an,
sl@0: * optional fill-in parameter. This magic field
sl@0: * is used to check for that initialization.
sl@0: * Text provider close functions must NOT clear
sl@0: * the magic field because that would prevent
sl@0: * reuse of the UText struct.
sl@0: * @internal
sl@0: */
sl@0: uint32_t magic;
sl@0:
sl@0:
sl@0: /**
sl@0: * (public) sizeOfStruct=sizeof(UText)
sl@0: * Allows possible backward compatible extension.
sl@0: *
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: int32_t sizeOfStruct;
sl@0:
sl@0: /**
sl@0: * (protected) Integer fields for use by text provider.
sl@0: * Not used by caller.
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: int32_t a, b, c;
sl@0:
sl@0:
sl@0: /**
sl@0: * Text provider properties. This set of flags is maintainted by the
sl@0: * text provider implementation.
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: int32_t providerProperties;
sl@0:
sl@0:
sl@0:
sl@0: /** descriptor for the text chunk that includes or is adjacent to
sl@0: * the current iteration position.
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: UTextChunk chunk;
sl@0:
sl@0:
sl@0: /**
sl@0: * (public) Function pointer for UTextClone
sl@0: *
sl@0: * @see UTextClone
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: UTextClone *clone;
sl@0:
sl@0: /**
sl@0: * (public) function pointer for UTextLength
sl@0: * May be expensive to compute!
sl@0: *
sl@0: * @see UTextLength
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: UTextNativeLength *nativeLength;
sl@0:
sl@0: /**
sl@0: * (public) Function pointer for UTextAccess.
sl@0: *
sl@0: * @see UTextAccess
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: UTextAccess *access;
sl@0:
sl@0: /**
sl@0: * (public) Function pointer for UTextExtract.
sl@0: *
sl@0: * @see UTextExtract
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: UTextExtract *extract;
sl@0:
sl@0: /**
sl@0: * (public) Function pointer for UTextReplace.
sl@0: *
sl@0: * @see UTextReplace
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: UTextReplace *replace;
sl@0:
sl@0: /**
sl@0: * (public) Function pointer for UTextCopy.
sl@0: *
sl@0: * @see UTextCopy
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: UTextCopy *copy;
sl@0:
sl@0: /**
sl@0: * (public) Function pointer for UTextMapOffsetToNative.
sl@0: *
sl@0: * @see UTextMapOffsetToNative
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: UTextMapOffsetToNative *mapOffsetToNative;
sl@0:
sl@0: /**
sl@0: * (public) Function pointer for UTextMapNativeIndexToUTF16.
sl@0: *
sl@0: * @see UTextMapNativeIndexToUTF16
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: UTextMapNativeIndexToUTF16 *mapNativeIndexToUTF16;
sl@0:
sl@0: /**
sl@0: * (public) Function pointer for UTextClose.
sl@0: *
sl@0: * @see UTextClose
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: UTextClose *close;
sl@0: };
sl@0:
sl@0:
sl@0: /**
sl@0: * Common function for use by Text Provider implementations to allocate and/or initialize
sl@0: * a new UText struct. To be called in the implementation of utext_open() functions.
sl@0: * If the supplied UText parameter is null, a new UText struct will be allocated on the heap.
sl@0: * If the supplied UText is already open, the provider's close function will be called
sl@0: * so that the struct can be reused by the open that is in progress.
sl@0: *
sl@0: * @param ut pointer to a UText struct to be re-used, or null if a new UText
sl@0: * should be allocated.
sl@0: * @param extraSpace The amount of additional space to be allocated as part
sl@0: * of this UText, for use by types of providers that require
sl@0: * additional storage.
sl@0: * @param status Errors are returned here.
sl@0: * @return pointer to the UText, allocated if necessary, with extra space set up if requested.
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: U_DRAFT UText * U_EXPORT2
sl@0: utext_setup(UText *ut, int32_t extraSpace, UErrorCode *status);
sl@0:
sl@0: /**
sl@0: * @internal
sl@0: */
sl@0: enum {
sl@0: UTEXT_MAGIC = 0x345ad82c
sl@0: };
sl@0:
sl@0:
sl@0: /**
sl@0: * Initializer for a UTextChunk
sl@0: * @internal
sl@0: */
sl@0: #define UTEXT_CHUNK_INIT { \
sl@0: NULL, /* contents */ \
sl@0: 0, /* offset */ \
sl@0: 0, /* length */ \
sl@0: 0, /* start */ \
sl@0: 0, /* limit */ \
sl@0: FALSE, /* nonUTF16idx */ \
sl@0: FALSE, FALSE, FALSE, /* padding1,2,3 */ \
sl@0: 0, 0, /* padInt1, 2 */ \
sl@0: sizeof(UTextChunk) \
sl@0: }
sl@0:
sl@0:
sl@0:
sl@0: /**
sl@0: * Initializer for the first part of a UText struct, the part that is
sl@0: * in common for all types of text providers.
sl@0: *
sl@0: * @internal
sl@0: */
sl@0: #define UTEXT_INITIALIZER_HEAD \
sl@0: NULL, /* context */ \
sl@0: NULL, NULL, NULL, /* p, q, r */ \
sl@0: NULL, /* pExtra */ \
sl@0: 0, /* extraSize */ \
sl@0: 0, /* flags */ \
sl@0: UTEXT_MAGIC, /* magic */ \
sl@0: sizeof(UText), /* sizeOfStruct */ \
sl@0: 0, 0, 0, /* a, b, c */ \
sl@0: 0, /* providerProps */ \
sl@0: UTEXT_CHUNK_INIT /* UTextChunk */
sl@0:
sl@0:
sl@0:
sl@0: /**
sl@0: * initializer to be used with local (stack) instances of a UText
sl@0: * struct. UText structs must be initialized before passing
sl@0: * them to one of the utext_open functions.
sl@0: *
sl@0: * @draft ICU 3.4
sl@0: */
sl@0: #define UTEXT_INITIALIZER { \
sl@0: UTEXT_INITIALIZER_HEAD, \
sl@0: NULL, /* clone () */ \
sl@0: NULL, /* length () */ \
sl@0: NULL, /* access () */ \
sl@0: NULL, /* extract () */ \
sl@0: NULL, /* replace () */ \
sl@0: NULL, /* copy () */ \
sl@0: NULL, NULL, /* map * 2 () */ \
sl@0: NULL /* close () */ \
sl@0: }
sl@0:
sl@0:
sl@0: U_CDECL_END
sl@0:
sl@0:
sl@0:
sl@0: #endif /* U_HIDE_DRAFT_API */
sl@0:
sl@0: #endif