1/*
2**********************************************************************
3*   Copyright (c) 2002-2005, International Business Machines Corporation
4*   and others.  All Rights Reserved.
5**********************************************************************
6*   Date        Name        Description
7*   01/14/2002  aliu        Creation.
8**********************************************************************
9*/
10#ifndef UNIREPL_H
11#define UNIREPL_H
12
13#include "unicode/utypes.h"
14
15/**
16 * \file
17 * \brief C++ API: UnicodeReplacer
18 */
19
20U_NAMESPACE_BEGIN
21
22class Replaceable;
23class UnicodeString;
24class UnicodeSet;
25
26/**
27 * <code>UnicodeReplacer</code> defines a protocol for objects that
28 * replace a range of characters in a Replaceable string with output
29 * text.  The replacement is done via the Replaceable API so as to
30 * preserve out-of-band data.
31 *
32 * <p>This is a mixin class.
33 * @author Alan Liu
34 * @stable ICU 2.4
35 */
36class U_I18N_API UnicodeReplacer /* not : public UObject because this is an interface/mixin class */ {
37
38 public:
39
40    /**
41     * Destructor.
42     * @stable ICU 2.4
43     */
44    virtual ~UnicodeReplacer();
45
46    /**
47     * Replace characters in 'text' from 'start' to 'limit' with the
48     * output text of this object.  Update the 'cursor' parameter to
49     * give the cursor position and return the length of the
50     * replacement text.
51     *
52     * @param text the text to be matched
53     * @param start inclusive start index of text to be replaced
54     * @param limit exclusive end index of text to be replaced;
55     * must be greater than or equal to start
56     * @param cursor output parameter for the cursor position.
57     * Not all replacer objects will update this, but in a complete
58     * tree of replacer objects, representing the entire output side
59     * of a transliteration rule, at least one must update it.
60     * @return the number of 16-bit code units in the text replacing
61     * the characters at offsets start..(limit-1) in text
62     * @stable ICU 2.4
63     */
64    virtual int32_t replace(Replaceable& text,
65                            int32_t start,
66                            int32_t limit,
67                            int32_t& cursor) = 0;
68
69    /**
70     * Returns a string representation of this replacer.  If the
71     * result of calling this function is passed to the appropriate
72     * parser, typically TransliteratorParser, it will produce another
73     * replacer that is equal to this one.
74     * @param result the string to receive the pattern.  Previous
75     * contents will be deleted.
76     * @param escapeUnprintable if TRUE then convert unprintable
77     * character to their hex escape representations, \\uxxxx or
78     * \\Uxxxxxxxx.  Unprintable characters are defined by
79     * Utility.isUnprintable().
80     * @return a reference to 'result'.
81     * @stable ICU 2.4
82     */
83    virtual UnicodeString& toReplacerPattern(UnicodeString& result,
84                                             UBool escapeUnprintable) const = 0;
85
86    /**
87     * Union the set of all characters that may output by this object
88     * into the given set.
89     * @param toUnionTo the set into which to union the output characters
90     * @stable ICU 2.4
91     */
92    virtual void addReplacementSetTo(UnicodeSet& toUnionTo) const = 0;
93};
94
95U_NAMESPACE_END
96
97#endif
98