ICU-551.24.tar.gz

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

diff --git a/icuSources/common/unicode/ulistformatter.h b/icuSources/common/unicode/ulistformatter.h
new file mode 100644 (file)
index 0000000..1c6cb2d
--- /dev/null
+++ b/icuSources/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