Lines Matching defs: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.
148 struct UText;
149 typedef struct UText UText; /**< C typedef for struct UText. @stable ICU 3.6 */
154 * C Functions for creating UText wrappers around various kinds of text strings.
160 * Close function for UText instances.
161 * Cleans up, releases any resources being held by an open UText.
163 * If the UText was originally allocated by one of the utext_open functions,
164 * the storage associated with the utext will also be freed.
165 * If the UText storage originated with the application, as it would with
168 * An open UText can be reset to refer to new string by using one of the utext_open()
169 * functions without first closing the UText.
171 * @param ut The UText to be closed.
172 * @return NULL if the UText struct was deleted by the close. If the UText struct
179 U_STABLE UText * U_EXPORT2
180 utext_close(UText *ut);
184 * Open a read-only UText implementation for UTF-8 strings.
193 * @param ut Pointer to a UText struct. If NULL, a new UText will be created.
194 * If non-NULL, must refer to an initialized UText struct, which will then
200 * @return A pointer to the UText. If a pre-allocated UText was provided, it
204 U_STABLE UText * U_EXPORT2
205 utext_openUTF8(UText *ut, const char *s, int64_t length, UErrorCode *status);
209 * Open a read-only UText for UChar * string.
211 * @param ut Pointer to a UText struct. If NULL, a new UText will be created.
212 * If non-NULL, must refer to an initialized UText struct, which will then
218 * @return A pointer to the UText. If a pre-allocated UText was provided, it
222 U_STABLE UText * U_EXPORT2
223 utext_openUChars(UText *ut, const UChar *s, int64_t length, UErrorCode *status);
228 * Open a writable UText for a non-const UnicodeString.
230 * @param ut Pointer to a UText struct. If NULL, a new UText will be created.
231 * If non-NULL, must refer to an initialized UText struct, which will then
235 * @return Pointer to the UText. If a UText was supplied as input, this
239 U_STABLE UText * U_EXPORT2
240 utext_openUnicodeString(UText *ut, U_NAMESPACE_QUALIFIER UnicodeString *s, UErrorCode *status);
244 * Open a UText for a const UnicodeString. The resulting UText will not be writable.
246 * @param ut Pointer to a UText struct. If NULL, a new UText will be created.
247 * If non-NULL, must refer to an initialized UText struct, which will then
251 * @return Pointer to the UText. If a UText was supplied as input, this
255 U_STABLE UText * U_EXPORT2
256 utext_openConstUnicodeString(UText *ut, const U_NAMESPACE_QUALIFIER UnicodeString *s, UErrorCode *status);
260 * Open a writable UText implementation for an ICU Replaceable object.
261 * @param ut Pointer to a UText struct. If NULL, a new UText will be created.
262 * If non-NULL, must refer to an already existing UText, which will then
266 * @return Pointer to the UText. If a UText was supplied as input, this
271 U_STABLE UText * U_EXPORT2
272 utext_openReplaceable(UText *ut, U_NAMESPACE_QUALIFIER Replaceable *rep, UErrorCode *status);
275 * Open a UText implementation over an ICU CharacterIterator.
276 * @param ut Pointer to a UText struct. If NULL, a new UText will be created.
277 * If non-NULL, must refer to an already existing UText, which will then
281 * @return Pointer to the UText. If a UText was supplied as input, this
286 U_STABLE UText * U_EXPORT2
287 utext_openCharacterIterator(UText *ut, U_NAMESPACE_QUALIFIER CharacterIterator *ic, UErrorCode *status);
293 * Clone a UText. This is much like opening a UText where the source text is itself
294 * another UText.
296 * A deep clone will copy both the UText data structures and the underlying text.
297 * The original and cloned UText will operate completely independently; modifications
302 * The standard UText implementations for UTF8, UChar *, UnicodeString and
305 * The UText returned from a deep clone will be writable, assuming that the text
306 * provider is able to support writing, even if the source UText had been made
309 * A shallow clone replicates only the UText data structures; it does not make
317 * Shallow UText clones should be avoided if the UText functions that modify the
318 * text are expected to be used, either on the original or the cloned UText.
321 * disabling text modification via the cloned UText.
325 * write operations must be avoided while more than one UText exists that refer
328 * A UText and its clone may be safely concurrently accessed by separate threads.
334 * @param dest A UText struct to be filled in with the result of the clone operation,
335 * or NULL if the clone function should heap-allocate a new UText struct.
336 * If non-NULL, must refer to an already existing UText, which will then
338 * @param src The UText to be cloned.
340 * @param readOnly TRUE to request that the cloned UText have read only access to the
349 U_STABLE UText * U_EXPORT2
350 utext_clone(UText *dest, const UText *src, UBool deep, UBool readOnly, UErrorCode *status);
354 * Compare two UText objects for equality.
360 * @param b The other UText to be compared.
365 utext_equals(const UText *a, const UText *b);
370 * Functions to work with the text represeted by a UText wrapper
386 utext_nativeLength(UText *ut);
393 * as the result of other operations on a UText.
402 UText *ut);
430 utext_char32At(UText *ut, int64_t nativeIndex);
444 utext_current32(UText *ut);
448 * Get the code point at the current iteration position of the UText, and
466 utext_next32(UText *ut);
487 utext_previous32(UText *ut);
509 utext_next32From(UText *ut, int64_t nativeIndex);
529 utext_previous32From(UText *ut, int64_t nativeIndex);
544 utext_getNativeIndex(const UText *ut);
570 utext_setNativeIndex(UText *ut, int64_t nativeIndex);
589 utext_moveIndex32(UText *ut, int32_t delta);
599 * UText *ut = whatever;
614 utext_getPreviousNativeIndex(UText *ut);
619 * Extract text from a UText into a UChar buffer. The range of text to be extracted
620 * is specified in the native indices of the UText provider. These may not necessarily
633 * @param ut the UText from which to extract data.
652 utext_extract(UText *ut,
676 * Get the code point at the current iteration position of the UText, and
744 * modify a read-only UText will return an error status.
752 * be of a type that supports writing and the UText must not be frozen.
758 * @param ut the UText to be tested.
768 utext_isWritable(const UText *ut);
775 * @param ut The UText to be tested
780 utext_hasMetaData(const UText *ut);
789 * This function is only available on UText types that support writing,
792 * When using this function, there should be only a single UText opened onto the
794 * on a UText is undefined for any other additional UTexts that refer to the
797 * @param ut the UText representing the text to be operated on.
811 utext_replace(UText *ut,
831 UText types that support writing,
834 * When using this function, there should be only a single UText opened onto the
836 * on a UText is undefined in any other additional UTexts that refer to the
839 * @param ut The UText representing the text to be operated on.
851 utext_copy(UText *ut,
860 * Freeze a UText. This prevents any modification to the underlying text itself
861 * by means of functions operating on this UText.
864 * Once frozen, a UText can not be unfrozen. The intent is to ensure
865 * that a the text underlying a frozen UText wrapper cannot be modified via that UText.
868 * Caution: freezing a UText will disable changes made via the specific
869 * frozen UText wrapper only; it will not have any effect on the ability to
870 * directly modify the text by bypassing the UText. Any such backdoor modifications
871 * are always an error while UText access is occuring because the underlying
872 * text can get out of sync with UText's buffering.
875 * @param ut The UText to be frozen.
880 utext_freeze(UText *ut);
884 * UText provider properties (bit field indexes).
886 * @see UText
917 * Generally occurs as the result of a deep clone of the UText.
918 * When closing the UText, the associated text must
926 * Function type declaration for UText.clone().
928 * clone a UText. Much like opening a UText where the source text is itself
929 * another UText.
931 * A deep clone will copy both the UText data structures and the underlying text.
932 * The original and cloned UText will operate completely independently; modifications
937 * A shallow clone replicates only the UText data structures; it does not make
945 * A UText and its clone may be safely concurrently accessed by separate threads.
951 * @param dest A UText struct to be filled in with the result of the clone operation,
952 * or NULL if the clone function should heap-allocate a new UText struct.
953 * @param src The UText to be cloned.
962 typedef UText * U_CALLCONV
963 UTextClone(UText *dest, const UText *src, UBool deep, UErrorCode *status);
967 * Function type declaration for UText.nativeLength().
969 * @param ut the UText to get the length of.
971 * @see UText
975 UTextNativeLength(UText *ut);
978 * Function type declaration for UText.access(). Get the description of the text chunk
979 * containing the text at a requested native index. The UText's iteration
988 * @param ut the UText being accessed.
999 * @see UText
1003 UTextAccess(UText *ut, int64_t nativeIndex, UBool forward);
1006 * Function type declaration for UText.extract().
1008 * Extract text from a UText into a UChar buffer. The range of text to be extracted
1009 * is specified in the native indices of the UText provider. These may not necessarily
1018 * @param ut the UText from which to extract data.
1033 UTextExtract(UText *ut,
1039 * Function type declaration for UText.replace().
1046 * This function need only be implemented on UText types that support writing.
1048 * When using this function, there should be only a single UText opened onto the
1050 * text chunk within the UText to reflect the updated iteration position,
1054 * @param ut the UText representing the text to be operated on.
1068 UTextReplace(UText *ut,
1074 * Function type declaration for UText.copy().
1084 * This function need only be implemented for UText types that support writing.
1086 * When using this function, there should be only a single UText opened onto the
1088 * text chunk within the UText to reflect the updated iteration position,
1092 * @param ut The UText representing the text to be operated on.
1102 UTextCopy(UText *ut,
1109 * Function type declaration for UText.mapOffsetToNative().
1115 * @param ut the UText.
1122 UTextMapOffsetToNative(const UText *ut);
1125 * Function type declaration for UText.mapIndexToUTF16().
1132 * @param ut The UText containing the text chunk.
1140 UTextMapNativeIndexToUTF16(const UText *ut, int64_t nativeIndex);
1144 * Function type declaration for UText.utextClose().
1148 * cleaned when the UText is closed.
1150 * The allocation of the UText struct itself and any "extra" storage
1151 * associated with the UText is handled by the common UText implementation
1154 * Most UText provider implementations do not need to implement this function.
1156 * @param ut A UText object to be closed.
1161 UTextClose(UText *ut);
1165 * (public) Function dispatch table for UText.
1192 * Do not use, reserved for use by the UText framework only.
1291 * Function dispatch table for UText
1297 * UText struct. Provides the interface between the generic UText access code
1298 * and the UText provider code that works on specific kinds of
1303 * internals of the UText structs that they open.
1307 struct UText {
1309 * (private) Magic. Used to help detect when UText functions are handed
1310 * invalid or unitialized UText structs.
1312 * but not necessarily open, UText struct as an
1317 * reuse of the UText struct.
1325 * memory associated with this UText.
1339 * (public) sizeOfStruct=sizeof(UText)
1398 * if conversion was required, to a buffer owned by the UText.
1404 * (public) Pointer to Dispatch table for accessing functions for this UText.
1418 * This is the source of the text that this UText is wrapping, in a format
1428 * Not used by UText common code.
1434 * Not used by UText common code.
1440 * Not used by UText common code.
1446 * Private field reserved for future use by the UText framework
1458 * Not used by the UText framework, or by the client (user) of the UText.
1465 * Not used by the UText framework, or by the client (user) of the UText.
1472 * Not used by the UText framework, or by the client (user) of the UText.
1481 * Private field reserved for future use by the UText framework
1487 * Private field reserved for future use by the UText framework
1493 * Private field reserved for future use by the UText framework
1503 * a new UText struct. To be called in the implementation of utext_open() functions.
1504 * If the supplied UText parameter is null, a new UText struct will be allocated on the heap.
1505 * If the supplied UText is already open, the provider's close function will be called
1508 * @param ut pointer to a UText struct to be re-used, or null if a new UText
1511 * of this UText, for use by types of providers that require
1514 * @return pointer to the UText, allocated if necessary, with extra space set up if requested.
1517 U_STABLE UText * U_EXPORT2
1518 utext_setup(UText *ut, int32_t extraSpace, UErrorCode *status);
1522 * Value used to help identify correctly initialized UText structs.
1530 * initializer to be used with local (stack) instances of a UText
1531 * struct. UText structs must be initialized before passing
1540 sizeof(UText), /* sizeOfStruct */ \
