ICU-59117.0.1.tar.gz

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

diff --git a/icuSources/common/unicode/utf_old.h b/icuSources/common/unicode/utf_old.h
index eabc904bbc407b2ba81ef088709f443efa88a7e0..250cb8c0ae01b3fa1afc5d0668840a521c93d06b 100644 (file)
--- a/icuSources/common/unicode/utf_old.h
+++ b/icuSources/common/unicode/utf_old.h
@@ -1,12 +1,14 @@
+// © 2016 and later: Unicode, Inc. and others.
+// License & terms of use: http://www.unicode.org/copyright.html
 /*
 *******************************************************************************
 *
-*   Copyright (C) 2002-2004, International Business Machines
+*   Copyright (C) 2002-2012, International Business Machines
 *   Corporation and others.  All Rights Reserved.
 *
 *******************************************************************************
-*   file name:  utf.h
-*   encoding:   US-ASCII
+*   file name:  utf_old.h
+*   encoding:   UTF-8
 *   tab size:   8 (not used)
 *   indentation:4
 *
@@ -16,6 +18,11 @@
 
 /**
  * \file
+ * \brief C API: Deprecated macros for Unicode string handling
+ */
+
+/**
+ *
  * The macros in utf_old.h are all deprecated and their use discouraged.
  * Some of the design principles behind the set of UTF macros
  * have changed or proved impractical.
@@ -23,9 +30,6 @@
  * If you are looking for a new equivalent to an old macro, please see the
  * comment at the old one.
  *
- * utf_old.h is included by utf.h after unicode/umachine.h
- * and some common definitions, to not break old code.
- *
  * Brief summary of reasons for deprecation:
  * - Switch on UTF_SIZE (selection of UTF-8/16/32 default string processing)
  *   was impractical.
@@ -84,9 +88,10 @@
  * accordingly. UTF-16 was the default.</p>
  *
  * <p>This concept has been abandoned.
- * A lot of the ICU source code &#8212; especially low-level code like
- * conversion, normalization, and collation &#8212; assumes UTF-16,
- * utf.h enforces the default of UTF-16.
+ * A lot of the ICU source code assumes UChar strings are in UTF-16.
+ * This is especially true for low-level code like
+ * conversion, normalization, and collation.
+ * The utf.h header enforces the default of UTF-16.
  * The UTF-8 and UTF-32 macros remain for now for completeness and backward compatibility.</p>
  *
  * <p>Accordingly, utf.h defines UChar to be an unsigned 16-bit integer. If this matches wchar_t, then
@@ -142,10 +147,9 @@
 
 #ifndef U_HIDE_DEPRECATED_API
 
-/* utf.h must be included first. */
-#ifndef __UTF_H__
-#   include "unicode/utf.h"
-#endif
+#include "unicode/utf.h"
+#include "unicode/utf8.h"
+#include "unicode/utf16.h"
 
 /* Formerly utf.h, part 1 --------------------------------------------------- */
 
@@ -176,14 +180,16 @@ typedef int32_t UTextOffset;
 #undef UTF_STRICT
 
 /**
- * <p>UTF8_ERROR_VALUE_1 and UTF8_ERROR_VALUE_2 are special error values for UTF-8,
- * which need 1 or 2 bytes in UTF-8:<br>
- * U+0015 = NAK = Negative Acknowledge, C0 control character<br>
- * U+009f = highest C1 control character</p>
+ * UTF8_ERROR_VALUE_1 and UTF8_ERROR_VALUE_2 are special error values for UTF-8,
+ * which need 1 or 2 bytes in UTF-8:
+ * \code
+ * U+0015 = NAK = Negative Acknowledge, C0 control character
+ * U+009f = highest C1 control character
+ * \endcode
  *
- * <p>These are used by UTF8_..._SAFE macros so that they can return an error value
+ * These are used by UTF8_..._SAFE macros so that they can return an error value
  * that needs the same number of code units (bytes) as were seen by
- * a macro. They should be tested with UTF_IS_ERROR() or UTF_IS_VALID().</p>
+ * a macro. They should be tested with UTF_IS_ERROR() or UTF_IS_VALID().
  *
  * @deprecated ICU 2.4. Obsolete, see utf_old.h.
  */
@@ -261,6 +267,25 @@ typedef int32_t UTextOffset;
 
 /* Formerly utf8.h ---------------------------------------------------------- */
 
+/**
+* \var utf8_countTrailBytes
+* Internal array with numbers of trail bytes for any given byte used in
+* lead byte position.
+*
+* This is internal since it is not meant to be called directly by external clients;
+* however it is called by public macros in this file and thus must remain stable,
+* and should not be hidden when other internal functions are hidden (otherwise
+* public macros would fail to compile).
+* @internal
+*/
+#ifdef U_UTF8_IMPL
+// No forward declaration if compiling utf_impl.cpp, which defines utf8_countTrailBytes.
+#elif defined(U_STATIC_IMPLEMENTATION) || defined(U_COMMON_IMPLEMENTATION)
+U_CFUNC const uint8_t utf8_countTrailBytes[];
+#else
+U_CFUNC U_IMPORT const uint8_t utf8_countTrailBytes[];    /* U_IMPORT2? */ /*U_IMPORT*/
+#endif
+
 /**
  * Count the trail bytes for a UTF-8 lead byte.
  * @deprecated ICU 2.4. Renamed to U8_COUNT_TRAIL_BYTES, see utf_old.h.
@@ -294,7 +319,7 @@ typedef int32_t UTextOffset;
  * Code point comparisons need to be in uint32_t because UChar32
  * may be a signed type, and negative values must be recognized.
  *
- * @deprecated ICU 2.4. Use U8_LENGTH instead, see utf_old.h.
+ * @deprecated ICU 2.4. Use U8_LENGTH instead, see utf.h.
  */
 #if 1
 #   define UTF8_CHAR_LENGTH(c) \