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

/*
*****************************************************************************************
* 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
Commit	Line	Data
b331163b A	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