include/unicode/urep.h

0001 // © 2016 and later: Unicode, Inc. and others.
0002 // License & terms of use: http://www.unicode.org/copyright.html
0003 /*
0004 ******************************************************************************
0005 *   Copyright (C) 1997-2010, International Business Machines
0006 *   Corporation and others.  All Rights Reserved.
0007 ******************************************************************************
0008 *   Date        Name        Description
0009 *   06/23/00    aliu        Creation.
0010 ******************************************************************************
0011 */
0012
0013 #ifndef __UREP_H
0014 #define __UREP_H
0015
0016 #include "unicode/utypes.h"
0017
0018 U_CDECL_BEGIN
0019
0020 /********************************************************************
0021  * General Notes
0022  ********************************************************************
0023  * TODO
0024  * Add usage scenario
0025  * Add test code
0026  * Talk about pinning
0027  * Talk about "can truncate result if out of memory"
0028  */
0029
0030 /********************************************************************
0031  * Data Structures
0032  ********************************************************************/
0033 /**
0034  * \file
0035  * \brief C API: Callbacks for UReplaceable
0036  */
0037 /**
0038  * An opaque replaceable text object.  This will be manipulated only
0039  * through the caller-supplied UReplaceableFunctor struct.  Related
0040  * to the C++ class Replaceable.
0041  * This is currently only used in the Transliterator C API, see utrans.h .
0042  * @stable ICU 2.0
0043  */
0044 typedef void* UReplaceable;
0045
0046 /**
0047  * A set of function pointers that transliterators use to manipulate a
0048  * UReplaceable.  The caller should supply the required functions to
0049  * manipulate their text appropriately.  Related to the C++ class
0050  * Replaceable.
0051  * @stable ICU 2.0
0052  */
0053 typedef struct UReplaceableCallbacks {
0054
0055     /**
0056      * Function pointer that returns the number of UChar code units in
0057      * this text.
0058      *
0059      * @param rep A pointer to "this" UReplaceable object.
0060      * @return The length of the text.
0061      * @stable ICU 2.0
0062      */
0063     int32_t (*length)(const UReplaceable* rep);
0064
0065     /**
0066      * Function pointer that returns a UChar code units at the given
0067      * offset into this text; 0 <= offset < n, where n is the value
0068      * returned by (*length)(rep).  See unistr.h for a description of
0069      * charAt() vs. char32At().
0070      *
0071      * @param rep A pointer to "this" UReplaceable object.
0072      * @param offset The index at which to fetch the UChar (code unit).
0073      * @return The UChar (code unit) at offset, or U+FFFF if the offset is out of bounds.
0074      * @stable ICU 2.0
0075      */
0076     UChar   (*charAt)(const UReplaceable* rep,
0077                       int32_t offset);
0078
0079     /**
0080      * Function pointer that returns a UChar32 code point at the given
0081      * offset into this text.  See unistr.h for a description of
0082      * charAt() vs. char32At().
0083      *
0084      * @param rep A pointer to "this" UReplaceable object.
0085      * @param offset The index at which to fetch the UChar32 (code point).
0086      * @return The UChar32 (code point) at offset, or U+FFFF if the offset is out of bounds.
0087      * @stable ICU 2.0
0088      */
0089     UChar32 (*char32At)(const UReplaceable* rep,
0090                         int32_t offset);
0091
0092     /**
0093      * Function pointer that replaces text between start and limit in
0094      * this text with the given text.  Attributes (out of band info)
0095      * should be retained.
0096      *
0097      * @param rep A pointer to "this" UReplaceable object.
0098      * @param start the starting index of the text to be replaced,
0099      * inclusive.
0100      * @param limit the ending index of the text to be replaced,
0101      * exclusive.
0102      * @param text the new text to replace the UChars from
0103      * start..limit-1.
0104      * @param textLength the number of UChars at text, or -1 if text
0105      * is null-terminated.
0106      * @stable ICU 2.0
0107      */
0108     void    (*replace)(UReplaceable* rep,
0109                        int32_t start,
0110                        int32_t limit,
0111                        const UChar* text,
0112                        int32_t textLength);
0113
0114     /**
0115      * Function pointer that copies the characters in the range
0116      * [<tt>start</tt>, <tt>limit</tt>) into the array <tt>dst</tt>.
0117      *
0118      * @param rep A pointer to "this" UReplaceable object.
0119      * @param start offset of first character which will be copied
0120      * into the array
0121      * @param limit offset immediately following the last character to
0122      * be copied
0123      * @param dst array in which to copy characters.  The length of
0124      * <tt>dst</tt> must be at least <tt>(limit - start)</tt>.
0125      * @stable ICU 2.1
0126      */
0127     void    (*extract)(UReplaceable* rep,
0128                        int32_t start,
0129                        int32_t limit,
0130                        UChar* dst);
0131
0132     /**
0133      * Function pointer that copies text between start and limit in
0134      * this text to another index in the text.  Attributes (out of
0135      * band info) should be retained.  After this call, there will be
0136      * (at least) two copies of the characters originally located at
0137      * start..limit-1.
0138      *
0139      * @param rep A pointer to "this" UReplaceable object.
0140      * @param start the starting index of the text to be copied,
0141      * inclusive.
0142      * @param limit the ending index of the text to be copied,
0143      * exclusive.
0144      * @param dest the index at which the copy of the UChars should be
0145      * inserted.
0146      * @stable ICU 2.0
0147      */
0148     void    (*copy)(UReplaceable* rep,
0149                     int32_t start,
0150                     int32_t limit,
0151                     int32_t dest);
0152
0153 } UReplaceableCallbacks;
0154
0155 U_CDECL_END
0156
0157 #endif