icuSources/common/unicode/urep.h

   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