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 * @addtogroup icu4c ICU4C 35 * @{ 36 * \file 37 * \brief C API: Callbacks for UReplaceable 38 */ 39 /** 40 * An opaque replaceable text object. This will be manipulated only 41 * through the caller-supplied UReplaceableFunctor struct. Related 42 * to the C++ class Replaceable. 43 * This is currently only used in the Transliterator C API, see utrans.h . 44 * \xrefitem stable "Stable" "Stable List" ICU 2.0 45 */ 46 typedef void* UReplaceable; 47 48 /** 49 * A set of function pointers that transliterators use to manipulate a 50 * UReplaceable. The caller should supply the required functions to 51 * manipulate their text appropriately. Related to the C++ class 52 * Replaceable. 53 * \xrefitem stable "Stable" "Stable List" ICU 2.0 54 */ 55 typedef struct UReplaceableCallbacks { 56 57 /** 58 * Function pointer that returns the number of UChar code units in 59 * this text. 60 * 61 * @param rep A pointer to "this" UReplaceable object. 62 * @return The length of the text. 63 * \xrefitem stable "Stable" "Stable List" ICU 2.0 64 */ 65 int32_t (*length)(const UReplaceable* rep); 66 67 /** 68 * Function pointer that returns a UChar code units at the given 69 * offset into this text; 0 <= offset < n, where n is the value 70 * returned by (*length)(rep). See unistr.h for a description of 71 * charAt() vs. char32At(). 72 * 73 * @param rep A pointer to "this" UReplaceable object. 74 * @param offset The index at which to fetch the UChar (code unit). 75 * @return The UChar (code unit) at offset, or U+FFFF if the offset is out of bounds. 76 * \xrefitem stable "Stable" "Stable List" ICU 2.0 77 */ 78 UChar (*charAt)(const UReplaceable* rep, 79 int32_t offset); 80 81 /** 82 * Function pointer that returns a UChar32 code point at the given 83 * offset into this text. See unistr.h for a description of 84 * charAt() vs. char32At(). 85 * 86 * @param rep A pointer to "this" UReplaceable object. 87 * @param offset The index at which to fetch the UChar32 (code point). 88 * @return The UChar32 (code point) at offset, or U+FFFF if the offset is out of bounds. 89 * \xrefitem stable "Stable" "Stable List" ICU 2.0 90 */ 91 UChar32 (*char32At)(const UReplaceable* rep, 92 int32_t offset); 93 94 /** 95 * Function pointer that replaces text between start and limit in 96 * this text with the given text. Attributes (out of band info) 97 * should be retained. 98 * 99 * @param rep A pointer to "this" UReplaceable object. 100 * @param start the starting index of the text to be replaced, 101 * inclusive. 102 * @param limit the ending index of the text to be replaced, 103 * exclusive. 104 * @param text the new text to replace the UChars from 105 * start..limit-1. 106 * @param textLength the number of UChars at text, or -1 if text 107 * is null-terminated. 108 * \xrefitem stable "Stable" "Stable List" ICU 2.0 109 */ 110 void (*replace)(UReplaceable* rep, 111 int32_t start, 112 int32_t limit, 113 const UChar* text, 114 int32_t textLength); 115 116 /** 117 * Function pointer that copies the characters in the range 118 * [<tt>start</tt>, <tt>limit</tt>) into the array <tt>dst</tt>. 119 * 120 * @param rep A pointer to "this" UReplaceable object. 121 * @param start offset of first character which will be copied 122 * into the array 123 * @param limit offset immediately following the last character to 124 * be copied 125 * @param dst array in which to copy characters. The length of 126 * <tt>dst</tt> must be at least <tt>(limit - start)</tt>. 127 * \xrefitem stable "Stable" "Stable List" ICU 2.1 128 */ 129 void (*extract)(UReplaceable* rep, 130 int32_t start, 131 int32_t limit, 132 UChar* dst); 133 134 /** 135 * Function pointer that copies text between start and limit in 136 * this text to another index in the text. Attributes (out of 137 * band info) should be retained. After this call, there will be 138 * (at least) two copies of the characters originally located at 139 * start..limit-1. 140 * 141 * @param rep A pointer to "this" UReplaceable object. 142 * @param start the starting index of the text to be copied, 143 * inclusive. 144 * @param limit the ending index of the text to be copied, 145 * exclusive. 146 * @param dest the index at which the copy of the UChars should be 147 * inserted. 148 * \xrefitem stable "Stable" "Stable List" ICU 2.0 149 */ 150 void (*copy)(UReplaceable* rep, 151 int32_t start, 152 int32_t limit, 153 int32_t dest); 154 155 } UReplaceableCallbacks; 156 157 U_CDECL_END 158 159 #endif 160 161 /** @} */ // addtogroup 162