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
16U_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 */
42typedef 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 */
51typedef 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
153U_CDECL_END
154
155#endif
156