Lines Matching refs:UText
8 * file name: utext.h
30 * UTF-16 strings, to be placed in a UText wrapper and then passed to ICU services.
32 * There are three general classes of usage for UText:
36 * the resulting UText to the desired ICU service.
39 * operate on input presented to them as a UText. These implementations
40 * will need to use the iteration and related UText functions to gain
43 * The third class of UText users are "text providers." These are the
44 * UText implementations for the various text storage formats. An application
46 * UText provider functions for that format, which will then allow
52 * Here is sample code for a forward iteration over the contents of a UText
56 * UText *ut = whatever();
68 * UText *ut = whatever();
77 * Indexing into text by UText functions is nearly always in terms of the native
79 * or UTF-32, for example. When coding to the UText access API, no assumptions
83 * All indices supplied to UText functions are pinned to the length of the
88 * When an index position is returned from a UText function, it will be
94 * When a native index is supplied to a UText function, all indices that
105 * <em>Conventions for calling UText functions</em>
107 * Most UText access functions have as their first parameter a (UText *) pointer,
108 * which specifies the UText to be used. Unless otherwise noted, the
109 * pointer must refer to a valid, open UText. Attempting to
110 * use a closed UText or passing a NULL pointer is a programming error and
114 * UText, or heap allocate a new UText. Here is sample code for creating
115 * a stack-allocated UText.
120 * UText ut = UTEXT_INITIALIZER;
125 * // work with the UText
129 * Any existing UText passed to an open function _must_ have been initialized,
132 * heap-allocate and fully initialize a new UText.
150 struct UText;
151 typedef struct UText UText; /**< C typedef for struct UText. @stable ICU 3.6 */
156 * C Functions for creating UText wrappers around various kinds of text strings.
162 * Close function for UText instances.
163 * Cleans up, releases any resources being held by an open UText.
165 * If the UText was originally allocated by one of the utext_open functions,
166 * the storage associated with the utext will also be freed.
167 * If the UText storage originated with the application, as it would with
170 * An open UText can be reset to refer to new string by using one of the utext_open()
171 * functions without first closing the UText.
173 * @param ut The UText to be closed.
174 * @return NULL if the UText struct was deleted by the close. If the UText struct
181 U_STABLE UText * U_EXPORT2
182 utext_close(UText *ut);
190 * "Smart pointer" class, closes a UText via utext_close().
197 U_DEFINE_LOCAL_OPEN_POINTER(LocalUTextPointer, UText, utext_close);
204 * Open a read-only UText implementation for UTF-8 strings.
213 * @param ut Pointer to a UText struct. If NULL, a new UText will be created.
214 * If non-NULL, must refer to an initialized UText struct, which will then
220 * @return A pointer to the UText. If a pre-allocated UText was provided, it
224 U_STABLE UText * U_EXPORT2
225 utext_openUTF8(UText *ut, const char *s, int64_t length, UErrorCode *status);
229 * Open a read-only UText for UChar * string.
231 * @param ut Pointer to a UText struct. If NULL, a new UText will be created.
232 * If non-NULL, must refer to an initialized UText struct, which will then
238 * @return A pointer to the UText. If a pre-allocated UText was provided, it
242 U_STABLE UText * U_EXPORT2
243 utext_openUChars(UText *ut, const UChar *s, int64_t length, UErrorCode *status);
248 * Open a writable UText for a non-const UnicodeString.
250 * @param ut Pointer to a UText struct. If NULL, a new UText will be created.
251 * If non-NULL, must refer to an initialized UText struct, which will then
255 * @return Pointer to the UText. If a UText was supplied as input, this
259 U_STABLE UText * U_EXPORT2
260 utext_openUnicodeString(UText *ut, U_NAMESPACE_QUALIFIER UnicodeString *s, UErrorCode *status);
264 * Open a UText for a const UnicodeString. The resulting UText will not be writable.
266 * @param ut Pointer to a UText struct. If NULL, a new UText will be created.
267 * If non-NULL, must refer to an initialized UText struct, which will then
271 * @return Pointer to the UText. If a UText was supplied as input, this
275 U_STABLE UText * U_EXPORT2
276 utext_openConstUnicodeString(UText *ut, const U_NAMESPACE_QUALIFIER UnicodeString *s, UErrorCode *status);
280 * Open a writable UText implementation for an ICU Replaceable object.
281 * @param ut Pointer to a UText struct. If NULL, a new UText will be created.
282 * If non-NULL, must refer to an already existing UText, which will then
286 * @return Pointer to the UText. If a UText was supplied as input, this
291 U_STABLE UText * U_EXPORT2
292 utext_openReplaceable(UText *ut, U_NAMESPACE_QUALIFIER Replaceable *rep, UErrorCode *status);
295 * Open a UText implementation over an ICU CharacterIterator.
296 * @param ut Pointer to a UText struct. If NULL, a new UText will be created.
297 * If non-NULL, must refer to an already existing UText, which will then
301 * @return Pointer to the UText. If a UText was supplied as input, this
306 U_STABLE UText * U_EXPORT2
307 utext_openCharacterIterator(UText *ut, U_NAMESPACE_QUALIFIER CharacterIterator *ic, UErrorCode *status);
313 * Clone a UText. This is much like opening a UText where the source text is itself
314 * another UText.
316 * A deep clone will copy both the UText data structures and the underlying text.
317 * The original and cloned UText will operate completely independently; modifications
322 * The standard UText implementations for UTF8, UChar *, UnicodeString and
325 * The UText returned from a deep clone will be writable, assuming that the text
326 * provider is able to support writing, even if the source UText had been made
329 * A shallow clone replicates only the UText data structures; it does not make
337 * Shallow UText clones should be avoided if the UText functions that modify the
338 * text are expected to be used, either on the original or the cloned UText.
341 * disabling text modification via the cloned UText.
345 * write operations must be avoided while more than one UText exists that refer
348 * A UText and its clone may be safely concurrently accessed by separate threads.
354 * @param dest A UText struct to be filled in with the result of the clone operation,
355 * or NULL if the clone function should heap-allocate a new UText struct.
356 * If non-NULL, must refer to an already existing UText, which will then
358 * @param src The UText to be cloned.
360 * @param readOnly TRUE to request that the cloned UText have read only access to the
369 U_STABLE UText * U_EXPORT2
370 utext_clone(UText *dest, const UText *src, UBool deep, UBool readOnly, UErrorCode *status);
374 * Compare two UText objects for equality.
380 * @param b The other UText to be compared.
385 utext_equals(const UText *a, const UText *b);
390 * Functions to work with the text represeted by a UText wrapper
406 utext_nativeLength(UText *ut);
413 * as the result of other operations on a UText.
422 utext_isLengthExpensive(const UText *ut);
450 utext_char32At(UText *ut, int64_t nativeIndex);
464 utext_current32(UText *ut);
468 * Get the code point at the current iteration position of the UText, and
486 utext_next32(UText *ut);
507 utext_previous32(UText *ut);
529 utext_next32From(UText *ut, int64_t nativeIndex);
549 utext_previous32From(UText *ut, int64_t nativeIndex);
564 utext_getNativeIndex(const UText *ut);
590 utext_setNativeIndex(UText *ut, int64_t nativeIndex);
609 utext_moveIndex32(UText *ut, int32_t delta);
619 * UText *ut = whatever;
634 utext_getPreviousNativeIndex(UText *ut);
639 * Extract text from a UText into a UChar buffer. The range of text to be extracted
640 * is specified in the native indices of the UText provider. These may not necessarily
653 * @param ut the UText from which to extract data.
672 utext_extract(UText *ut,
680 * iteration position. The iteration position of each UText will be left following
685 * in a UText are accessed one code point at a time, and may not be from a UTF-16
705 utext_compare(UText *s1, int32_t length1,
706 UText *s2, int32_t length2);
710 * iteration position. The iteration position of each UText will be left following
716 * in a UText are accessed one code point at a time, and may not be from a UTF-16
736 utext_compareNativeLimit(UText *s1, int64_t limit1,
737 UText *s2, int64_t limit2);
742 * UText will be left following the last character compared.
745 * in a UText are accessed one code point at a time, and may not be from a UTF-16
774 utext_caseCompare(UText *s1, int32_t length1,
775 UText *s2, int32_t length2,
781 * UText will be left following the last character compared. This method differs from
786 * in a UText are accessed one code point at a time, and may not be from a UTF-16
815 utext_caseCompareNativeLimit(UText *s1, int64_t limit1,
816 UText *s2, int64_t limit2,
838 * Get the code point at the current iteration position of the UText.
851 * Get the code point at the current iteration position of the UText, and
919 * modify a read-only UText will return an error status.
927 * be of a type that supports writing and the UText must not be frozen.
933 * @param ut the UText to be tested.
943 utext_isWritable(const UText *ut);
950 * @param ut The UText to be tested
955 utext_hasMetaData(const UText *ut);
964 * This function is only available on UText types that support writing,
967 * When using this function, there should be only a single UText opened onto the
969 * on a UText is undefined for any other additional UTexts that refer to the
972 * @param ut the UText representing the text to be operated on.
986 utext_replace(UText *ut,
1006 * This function is only available on UText types that support writing,
1009 * When using this function, there should be only a single UText opened onto the
1011 * on a UText is undefined in any other additional UTexts that refer to the
1014 * @param ut The UText representing the text to be operated on.
1026 utext_copy(UText *ut,
1035 * Freeze a UText. This prevents any modification to the underlying text itself
1036 * by means of functions operating on this UText.
1039 * Once frozen, a UText can not be unfrozen. The intent is to ensure
1040 * that a the text underlying a frozen UText wrapper cannot be modified via that UText.
1043 * Caution: freezing a UText will disable changes made via the specific
1044 * frozen UText wrapper only; it will not have any effect on the ability to
1045 * directly modify the text by bypassing the UText. Any such backdoor modifications
1046 * are always an error while UText access is occuring because the underlying
1047 * text can get out of sync with UText's buffering.
1050 * @param ut The UText to be frozen.
1055 utext_freeze(UText *ut);
1059 * UText provider properties (bit field indexes).
1061 * @see UText
1092 * Generally occurs as the result of a deep clone of the UText.
1093 * When closing the UText, the associated text must
1101 * Function type declaration for UText.clone().
1103 * clone a UText. Much like opening a UText where the source text is itself
1104 * another UText.
1106 * A deep clone will copy both the UText data structures and the underlying text.
1107 * The original and cloned UText will operate completely independently; modifications
1112 * A shallow clone replicates only the UText data structures; it does not make
1120 * A UText and its clone may be safely concurrently accessed by separate threads.
1126 * @param dest A UText struct to be filled in with the result of the clone operation,
1127 * or NULL if the clone function should heap-allocate a new UText struct.
1128 * @param src The UText to be cloned.
1137 typedef UText * U_CALLCONV
1138 UTextClone(UText *dest, const UText *src, UBool deep, UErrorCode *status);
1142 * Function type declaration for UText.nativeLength().
1144 * @param ut the UText to get the length of.
1146 * @see UText
1150 UTextNativeLength(UText *ut);
1153 * Function type declaration for UText.access(). Get the description of the text chunk
1154 * containing the text at a requested native index. The UText's iteration
1163 * @param ut the UText being accessed.
1174 * @see UText
1178 UTextAccess(UText *ut, int64_t nativeIndex, UBool forward);
1181 * Function type declaration for UText.extract().
1183 * Extract text from a UText into a UChar buffer. The range of text to be extracted
1184 * is specified in the native indices of the UText provider. These may not necessarily
1193 * @param ut the UText from which to extract data.
1208 UTextExtract(UText *ut,
1214 * Function type declaration for UText.replace().
1221 * This function need only be implemented on UText types that support writing.
1223 * When using this function, there should be only a single UText opened onto the
1225 * text chunk within the UText to reflect the updated iteration position,
1229 * @param ut the UText representing the text to be operated on.
1243 UTextReplace(UText *ut,
1249 * Function type declaration for UText.copy().
1259 * This function need only be implemented for UText types that support writing.
1261 * When using this function, there should be only a single UText opened onto the
1263 * text chunk within the UText to reflect the updated iteration position,
1267 * @param ut The UText representing the text to be operated on.
1277 UTextCopy(UText *ut,
1284 * Function type declaration for UText.mapOffsetToNative().
1290 * @param ut the UText.
1297 UTextMapOffsetToNative(const UText *ut);
1300 * Function type declaration for UText.mapIndexToUTF16().
1307 * @param ut The UText containing the text chunk.
1315 UTextMapNativeIndexToUTF16(const UText *ut, int64_t nativeIndex);
1319 * Function type declaration for UText.utextClose().
1323 * cleaned when the UText is closed.
1325 * The allocation of the UText struct itself and any "extra" storage
1326 * associated with the UText is handled by the common UText implementation
1329 * Most UText provider implementations do not need to implement this function.
1331 * @param ut A UText object to be closed.
1336 UTextClose(UText *ut);
1340 * (public) Function dispatch table for UText.
1367 * Do not use, reserved for use by the UText framework only.
1466 * Function dispatch table for UText
1472 * UText struct. Provides the interface between the generic UText access code
1473 * and the UText provider code that works on specific kinds of
1478 * internals of the UText structs that they open.
1482 struct UText {
1484 * (private) Magic. Used to help detect when UText functions are handed
1485 * invalid or unitialized UText structs.
1487 * but not necessarily open, UText struct as an
1492 * reuse of the UText struct.
1500 * memory associated with this UText.
1514 * (public) sizeOfStruct=sizeof(UText)
1573 * if conversion was required, to a buffer owned by the UText.
1579 * (public) Pointer to Dispatch table for accessing functions for this UText.
1593 * This is the source of the text that this UText is wrapping, in a format
1603 * Not used by UText common code.
1609 * Not used by UText common code.
1615 * Not used by UText common code.
1621 * Private field reserved for future use by the UText framework
1633 * Not used by the UText framework, or by the client (user) of the UText.
1640 * Not used by the UText framework, or by the client (user) of the UText.
1647 * Not used by the UText framework, or by the client (user) of the UText.
1656 * Private field reserved for future use by the UText framework
1662 * Private field reserved for future use by the UText framework
1668 * Private field reserved for future use by the UText framework
1678 * a new UText struct. To be called in the implementation of utext_open() functions.
1679 * If the supplied UText parameter is null, a new UText struct will be allocated on the heap.
1680 * If the supplied UText is already open, the provider's close function will be called
1683 * @param ut pointer to a UText struct to be re-used, or null if a new UText
1686 * of this UText, for use by types of providers that require
1689 * @return pointer to the UText, allocated if necessary, with extra space set up if requested.
1692 U_STABLE UText * U_EXPORT2
1693 utext_setup(UText *ut, int32_t extraSpace, UErrorCode *status);
1697 * Value used to help identify correctly initialized UText structs.
1705 * initializer to be used with local (stack) instances of a UText
1706 * struct. UText structs must be initialized before passing
1715 sizeof(UText), /* sizeOfStruct */ \
