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

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

#ifndef UDATEINTERVALFORMAT_H
#define UDATEINTERVALFORMAT_H

#include "unicode/utypes.h"

#if !UCONFIG_NO_FORMATTING

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

/**
 * \file
 * \brief C API: Format a date interval.
 *
 * A UDateIntervalFormat is used to format the range between two UDate values
 * in a locale-sensitive way, using a skeleton that specifies the precision and
 * completeness of the information to show. If the range smaller than the resolution
 * specified by the skeleton, a single date format will be produced. If the range
 * is larger than the format specified by the skeleton, a locale-specific fallback
 * will be used to format the items missing from the skeleton.
 *
 * For example, if the range is 2010-03-04 07:56 - 2010-03-04 19:56 (12 hours)
 * - The skeleton jm will produce
 *   for en_US, "7:56 AM - 7:56 PM"
 *   for en_GB, "7:56 - 19:56"
 * - The skeleton MMMd will produce
 *   for en_US, "Mar 4"
 *   for en_GB, "4 Mar"
 * If the range is 2010-03-04 07:56 - 2010-03-08 16:11 (4 days, 8 hours, 15 minutes)
 * - The skeleton jm will produce
 *   for en_US, "3/4/2010 7:56 AM - 3/8/2010 4:11 PM"
 *   for en_GB, "4/3/2010 7:56 - 8/3/2010 16:11"
 * - The skeleton MMMd will produce
 *   for en_US, "Mar 4-8"
 *   for en_GB, "4-8 Mar"
 * 
 * Note:  the "-" characters in the above sample output will actually be
 * Unicode 2013, EN_DASH, in all but the last example.
 *
 * Note, in ICU 4.4 the standard skeletons for which date interval format data
 * is usually available are as follows; best results will be obtained by using
 * skeletons from this set, or those formed by combining these standard skeletons
 * (note that for these skeletons, the length of digit field such as d, y, or
 * M vs MM is irrelevant (but for non-digit fields such as MMM vs MMMM it is
 * relevant). Note that a skeleton involving h or H generally explicitly requests
 * that time style (12- or 24-hour time respectively). For a skeleton that
 * requests the locale's default time style (h or H), use 'j' instead of h or H.
 *   h, H, hm, Hm,
 *   hv, Hv, hmv, Hmv,
 *   d,
 *   M, MMM, MMMM,
 *   Md, MMMd,
 *   MEd, MMMEd,
 *   y,
 *   yM, yMMM, yMMMM,
 *   yMd, yMMMd,
 *   yMEd, yMMMEd
 *
 * Locales for which ICU 4.4 seems to have a reasonable amount of this data
 * include:
 *   af, am, ar, be, bg, bn, ca, cs, da, de (_AT), el, en (_AU,_CA,_GB,_IE,_IN...),
 *   eo, es (_AR,_CL,_CO,...,_US) et, fa, fi, fo, fr (_BE,_CH,_CA), fur, gsw, he,
 *   hr, hu, hy, is, it (_CH), ja, kk, km, ko, lt, lv, mk, ml, mt, nb, nl )_BE),
 *   nn, pl, pt (_PT), rm, ro, ru (_UA), sk, sl, so, sq, sr, sr_Latn, sv, th, to,
 *   tr, uk, ur, vi, zh (_SG), zh_Hant (_HK,_MO)
 */

/**
 * Opaque UDateIntervalFormat object for use in C programs.
 * @stable ICU 4.8
 */
struct UDateIntervalFormat;
typedef struct UDateIntervalFormat UDateIntervalFormat;  /**< C typedef for struct UDateIntervalFormat. @stable ICU 4.8 */

/**
 * Open a new UDateIntervalFormat object using the predefined rules for a
 * given locale plus a specified skeleton.
 * @param locale
 *            The locale for whose rules should be used; may be NULL for
 *            default locale.
 * @param skeleton
 *            A pattern containing only the fields desired for the interval
 *            format, for example "Hm", "yMMMd", or "yMMMEdHm".
 * @param skeletonLength
 *            The length of skeleton; may be -1 if the skeleton is zero-terminated.
 * @param tzID
 *            A timezone ID specifying the timezone to use. If 0, use the default
 *            timezone.
 * @param tzIDLength
 *            The length of tzID, or -1 if null-terminated. If 0, use the default
 *            timezone.
 * @param status
 *            A pointer to a UErrorCode to receive any errors.
 * @return
 *            A pointer to a UDateIntervalFormat object for the specified locale,
 *            or NULL if an error occurred.
 * @stable ICU 4.8
 */
U_STABLE UDateIntervalFormat* U_EXPORT2
udtitvfmt_open(const char*  locale,
              const UChar* skeleton,
              int32_t      skeletonLength,
              const UChar* tzID,
              int32_t      tzIDLength,
              UErrorCode*  status);

/**
 * Close a UDateIntervalFormat object. Once closed it may no longer be used.
 * @param formatter
 *            The UDateIntervalFormat object to close.
 * @stable ICU 4.8
 */
U_STABLE void U_EXPORT2
udtitvfmt_close(UDateIntervalFormat *formatter);


#if U_SHOW_CPLUSPLUS_API

U_NAMESPACE_BEGIN

/**
 * \class LocalUDateIntervalFormatPointer
 * "Smart pointer" class, closes a UDateIntervalFormat via udtitvfmt_close().
 * For most methods see the LocalPointerBase base class.
 *
 * @see LocalPointerBase
 * @see LocalPointer
 * @stable ICU 4.8
 */
U_DEFINE_LOCAL_OPEN_POINTER(LocalUDateIntervalFormatPointer, UDateIntervalFormat, udtitvfmt_close);

U_NAMESPACE_END

#endif // U_SHOW_CPLUSPLUS_API


/**
 * Formats a date/time range using the conventions established for the
 * UDateIntervalFormat object.
 * @param formatter
 *            The UDateIntervalFormat object specifying the format conventions.
 * @param fromDate
 *            The starting point of the range.
 * @param toDate
 *            The ending point of the range.
 * @param result
 *            A pointer to a buffer to receive the formatted range.
 * @param resultCapacity
 *            The maximum size of result.
 * @param position
 *            A pointer to a UFieldPosition. On input, position->field is read.
 *            On output, position->beginIndex and position->endIndex indicate
 *            the beginning and ending indices of field number position->field,
 *            if such a field exists. This parameter may be NULL, in which case
 *            no field position data is returned.
 *            There may be multiple instances of a given field type in an
 *            interval format; in this case the position indices refer to the
 *            first instance.
 * @param status
 *            A pointer to a UErrorCode to receive any errors.
 * @return
 *            The total buffer size needed; if greater than resultLength, the
 *            output was truncated.
 * @stable ICU 4.8
 */
U_STABLE int32_t U_EXPORT2
udtitvfmt_format(const UDateIntervalFormat* formatter,
                UDate           fromDate,
                UDate           toDate,
                UChar*          result,
                int32_t         resultCapacity,
                UFieldPosition* position,
                UErrorCode*     status);

#ifndef U_HIDE_DRAFT_API
/**
 * Attributes and values to control the behavior of udtitvfmt_format.
 * @internal
 */
typedef enum UDateIntervalFormatAttribute {
    /**
     * @internal
     */
    UDTITVFMT_MINIMIZE_TYPE
} UDateIntervalFormatAttribute;

typedef enum UDateIntervalFormatAttributeValue {
    /**
     * Standard behavior, no additional minimization.
     * @internal
     */
    UDTITVFMT_MINIMIZE_NONE = 0,
    /**
     * For intervals of less than 1 month that cross month boundaries,
     * only show one month (use format for greatestDifference=d).
     * @internal
     */
    UDTITVFMT_MINIMIZE_ADJACENT_MONTHS,
    /**
     * For intervals of less than 12 hours that cross day boundaries,
     * only show one day (use format for greatestDifference=h).
     * @internal
     */
    UDTITVFMT_MINIMIZE_ADJACENT_DAYS
} UDateIntervalFormatAttributeValue;

/**
 * Change attributes for the UDateIntervalFormat object.
 * @param formatter
 *            The UDateIntervalFormat object whose attributes are to be changed.
 * @param attr
 *            The attribute to change.
 * @param value
 *            The new value for the attribute.
 * @param status
 *            A pointer to a UErrorCode to receive any errors.
 * @internal
 */
U_INTERNAL void U_EXPORT2 
udtitvfmt_setAttribute(UDateIntervalFormat*             formatter,
                      UDateIntervalFormatAttribute      attr,
                      UDateIntervalFormatAttributeValue value,
                      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
4388f060 A	3	/*
4388f060 A	4	*****************************************************************************************
2ca993e8	5	* Copyright (C) 2010-2012,2015-2016 International Business Machines
4388f060 A	6	* Corporation and others. All Rights Reserved.
	7	*****************************************************************************************
	8	*/
	9
	10	#ifndef UDATEINTERVALFORMAT_H
	11	#define UDATEINTERVALFORMAT_H
	12
	13	#include "unicode/utypes.h"
	14
	15	#if !UCONFIG_NO_FORMATTING
	16
	17	#include "unicode/umisc.h"
	18	#include "unicode/localpointer.h"
	19
	20	/**
	21	* \file
	22	* \brief C API: Format a date interval.
	23	*
	24	* A UDateIntervalFormat is used to format the range between two UDate values
	25	* in a locale-sensitive way, using a skeleton that specifies the precision and
	26	* completeness of the information to show. If the range smaller than the resolution
	27	* specified by the skeleton, a single date format will be produced. If the range
	28	* is larger than the format specified by the skeleton, a locale-specific fallback
	29	* will be used to format the items missing from the skeleton.
	30	*
	31	* For example, if the range is 2010-03-04 07:56 - 2010-03-04 19:56 (12 hours)
	32	* - The skeleton jm will produce
	33	* for en_US, "7:56 AM - 7:56 PM"
	34	* for en_GB, "7:56 - 19:56"
	35	* - The skeleton MMMd will produce
	36	* for en_US, "Mar 4"
	37	* for en_GB, "4 Mar"
	38	* If the range is 2010-03-04 07:56 - 2010-03-08 16:11 (4 days, 8 hours, 15 minutes)
	39	* - The skeleton jm will produce
	40	* for en_US, "3/4/2010 7:56 AM - 3/8/2010 4:11 PM"
	41	* for en_GB, "4/3/2010 7:56 - 8/3/2010 16:11"
	42	* - The skeleton MMMd will produce
	43	* for en_US, "Mar 4-8"
	44	* for en_GB, "4-8 Mar"
	45	*
	46	* Note: the "-" characters in the above sample output will actually be
	47	* Unicode 2013, EN_DASH, in all but the last example.
	48	*
	49	* Note, in ICU 4.4 the standard skeletons for which date interval format data
	50	* is usually available are as follows; best results will be obtained by using
	51	* skeletons from this set, or those formed by combining these standard skeletons
	52	* (note that for these skeletons, the length of digit field such as d, y, or
	53	* M vs MM is irrelevant (but for non-digit fields such as MMM vs MMMM it is
	54	* relevant). Note that a skeleton involving h or H generally explicitly requests
	55	* that time style (12- or 24-hour time respectively). For a skeleton that
	56	* requests the locale's default time style (h or H), use 'j' instead of h or H.
	57	* h, H, hm, Hm,
	58	* hv, Hv, hmv, Hmv,
	59	* d,
	60	* M, MMM, MMMM,
	61	* Md, MMMd,
	62	* MEd, MMMEd,
	63	* y,
	64	* yM, yMMM, yMMMM,
	65	* yMd, yMMMd,
	66	* yMEd, yMMMEd
	67	*
	68	* Locales for which ICU 4.4 seems to have a reasonable amount of this data
	69	* include:
70	* af, am, ar, be, bg, bn, ca, cs, da, de (_AT), el, en (_AU,_CA,_GB,_IE,_IN...),
71	* eo, es (_AR,_CL,_CO,...,_US) et, fa, fi, fo, fr (_BE,_CH,_CA), fur, gsw, he,
72	* hr, hu, hy, is, it (_CH), ja, kk, km, ko, lt, lv, mk, ml, mt, nb, nl )_BE),
73	* nn, pl, pt (_PT), rm, ro, ru (_UA), sk, sl, so, sq, sr, sr_Latn, sv, th, to,
74	* tr, uk, ur, vi, zh (_SG), zh_Hant (_HK,_MO)
75	*/
76
77	/**
78	* Opaque UDateIntervalFormat object for use in C programs.
79	* @stable ICU 4.8
80	*/
81	struct UDateIntervalFormat;
82	typedef struct UDateIntervalFormat UDateIntervalFormat; /*< C typedef for struct UDateIntervalFormat. @stable ICU 4.8 /
83
84	/**
85	* Open a new UDateIntervalFormat object using the predefined rules for a
86	* given locale plus a specified skeleton.
87	* @param locale
88	* The locale for whose rules should be used; may be NULL for
89	* default locale.
90	* @param skeleton
91	* A pattern containing only the fields desired for the interval
92	* format, for example "Hm", "yMMMd", or "yMMMEdHm".
93	* @param skeletonLength
94	* The length of skeleton; may be -1 if the skeleton is zero-terminated.
95	* @param tzID
96	* A timezone ID specifying the timezone to use. If 0, use the default
97	* timezone.
98	* @param tzIDLength
99	* The length of tzID, or -1 if null-terminated. If 0, use the default
100	* timezone.
101	* @param status
102	* A pointer to a UErrorCode to receive any errors.
103	* @return
104	* A pointer to a UDateIntervalFormat object for the specified locale,
105	* or NULL if an error occurred.
106	* @stable ICU 4.8
107	*/
51004dcb	108	U_STABLE UDateIntervalFormat* U_EXPORT2
4388f060 A	109	udtitvfmt_open(const char* locale,
	110	const UChar* skeleton,
	111	int32_t skeletonLength,
	112	const UChar* tzID,
	113	int32_t tzIDLength,
	114	UErrorCode* status);
	115
	116	/**
	117	* Close a UDateIntervalFormat object. Once closed it may no longer be used.
	118	* @param formatter
	119	* The UDateIntervalFormat object to close.
	120	* @stable ICU 4.8
	121	*/
51004dcb	122	U_STABLE void U_EXPORT2
4388f060 A	123	udtitvfmt_close(UDateIntervalFormat *formatter);
	124
	125
	126	#if U_SHOW_CPLUSPLUS_API
	127
	128	U_NAMESPACE_BEGIN
	129
	130	/**
	131	* \class LocalUDateIntervalFormatPointer
	132	* "Smart pointer" class, closes a UDateIntervalFormat via udtitvfmt_close().
	133	* For most methods see the LocalPointerBase base class.
	134	*
	135	* @see LocalPointerBase
	136	* @see LocalPointer
	137	* @stable ICU 4.8
	138	*/
	139	U_DEFINE_LOCAL_OPEN_POINTER(LocalUDateIntervalFormatPointer, UDateIntervalFormat, udtitvfmt_close);
	140
	141	U_NAMESPACE_END
	142
f3c0d7a5	143	#endif // U_SHOW_CPLUSPLUS_API
4388f060 A	144
	145
	146	/**
	147	* Formats a date/time range using the conventions established for the
	148	* UDateIntervalFormat object.
	149	* @param formatter
	150	* The UDateIntervalFormat object specifying the format conventions.
	151	* @param fromDate
	152	* The starting point of the range.
	153	* @param toDate
	154	* The ending point of the range.
	155	* @param result
	156	* A pointer to a buffer to receive the formatted range.
	157	* @param resultCapacity
	158	* The maximum size of result.
	159	* @param position
	160	* A pointer to a UFieldPosition. On input, position->field is read.
	161	* On output, position->beginIndex and position->endIndex indicate
	162	* the beginning and ending indices of field number position->field,
	163	* if such a field exists. This parameter may be NULL, in which case
	164	* no field position data is returned.
2ca993e8 A	165	* There may be multiple instances of a given field type in an
	166	* interval format; in this case the position indices refer to the
	167	* first instance.
4388f060 A	168	* @param status
	169	* A pointer to a UErrorCode to receive any errors.
	170	* @return
	171	* The total buffer size needed; if greater than resultLength, the
	172	* output was truncated.
	173	* @stable ICU 4.8
	174	*/
51004dcb	175	U_STABLE int32_t U_EXPORT2
4388f060 A	176	udtitvfmt_format(const UDateIntervalFormat* formatter,
	177	UDate fromDate,
	178	UDate toDate,
	179	UChar* result,
	180	int32_t resultCapacity,
	181	UFieldPosition* position,
	182	UErrorCode* status);
	183
	184	#ifndef U_HIDE_DRAFT_API
	185	/**
	186	* Attributes and values to control the behavior of udtitvfmt_format.
	187	* @internal
	188	*/
	189	typedef enum UDateIntervalFormatAttribute {
	190	/**
	191	* @internal
	192	*/
	193	UDTITVFMT_MINIMIZE_TYPE
	194	} UDateIntervalFormatAttribute;
	195
	196	typedef enum UDateIntervalFormatAttributeValue {
	197	/**
	198	* Standard behavior, no additional minimization.
	199	* @internal
	200	*/
	201	UDTITVFMT_MINIMIZE_NONE = 0,
	202	/**
	203	* For intervals of less than 1 month that cross month boundaries,
	204	* only show one month (use format for greatestDifference=d).
	205	* @internal
	206	*/
2ca993e8 A	207	UDTITVFMT_MINIMIZE_ADJACENT_MONTHS,
	208	/**
	209	* For intervals of less than 12 hours that cross day boundaries,
	210	* only show one day (use format for greatestDifference=h).
	211	* @internal
	212	*/
	213	UDTITVFMT_MINIMIZE_ADJACENT_DAYS
4388f060 A	214	} UDateIntervalFormatAttributeValue;
	215
	216	/**
	217	* Change attributes for the UDateIntervalFormat object.
	218	* @param formatter
	219	* The UDateIntervalFormat object whose attributes are to be changed.
	220	* @param attr
	221	* The attribute to change.
	222	* @param value
	223	* The new value for the attribute.
	224	* @param status
	225	* A pointer to a UErrorCode to receive any errors.
	226	* @internal
	227	*/
	228	U_INTERNAL void U_EXPORT2
	229	udtitvfmt_setAttribute(UDateIntervalFormat* formatter,
	230	UDateIntervalFormatAttribute attr,
	231	UDateIntervalFormatAttributeValue value,
	232	UErrorCode* status);
	233
	234	#endif /* U_HIDE_DRAFT_API */
	235	#endif /* #if !UCONFIG_NO_FORMATTING */
	236
	237	#endif