Index: source/common/unicode/ulistformatter.h |
diff --git a/source/common/unicode/ulistformatter.h b/source/common/unicode/ulistformatter.h |
new file mode 100644 |
index 0000000000000000000000000000000000000000..1c6cb2d7b12395402cb21d6269bf44449f5bdeb9 |
--- /dev/null |
+++ b/source/common/unicode/ulistformatter.h |
@@ -0,0 +1,130 @@ |
+/* |
+***************************************************************************************** |
+* Copyright (C) 2015, International Business Machines |
+* Corporation and others. All Rights Reserved. |
+***************************************************************************************** |
+*/ |
+ |
+#ifndef ULISTFORMATTER_H |
+#define ULISTFORMATTER_H |
+ |
+#include "unicode/utypes.h" |
+ |
+#if !UCONFIG_NO_FORMATTING |
+#ifndef U_HIDE_DRAFT_API |
+ |
+#include "unicode/localpointer.h" |
+ |
+/** |
+ * \file |
+ * \brief C API: Format a list in a locale-appropriate way. |
+ * |
+ * A UListFormatter is used to format a list of items in a locale-appropriate way, |
+ * using data from CLDR. |
+ * Example: Input data ["Alice", "Bob", "Charlie", "Delta"] will be formatted |
+ * as "Alice, Bob, Charlie, and Delta" in English. |
+ */ |
+ |
+/** |
+ * Opaque UListFormatter object for use in C |
+ * @draft ICU 55 |
+ */ |
+struct UListFormatter; |
+typedef struct UListFormatter UListFormatter; /**< C typedef for struct UListFormatter. @draft ICU 55 */ |
+ |
+/** |
+ * Open a new UListFormatter object using the rules for a given locale. |
+ * @param locale |
+ * The locale whose rules should be used; may be NULL for |
+ * default locale. |
+ * @param status |
+ * A pointer to a standard ICU UErrorCode (input/output parameter). |
+ * Its input value must pass the U_SUCCESS() test, or else the |
+ * function returns immediately. The caller should check its output |
+ * value with U_FAILURE(), or use with function chaining (see User |
+ * Guide for details). |
+ * @return |
+ * A pointer to a UListFormatter object for the specified locale, |
+ * or NULL if an error occurred. |
+ * @draft ICU 55 |
+ */ |
+U_DRAFT UListFormatter* U_EXPORT2 |
+ulistfmt_open(const char* locale, |
+ UErrorCode* status); |
+ |
+/** |
+ * Close a UListFormatter object. Once closed it may no longer be used. |
+ * @param listfmt |
+ * The UListFormatter object to close. |
+ * @draft ICU 55 |
+ */ |
+U_DRAFT void U_EXPORT2 |
+ulistfmt_close(UListFormatter *listfmt); |
+ |
+ |
+#if U_SHOW_CPLUSPLUS_API |
+ |
+U_NAMESPACE_BEGIN |
+ |
+/** |
+ * \class LocalUListFormatterPointer |
+ * "Smart pointer" class, closes a UListFormatter via ulistfmt_close(). |
+ * For most methods see the LocalPointerBase base class. |
+ * |
+ * @see LocalPointerBase |
+ * @see LocalPointer |
+ * @draft ICU 55 |
+ */ |
+U_DEFINE_LOCAL_OPEN_POINTER(LocalUListFormatterPointer, UListFormatter, ulistfmt_close); |
+ |
+U_NAMESPACE_END |
+ |
+#endif |
+ |
+/** |
+ * Formats a list of strings using the conventions established for the |
+ * UListFormatter object. |
+ * @param listfmt |
+ * The UListFormatter object specifying the list conventions. |
+ * @param strings |
+ * An array of pointers to UChar strings; the array length is |
+ * specified by stringCount. Must be non-NULL if stringCount > 0. |
+ * @param stringLengths |
+ * An array of string lengths corresponding to the strings[] |
+ * parameter; any individual length value may be negative to indicate |
+ * that the corresponding strings[] entry is 0-terminated, or |
+ * stringLengths itself may be NULL if all of the strings are |
+ * 0-terminated. If non-NULL, the stringLengths array must have |
+ * stringCount entries. |
+ * @param stringCount |
+ * the number of entries in strings[], and the number of entries |
+ * in the stringLengths array if it is not NULL. Must be >= 0. |
+ * @param result |
+ * A pointer to a buffer to receive the formatted list. |
+ * @param resultCapacity |
+ * The maximum size of result. |
+ * @param status |
+ * A pointer to a standard ICU UErrorCode (input/output parameter). |
+ * Its input value must pass the U_SUCCESS() test, or else the |
+ * function returns immediately. The caller should check its output |
+ * value with U_FAILURE(), or use with function chaining (see User |
+ * Guide for details). |
+ * @return |
+ * The total buffer size needed; if greater than resultLength, the |
+ * output was truncated. May be <=0 if unable to determine the |
+ * total buffer size needed (e.g. for illegal arguments). |
+ * @draft ICU 55 |
+ */ |
+U_DRAFT int32_t U_EXPORT2 |
+ulistfmt_format(const UListFormatter* listfmt, |
+ const UChar* const strings[], |
+ const int32_t * stringLengths, |
+ int32_t stringCount, |
+ UChar* result, |
+ int32_t resultCapacity, |
+ UErrorCode* status); |
+ |
+#endif /* U_HIDE_DRAFT_API */ |
+#endif /* #if !UCONFIG_NO_FORMATTING */ |
+ |
+#endif |