ICU-66108.tar.gz

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

diff --git a/icuSources/common/unicode/udata.h b/icuSources/common/unicode/udata.h
index 47edbd86c9fc9c3ea92c6e264ddccaee2bb51f42..76e9e3ca2198eba4e79cba8490ea2ada540ef762 100644 (file)
--- a/icuSources/common/unicode/udata.h
+++ b/icuSources/common/unicode/udata.h
@@ -1,12 +1,14 @@
+// © 2016 and later: Unicode, Inc. and others.
+// License & terms of use: http://www.unicode.org/copyright.html
 /*
 ******************************************************************************
 *
-*   Copyright (C) 1999-2010, International Business Machines
+*   Copyright (C) 1999-2014, International Business Machines
 *   Corporation and others.  All Rights Reserved.
 *
 ******************************************************************************
 *   file name:  udata.h
-*   encoding:   US-ASCII
+*   encoding:   UTF-8
 *   tab size:   8 (not used)
 *   indentation:4
 *
@@ -77,6 +79,10 @@ U_CDECL_BEGIN
  * <p>This structure may grow in the future, indicated by the
  * <code>size</code> field.</p>
  *
+ * <p>ICU data must be at least 8-aligned, and should be 16-aligned.
+ * The UDataInfo struct begins 4 bytes after the start of the data item,
+ * so it is 4-aligned.
+ *
  * <p>The platform data property fields help determine if a data
  * file can be efficiently used on a given machine.
  * The particular fields are of importance only if the data
@@ -92,7 +98,7 @@ U_CDECL_BEGIN
  *
  * <p>The <code>formatVersion</code> field should be used to
  * make sure that the format can be interpreted.
- * I may be a good idea to check only for the one or two highest
+ * It may be a good idea to check only for the one or two highest
  * of the version elements to allow the data memory to
  * get more or somewhat rearranged contents, for as long
  * as the using code can still interpret the older contents.</p>
@@ -101,6 +107,7 @@ U_CDECL_BEGIN
  * common place to store the source version of the data;
  * for data from the Unicode character database, this could
  * reflect the Unicode version.</p>
+ *
  * @stable ICU 2.0
  */
 typedef struct {
@@ -257,28 +264,12 @@ udata_openChoice(const char *path, const char *type, const char *name,
 U_STABLE void U_EXPORT2
 udata_close(UDataMemory *pData);
 
-#if U_SHOW_CPLUSPLUS_API
-
-U_NAMESPACE_BEGIN
-
-/**
- * \class LocalUDataMemoryPointer
- * "Smart pointer" class, closes a UDataMemory via udata_close().
- * For most methods see the LocalPointerBase base class.
- *
- * @see LocalPointerBase
- * @see LocalPointer
- * @stable ICU 4.4
- */
-U_DEFINE_LOCAL_OPEN_POINTER(LocalUDataMemoryPointer, UDataMemory, udata_close);
-
-U_NAMESPACE_END
-
-#endif
-
 /**
  * Get the pointer to the actual data inside the data memory.
  * The data is read-only.
+ *
+ * ICU data must be at least 8-aligned, and should be 16-aligned.
+ *
  * @param pData The pointer to data memory object
  * @stable ICU 2.0
  */
@@ -311,6 +302,9 @@ udata_getInfo(UDataMemory *pData, UDataInfo *pInfo);
  * allows you to force ICU's system data to come out of a user-specified
  * area in memory.
  *
+ * ICU data must be at least 8-aligned, and should be 16-aligned.
+ * See http://userguide.icu-project.org/icudata
+ *
  * The format of this data is that of the icu common data file, as is
  * generated by the pkgdata tool with mode=common or mode=dll.
  * You can read in a whole common mode file and pass the address to the start of the
@@ -355,6 +349,9 @@ udata_setCommonData(const void *data, UErrorCode *err);
  * data and allows you to force the it to come out of a user-specified
  * pointer.
  *
+ * ICU data must be at least 8-aligned, and should be 16-aligned.
+ * See http://userguide.icu-project.org/icudata
+ *
  * The format of this data is that of the icu common data file, like 'icudt26l.dat'
  * or the corresponding shared library (DLL) file.
  * The application must read in or otherwise construct an image of the data and then
@@ -383,18 +380,31 @@ udata_setAppData(const char *packageName, const void *data, UErrorCode *err);
  * @stable ICU 3.4
  */
 typedef enum UDataFileAccess {
-    /** ICU looks for data in single files first, then in packages. (default) */
+    /** ICU looks for data in single files first, then in packages. (default) @stable ICU 3.4 */
     UDATA_FILES_FIRST,
-    /** ICU only loads data from packages, not from single files. */
+#if U_PLATFORM!=U_PF_IPHONE
+    /** An alias for the default access mode. @stable ICU 3.4 */
+    UDATA_DEFAULT_ACCESS = UDATA_FILES_FIRST,
+#endif
+    /** ICU only loads data from packages, not from single files. @stable ICU 3.4 */
     UDATA_ONLY_PACKAGES,
+#if U_PLATFORM==U_PF_IPHONE
+    /** An alias for the default access mode. For iOS, Apple modifies UDATA_DEFAULT_ACCESS
+        to be UDATA_ONLY_PACKAGES, not UDATA_FILES_FIRST. @stable ICU 3.4 */
+    UDATA_DEFAULT_ACCESS = UDATA_ONLY_PACKAGES,
+#endif
     /** ICU loads data from packages first, and only from single files
-        if the data cannot be found in a package. */
+        if the data cannot be found in a package. @stable ICU 3.4 */
     UDATA_PACKAGES_FIRST,
-    /** ICU does not access the file system for data loading. */
+    /** ICU does not access the file system for data loading. @stable ICU 3.4 */
     UDATA_NO_FILES,
-    /** An alias for the default access mode. */
-    UDATA_DEFAULT_ACCESS = UDATA_FILES_FIRST,
+#ifndef U_HIDE_DEPRECATED_API
+    /**
+     * Number of real UDataFileAccess values.
+     * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
+     */
     UDATA_FILE_ACCESS_COUNT
+#endif  // U_HIDE_DEPRECATED_API
 } UDataFileAccess;
 
 /**
@@ -412,4 +422,23 @@ udata_setFileAccess(UDataFileAccess access, UErrorCode *status);
 
 U_CDECL_END
 
+#if U_SHOW_CPLUSPLUS_API
+
+U_NAMESPACE_BEGIN
+
+/**
+ * \class LocalUDataMemoryPointer
+ * "Smart pointer" class, closes a UDataMemory via udata_close().
+ * For most methods see the LocalPointerBase base class.
+ *
+ * @see LocalPointerBase
+ * @see LocalPointer
+ * @stable ICU 4.4
+ */
+U_DEFINE_LOCAL_OPEN_POINTER(LocalUDataMemoryPointer, UDataMemory, udata_close);
+
+U_NAMESPACE_END
+
+#endif  // U_SHOW_CPLUSPLUS_API
+
 #endif