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