ICU-66108.tar.gz

[apple/icu.git] / icuSources / common / unicode / unistr.h

diff --git a/icuSources/common/unicode/unistr.h b/icuSources/common/unicode/unistr.h
index 55739ac2425fd1840a6d7dffc8c31bc189300adc..da79053765acf6fa2ee1f2cde9a5b073e5dd80ce 100644 (file)
--- a/icuSources/common/unicode/unistr.h
+++ b/icuSources/common/unicode/unistr.h
@@ -28,8 +28,11 @@
  * \brief C++ API: Unicode String
  */
 
-#include <cstddef>
 #include "unicode/utypes.h"
+
+#if U_SHOW_CPLUSPLUS_API
+
+#include <cstddef>
 #include "unicode/char16ptr.h"
 #include "unicode/rep.h"
 #include "unicode/std_string.h"
@@ -46,7 +49,6 @@ U_STABLE int32_t U_EXPORT2
 u_strlen(const UChar *s);
 #endif
 
-#if U_SHOW_CPLUSPLUS_API
 U_NAMESPACE_BEGIN
 
 #if !UCONFIG_NO_BREAK_ITERATION
@@ -55,9 +57,7 @@ class BreakIterator;        // unicode/brkiter.h
 class Edits;
 
 U_NAMESPACE_END
-#endif // U_SHOW_CPLUSPLUS_API
 
-#if U_SHOW_CPLUSPLUS_API
 // Not #ifndef U_HIDE_INTERNAL_API because UnicodeString needs the UStringCaseMapper.
 /**
  * Internal string case mapping function type.
@@ -74,9 +74,7 @@ UStringCaseMapper(int32_t caseLocale, uint32_t options,
                   const char16_t *src, int32_t srcLength,
                   icu::Edits *edits,
                   UErrorCode &errorCode);
-#endif // U_SHOW_CPLUSPLUS_API
 
-#if U_SHOW_CPLUSPLUS_API
 U_NAMESPACE_BEGIN
 
 class Locale;               // unicode/locid.h
@@ -214,7 +212,9 @@ class UnicodeStringAppendable;  // unicode/appendable.h
  * similar functionality as the Java String and StringBuffer/StringBuilder classes.
  * It is a concrete implementation of the abstract class Replaceable (for transliteration).
  *
- * A UnicodeString may also "alias" an external array of characters
+ * The UnicodeString equivalent of std::string’s clear() is remove().
+ *
+ * A UnicodeString may "alias" an external array of characters
  * (that is, point to it, rather than own the array)
  * whose lifetime must then at least match the lifetime of the aliasing object.
  * This aliasing may be preserved when returning a UnicodeString by value,
@@ -2097,8 +2097,7 @@ public:
    *   s.truncate(0);        // set to an empty string (complete truncation), or
    *   s=UnicodeString();    // assign an empty string, or
    *   s.setTo((UChar32)-1); // set to a pseudo code point that is out of range, or
-   *   static const char16_t nul=0;
-   *   s.setTo(&nul, 0);     // set to an empty C Unicode string
+   *   s.setTo(u"", 0);      // set to an empty C Unicode string
    * }
    * \endcode
    *
@@ -2539,11 +2538,14 @@ public:
   /* Remove operations */
 
   /**
-   * Remove all characters from the UnicodeString object.
+   * Removes all characters from the UnicodeString object and clears the bogus flag.
+   * This is the UnicodeString equivalent of std::string’s clear().
+   *
    * @return a reference to this
+   * @see setToBogus
    * @stable ICU 2.0
    */
-  inline UnicodeString& remove(void);
+  inline UnicodeString& remove();
 
   /**
    * Remove the characters in the range
@@ -3039,11 +3041,11 @@ public:
    * uint16_t * constructor.
    * Delegates to UnicodeString(const char16_t *, int32_t).
    * @param text UTF-16 string
-   * @param length string length
+   * @param textLength string length
    * @stable ICU 59
    */
-  UnicodeString(const uint16_t *text, int32_t length) :
-      UnicodeString(ConstChar16Ptr(text), length) {}
+  UnicodeString(const uint16_t *text, int32_t textLength) :
+      UnicodeString(ConstChar16Ptr(text), textLength) {}
 #endif
 
 #if U_SIZEOF_WCHAR_T==2 || defined(U_IN_DOXYGEN)
@@ -3052,21 +3054,21 @@ public:
    * (Only defined if U_SIZEOF_WCHAR_T==2.)
    * Delegates to UnicodeString(const char16_t *, int32_t).
    * @param text NUL-terminated UTF-16 string
-   * @param length string length
+   * @param textLength string length
    * @stable ICU 59
    */
-  UnicodeString(const wchar_t *text, int32_t length) :
-      UnicodeString(ConstChar16Ptr(text), length) {}
+  UnicodeString(const wchar_t *text, int32_t textLength) :
+      UnicodeString(ConstChar16Ptr(text), textLength) {}
 #endif
 
   /**
    * nullptr_t constructor.
    * Effectively the same as the default constructor, makes an empty string object.
    * @param text nullptr
-   * @param length ignored
+   * @param textLength ignored
    * @stable ICU 59
    */
-  inline UnicodeString(const std::nullptr_t text, int32_t length);
+  inline UnicodeString(const std::nullptr_t text, int32_t textLength);
 
   /**
    * Readonly-aliasing char16_t* constructor.
@@ -3271,13 +3273,13 @@ public:
    *     }
    * \endcode
    * @param src String using only invariant characters.
-   * @param length Length of src, or -1 if NUL-terminated.
+   * @param textLength Length of src, or -1 if NUL-terminated.
    * @param inv Signature-distinguishing paramater, use US_INV.
    *
    * @see US_INV
    * @stable ICU 3.2
    */
-  UnicodeString(const char *src, int32_t length, enum EInvariant inv);
+  UnicodeString(const char *src, int32_t textLength, enum EInvariant inv);
 
 
   /**
@@ -3328,9 +3330,6 @@ public:
    * Clones can be used concurrently in multiple threads.
    * If a subclass does not implement clone(), or if an error occurs,
    * then NULL is returned.
-   * The clone functions in all subclasses return a pointer to a Replaceable
-   * because some compilers do not support covariant (same-as-this)
-   * return types; cast to the appropriate subclass if necessary.
    * The caller must delete the clone.
    *
    * @return a clone of this object
@@ -3339,7 +3338,7 @@ public:
    * @see getDynamicClassID
    * @stable ICU 2.6
    */
-  virtual Replaceable *clone() const;
+  virtual UnicodeString *clone() const;
 
   /** Destructor.
    * @stable ICU 2.0
@@ -4752,6 +4751,7 @@ UnicodeString::reverse(int32_t start,
 { return doReverse(start, _length); }
 
 U_NAMESPACE_END
-#endif // U_SHOW_CPLUSPLUS_API
+
+#endif /* U_SHOW_CPLUSPLUS_API */
 
 #endif