From: Markus Scherer <markus.icu@gmail.com>
Date: Fri, 8 Jul 2011 22:09:28 +0000 (+0000)
Subject: ICU-7877 more documentation for explicit UnicodeString constructors
X-Git-Tag: milestone-59-0-1~4667
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=6e70106104a7980e22c5bd139a670fd84906b6ae;p=icu

ICU-7877 more documentation for explicit UnicodeString constructors

X-SVN-Rev: 30300
---

diff --git a/icu4c/readme.html b/icu4c/readme.html
index da454e29412..b75aa9a30f5 100644
--- a/icu4c/readme.html
+++ b/icu4c/readme.html
@@ -562,6 +562,21 @@
 
  /*===========================================================================*/
 </pre></li>
+      <li><b>UnicodeString constructors:</b> The UnicodeString class has
+        several single-argument constructors that are not marked "explicit"
+        for historical reasons.
+        This can lead to inadvertent construction of a <code>UnicodeString</code>
+        with a single character by using an integer,
+        and it can lead to inadvertent dependency on the conversion framework
+        by using a C string literal.
+        <ul>
+          <li>Consider marking the from-<code>UChar</code>
+            and from-<code>UChar32</code> constructors explicit via
+            <code>-DUNISTR_FROM_CHAR_EXPLICIT=explicit</code> or similar.</li>
+          <li>Consider marking the from-<code>const char*</code> and
+            from-<code>const UChar*</code></li> constructors explicit via
+            <code>-DUNISTR_FROM_STRING_EXPLICIT=explicit</code> or similar.</li>
+      </li>
       <li><b>.dat file:</b> By default, the ICU data is built into
         a shared library (DLL). This is convenient because it requires no
         install-time or runtime configuration,
diff --git a/icu4c/source/common/unicode/unistr.h b/icu4c/source/common/unicode/unistr.h
index e9785d673ae..f895bab9dff 100644
--- a/icu4c/source/common/unicode/unistr.h
+++ b/icu4c/source/common/unicode/unistr.h
@@ -2951,12 +2951,19 @@ public:
    * Uses the default converter (and thus depends on the ICU conversion code)
    * unless U_CHARSET_IS_UTF8 is set to 1.
    *
+   * For ASCII (really "invariant character") strings it is more efficient to use
+   * the constructor that takes a US_INV (for its enum EInvariant).
+   * For ASCII (invariant-character) string literals, see UNICODE_STRING and
+   * UNICODE_STRING_SIMPLE.
+   *
    * It is recommended to mark this constructor "explicit" by
    * <code>-DUNISTR_FROM_STRING_EXPLICIT=explicit</code>
    * on the compiler command line or similar.
    * @param codepageData an array of bytes, null-terminated,
    *                     in the platform's default codepage.
    * @stable ICU 2.0
+   * @see UNICODE_STRING
+   * @see UNICODE_STRING_SIMPLE
    */
   UNISTR_FROM_STRING_EXPLICIT UnicodeString(const char *codepageData);