sl@0: /*
sl@0: ******************************************************************************
sl@0: *   Copyright (C) 1997-2005, International Business Machines
sl@0: *   Corporation and others.  All Rights Reserved.
sl@0: ******************************************************************************
sl@0: *   Date        Name        Description
sl@0: *   06/23/00    aliu        Creation.
sl@0: ******************************************************************************
sl@0: */
sl@0: 
sl@0: #ifndef __UREP_H
sl@0: #define __UREP_H
sl@0: 
sl@0: #include "unicode/utypes.h"
sl@0: 
sl@0: U_CDECL_BEGIN
sl@0: 
sl@0: /********************************************************************
sl@0:  * General Notes
sl@0:  ********************************************************************
sl@0:  * TODO
sl@0:  * Add usage scenario
sl@0:  * Add test code
sl@0:  * Talk about pinning
sl@0:  * Talk about "can truncate result if out of memory"
sl@0:  */
sl@0: 
sl@0: /********************************************************************
sl@0:  * Data Structures
sl@0:  ********************************************************************/
sl@0: /**
sl@0:  * \file
sl@0:  * \brief C API: Callbacks for UReplacebale
sl@0:  */
sl@0: /**
sl@0:  * An opaque replaceable text object.  This will be manipulated only
sl@0:  * through the caller-supplied UReplaceableFunctor struct.  Related
sl@0:  * to the C++ class Replaceable.
sl@0:  * This is currently only used in the Transliterator C API, see utrans.h .
sl@0:  * @stable ICU 2.0
sl@0:  */
sl@0: typedef void* UReplaceable;
sl@0: 
sl@0: /**
sl@0:  * A set of function pointers that transliterators use to manipulate a
sl@0:  * UReplaceable.  The caller should supply the required functions to
sl@0:  * manipulate their text appropriately.  Related to the C++ class
sl@0:  * Replaceable.
sl@0:  * @stable ICU 2.0
sl@0:  */
sl@0: typedef struct UReplaceableCallbacks {
sl@0: 
sl@0:     /**
sl@0:      * Function pointer that returns the number of UChar code units in
sl@0:      * this text.
sl@0:      *
sl@0:      * @param rep A pointer to "this" UReplaceable object.
sl@0:      * @return The length of the text.
sl@0:      * @stable ICU 2.0
sl@0:      */
sl@0:     int32_t (*length)(const UReplaceable* rep);
sl@0: 
sl@0:     /**
sl@0:      * Function pointer that returns a UChar code units at the given
sl@0:      * offset into this text; 0 <= offset < n, where n is the value
sl@0:      * returned by (*length)(rep).  See unistr.h for a description of
sl@0:      * charAt() vs. char32At().
sl@0:      *
sl@0:      * @param rep A pointer to "this" UReplaceable object.
sl@0:      * @param offset The index at which to fetch the UChar (code unit).
sl@0:      * @return The UChar (code unit) at offset, or U+FFFF if the offset is out of bounds.
sl@0:      * @stable ICU 2.0
sl@0:      */
sl@0:     UChar   (*charAt)(const UReplaceable* rep,
sl@0:                       int32_t offset);
sl@0: 
sl@0:     /**
sl@0:      * Function pointer that returns a UChar32 code point at the given
sl@0:      * offset into this text.  See unistr.h for a description of
sl@0:      * charAt() vs. char32At().
sl@0:      *
sl@0:      * @param rep A pointer to "this" UReplaceable object.
sl@0:      * @param offset The index at which to fetch the UChar32 (code point).
sl@0:      * @return The UChar32 (code point) at offset, or U+FFFF if the offset is out of bounds.
sl@0:      * @stable ICU 2.0
sl@0:      */
sl@0:     UChar32 (*char32At)(const UReplaceable* rep,
sl@0:                         int32_t offset);
sl@0:     
sl@0:     /**
sl@0:      * Function pointer that replaces text between start and limit in
sl@0:      * this text with the given text.  Attributes (out of band info)
sl@0:      * should be retained.
sl@0:      *
sl@0:      * @param rep A pointer to "this" UReplaceable object.
sl@0:      * @param start the starting index of the text to be replaced,
sl@0:      * inclusive.
sl@0:      * @param limit the ending index of the text to be replaced,
sl@0:      * exclusive.
sl@0:      * @param text the new text to replace the UChars from
sl@0:      * start..limit-1.
sl@0:      * @param textLength the number of UChars at text, or -1 if text
sl@0:      * is null-terminated.
sl@0:      * @stable ICU 2.0
sl@0:      */
sl@0:     void    (*replace)(UReplaceable* rep,
sl@0:                        int32_t start,
sl@0:                        int32_t limit,
sl@0:                        const UChar* text,
sl@0:                        int32_t textLength);
sl@0:     
sl@0:     /**
sl@0:      * Function pointer that copies the characters in the range
sl@0:      * [<tt>start</tt>, <tt>limit</tt>) into the array <tt>dst</tt>.
sl@0:      *
sl@0:      * @param rep A pointer to "this" UReplaceable object.
sl@0:      * @param start offset of first character which will be copied
sl@0:      * into the array
sl@0:      * @param limit offset immediately following the last character to
sl@0:      * be copied
sl@0:      * @param dst array in which to copy characters.  The length of
sl@0:      * <tt>dst</tt> must be at least <tt>(limit - start)</tt>.
sl@0:      * @stable ICU 2.1
sl@0:      */
sl@0:     void    (*extract)(UReplaceable* rep,
sl@0:                        int32_t start,
sl@0:                        int32_t limit,
sl@0:                        UChar* dst);
sl@0: 
sl@0:     /**
sl@0:      * Function pointer that copies text between start and limit in
sl@0:      * this text to another index in the text.  Attributes (out of
sl@0:      * band info) should be retained.  After this call, there will be
sl@0:      * (at least) two copies of the characters originally located at
sl@0:      * start..limit-1.
sl@0:      *
sl@0:      * @param rep A pointer to "this" UReplaceable object.
sl@0:      * @param start the starting index of the text to be copied,
sl@0:      * inclusive.
sl@0:      * @param limit the ending index of the text to be copied,
sl@0:      * exclusive.
sl@0:      * @param dest the index at which the copy of the UChars should be
sl@0:      * inserted.
sl@0:      * @stable ICU 2.0
sl@0:      */
sl@0:     void    (*copy)(UReplaceable* rep,
sl@0:                     int32_t start,
sl@0:                     int32_t limit,
sl@0:                     int32_t dest);    
sl@0: 
sl@0: } UReplaceableCallbacks;
sl@0: 
sl@0: U_CDECL_END
sl@0: 
sl@0: #endif