icuSources/common/unicode/urep.h

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