/*

******************************************************************************

*   Copyright (C) 1997-2005, International Business Machines

*   Corporation and others.  All Rights Reserved.

******************************************************************************

*   Date        Name        Description

*   06/23/00    aliu        Creation.

******************************************************************************

*/

#ifndef __UREP_H

#define __UREP_H

#include "unicode/utypes.h"

U_CDECL_BEGIN

/********************************************************************

 * General Notes

 ********************************************************************

 * TODO

 * Add usage scenario

 * Add test code

 * Talk about pinning

 * Talk about "can truncate result if out of memory"

 */

/********************************************************************

 * Data Structures

 ********************************************************************/

/**

 * \file

 * \brief C API: Callbacks for UReplacebale

 */

/**

 * An opaque replaceable text object.  This will be manipulated only

 * through the caller-supplied UReplaceableFunctor struct.  Related

 * to the C++ class Replaceable.

 * This is currently only used in the Transliterator C API, see utrans.h .

 * @stable ICU 2.0

 */

typedef void* UReplaceable;

/**

 * A set of function pointers that transliterators use to manipulate a

 * UReplaceable.  The caller should supply the required functions to

 * manipulate their text appropriately.  Related to the C++ class

 * Replaceable.

 * @stable ICU 2.0

 */

typedef struct UReplaceableCallbacks {

    /**

     * Function pointer that returns the number of UChar code units in

     * this text.

     *

     * @param rep A pointer to "this" UReplaceable object.

     * @return The length of the text.

     * @stable ICU 2.0

     */

    int32_t (*length)(const UReplaceable* rep);

    /**

     * Function pointer that returns a UChar code units at the given

     * offset into this text; 0 <= offset < n, where n is the value

     * returned by (*length)(rep).  See unistr.h for a description of

     * charAt() vs. char32At().

     *

     * @param rep A pointer to "this" UReplaceable object.

     * @param offset The index at which to fetch the UChar (code unit).

     * @return The UChar (code unit) at offset, or U+FFFF if the offset is out of bounds.

     * @stable ICU 2.0

     */

    UChar   (*charAt)(const UReplaceable* rep,

                      int32_t offset);

    /**

     * Function pointer that returns a UChar32 code point at the given

     * offset into this text.  See unistr.h for a description of

     * charAt() vs. char32At().

     *

     * @param rep A pointer to "this" UReplaceable object.

     * @param offset The index at which to fetch the UChar32 (code point).

     * @return The UChar32 (code point) at offset, or U+FFFF if the offset is out of bounds.

     * @stable ICU 2.0

     */

    UChar32 (*char32At)(const UReplaceable* rep,

                        int32_t offset);

    /**

     * Function pointer that replaces text between start and limit in

     * this text with the given text.  Attributes (out of band info)

     * should be retained.

     *

     * @param rep A pointer to "this" UReplaceable object.

     * @param start the starting index of the text to be replaced,

     * inclusive.

     * @param limit the ending index of the text to be replaced,

     * exclusive.

     * @param text the new text to replace the UChars from

     * start..limit-1.

     * @param textLength the number of UChars at text, or -1 if text

     * is null-terminated.

     * @stable ICU 2.0

     */

    void    (*replace)(UReplaceable* rep,

                       int32_t start,

                       int32_t limit,

                       const UChar* text,

                       int32_t textLength);

    /**

     * Function pointer that copies the characters in the range

     * [<tt>start</tt>, <tt>limit</tt>) into the array <tt>dst</tt>.

     *

     * @param rep A pointer to "this" UReplaceable object.

     * @param start offset of first character which will be copied

     * into the array

     * @param limit offset immediately following the last character to

     * be copied

     * @param dst array in which to copy characters.  The length of

     * <tt>dst</tt> must be at least <tt>(limit - start)</tt>.

     * @stable ICU 2.1

     */

    void    (*extract)(UReplaceable* rep,

                       int32_t start,

                       int32_t limit,

                       UChar* dst);

    /**

     * Function pointer that copies text between start and limit in

     * this text to another index in the text.  Attributes (out of

     * band info) should be retained.  After this call, there will be

     * (at least) two copies of the characters originally located at

     * start..limit-1.

     *

     * @param rep A pointer to "this" UReplaceable object.

     * @param start the starting index of the text to be copied,

     * inclusive.

     * @param limit the ending index of the text to be copied,

     * exclusive.

     * @param dest the index at which the copy of the UChars should be

     * inserted.

     * @stable ICU 2.0

     */

    void    (*copy)(UReplaceable* rep,

                    int32_t start,

                    int32_t limit,

                    int32_t dest);    

} UReplaceableCallbacks;

U_CDECL_END

#endif