1 // © 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
3 /*
4 ******************************************************************************
5 *   Copyright (C) 1997-2010, International Business Machines
6 *   Corporation and others.  All Rights Reserved.
7 ******************************************************************************
8 *   Date        Name        Description
9 *   06/23/00    aliu        Creation.
10 ******************************************************************************
11 */
12 
13 #ifndef __UREP_H
14 #define __UREP_H
15 
16 #include "unicode/utypes.h"
17 
18 U_CDECL_BEGIN
19 
20 /********************************************************************
21  * General Notes
22  ********************************************************************
23  * TODO
24  * Add usage scenario
25  * Add test code
26  * Talk about pinning
27  * Talk about "can truncate result if out of memory"
28  */
29 
30 /********************************************************************
31  * Data Structures
32  ********************************************************************/
33 /**
34  * \file
35  * \brief C API: Callbacks for UReplaceable
36  */
37 /**
38  * An opaque replaceable text object.  This will be manipulated only
39  * through the caller-supplied UReplaceableFunctor struct.  Related
40  * to the C++ class Replaceable.
41  * This is currently only used in the Transliterator C API, see utrans.h .
42  * @stable ICU 2.0
43  */
44 typedef void* UReplaceable;
45 
46 /**
47  * A set of function pointers that transliterators use to manipulate a
48  * UReplaceable.  The caller should supply the required functions to
49  * manipulate their text appropriately.  Related to the C++ class
50  * Replaceable.
51  * @stable ICU 2.0
52  */
53 typedef struct UReplaceableCallbacks {
54 
55     /**
56      * Function pointer that returns the number of UChar code units in
57      * this text.
58      *
59      * @param rep A pointer to "this" UReplaceable object.
60      * @return The length of the text.
61      * @stable ICU 2.0
62      */
63     int32_t (*length)(const UReplaceable* rep);
64 
65     /**
66      * Function pointer that returns a UChar code units at the given
67      * offset into this text; 0 <= offset < n, where n is the value
68      * returned by (*length)(rep).  See unistr.h for a description of
69      * charAt() vs. char32At().
70      *
71      * @param rep A pointer to "this" UReplaceable object.
72      * @param offset The index at which to fetch the UChar (code unit).
73      * @return The UChar (code unit) at offset, or U+FFFF if the offset is out of bounds.
74      * @stable ICU 2.0
75      */
76     UChar   (*charAt)(const UReplaceable* rep,
77                       int32_t offset);
78 
79     /**
80      * Function pointer that returns a UChar32 code point at the given
81      * offset into this text.  See unistr.h for a description of
82      * charAt() vs. char32At().
83      *
84      * @param rep A pointer to "this" UReplaceable object.
85      * @param offset The index at which to fetch the UChar32 (code point).
86      * @return The UChar32 (code point) at offset, or U+FFFF if the offset is out of bounds.
87      * @stable ICU 2.0
88      */
89     UChar32 (*char32At)(const UReplaceable* rep,
90                         int32_t offset);
91 
92     /**
93      * Function pointer that replaces text between start and limit in
94      * this text with the given text.  Attributes (out of band info)
95      * should be retained.
96      *
97      * @param rep A pointer to "this" UReplaceable object.
98      * @param start the starting index of the text to be replaced,
99      * inclusive.
100      * @param limit the ending index of the text to be replaced,
101      * exclusive.
102      * @param text the new text to replace the UChars from
103      * start..limit-1.
104      * @param textLength the number of UChars at text, or -1 if text
105      * is null-terminated.
106      * @stable ICU 2.0
107      */
108     void    (*replace)(UReplaceable* rep,
109                        int32_t start,
110                        int32_t limit,
111                        const UChar* text,
112                        int32_t textLength);
113 
114     /**
115      * Function pointer that copies the characters in the range
116      * [<tt>start</tt>, <tt>limit</tt>) into the array <tt>dst</tt>.
117      *
118      * @param rep A pointer to "this" UReplaceable object.
119      * @param start offset of first character which will be copied
120      * into the array
121      * @param limit offset immediately following the last character to
122      * be copied
123      * @param dst array in which to copy characters.  The length of
124      * <tt>dst</tt> must be at least <tt>(limit - start)</tt>.
125      * @stable ICU 2.1
126      */
127     void    (*extract)(UReplaceable* rep,
128                        int32_t start,
129                        int32_t limit,
130                        UChar* dst);
131 
132     /**
133      * Function pointer that copies text between start and limit in
134      * this text to another index in the text.  Attributes (out of
135      * band info) should be retained.  After this call, there will be
136      * (at least) two copies of the characters originally located at
137      * start..limit-1.
138      *
139      * @param rep A pointer to "this" UReplaceable object.
140      * @param start the starting index of the text to be copied,
141      * inclusive.
142      * @param limit the ending index of the text to be copied,
143      * exclusive.
144      * @param dest the index at which the copy of the UChars should be
145      * inserted.
146      * @stable ICU 2.0
147      */
148     void    (*copy)(UReplaceable* rep,
149                     int32_t start,
150                     int32_t limit,
151                     int32_t dest);
152 
153 } UReplaceableCallbacks;
154 
155 U_CDECL_END
156 
157 #endif
158