1// Copyright (C) 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
18U_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 */
44typedef 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 */
53typedef 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
155U_CDECL_END
156
157#endif
158