include/unicode/rep.h

0001 // © 2016 and later: Unicode, Inc. and others.
0002 // License & terms of use: http://www.unicode.org/copyright.html
0003 /*
0004 **************************************************************************
0005 * Copyright (C) 1999-2012, International Business Machines Corporation and
0006 * others. All Rights Reserved.
0007 **************************************************************************
0008 *   Date        Name        Description
0009 *   11/17/99    aliu        Creation.  Ported from java.  Modified to
0010 *                           match current UnicodeString API.  Forced
0011 *                           to use name "handleReplaceBetween" because
0012 *                           of existing methods in UnicodeString.
0013 **************************************************************************
0014 */
0015
0016 #ifndef REP_H
0017 #define REP_H
0018
0019 #include "unicode/utypes.h"
0020
0021 #if U_SHOW_CPLUSPLUS_API
0022
0023 #include "unicode/uobject.h"
0024
0025 /**
0026  * \file
0027  * \brief C++ API: Replaceable String
0028  */
0029
0030 U_NAMESPACE_BEGIN
0031
0032 class UnicodeString;
0033
0034 /**
0035  * <code>Replaceable</code> is an abstract base class representing a
0036  * string of characters that supports the replacement of a range of
0037  * itself with a new string of characters.  It is used by APIs that
0038  * change a piece of text while retaining metadata.  Metadata is data
0039  * other than the Unicode characters returned by char32At().  One
0040  * example of metadata is style attributes; another is an edit
0041  * history, marking each character with an author and revision number.
0042  *
0043  * <p>An implicit aspect of the <code>Replaceable</code> API is that
0044  * during a replace operation, new characters take on the metadata of
0045  * the old characters.  For example, if the string "the <b>bold</b>
0046  * font" has range (4, 8) replaced with "strong", then it becomes "the
0047  * <b>strong</b> font".
0048  *
0049  * <p><code>Replaceable</code> specifies ranges using a start
0050  * offset and a limit offset.  The range of characters thus specified
0051  * includes the characters at offset start..limit-1.  That is, the
0052  * start offset is inclusive, and the limit offset is exclusive.
0053  *
0054  * <p><code>Replaceable</code> also includes API to access characters
0055  * in the string: <code>length()</code>, <code>charAt()</code>,
0056  * <code>char32At()</code>, and <code>extractBetween()</code>.
0057  *
0058  * <p>For a subclass to support metadata, typical behavior of
0059  * <code>replace()</code> is the following:
0060  * <ul>
0061  *   <li>Set the metadata of the new text to the metadata of the first
0062  *   character replaced</li>
0063  *   <li>If no characters are replaced, use the metadata of the
0064  *   previous character</li>
0065  *   <li>If there is no previous character (i.e. start == 0), use the
0066  *   following character</li>
0067  *   <li>If there is no following character (i.e. the replaceable was
0068  *   empty), use default metadata.<br>
0069  *   <li>If the code point U+FFFF is seen, it should be interpreted as
0070  *   a special marker having no metadata<li>
0071  *   </li>
0072  * </ul>
0073  * If this is not the behavior, the subclass should document any differences.
0074  * @author Alan Liu
0075  * @stable ICU 2.0
0076  */
0077 class U_COMMON_API Replaceable : public UObject {
0078
0079 public:
0080     /**
0081      * Destructor.
0082      * @stable ICU 2.0
0083      */
0084     virtual ~Replaceable();
0085
0086     /**
0087      * Returns the number of 16-bit code units in the text.
0088      * @return number of 16-bit code units in text
0089      * @stable ICU 1.8
0090      */
0091     inline int32_t length() const;
0092
0093     /**
0094      * Returns the 16-bit code unit at the given offset into the text.
0095      * @param offset an integer between 0 and <code>length()</code>-1
0096      * inclusive
0097      * @return 16-bit code unit of text at given offset
0098      * @stable ICU 1.8
0099      */
0100     inline char16_t charAt(int32_t offset) const;
0101
0102     /**
0103      * Returns the 32-bit code point at the given 16-bit offset into
0104      * the text.  This assumes the text is stored as 16-bit code units
0105      * with surrogate pairs intermixed.  If the offset of a leading or
0106      * trailing code unit of a surrogate pair is given, return the
0107      * code point of the surrogate pair.
0108      *
0109      * @param offset an integer between 0 and <code>length()</code>-1
0110      * inclusive
0111      * @return 32-bit code point of text at given offset
0112      * @stable ICU 1.8
0113      */
0114     inline UChar32 char32At(int32_t offset) const;
0115
0116     /**
0117      * Copies characters in the range [<tt>start</tt>, <tt>limit</tt>)
0118      * into the UnicodeString <tt>target</tt>.
0119      * @param start offset of first character which will be copied
0120      * @param limit offset immediately following the last character to
0121      * be copied
0122      * @param target UnicodeString into which to copy characters.
0123      * @return A reference to <TT>target</TT>
0124      * @stable ICU 2.1
0125      */
0126     virtual void extractBetween(int32_t start,
0127                                 int32_t limit,
0128                                 UnicodeString& target) const = 0;
0129
0130     /**
0131      * Replaces a substring of this object with the given text.  If the
0132      * characters being replaced have metadata, the new characters
0133      * that replace them should be given the same metadata.
0134      *
0135      * <p>Subclasses must ensure that if the text between start and
0136      * limit is equal to the replacement text, that replace has no
0137      * effect. That is, any metadata
0138      * should be unaffected. In addition, subclasses are encouraged to
0139      * check for initial and trailing identical characters, and make a
0140      * smaller replacement if possible. This will preserve as much
0141      * metadata as possible.
0142      * @param start the beginning index, inclusive; <code>0 <= start
0143      * <= limit</code>.
0144      * @param limit the ending index, exclusive; <code>start <= limit
0145      * <= length()</code>.
0146      * @param text the text to replace characters <code>start</code>
0147      * to <code>limit - 1</code>
0148      * @stable ICU 2.0
0149      */
0150     virtual void handleReplaceBetween(int32_t start,
0151                                       int32_t limit,
0152                                       const UnicodeString& text) = 0;
0153     // Note: All other methods in this class take the names of
0154     // existing UnicodeString methods.  This method is the exception.
0155     // It is named differently because all replace methods of
0156     // UnicodeString return a UnicodeString&.  The 'between' is
0157     // required in order to conform to the UnicodeString naming
0158     // convention; API taking start/length are named <operation>, and
0159     // those taking start/limit are named <operationBetween>.  The
0160     // 'handle' is added because 'replaceBetween' and
0161     // 'doReplaceBetween' are already taken.
0162
0163     /**
0164      * Copies a substring of this object, retaining metadata.
0165      * This method is used to duplicate or reorder substrings.
0166      * The destination index must not overlap the source range.
0167      *
0168      * @param start the beginning index, inclusive; <code>0 <= start <=
0169      * limit</code>.
0170      * @param limit the ending index, exclusive; <code>start <= limit <=
0171      * length()</code>.
0172      * @param dest the destination index.  The characters from
0173      * <code>start..limit-1</code> will be copied to <code>dest</code>.
0174      * Implementations of this method may assume that <code>dest <= start ||
0175      * dest >= limit</code>.
0176      * @stable ICU 2.0
0177      */
0178     virtual void copy(int32_t start, int32_t limit, int32_t dest) = 0;
0179
0180     /**
0181      * Returns true if this object contains metadata.  If a
0182      * Replaceable object has metadata, calls to the Replaceable API
0183      * must be made so as to preserve metadata.  If it does not, calls
0184      * to the Replaceable API may be optimized to improve performance.
0185      * The default implementation returns true.
0186      * @return true if this object contains metadata
0187      * @stable ICU 2.2
0188      */
0189     virtual UBool hasMetaData() const;
0190
0191     /**
0192      * Clone this object, an instance of a subclass of Replaceable.
0193      * Clones can be used concurrently in multiple threads.
0194      * If a subclass does not implement clone(), or if an error occurs,
0195      * then nullptr is returned.
0196      * The caller must delete the clone.
0197      *
0198      * @return a clone of this object
0199      *
0200      * @see getDynamicClassID
0201      * @stable ICU 2.6
0202      */
0203     virtual Replaceable *clone() const;
0204
0205 protected:
0206
0207     /**
0208      * Default constructor.
0209      * @stable ICU 2.4
0210      */
0211     inline Replaceable();
0212
0213     /*
0214      * Assignment operator not declared. The compiler will provide one
0215      * which does nothing since this class does not contain any data members.
0216      * API/code coverage may show the assignment operator as present and
0217      * untested - ignore.
0218      * Subclasses need this assignment operator if they use compiler-provided
0219      * assignment operators of their own. An alternative to not declaring one
0220      * here would be to declare and empty-implement a protected or public one.
0221     Replaceable &Replaceable::operator=(const Replaceable &);
0222      */
0223
0224     /**
0225      * Virtual version of length().
0226      * @stable ICU 2.4
0227      */
0228     virtual int32_t getLength() const = 0;
0229
0230     /**
0231      * Virtual version of charAt().
0232      * @stable ICU 2.4
0233      */
0234     virtual char16_t getCharAt(int32_t offset) const = 0;
0235
0236     /**
0237      * Virtual version of char32At().
0238      * @stable ICU 2.4
0239      */
0240     virtual UChar32 getChar32At(int32_t offset) const = 0;
0241 };
0242
0243 inline Replaceable::Replaceable() {}
0244
0245 inline int32_t
0246 Replaceable::length() const {
0247     return getLength();
0248 }
0249
0250 inline char16_t
0251 Replaceable::charAt(int32_t offset) const {
0252     return getCharAt(offset);
0253 }
0254
0255 inline UChar32
0256 Replaceable::char32At(int32_t offset) const {
0257     return getChar32At(offset);
0258 }
0259
0260 // There is no rep.cpp, see unistr.cpp for Replaceable function implementations.
0261
0262 U_NAMESPACE_END
0263
0264 #endif /* U_SHOW_CPLUSPLUS_API */
0265
0266 #endif