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