1 /*
2 *****************************************************************************************
3 * Copyright (C) 2015, International Business Machines
4 * Corporation and others. All Rights Reserved.
5 *****************************************************************************************
6 */
7 
8 #ifndef ULISTFORMATTER_H
9 #define ULISTFORMATTER_H
10 
11 #include "unicode/utypes.h"
12 
13 #if !UCONFIG_NO_FORMATTING
14 #ifndef U_HIDE_DRAFT_API
15 
16 #include "unicode/localpointer.h"
17 
18 /**
19  * \file
20  * \brief C API: Format a list in a locale-appropriate way.
21  *
22  * A UListFormatter is used to format a list of items in a locale-appropriate way,
23  * using data from CLDR.
24  * Example: Input data ["Alice", "Bob", "Charlie", "Delta"] will be formatted
25  * as "Alice, Bob, Charlie, and Delta" in English.
26  */
27 
28 /**
29  * Opaque UListFormatter object for use in C
30  * @draft ICU 55
31  */
32 struct UListFormatter;
33 typedef struct UListFormatter UListFormatter;  /**< C typedef for struct UListFormatter. @draft ICU 55 */
34 
35 /**
36  * Open a new UListFormatter object using the rules for a given locale.
37  * @param locale
38  *            The locale whose rules should be used; may be NULL for
39  *            default locale.
40  * @param status
41  *            A pointer to a standard ICU UErrorCode (input/output parameter).
42  *            Its input value must pass the U_SUCCESS() test, or else the
43  *            function returns immediately. The caller should check its output
44  *            value with U_FAILURE(), or use with function chaining (see User
45  *            Guide for details).
46  * @return
47  *            A pointer to a UListFormatter object for the specified locale,
48  *            or NULL if an error occurred.
49  * @draft ICU 55
50  */
51 U_DRAFT UListFormatter* U_EXPORT2
52 ulistfmt_open(const char*  locale,
53               UErrorCode*  status);
54 
55 /**
56  * Close a UListFormatter object. Once closed it may no longer be used.
57  * @param listfmt
58  *            The UListFormatter object to close.
59  * @draft ICU 55
60  */
61 U_DRAFT void U_EXPORT2
62 ulistfmt_close(UListFormatter *listfmt);
63 
64 
65 #if U_SHOW_CPLUSPLUS_API
66 
67 U_NAMESPACE_BEGIN
68 
69 /**
70  * \class LocalUListFormatterPointer
71  * "Smart pointer" class, closes a UListFormatter via ulistfmt_close().
72  * For most methods see the LocalPointerBase base class.
73  *
74  * @see LocalPointerBase
75  * @see LocalPointer
76  * @draft ICU 55
77  */
78 U_DEFINE_LOCAL_OPEN_POINTER(LocalUListFormatterPointer, UListFormatter, ulistfmt_close);
79 
80 U_NAMESPACE_END
81 
82 #endif
83 
84 /**
85  * Formats a list of strings using the conventions established for the
86  * UListFormatter object.
87  * @param listfmt
88  *            The UListFormatter object specifying the list conventions.
89  * @param strings
90  *            An array of pointers to UChar strings; the array length is
91  *            specified by stringCount. Must be non-NULL if stringCount > 0.
92  * @param stringLengths
93  *            An array of string lengths corresponding to the strings[]
94  *            parameter; any individual length value may be negative to indicate
95  *            that the corresponding strings[] entry is 0-terminated, or
96  *            stringLengths itself may be NULL if all of the strings are
97  *            0-terminated. If non-NULL, the stringLengths array must have
98  *            stringCount entries.
99  * @param stringCount
100  *            the number of entries in strings[], and the number of entries
101  *            in the stringLengths array if it is not NULL. Must be >= 0.
102  * @param result
103  *            A pointer to a buffer to receive the formatted list.
104  * @param resultCapacity
105  *            The maximum size of result.
106  * @param status
107  *            A pointer to a standard ICU UErrorCode (input/output parameter).
108  *            Its input value must pass the U_SUCCESS() test, or else the
109  *            function returns immediately. The caller should check its output
110  *            value with U_FAILURE(), or use with function chaining (see User
111  *            Guide for details).
112  * @return
113  *            The total buffer size needed; if greater than resultLength, the
114  *            output was truncated. May be <=0 if unable to determine the
115  *            total buffer size needed (e.g. for illegal arguments).
116  * @draft ICU 55
117  */
118 U_DRAFT int32_t U_EXPORT2
119 ulistfmt_format(const UListFormatter* listfmt,
120                 const UChar* const strings[],
121                 const int32_t *    stringLengths,
122                 int32_t            stringCount,
123                 UChar*             result,
124                 int32_t            resultCapacity,
125                 UErrorCode*        status);
126 
127 #endif /* U_HIDE_DRAFT_API */
128 #endif /* #if !UCONFIG_NO_FORMATTING */
129 
130 #endif
131