ICU-1544 add hasMetaData() to Replaceable

X-SVN-Rev: 9021

icu4c/source/common/unicode/rep.h

@@ -25,31 +25,37 @@ class UnicodeString;
  * <code>Replaceable</code> is an abstract base class representing a
  * string of characters that supports the replacement of a range of
  * itself with a new string of characters.  It is used by APIs that
- * change a piece of text while retaining style attributes.  In other
- * words, an implicit aspect of the <code>Replaceable</code> API is
- * that during a replace operation, new characters take on the
- * attributes, if any, of the old characters.  For example, if the
- * string "the <b>bold</b> font" has range (4, 8) replaced with
- * "strong", then it becomes "the <b>strong</b> font".
+ * change a piece of text while retaining metadata.  Metadata is data
+ * other than the Unicode characters returned by char32At().  One
+ * example of metadata is style attributes; another is an edit
+ * history, marking each character with an author and revision number.
  *
- * <p><code>Replaceable</code> specifies ranges using an initial
+ * <p>An implicit aspect of the <code>Replaceable</code> API is that
+ * during a replace operation, new characters take on the metadata of
+ * the old characters.  For example, if the string "the <b>bold</b>
+ * font" has range (4, 8) replaced with "strong", then it becomes "the
+ * <b>strong</b> font".
+ *
+ * <p><code>Replaceable</code> specifies ranges using a start
  * offset and a limit offset.  The range of characters thus specified
- * includes the characters at offset initial..limit-1.  That is, the
+ * includes the characters at offset start..limit-1.  That is, the
  * start offset is inclusive, and the limit offset is exclusive.
  *
  * <p><code>Replaceable</code> also includes API to access characters
- * in the string: <code>length()</code>, <code>charAt()</code>, and
- * <code>extractBetween()</code>.
+ * in the string: <code>length()</code>, <code>charAt()</code>,
+ * <code>char32At()</code>, and <code>extractBetween()</code>.
  *
- * <p>If a subclass supports styles, then typically the behavior is the following:
+ * <p>For a subclass to support metadata, typical behavior of
+ * <code>replace()</code> is the following:
  * <ul>
- *   <li>Set the styles to the style of the first character replaced</li>
- *   <li>If no characters are replaced, use the style of the previous
- * character</li>
- *   <li>If there is no previous character (i.e. start == 0), use the following
- *     character</li>
- *   <li>If there is no following character (i.e. the replaceable was empty), a
- *     default style.<br>
+ *   <li>Set the metadata of the new text to the metadata of the first
+ *   character replaced</li>
+ *   <li>If no characters are replaced, use the metadata of the
+ *   previous character</li>
+ *   <li>If there is no previous character (i.e. start == 0), use the
+ *   following character</li>
+ *   <li>If there is no following character (i.e. the replaceable was
+ *   empty), use default metadata.<br>
  *   </li>
  * </ul>
  * If this is not the behavior, the subclass should document any differences.
@@ -66,58 +72,61 @@ public:
     virtual ~Replaceable();
 
     /**
-     * Return the number of characters in the text.
-     * @return number of characters in text
-     * @draft ICU 1.8
+     * Returns the number of 16-bit code units in the text.
+     * @return number of 16-bit code units in text
+     * @since ICU 1.8
      */ 
     inline int32_t length() const;
 
     /**
-     * Return the Unicode code unit at the given offset into the text.
+     * Returns the 16-bit code unit at the given offset into the text.
      * @param offset an integer between 0 and <code>length()</code>-1
      * inclusive
-     * @return code unit of text at given offset
-     * @draft ICU 1.8
+     * @return 16-bit code unit of text at given offset
+     * @since ICU 1.8
      */
     inline UChar charAt(int32_t offset) const;
 
     /**
-     * Return the Unicode code point that contains the code unit
-     * at the given offset into the text.
+     * Returns the 32-bit code point at the given 16-bit offset into
+     * the text.  This assumes the text is stored as 16-bit code units
+     * with surrogate pairs intermixed.  If the offset of a leading or
+     * trailing code unit of a surrogate pair is given, return the
+     * code point of the surrogate pair.
+     *
      * @param offset an integer between 0 and <code>length()</code>-1
-     * inclusive that indicates the text offset of any of the code units
-     * that will be assembled into a code point (21-bit value) and returned
-     * @return code point of text at given offset
-     * @draft ICU 1.8
+     * inclusive
+     * @return 32-bit code point of text at given offset
+     * @since ICU 1.8
      */
     inline UChar32 char32At(int32_t offset) const;
 
     /**
-     * Copy the characters in the range [<tt>start</tt>, <tt>limit</tt>) 
+     * Copies characters in the range [<tt>start</tt>, <tt>limit</tt>) 
      * into the UnicodeString <tt>target</tt>.
      * @param start offset of first character which will be copied
      * @param limit offset immediately following the last character to
      * be copied
      * @param target UnicodeString into which to copy characters.
      * @return A reference to <TT>target</TT>
-     * @draft ICU 2.1
+     * @since ICU 2.1
      */
     virtual void extractBetween(int32_t start,
                                 int32_t limit,
                                 UnicodeString& target) const = 0;
 
     /**
-     * Replace a substring of this object with the given text.  If the
-     * characters being replaced have attributes, the new characters
-     * that replace them should be given the same attributes.
+     * Replaces a substring of this object with the given text.  If the
+     * characters being replaced have metadata, the new characters
+     * that replace them should be given the same metadata.
      *
      * <p>Subclasses must ensure that if the text between start and
      * limit is equal to the replacement text, that replace has no
-     * effect. That is, any out-of-band information such as styles
-     * should be unaffected. In addition, subclasses are encourage to
+     * effect. That is, any metadata
+     * should be unaffected. In addition, subclasses are encouraged to
      * check for initial and trailing identical characters, and make a
      * smaller replacement if possible. This will preserve as much
-     * style information as possible.
+     * metadata as possible.
      * @param start the beginning index, inclusive; <code>0 <= start
      * <= limit</code>.
      * @param limit the ending index, exclusive; <code>start <= limit
@@ -140,16 +149,9 @@ public:
     // 'doReplaceBetween' are already taken.
 
     /**
-     * Copy a substring of this object, retaining attribute (out-of-band)
-     * information.  This method is used to duplicate or reorder substrings.
+     * Copies a substring of this object, retaining metadata.
+     * This method is used to duplicate or reorder substrings.
      * The destination index must not overlap the source range.
-     * Implementations that do not care about maintaining out-of-band
-     * information or performance during copying may use the naive
-     * implementation:
-     *
-     * <pre> char[] text = new char[limit - start];
-     * getChars(start, limit, text, 0);
-     * replace(dest, dest, text, 0, limit - start);</pre>
      * 
      * @param start the beginning index, inclusive; <code>0 <= start <=
      * limit</code>.
@@ -159,9 +161,21 @@ public:
      * <code>start..limit-1</code> will be copied to <code>dest</code>.
      * Implementations of this method may assume that <code>dest <= start ||
      * dest >= limit</code>.
-     * @stable */
+     * @stable
+     */
     virtual void copy(int32_t start, int32_t limit, int32_t dest) = 0;
 
+    /**
+     * Returns true if this object contains metadata.  If a
+     * Replaceable object has metadata, calls to the Replaceable API
+     * must be made so as to preserve metadata.  If it does not, calls
+     * to the Replaceable API may be optimized to improve performance.
+     * The default implementation returns true.
+     * @return true if this object contains metadata
+     * @since ICU 2.2
+     */
+    virtual UBool hasMetaData() const;
+
 protected:
 
     /**
@@ -204,6 +218,8 @@ Replaceable::char32At(int32_t offset) const {
     return getChar32At(offset);
 }
 
+// See unistr.cpp for Replaceable::hasMetaData()
+
 U_NAMESPACE_END
 
 #endif

icu4c/source/common/unicode/unistr.h

@@ -2158,6 +2158,11 @@ public:
                                     int32_t limit,
                                     const UnicodeString& text);
 
+  /**
+   * Replaceable API
+   */
+  virtual UBool hasMetaData() const;
+
   /**
    * Copy a substring of this object, retaining attribute (out-of-band)
    * information.  This method is used to duplicate or reorder substrings.

icu4c/source/common/unistr.cpp

@@ -1353,6 +1353,23 @@ UnicodeString::copy(int32_t start, int32_t limit, int32_t dest) {
     uprv_free(text);
 }
 
+/**
+ * Replaceable API
+ *
+ * NOTE: This is for the Replaceable class.  There is no rep.cpp,
+ * so we implement this function here.
+ */
+UBool Replaceable::hasMetaData() const {
+    return TRUE;
+}
+
+/**
+ * Replaceable API
+ */
+UBool UnicodeString::hasMetaData() const {
+    return FALSE;
+}
+
 UnicodeString&
 UnicodeString::doReverse(int32_t start,
              int32_t length)