icuSources/i18n/unicode/unirepl.h

   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