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

/*
*****************************************************************************************
* Copyright (C) 2014 Apple Inc. All Rights Reserved.
*****************************************************************************************
*/

#ifndef UATIMEUNITFORMAT_H
#define UATIMEUNITFORMAT_H

#include "unicode/utypes.h"

#if !UCONFIG_NO_FORMATTING
#ifndef U_HIDE_DRAFT_API

#include "unicode/localpointer.h"
#include "unicode/unum.h"

/**
 * \file
 * \brief C API: Support functions for formatting time units or portions thereof.
 *
 * These are somewhat temporary Apple-only functions to support NSDateComponentsFormatter.
 */

/**
 * Opaque UATimeUnitFormat object for use in C programs.
 * @draft ICU 53
 */
struct UATimeUnitFormat;
typedef struct UATimeUnitFormat UATimeUnitFormat;  /**< C typedef for struct UATimeUnitFormat. @draft ICU 53 */

/**
 * TimeUnit format styles
 * @draft ICU 53
 */
typedef enum UATimeUnitStyle {
    /**
     * full style, e.g. "1.0 minutes"
     * @draft ICU 53 */
    UATIMEUNITSTYLE_FULL,
    /**
     * abbreviated/short style, e.g. "1.0 min"
     * @draft ICU 53 */
    UATIMEUNITSTYLE_ABBREVIATED,
    /**
     * narrow style, e.g. "1.0 m"
     * @draft ICU 53 */
    UATIMEUNITSTYLE_NARROW,
    /**
     * shorter style,between abbreviated and narrow"
     * @draft ICU 57 */
    UATIMEUNITSTYLE_SHORTER,
    /** @draft ICU 53 */
    UATIMEUNITSTYLE_COUNT
} UATimeUnitStyle;

/**
 * TimeUnit fields
 * @draft ICU 53
 */
typedef enum UATimeUnitField {
    /** @draft ICU 53 */
    UATIMEUNITFIELD_YEAR,
    /** @draft ICU 53 */
    UATIMEUNITFIELD_MONTH,
    /** @draft ICU 53 */
    UATIMEUNITFIELD_DAY,
    /** @draft ICU 53 */
    UATIMEUNITFIELD_WEEK,
    /** @draft ICU 53 */
    UATIMEUNITFIELD_HOUR,
    /** @draft ICU 53 */
    UATIMEUNITFIELD_MINUTE,
    /** @draft ICU 53 */
    UATIMEUNITFIELD_SECOND,
    /** @draft ICU 53 */
    UATIMEUNITFIELD_COUNT
} UATimeUnitField;

/**
 * Open a new UATimeUnitFormat object for a given locale using the specified style,
 * using the default decimal formatter.
 * @param locale
 *            The locale
 * @param style
 *            The style (width) - full, abbreviated, etc.
 * @param status
 *            A pointer to a UErrorCode to receive any errors.
 * @return
 *            A pointer to a UATimeUnitFormat object for the specified locale,
 *            or NULL if an error occurred.
 * @draft ICU 53
 */
U_DRAFT UATimeUnitFormat* U_EXPORT2
uatmufmt_open(const char*  locale,
              UATimeUnitStyle style,
              UErrorCode*  status);

/**
 * Open a new UATimeUnitFormat object for a given locale using the specified style,
 * along with the number formatter to use for the numeric part of the time unit,
 * e.g. "1 min", "1.0 min", etc.
* @param locale
 *            The locale
 * @param style
 *            The style (width) - full, abbreviated, etc.
 * @param nfToAdopt
 *            A number formatter to set for this UATimeUnitFormat object (instead of
 *            the default decimal formatter). Ownership of this UNumberFormat object
 *            will pass to the UATimeUnitFormat object (the UATimeUnitFormat adopts the
 *            UNumberFormat), which becomes responsible for closing it. If the caller
 *            wishes to retain ownership of the UNumberFormat object, the caller must
 *            clone it (with unum_clone) and pass the clone to
 *            uatmufmt_openWithNumberFormat. May be NULL to use the default decimal
 *            formatter.
 * @param status
 *            A pointer to a UErrorCode to receive any errors.
 * @return
 *            A pointer to a UATimeUnitFormat object for the specified locale,
 *            or NULL if an error occurred.
 * @draft ICU 53
 */
U_DRAFT UATimeUnitFormat* U_EXPORT2
uatmufmt_openWithNumberFormat(const char*  locale,
                            UATimeUnitStyle style,
                            UNumberFormat*  nfToAdopt,
                            UErrorCode*  status);

/**
 * Close a UATimeUnitFormat object. Once closed it may no longer be used.
 * @param tufmt
 *            The UATimeUnitFormat object to close.
 * @draft ICU 53
 */
U_DRAFT void U_EXPORT2
uatmufmt_close(UATimeUnitFormat *tufmt);


#if U_SHOW_CPLUSPLUS_API

U_NAMESPACE_BEGIN

/**
 * \class LocalUDateIntervalFormatPointer
 * "Smart pointer" class, closes a UATimeUnitFormat via uatmufmt_close().
 * For most methods see the LocalPointerBase base class.
 *
 * @see LocalPointerBase
 * @see LocalPointer
 * @draft ICU 53
 */
U_DEFINE_LOCAL_OPEN_POINTER(LocalUATimeUnitFormatPointer, UATimeUnitFormat, uatmufmt_close);

U_NAMESPACE_END

#endif // U_SHOW_CPLUSPLUS_API


/**
 * Set the number formatter to use for the numeric part of the time unit,
 * e.g. "1 min", "1.0 min", etc.
 * DO NOT USE - use uatmufmt_openWithNumberFormat instead, this will be
 * removed soon.
 * @param tufmt
 *            The UATimeUnitFormat object specifying the format conventions.
 * @param numfmt
 *            The number formatter to set for this UATimeUnitFormat object;
 *            uatmufmt_setNumberFormat clones this for its own use, so the
 *            caller retains ownership of the passed-in UNumberFormat object.
 * @param status
 *            A pointer to a UErrorCode to receive any errors.
 * @deprecated ICU 53, use uatmufmt_openWithNumberFormat
 */
U_DEPRECATED void U_EXPORT2
uatmufmt_setNumberFormat(UATimeUnitFormat* tufmt,
                        UNumberFormat*  numfmt,
                        UErrorCode*     status);

/**
 * Format a value like 1.0 and a field like UATIMEUNIT_MINUTE to e.g. "1.0 minutes".
 * @param tufmt
 *            The UATimeUnitFormat object specifying the format conventions.
 * @param value
 *            The numeric value to format
 * @param field
 *            The time field to format with the specified numeric value
 * @param result
 *            A pointer to a buffer to receive the formatted result.
 * @param resultCapacity
 *            The maximum size of result.
 * @param status
 *            A pointer to a UErrorCode to receive any errors. In case of error status,
 *            the contents of result are undefined.
 * @return
 *            The length of the formatted result; may be greater than resultCapacity,
 *            in which case an error is returned.
 * @draft ICU 53
 */
U_DRAFT int32_t U_EXPORT2
uatmufmt_format(const UATimeUnitFormat* tufmt,
                double          value,
                UATimeUnitField field,
                UChar*          result,
                int32_t         resultCapacity,
                UErrorCode*     status);


/**
 * Parse a single formatted time unit like "1.0 minutes" into a numeric value and unit type.
 * NOT CURRENTLY SUPPORTED, sets status to U_UNSUPPORTED_ERROR and returns 0.0. 
 * @param tufmt
 *            The UATimeUnitFormat object specifying the format conventions.
 * @param text
 *            The text to parse
 * @param textLength
 *            The length of text, or -1 if null-terminated
 * @param parsePos
 *            A pointer to an offset index into text at which to begin parsing. On output,
 *            *parsePos will point after the last parsed character. This parameter may be
 *            NULL, in which case parsing begins at offset 0.
 * @param field
 *            A pointer to a UATimeUnitField to be set to the parsed firled type.
 * @param status
 *            A pointer to a UErrorCode to receive any errors.
 * @return
 *            The parsed double value.
 * @draft ICU 53
 */
U_DRAFT double U_EXPORT2
uatmufmt_parse( const UATimeUnitFormat* tufmt,
                const UChar*    text,
                int32_t         textLength,
                int32_t*        parsePos,
                UATimeUnitField* field,
                UErrorCode*     status);


/**
 * TimeUnit time duration positional pattern types
 * @draft ICU 53
 */
typedef enum UATimeUnitTimePattern {
    /**
     * e.g. "h:mm"
     * @draft ICU 53 */
    UATIMEUNITTIMEPAT_HM,
    /**
     * e.g. "h:mm:ss"
     * @draft ICU 53 */
    UATIMEUNITTIMEPAT_HMS,
    /**
     * e.g. "m:ss"
     * @draft ICU 53 */
    UATIMEUNITTIMEPAT_MS,
    /** @draft ICU 53 */
    UATIMEUNITTIMEPAT_COUNT
} UATimeUnitTimePattern;

/**
 * Get a localized pattern for positional duration style, e.g. "h:mm:ss".
 * This comes from the durationUnits CLDR data in ICU, e.g.
 *  durationUnits{
 *      hm{"h:mm"}
 *      hms{"h:mm:ss"}
 *      ms{"m:ss"}
 *  }
 * For usage see CLDR documentation on durationUnit under
 * <a href="http://www.unicode.org/reports/tr35/tr35-general.html#Unit_Elements">Unit Elements</a>.
 *
 * @param locale
 *            The locale
 * @param type
 *            The type of time pattern to get (hm, hms, ms)
 * @param result
 *            A pointer to a buffer to receive the formatted result.
 * @param resultCapacity
 *            The maximum size of result.
 * @param status
 *            A pointer to a UErrorCode to receive any errors. In case of error status,
 *            the contents of result are undefined.
 * @return
 *            The length of the formatted result; may be greater than resultCapacity,
 *            in which case an error is returned.
 * @draft ICU 53
 */
U_DRAFT int32_t U_EXPORT2
uatmufmt_getTimePattern(const char*     locale,
                        UATimeUnitTimePattern type,
                        UChar*          result,
                        int32_t         resultCapacity,
                        UErrorCode*     status);


/**
 * TimeUnit list pattern types
 * @draft ICU 53
 */
typedef enum UATimeUnitListPattern {
    /**
     * for two only, e.g. "{0} and {1}"
     * @draft ICU 53 */
    UATIMEUNITLISTPAT_TWO_ONLY,
    /**
     * for end of list with 3 or more, e.g. "{0}, and {1}"
     * @draft ICU 53 */
    UATIMEUNITLISTPAT_END_PIECE,
    /**
     * for middle of list with 3 or more, e.g. "{0}, {1}"
     * @draft ICU 53 */
    UATIMEUNITLISTPAT_MIDDLE_PIECE,
    /**
     * for start of list with 3 or more, e.g. "{0}, {1}"
     * @draft ICU 53 */
    UATIMEUNITLISTPAT_START_PIECE,
    /** @draft ICU 53 */
    UATIMEUNITLISTPAT_COUNT
} UATimeUnitListPattern;

/**
 * Get a localized pattern for combining units in a list, e.g. "3 min, 42 sec".
 * This comes from the listPattern/unit* CLDR data in ICU, e.g.
 *  listPattern{
 *      unit{
 *          .. use short if not present
 *      }
 *      unit-short{
 *          2{"{0}, {1}"}
 *          end{"{0}, {1}"}
 *          middle{"{0}, {1}"}
 *          start{"{0}, {1}"}
 *      }
 *      unit-narrow{
 *          .. use short if not present
 *      }
 *  }
 * For usage see CLDR documentation on
 * <a href="http://www.unicode.org/reports/tr35/tr35-general.html#ListPatterns">List Patterns</a>.
 *
 * @param locale
 *            The locale
 * @param style
 *            The style (width) - full, abbreviated, etc.
 * @param type
 *            The type of list pattern to get (for two items, end part for >= 3 items, etc.)
 * @param result
 *            A pointer to a buffer to receive the formatted result.
 * @param resultCapacity
 *            The maximum size of result.
 * @param status
 *            A pointer to a UErrorCode to receive any errors. In case of error status,
 *            the contents of result are undefined.
 * @return
 *            The length of the formatted result; may be greater than resultCapacity,
 *            in which case an error is returned.
 * @draft ICU 53
 */
U_DRAFT int32_t U_EXPORT2
uatmufmt_getListPattern(const char*     locale,
                        UATimeUnitStyle style,
                        UATimeUnitListPattern type,
                        UChar*          result,
                        int32_t         resultCapacity,
                        UErrorCode*     status);


#endif /* U_HIDE_DRAFT_API */
#endif /* #if !UCONFIG_NO_FORMATTING */

#endif /* #ifndef UATIMEUNITFORMAT_H */
Commit	Line	Data
57a6839d A	1	/*
	2	*****************************************************************************************
	3	* Copyright (C) 2014 Apple Inc. All Rights Reserved.
	4	*****************************************************************************************
	5	*/
	6
	7	#ifndef UATIMEUNITFORMAT_H
	8	#define UATIMEUNITFORMAT_H
	9
	10	#include "unicode/utypes.h"
	11
	12	#if !UCONFIG_NO_FORMATTING
	13	#ifndef U_HIDE_DRAFT_API
	14
	15	#include "unicode/localpointer.h"
	16	#include "unicode/unum.h"
	17
	18	/**
	19	* \file
	20	* \brief C API: Support functions for formatting time units or portions thereof.
	21	*
	22	* These are somewhat temporary Apple-only functions to support NSDateComponentsFormatter.
	23	*/
	24
	25	/**
	26	* Opaque UATimeUnitFormat object for use in C programs.
	27	* @draft ICU 53
	28	*/
	29	struct UATimeUnitFormat;
	30	typedef struct UATimeUnitFormat UATimeUnitFormat; /*< C typedef for struct UATimeUnitFormat. @draft ICU 53 /
	31
	32	/**
	33	* TimeUnit format styles
	34	* @draft ICU 53
	35	*/
	36	typedef enum UATimeUnitStyle {
	37	/**
	38	* full style, e.g. "1.0 minutes"
	39	* @draft ICU 53 */
	40	UATIMEUNITSTYLE_FULL,
	41	/**
	42	* abbreviated/short style, e.g. "1.0 min"
	43	* @draft ICU 53 */
	44	UATIMEUNITSTYLE_ABBREVIATED,
	45	/**
	46	* narrow style, e.g. "1.0 m"
	47	* @draft ICU 53 */
	48	UATIMEUNITSTYLE_NARROW,
2ca993e8 A	49	/**
	50	* shorter style,between abbreviated and narrow"
	51	* @draft ICU 57 */
	52	UATIMEUNITSTYLE_SHORTER,
57a6839d A	53	/** @draft ICU 53 */
	54	UATIMEUNITSTYLE_COUNT
	55	} UATimeUnitStyle;
	56
	57	/**
	58	* TimeUnit fields
	59	* @draft ICU 53
	60	*/
	61	typedef enum UATimeUnitField {
	62	/** @draft ICU 53 */
	63	UATIMEUNITFIELD_YEAR,
	64	/** @draft ICU 53 */
	65	UATIMEUNITFIELD_MONTH,
	66	/** @draft ICU 53 */
	67	UATIMEUNITFIELD_DAY,
	68	/** @draft ICU 53 */
	69	UATIMEUNITFIELD_WEEK,
	70	/** @draft ICU 53 */
	71	UATIMEUNITFIELD_HOUR,
	72	/** @draft ICU 53 */
	73	UATIMEUNITFIELD_MINUTE,
	74	/** @draft ICU 53 */
	75	UATIMEUNITFIELD_SECOND,
	76	/** @draft ICU 53 */
	77	UATIMEUNITFIELD_COUNT
	78	} UATimeUnitField;
	79
	80	/**
	81	* Open a new UATimeUnitFormat object for a given locale using the specified style,
	82	* using the default decimal formatter.
	83	* @param locale
	84	* The locale
	85	* @param style
	86	* The style (width) - full, abbreviated, etc.
	87	* @param status
	88	* A pointer to a UErrorCode to receive any errors.
	89	* @return
	90	* A pointer to a UATimeUnitFormat object for the specified locale,
	91	* or NULL if an error occurred.
	92	* @draft ICU 53
	93	*/
	94	U_DRAFT UATimeUnitFormat* U_EXPORT2
	95	uatmufmt_open(const char* locale,
	96	UATimeUnitStyle style,
	97	UErrorCode* status);
	98
	99	/**
	100	* Open a new UATimeUnitFormat object for a given locale using the specified style,
	101	* along with the number formatter to use for the numeric part of the time unit,
	102	* e.g. "1 min", "1.0 min", etc.
	103	* @param locale
	104	* The locale
	105	* @param style
	106	* The style (width) - full, abbreviated, etc.
	107	* @param nfToAdopt
	108	* A number formatter to set for this UATimeUnitFormat object (instead of
	109	* the default decimal formatter). Ownership of this UNumberFormat object
	110	* will pass to the UATimeUnitFormat object (the UATimeUnitFormat adopts the
	111	* UNumberFormat), which becomes responsible for closing it. If the caller
	112	* wishes to retain ownership of the UNumberFormat object, the caller must
	113	* clone it (with unum_clone) and pass the clone to
	114	* uatmufmt_openWithNumberFormat. May be NULL to use the default decimal
	115	* formatter.
	116	* @param status
117	* A pointer to a UErrorCode to receive any errors.
118	* @return
119	* A pointer to a UATimeUnitFormat object for the specified locale,
120	* or NULL if an error occurred.
121	* @draft ICU 53
122	*/
123	U_DRAFT UATimeUnitFormat* U_EXPORT2
124	uatmufmt_openWithNumberFormat(const char* locale,
125	UATimeUnitStyle style,
126	UNumberFormat* nfToAdopt,
127	UErrorCode* status);
128
129	/**
130	* Close a UATimeUnitFormat object. Once closed it may no longer be used.
131	* @param tufmt
132	* The UATimeUnitFormat object to close.
133	* @draft ICU 53
134	*/
135	U_DRAFT void U_EXPORT2
136	uatmufmt_close(UATimeUnitFormat *tufmt);
137
138
139	#if U_SHOW_CPLUSPLUS_API
140
141	U_NAMESPACE_BEGIN
142
143	/**
144	* \class LocalUDateIntervalFormatPointer
145	* "Smart pointer" class, closes a UATimeUnitFormat via uatmufmt_close().
146	* For most methods see the LocalPointerBase base class.
147	*
148	* @see LocalPointerBase
149	* @see LocalPointer
150	* @draft ICU 53
151	*/
152	U_DEFINE_LOCAL_OPEN_POINTER(LocalUATimeUnitFormatPointer, UATimeUnitFormat, uatmufmt_close);
153
154	U_NAMESPACE_END
155
f3c0d7a5	156	#endif // U_SHOW_CPLUSPLUS_API
57a6839d A	157
	158
	159	/**
	160	* Set the number formatter to use for the numeric part of the time unit,
	161	* e.g. "1 min", "1.0 min", etc.
	162	* DO NOT USE - use uatmufmt_openWithNumberFormat instead, this will be
	163	* removed soon.
	164	* @param tufmt
	165	* The UATimeUnitFormat object specifying the format conventions.
	166	* @param numfmt
	167	* The number formatter to set for this UATimeUnitFormat object;
	168	* uatmufmt_setNumberFormat clones this for its own use, so the
	169	* caller retains ownership of the passed-in UNumberFormat object.
	170	* @param status
	171	* A pointer to a UErrorCode to receive any errors.
	172	* @deprecated ICU 53, use uatmufmt_openWithNumberFormat
	173	*/
	174	U_DEPRECATED void U_EXPORT2
	175	uatmufmt_setNumberFormat(UATimeUnitFormat* tufmt,
	176	UNumberFormat* numfmt,
	177	UErrorCode* status);
	178
	179	/**
	180	* Format a value like 1.0 and a field like UATIMEUNIT_MINUTE to e.g. "1.0 minutes".
	181	* @param tufmt
	182	* The UATimeUnitFormat object specifying the format conventions.
	183	* @param value
	184	* The numeric value to format
	185	* @param field
	186	* The time field to format with the specified numeric value
	187	* @param result
	188	* A pointer to a buffer to receive the formatted result.
	189	* @param resultCapacity
	190	* The maximum size of result.
	191	* @param status
	192	* A pointer to a UErrorCode to receive any errors. In case of error status,
	193	* the contents of result are undefined.
	194	* @return
	195	* The length of the formatted result; may be greater than resultCapacity,
	196	* in which case an error is returned.
	197	* @draft ICU 53
	198	*/
	199	U_DRAFT int32_t U_EXPORT2
	200	uatmufmt_format(const UATimeUnitFormat* tufmt,
	201	double value,
	202	UATimeUnitField field,
	203	UChar* result,
	204	int32_t resultCapacity,
	205	UErrorCode* status);
	206
	207
	208	/**
	209	* Parse a single formatted time unit like "1.0 minutes" into a numeric value and unit type.
	210	* NOT CURRENTLY SUPPORTED, sets status to U_UNSUPPORTED_ERROR and returns 0.0.
	211	* @param tufmt
	212	* The UATimeUnitFormat object specifying the format conventions.
	213	* @param text
	214	* The text to parse
	215	* @param textLength
	216	* The length of text, or -1 if null-terminated
	217	* @param parsePos
	218	* A pointer to an offset index into text at which to begin parsing. On output,
	219	* *parsePos will point after the last parsed character. This parameter may be
	220	* NULL, in which case parsing begins at offset 0.
221	* @param field
222	* A pointer to a UATimeUnitField to be set to the parsed firled type.
223	* @param status
224	* A pointer to a UErrorCode to receive any errors.
225	* @return
226	* The parsed double value.
227	* @draft ICU 53
228	*/
229	U_DRAFT double U_EXPORT2
230	uatmufmt_parse( const UATimeUnitFormat* tufmt,
231	const UChar* text,
232	int32_t textLength,
233	int32_t* parsePos,
234	UATimeUnitField* field,
235	UErrorCode* status);
236
237
238	/**
239	* TimeUnit time duration positional pattern types
240	* @draft ICU 53
241	*/
242	typedef enum UATimeUnitTimePattern {
243	/**
244	* e.g. "h:mm"
245	* @draft ICU 53 */
246	UATIMEUNITTIMEPAT_HM,
247	/**
248	* e.g. "h:mm:ss"
249	* @draft ICU 53 */
250	UATIMEUNITTIMEPAT_HMS,
251	/**
252	* e.g. "m:ss"
253	* @draft ICU 53 */
254	UATIMEUNITTIMEPAT_MS,
255	/** @draft ICU 53 */
256	UATIMEUNITTIMEPAT_COUNT
257	} UATimeUnitTimePattern;
258
259	/**
260	* Get a localized pattern for positional duration style, e.g. "h:mm:ss".
261	* This comes from the durationUnits CLDR data in ICU, e.g.
262	* durationUnits{
263	* hm{"h:mm"}
264	* hms{"h:mm:ss"}
265	* ms{"m:ss"}
266	* }
267	* For usage see CLDR documentation on durationUnit under
268	* <a href="http://www.unicode.org/reports/tr35/tr35-general.html#Unit_Elements">Unit Elements</a>.
269	*
270	* @param locale
271	* The locale
272	* @param type
273	* The type of time pattern to get (hm, hms, ms)
274	* @param result
275	* A pointer to a buffer to receive the formatted result.
276	* @param resultCapacity
277	* The maximum size of result.
278	* @param status
279	* A pointer to a UErrorCode to receive any errors. In case of error status,
280	* the contents of result are undefined.
281	* @return
282	* The length of the formatted result; may be greater than resultCapacity,
283	* in which case an error is returned.
284	* @draft ICU 53
285	*/
286	U_DRAFT int32_t U_EXPORT2
287	uatmufmt_getTimePattern(const char* locale,
288	UATimeUnitTimePattern type,
289	UChar* result,
290	int32_t resultCapacity,
291	UErrorCode* status);
292
293
294	/**
295	* TimeUnit list pattern types
296	* @draft ICU 53
297	*/
298	typedef enum UATimeUnitListPattern {
299	/**
300	* for two only, e.g. "{0} and {1}"
301	* @draft ICU 53 */
302	UATIMEUNITLISTPAT_TWO_ONLY,
303	/**
304	* for end of list with 3 or more, e.g. "{0}, and {1}"
305	* @draft ICU 53 */
306	UATIMEUNITLISTPAT_END_PIECE,
307	/**
308	* for middle of list with 3 or more, e.g. "{0}, {1}"
309	* @draft ICU 53 */
310	UATIMEUNITLISTPAT_MIDDLE_PIECE,
311	/**
312	* for start of list with 3 or more, e.g. "{0}, {1}"
313	* @draft ICU 53 */
314	UATIMEUNITLISTPAT_START_PIECE,
315	/** @draft ICU 53 */
316	UATIMEUNITLISTPAT_COUNT
317	} UATimeUnitListPattern;
318
319	/**
320	* Get a localized pattern for combining units in a list, e.g. "3 min, 42 sec".
321	* This comes from the listPattern/unit* CLDR data in ICU, e.g.
322	* listPattern{
323	* unit{
324	* .. use short if not present
325	* }
326	* unit-short{
327	* 2{"{0}, {1}"}
328	* end{"{0}, {1}"}
329	* middle{"{0}, {1}"}
330	* start{"{0}, {1}"}
331	* }
332	* unit-narrow{
333	* .. use short if not present
334	* }
335	* }
336	* For usage see CLDR documentation on
337	* <a href="http://www.unicode.org/reports/tr35/tr35-general.html#ListPatterns">List Patterns</a>.
338	*
339	* @param locale
340	* The locale
341	* @param style
342	* The style (width) - full, abbreviated, etc.
343	* @param type
344	* The type of list pattern to get (for two items, end part for >= 3 items, etc.)
345	* @param result
346	* A pointer to a buffer to receive the formatted result.
347	* @param resultCapacity
348	* The maximum size of result.
349	* @param status
350	* A pointer to a UErrorCode to receive any errors. In case of error status,
351	* the contents of result are undefined.
352	* @return
353	* The length of the formatted result; may be greater than resultCapacity,
354	* in which case an error is returned.
355	* @draft ICU 53
356	*/
357	U_DRAFT int32_t U_EXPORT2
358	uatmufmt_getListPattern(const char* locale,
359	UATimeUnitStyle style,
360	UATimeUnitListPattern type,
361	UChar* result,
362	int32_t resultCapacity,
363	UErrorCode* status);
364
365
366	#endif /* U_HIDE_DRAFT_API */
367	#endif /* #if !UCONFIG_NO_FORMATTING */
368
369	#endif /* #ifndef UATIMEUNITFORMAT_H */