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