Check in the pristine copy of ICU 4.6...

icu46/source/common/unicode/urep.h

+/*
+******************************************************************************
+*   Copyright (C) 1997-2010, 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 UReplaceable
+ */
+/**
+ * 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