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