ICU-7877 more documentation for explicit UnicodeString constructors

X-SVN-Rev: 30300

diff --git a/icu4c/readme.html b/icu4c/readme.html
index da454e29412d59a9a51d736f131ffdaccd17bd58..b75aa9a30f5cfbee85dd6d98a2719b21e1b7f3d5 100644 (file)
--- 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 e9785d673ae168b94bd3a6174de6e8499b9c2174..f895bab9dff25594dd07409d4a49bb7a144a193b 100644 (file)
--- 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);