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, icu::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 icu::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, icu::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, icu::CharacterIterator *ci, 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,
698 * Get the code point at the current iteration position of the UText.
712 * Get the code point at the current iteration position of the UText, and
780 * modify a read-only UText will return an error status.
788 * be of a type that supports writing and the UText must not be frozen.
794 * @param ut the UText to be tested.
804 utext_isWritable(const UText *ut);
811 * @param ut The UText to be tested
816 utext_hasMetaData(const UText *ut);
825 * This function is only available on UText types that support writing,
828 * When using this function, there should be only a single UText opened onto the
830 * on a UText is undefined for any other additional UTexts that refer to the
833 * @param ut the UText representing the text to be operated on.
847 utext_replace(UText *ut,
867 * This function is only available on UText types that support writing,
870 * When using this function, there should be only a single UText opened onto the
872 * on a UText is undefined in any other additional UTexts that refer to the
875 * @param ut The UText representing the text to be operated on.
887 utext_copy(UText *ut,
896 * Freeze a UText. This prevents any modification to the underlying text itself
897 * by means of functions operating on this UText.
900 * Once frozen, a UText can not be unfrozen. The intent is to ensure
901 * that a the text underlying a frozen UText wrapper cannot be modified via that UText.
904 * Caution: freezing a UText will disable changes made via the specific
905 * frozen UText wrapper only; it will not have any effect on the ability to
906 * directly modify the text by bypassing the UText. Any such backdoor modifications
907 * are always an error while UText access is occuring because the underlying
908 * text can get out of sync with UText's buffering.
911 * @param ut The UText to be frozen.
916 utext_freeze(UText *ut);
920 * UText provider properties (bit field indexes).
922 * @see UText
953 * Generally occurs as the result of a deep clone of the UText.
954 * When closing the UText, the associated text must
962 * Function type declaration for UText.clone().
964 * clone a UText. Much like opening a UText where the source text is itself
965 * another UText.
967 * A deep clone will copy both the UText data structures and the underlying text.
968 * The original and cloned UText will operate completely independently; modifications
973 * A shallow clone replicates only the UText data structures; it does not make
981 * A UText and its clone may be safely concurrently accessed by separate threads.
987 * @param dest A UText struct to be filled in with the result of the clone operation,
988 * or NULL if the clone function should heap-allocate a new UText struct.
989 * @param src The UText to be cloned.
998 typedef UText * U_CALLCONV
999 UTextClone(UText *dest, const UText *src, UBool deep, UErrorCode *status);
1003 * Function type declaration for UText.nativeLength().
1005 * @param ut the UText to get the length of.
1007 * @see UText
1011 UTextNativeLength(UText *ut);
1014 * Function type declaration for UText.access(). Get the description of the text chunk
1015 * containing the text at a requested native index. The UText's iteration
1024 * @param ut the UText being accessed.
1035 * @see UText
1039 UTextAccess(UText *ut, int64_t nativeIndex, UBool forward);
1042 * Function type declaration for UText.extract().
1044 * Extract text from a UText into a UChar buffer. The range of text to be extracted
1045 * is specified in the native indices of the UText provider. These may not necessarily
1054 * @param ut the UText from which to extract data.
1069 UTextExtract(UText *ut,
1075 * Function type declaration for UText.replace().
1082 * This function need only be implemented on UText types that support writing.
1084 * When using this function, there should be only a single UText opened onto the
1086 * text chunk within the UText to reflect the updated iteration position,
1090 * @param ut the UText representing the text to be operated on.
1104 UTextReplace(UText *ut,
1110 * Function type declaration for UText.copy().
1120 * This function need only be implemented for UText types that support writing.
1122 * When using this function, there should be only a single UText opened onto the
1124 * text chunk within the UText to reflect the updated iteration position,
1128 * @param ut The UText representing the text to be operated on.
1138 UTextCopy(UText *ut,
1145 * Function type declaration for UText.mapOffsetToNative().
1151 * @param ut the UText.
1158 UTextMapOffsetToNative(const UText *ut);
1161 * Function type declaration for UText.mapIndexToUTF16().
1168 * @param ut The UText containing the text chunk.
1176 UTextMapNativeIndexToUTF16(const UText *ut, int64_t nativeIndex);
1180 * Function type declaration for UText.utextClose().
1184 * cleaned when the UText is closed.
1186 * The allocation of the UText struct itself and any "extra" storage
1187 * associated with the UText is handled by the common UText implementation
1190 * Most UText provider implementations do not need to implement this function.
1192 * @param ut A UText object to be closed.
1197 UTextClose(UText *ut);
1201 * (public) Function dispatch table for UText.
1228 * Do not use, reserved for use by the UText framework only.
1327 * Function dispatch table for UText
1333 * UText struct. Provides the interface between the generic UText access code
1334 * and the UText provider code that works on specific kinds of
1339 * internals of the UText structs that they open.
1343 struct UText {
1345 * (private) Magic. Used to help detect when UText functions are handed
1346 * invalid or unitialized UText structs.
1348 * but not necessarily open, UText struct as an
1353 * reuse of the UText struct.
1361 * memory associated with this UText.
1375 * (public) sizeOfStruct=sizeof(UText)
1434 * if conversion was required, to a buffer owned by the UText.
1440 * (public) Pointer to Dispatch table for accessing functions for this UText.
1454 * This is the source of the text that this UText is wrapping, in a format
1464 * Not used by UText common code.
1470 * Not used by UText common code.
1476 * Not used by UText common code.
1482 * Private field reserved for future use by the UText framework
1494 * Not used by the UText framework, or by the client (user) of the UText.
1501 * Not used by the UText framework, or by the client (user) of the UText.
1508 * Not used by the UText framework, or by the client (user) of the UText.
1517 * Private field reserved for future use by the UText framework
1523 * Private field reserved for future use by the UText framework
1529 * Private field reserved for future use by the UText framework
1539 * a new UText struct. To be called in the implementation of utext_open() functions.
1540 * If the supplied UText parameter is null, a new UText struct will be allocated on the heap.
1541 * If the supplied UText is already open, the provider's close function will be called
1544 * @param ut pointer to a UText struct to be re-used, or null if a new UText
1547 * of this UText, for use by types of providers that require
1550 * @return pointer to the UText, allocated if necessary, with extra space set up if requested.
1553 U_STABLE UText * U_EXPORT2
1554 utext_setup(UText *ut, int32_t extraSpace, UErrorCode *status);
1559 * Value used to help identify correctly initialized UText structs.
1568 * initializer to be used with local (stack) instances of a UText
1569 * struct. UText structs must be initialized before passing
1578 sizeof(UText), /* sizeOfStruct */ \
