urep.h (5507B)
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 * \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 */ 44 typedef 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 */ 53 typedef 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 155 U_CDECL_END 156 157 #endif