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