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

// © 2016 and later: Unicode, Inc. and others.
// License & terms of use: http://www.unicode.org/copyright.html
/*
*****************************************************************************************
* Copyright (C) 2015-2016, International Business Machines
* Corporation and others. All Rights Reserved.
*****************************************************************************************
*/

#ifndef ULISTFORMATTER_H
#define ULISTFORMATTER_H

#include "unicode/utypes.h"

#if !UCONFIG_NO_FORMATTING

#include "unicode/localpointer.h"
#include "unicode/uformattedvalue.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
 * @stable ICU 55
 */
struct UListFormatter;
typedef struct UListFormatter UListFormatter;  /**< C typedef for struct UListFormatter. @stable ICU 55 */

#ifndef U_HIDE_DRAFT_API
struct UFormattedList;
/**
 * Opaque struct to contain the results of a UListFormatter operation.
 * @draft ICU 64
 */
typedef struct UFormattedList UFormattedList;
#endif /* U_HIDE_DRAFT_API */

#ifndef U_HIDE_DRAFT_API
/**
 * FieldPosition and UFieldPosition selectors for format fields
 * defined by ListFormatter.
 * @draft ICU 63
 */
typedef enum UListFormatterField {
    /**
     * The literal text in the result which came from the resources.
     * @draft ICU 63
     */
    ULISTFMT_LITERAL_FIELD,
    /**
     * The element text in the result which came from the input strings.
     * @draft ICU 63
     */
    ULISTFMT_ELEMENT_FIELD
} UListFormatterField;
#endif // U_HIDE_DRAFT_API

/**
 * 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.
 * @stable ICU 55
 */
U_CAPI 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.
 * @stable ICU 55
 */
U_CAPI void U_EXPORT2
ulistfmt_close(UListFormatter *listfmt);

#ifndef U_HIDE_DRAFT_API
/**
 * Creates an object to hold the result of a UListFormatter
 * operation. The object can be used repeatedly; it is cleared whenever
 * passed to a format function.
 *
 * @param ec Set if an error occurs.
 * @return A pointer needing ownership.
 * @draft ICU 64
 */
U_CAPI UFormattedList* U_EXPORT2
ulistfmt_openResult(UErrorCode* ec);

/**
 * Returns a representation of a UFormattedList as a UFormattedValue,
 * which can be subsequently passed to any API requiring that type.
 *
 * The returned object is owned by the UFormattedList and is valid
 * only as long as the UFormattedList is present and unchanged in memory.
 *
 * You can think of this method as a cast between types.
 *
 * When calling ufmtval_nextPosition():
 * The fields are returned from start to end. The special field category
 * UFIELD_CATEGORY_LIST_SPAN is used to indicate which argument
 * was inserted at the given position. The span category will
 * always occur before the corresponding instance of UFIELD_CATEGORY_LIST
 * in the ufmtval_nextPosition() iterator.
 *
 * @param uresult The object containing the formatted string.
 * @param ec Set if an error occurs.
 * @return A UFormattedValue owned by the input object.
 * @draft ICU 64
 */
U_CAPI const UFormattedValue* U_EXPORT2
ulistfmt_resultAsValue(const UFormattedList* uresult, UErrorCode* ec);

/**
 * Releases the UFormattedList created by ulistfmt_openResult().
 *
 * @param uresult The object to release.
 * @draft ICU 64
 */
U_CAPI void U_EXPORT2
ulistfmt_closeResult(UFormattedList* uresult);
#endif /* U_HIDE_DRAFT_API */


#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
 * @stable ICU 55
 */
U_DEFINE_LOCAL_OPEN_POINTER(LocalUListFormatterPointer, UListFormatter, ulistfmt_close);

#ifndef U_HIDE_DRAFT_API
/**
 * \class LocalUFormattedListPointer
 * "Smart pointer" class, closes a UFormattedList via ulistfmt_closeResult().
 * For most methods see the LocalPointerBase base class.
 *
 * @see LocalPointerBase
 * @see LocalPointer
 * @draft ICU 64
 */
U_DEFINE_LOCAL_OPEN_POINTER(LocalUFormattedListPointer, UFormattedList, ulistfmt_closeResult);
#endif /* U_HIDE_DRAFT_API */

U_NAMESPACE_END

#endif // U_SHOW_CPLUSPLUS_API

/**
 * 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).
 * @stable ICU 55
 */
U_CAPI 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);

#ifndef U_HIDE_DRAFT_API
/**
 * Formats a list of strings to a UFormattedList, which exposes more
 * information than the string exported by ulistfmt_format().
 *
 * @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 uresult
 *            The object in which to store the result of the list formatting
 *            operation. See ulistfmt_openResult().
 * @param status
 *            Error code set if an error occurred during formatting.
 * @draft ICU 64
 */
U_CAPI void U_EXPORT2
ulistfmt_formatStringsToResult(
                const UListFormatter* listfmt,
                const UChar* const strings[],
                const int32_t *    stringLengths,
                int32_t            stringCount,
                UFormattedList*    uresult,
                UErrorCode*        status);
#endif /* U_HIDE_DRAFT_API */

#endif /* #if !UCONFIG_NO_FORMATTING */

#endif
Commit	Line	Data
f3c0d7a5 A	1	// © 2016 and later: Unicode, Inc. and others.
f3c0d7a5 A	2	// License & terms of use: http://www.unicode.org/copyright.html
b331163b A	3	/*
b331163b A	4	*****************************************************************************************
2ca993e8	5	* Copyright (C) 2015-2016, International Business Machines
b331163b A	6	* Corporation and others. All Rights Reserved.
	7	*****************************************************************************************
	8	*/
	9
	10	#ifndef ULISTFORMATTER_H
	11	#define ULISTFORMATTER_H
	12
	13	#include "unicode/utypes.h"
	14
	15	#if !UCONFIG_NO_FORMATTING
b331163b A	16
b331163b A	17	#include "unicode/localpointer.h"
3d1f044b	18	#include "unicode/uformattedvalue.h"
b331163b A	19
	20	/**
	21	* \file
	22	* \brief C API: Format a list in a locale-appropriate way.
	23	*
	24	* A UListFormatter is used to format a list of items in a locale-appropriate way,
	25	* using data from CLDR.
	26	* Example: Input data ["Alice", "Bob", "Charlie", "Delta"] will be formatted
	27	* as "Alice, Bob, Charlie, and Delta" in English.
	28	*/
	29
	30	/**
	31	* Opaque UListFormatter object for use in C
2ca993e8	32	* @stable ICU 55
b331163b A	33	*/
b331163b A	34	struct UListFormatter;
2ca993e8	35	typedef struct UListFormatter UListFormatter; /*< C typedef for struct UListFormatter. @stable ICU 55 /
b331163b	36
3d1f044b A	37	#ifndef U_HIDE_DRAFT_API
	38	struct UFormattedList;
	39	/**
	40	* Opaque struct to contain the results of a UListFormatter operation.
	41	* @draft ICU 64
	42	*/
	43	typedef struct UFormattedList UFormattedList;
	44	#endif /* U_HIDE_DRAFT_API */
	45
	46	#ifndef U_HIDE_DRAFT_API
	47	/**
	48	* FieldPosition and UFieldPosition selectors for format fields
	49	* defined by ListFormatter.
	50	* @draft ICU 63
	51	*/
	52	typedef enum UListFormatterField {
	53	/**
	54	* The literal text in the result which came from the resources.
	55	* @draft ICU 63
	56	*/
	57	ULISTFMT_LITERAL_FIELD,
	58	/**
	59	* The element text in the result which came from the input strings.
	60	* @draft ICU 63
	61	*/
	62	ULISTFMT_ELEMENT_FIELD
	63	} UListFormatterField;
	64	#endif // U_HIDE_DRAFT_API
	65
b331163b A	66	/**
	67	* Open a new UListFormatter object using the rules for a given locale.
	68	* @param locale
	69	* The locale whose rules should be used; may be NULL for
	70	* default locale.
	71	* @param status
	72	* A pointer to a standard ICU UErrorCode (input/output parameter).
	73	* Its input value must pass the U_SUCCESS() test, or else the
	74	* function returns immediately. The caller should check its output
	75	* value with U_FAILURE(), or use with function chaining (see User
	76	* Guide for details).
	77	* @return
	78	* A pointer to a UListFormatter object for the specified locale,
	79	* or NULL if an error occurred.
2ca993e8	80	* @stable ICU 55
b331163b	81	*/
f3c0d7a5	82	U_CAPI UListFormatter* U_EXPORT2
b331163b A	83	ulistfmt_open(const char* locale,
	84	UErrorCode* status);
	85
	86	/**
	87	* Close a UListFormatter object. Once closed it may no longer be used.
	88	* @param listfmt
	89	* The UListFormatter object to close.
2ca993e8	90	* @stable ICU 55
b331163b	91	*/
f3c0d7a5	92	U_CAPI void U_EXPORT2
b331163b A	93	ulistfmt_close(UListFormatter *listfmt);
b331163b A	94
3d1f044b A	95	#ifndef U_HIDE_DRAFT_API
	96	/**
	97	* Creates an object to hold the result of a UListFormatter
	98	* operation. The object can be used repeatedly; it is cleared whenever
	99	* passed to a format function.
	100	*
	101	* @param ec Set if an error occurs.
	102	* @return A pointer needing ownership.
	103	* @draft ICU 64
	104	*/
	105	U_CAPI UFormattedList* U_EXPORT2
	106	ulistfmt_openResult(UErrorCode* ec);
	107
	108	/**
	109	* Returns a representation of a UFormattedList as a UFormattedValue,
	110	* which can be subsequently passed to any API requiring that type.
	111	*
	112	* The returned object is owned by the UFormattedList and is valid
	113	* only as long as the UFormattedList is present and unchanged in memory.
	114	*
	115	* You can think of this method as a cast between types.
	116	*
	117	* When calling ufmtval_nextPosition():
	118	* The fields are returned from start to end. The special field category
	119	* UFIELD_CATEGORY_LIST_SPAN is used to indicate which argument
	120	* was inserted at the given position. The span category will
	121	* always occur before the corresponding instance of UFIELD_CATEGORY_LIST
	122	* in the ufmtval_nextPosition() iterator.
	123	*
	124	* @param uresult The object containing the formatted string.
	125	* @param ec Set if an error occurs.
	126	* @return A UFormattedValue owned by the input object.
	127	* @draft ICU 64
	128	*/
	129	U_CAPI const UFormattedValue* U_EXPORT2
	130	ulistfmt_resultAsValue(const UFormattedList* uresult, UErrorCode* ec);
	131
	132	/**
	133	* Releases the UFormattedList created by ulistfmt_openResult().
	134	*
	135	* @param uresult The object to release.
	136	* @draft ICU 64
	137	*/
	138	U_CAPI void U_EXPORT2
	139	ulistfmt_closeResult(UFormattedList* uresult);
	140	#endif /* U_HIDE_DRAFT_API */
	141
b331163b A	142
	143	#if U_SHOW_CPLUSPLUS_API
	144
	145	U_NAMESPACE_BEGIN
	146
	147	/**
	148	* \class LocalUListFormatterPointer
	149	* "Smart pointer" class, closes a UListFormatter via ulistfmt_close().
	150	* For most methods see the LocalPointerBase base class.
	151	*
	152	* @see LocalPointerBase
	153	* @see LocalPointer
2ca993e8	154	* @stable ICU 55
b331163b A	155	*/
	156	U_DEFINE_LOCAL_OPEN_POINTER(LocalUListFormatterPointer, UListFormatter, ulistfmt_close);
	157
3d1f044b A	158	#ifndef U_HIDE_DRAFT_API
	159	/**
	160	* \class LocalUFormattedListPointer
	161	* "Smart pointer" class, closes a UFormattedList via ulistfmt_closeResult().
	162	* For most methods see the LocalPointerBase base class.
	163	*
	164	* @see LocalPointerBase
	165	* @see LocalPointer
	166	* @draft ICU 64
	167	*/
	168	U_DEFINE_LOCAL_OPEN_POINTER(LocalUFormattedListPointer, UFormattedList, ulistfmt_closeResult);
	169	#endif /* U_HIDE_DRAFT_API */
	170
b331163b A	171	U_NAMESPACE_END
b331163b A	172
f3c0d7a5	173	#endif // U_SHOW_CPLUSPLUS_API
b331163b A	174
	175	/**
	176	* Formats a list of strings using the conventions established for the
	177	* UListFormatter object.
	178	* @param listfmt
	179	* The UListFormatter object specifying the list conventions.
	180	* @param strings
	181	* An array of pointers to UChar strings; the array length is
	182	* specified by stringCount. Must be non-NULL if stringCount > 0.
	183	* @param stringLengths
	184	* An array of string lengths corresponding to the strings[]
	185	* parameter; any individual length value may be negative to indicate
	186	* that the corresponding strings[] entry is 0-terminated, or
	187	* stringLengths itself may be NULL if all of the strings are
	188	* 0-terminated. If non-NULL, the stringLengths array must have
	189	* stringCount entries.
	190	* @param stringCount
	191	* the number of entries in strings[], and the number of entries
	192	* in the stringLengths array if it is not NULL. Must be >= 0.
	193	* @param result
	194	* A pointer to a buffer to receive the formatted list.
	195	* @param resultCapacity
	196	* The maximum size of result.
	197	* @param status
	198	* A pointer to a standard ICU UErrorCode (input/output parameter).
	199	* Its input value must pass the U_SUCCESS() test, or else the
	200	* function returns immediately. The caller should check its output
	201	* value with U_FAILURE(), or use with function chaining (see User
	202	* Guide for details).
	203	* @return
	204	* The total buffer size needed; if greater than resultLength, the
	205	* output was truncated. May be <=0 if unable to determine the
	206	* total buffer size needed (e.g. for illegal arguments).
2ca993e8	207	* @stable ICU 55
b331163b	208	*/
f3c0d7a5	209	U_CAPI int32_t U_EXPORT2
b331163b A	210	ulistfmt_format(const UListFormatter* listfmt,
	211	const UChar* const strings[],
	212	const int32_t * stringLengths,
	213	int32_t stringCount,
	214	UChar* result,
	215	int32_t resultCapacity,
	216	UErrorCode* status);
	217
3d1f044b A	218	#ifndef U_HIDE_DRAFT_API
	219	/**
	220	* Formats a list of strings to a UFormattedList, which exposes more
	221	* information than the string exported by ulistfmt_format().
	222	*
	223	* @param listfmt
	224	* The UListFormatter object specifying the list conventions.
	225	* @param strings
	226	* An array of pointers to UChar strings; the array length is
	227	* specified by stringCount. Must be non-NULL if stringCount > 0.
	228	* @param stringLengths
	229	* An array of string lengths corresponding to the strings[]
	230	* parameter; any individual length value may be negative to indicate
	231	* that the corresponding strings[] entry is 0-terminated, or
	232	* stringLengths itself may be NULL if all of the strings are
	233	* 0-terminated. If non-NULL, the stringLengths array must have
	234	* stringCount entries.
	235	* @param stringCount
	236	* the number of entries in strings[], and the number of entries
	237	* in the stringLengths array if it is not NULL. Must be >= 0.
	238	* @param uresult
	239	* The object in which to store the result of the list formatting
	240	* operation. See ulistfmt_openResult().
	241	* @param status
	242	* Error code set if an error occurred during formatting.
	243	* @draft ICU 64
	244	*/
	245	U_CAPI void U_EXPORT2
	246	ulistfmt_formatStringsToResult(
	247	const UListFormatter* listfmt,
	248	const UChar* const strings[],
	249	const int32_t * stringLengths,
	250	int32_t stringCount,
	251	UFormattedList* uresult,
	252	UErrorCode* status);
	253	#endif /* U_HIDE_DRAFT_API */
	254
b331163b A	255	#endif /* #if !UCONFIG_NO_FORMATTING */
	256
	257	#endif