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 
20 U_NAMESPACE_BEGIN
21 
22 class Replaceable;
23 class UnicodeString;
24 class 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  */
36 class 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 
95 U_NAMESPACE_END
96 
97 #endif
98