C API: Format a date interval. More...

#include "unicode/utypes.h"
#include "unicode/ucal.h"
#include "unicode/umisc.h"
#include "unicode/uformattedvalue.h"
#include "unicode/udisplaycontext.h"
#include "unicode/localpointer.h"

Namespaces
namespace	icu
	File coll.h.

Typedefs
typedef struct UDateIntervalFormat	UDateIntervalFormat
	C typedef for struct UDateIntervalFormat.

typedef struct UFormattedDateInterval	UFormattedDateInterval
	Opaque struct to contain the results of a UDateIntervalFormat operation.

Functions
U_CAPI UDateIntervalFormat *	udtitvfmt_open (const char locale, const UChar skeleton, int32_t skeletonLength, const UChar tzID, int32_t tzIDLength, UErrorCode status)
	Open a new UDateIntervalFormat object using the predefined rules for a given locale plus a specified skeleton.

U_CAPI void	udtitvfmt_close (UDateIntervalFormat *formatter)
	Close a UDateIntervalFormat object.

U_CAPI UFormattedDateInterval *	udtitvfmt_openResult (UErrorCode *ec)
	Creates an object to hold the result of a UDateIntervalFormat operation.

U_CAPI const UFormattedValue *	udtitvfmt_resultAsValue (const UFormattedDateInterval uresult, UErrorCode ec)
	Returns a representation of a UFormattedDateInterval as a UFormattedValue, which can be subsequently passed to any API requiring that type.

U_CAPI void	udtitvfmt_closeResult (UFormattedDateInterval *uresult)
	Releases the UFormattedDateInterval created by udtitvfmt_openResult().

U_CAPI int32_t	udtitvfmt_format (const UDateIntervalFormat formatter, UDate fromDate, UDate toDate, UChar result, int32_t resultCapacity, UFieldPosition position, UErrorCode status)
	Formats a date/time range using the conventions established for the UDateIntervalFormat object.

U_CAPI void	udtitvfmt_formatToResult (const UDateIntervalFormat formatter, UDate fromDate, UDate toDate, UFormattedDateInterval result, UErrorCode *status)
	Formats a date/time range using the conventions established for the UDateIntervalFormat object.

U_CAPI void	udtitvfmt_formatCalendarToResult (const UDateIntervalFormat formatter, UCalendar fromCalendar, UCalendar toCalendar, UFormattedDateInterval result, UErrorCode *status)
	Formats a date/time range using the conventions established for the UDateIntervalFormat object.

U_CAPI void	udtitvfmt_setContext (UDateIntervalFormat formatter, UDisplayContext value, UErrorCode status)
	Set a particular UDisplayContext value in the formatter, such as UDISPCTX_CAPITALIZATION_FOR_STANDALONE.

U_CAPI UDisplayContext	udtitvfmt_getContext (const UDateIntervalFormat formatter, UDisplayContextType type, UErrorCode status)
	Get the formatter's UDisplayContext value for the specified UDisplayContextType, such as UDISPCTX_TYPE_CAPITALIZATION.

Detailed Description

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)

Definition in file udateintervalformat.h.

Typedef Documentation

◆ UDateIntervalFormat

typedef struct UDateIntervalFormat UDateIntervalFormat

C typedef for struct UDateIntervalFormat.

Stable:: ICU 4.8

Definition at line 88 of file udateintervalformat.h.

◆ UFormattedDateInterval

typedef struct UFormattedDateInterval UFormattedDateInterval

Opaque struct to contain the results of a UDateIntervalFormat operation.

Stable:: ICU 64

Definition at line 95 of file udateintervalformat.h.

Function Documentation

◆ udtitvfmt_close()

U_CAPI void udtitvfmt_close ( UDateIntervalFormat * formatter )

Close a UDateIntervalFormat object.

Once closed it may no longer be used.

Parameters

formatter The UDateIntervalFormat object to close.

Stable:: ICU 4.8

◆ udtitvfmt_closeResult()

U_CAPI void udtitvfmt_closeResult ( UFormattedDateInterval * uresult )

Releases the UFormattedDateInterval created by udtitvfmt_openResult().

Parameters

uresult The object to release.

Stable:: ICU 64

◆ udtitvfmt_format()

U_CAPI int32_t udtitvfmt_format	(	const UDateIntervalFormat *	formatter,
		UDate	fromDate,
		UDate	toDate,
		UChar *	result,
		int32_t	resultCapacity,
		UFieldPosition *	position,
		UErrorCode *	status
	)

Formats a date/time range using the conventions established for the UDateIntervalFormat object.

Parameters

formatter	The UDateIntervalFormat object specifying the format conventions.
fromDate	The starting point of the range.
toDate	The ending point of the range.
result	A pointer to a buffer to receive the formatted range.
resultCapacity	The maximum size of result.
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.
status	A pointer to a UErrorCode to receive any errors.

Returns: The total buffer size needed; if greater than resultLength, the output was truncated.

Stable:: ICU 4.8

◆ udtitvfmt_formatCalendarToResult()

U_CAPI void udtitvfmt_formatCalendarToResult	(	const UDateIntervalFormat *	formatter,
		UCalendar *	fromCalendar,
		UCalendar *	toCalendar,
		UFormattedDateInterval *	result,
		UErrorCode *	status
	)

Formats a date/time range using the conventions established for the UDateIntervalFormat object.

Parameters

formatter	The UDateIntervalFormat object specifying the format conventions.
fromCalendar	The starting point of the range.
toCalendar	The ending point of the range.
result	The UFormattedDateInterval to contain the result of the formatting operation.
status	A pointer to a UErrorCode to receive any errors.

Stable:: ICU 67

◆ udtitvfmt_formatToResult()

U_CAPI void udtitvfmt_formatToResult	(	const UDateIntervalFormat *	formatter,
		UDate	fromDate,
		UDate	toDate,
		UFormattedDateInterval *	result,
		UErrorCode *	status
	)

Formats a date/time range using the conventions established for the UDateIntervalFormat object.

Parameters

formatter	The UDateIntervalFormat object specifying the format conventions.
fromDate	The starting point of the range.
toDate	The ending point of the range.
result	The UFormattedDateInterval to contain the result of the formatting operation.
status	A pointer to a UErrorCode to receive any errors.

Stable:: ICU 67

◆ udtitvfmt_getContext()

U_CAPI UDisplayContext udtitvfmt_getContext	(	const UDateIntervalFormat *	formatter,
		UDisplayContextType	type,
		UErrorCode *	status
	)

Get the formatter's UDisplayContext value for the specified UDisplayContextType, such as UDISPCTX_TYPE_CAPITALIZATION.

Parameters

formatter	The formatter to query.
type	The UDisplayContextType whose value to return
status	A pointer to an UErrorCode to receive any errors

Returns: The UDisplayContextValue for the specified type.

Stable:: ICU 68

◆ udtitvfmt_open()

U_CAPI UDateIntervalFormat * udtitvfmt_open	(	const char *	locale,
		const UChar *	skeleton,
		int32_t	skeletonLength,
		const UChar *	tzID,
		int32_t	tzIDLength,
		UErrorCode *	status
	)

Open a new UDateIntervalFormat object using the predefined rules for a given locale plus a specified skeleton.

Parameters

locale	The locale for whose rules should be used; may be NULL for default locale.
skeleton	A pattern containing only the fields desired for the interval format, for example "Hm", "yMMMd", or "yMMMEdHm".
skeletonLength	The length of skeleton; may be -1 if the skeleton is zero-terminated.
tzID	A timezone ID specifying the timezone to use. If 0, use the default timezone.
tzIDLength	The length of tzID, or -1 if null-terminated. If 0, use the default timezone.
status	A pointer to a UErrorCode to receive any errors.

Returns: A pointer to a UDateIntervalFormat object for the specified locale, or NULL if an error occurred.

Stable:: ICU 4.8

◆ udtitvfmt_openResult()

U_CAPI UFormattedDateInterval * udtitvfmt_openResult ( UErrorCode * ec )

Creates an object to hold the result of a UDateIntervalFormat operation.

The object can be used repeatedly; it is cleared whenever passed to a format function.

Parameters

ec	Set if an error occurs.

Returns: A pointer needing ownership.

Stable:: ICU 64

◆ udtitvfmt_resultAsValue()

U_CAPI const UFormattedValue * udtitvfmt_resultAsValue	(	const UFormattedDateInterval *	uresult,
		UErrorCode *	ec
	)

Returns a representation of a UFormattedDateInterval as a UFormattedValue, which can be subsequently passed to any API requiring that type.

The returned object is owned by the UFormattedDateInterval and is valid only as long as the UFormattedDateInterval 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 left to right. The special field category UFIELD_CATEGORY_DATE_INTERVAL_SPAN is used to indicate which datetime primitives came from which arguments: 0 means fromCalendar, and 1 means toCalendar. The span category will always occur before the corresponding fields in UFIELD_CATEGORY_DATE in the ufmtval_nextPosition() iterator.

Parameters

uresult	The object containing the formatted string.
ec	Set if an error occurs.

Returns: A UFormattedValue owned by the input object.

Stable:: ICU 64

◆ udtitvfmt_setContext()

U_CAPI void udtitvfmt_setContext	(	UDateIntervalFormat *	formatter,
		UDisplayContext	value,
		UErrorCode *	status
	)

Set a particular UDisplayContext value in the formatter, such as UDISPCTX_CAPITALIZATION_FOR_STANDALONE.

This causes the formatted result to be capitalized appropriately for the context in which it is intended to be used, considering both the locale and the type of field at the beginning of the formatted result.

Parameters

formatter	The formatter for which to set a UDisplayContext value.
value	The UDisplayContext value to set.
status	A pointer to an UErrorCode to receive any errors

Stable:: ICU 68

Namespaces

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ UDateIntervalFormat

◆ UFormattedDateInterval

Function Documentation

◆ udtitvfmt_close()

◆ udtitvfmt_closeResult()

◆ udtitvfmt_format()

◆ udtitvfmt_formatCalendarToResult()

◆ udtitvfmt_formatToResult()

◆ udtitvfmt_getContext()

◆ udtitvfmt_open()

◆ udtitvfmt_openResult()

◆ udtitvfmt_resultAsValue()

◆ udtitvfmt_setContext()