icuSources/common/unicode/urep.h

   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