Date Interval Format module formats date intervals in a language-independent manner.

Required Header

#include <utils_i18n.h>

Overview

Date Interval Format module formats a Date Interval into text as compactly as possible. For example, the date interval format from "Jan 11, 2008" to "Jan 18,. 2008" is "Jan 11-18, 2008" for English.

There is no structural information in date time patterns. For any punctuations and string literals inside a date time pattern, we do not know whether it is just a separator, or a prefix, or a suffix. Without such information, so, it is difficult to generate a sub-pattern (or super-pattern) by algorithm. So, formatting a Date Interval is pattern-driven.

A skeleton * only keeps the field pattern letter and ignores all other parts in a pattern, such as space, punctuations, and string literals. * hides the order of fields. * might hide a field's pattern letter length.

For those non-digit calendar fields, the pattern letter length is important, such as MMM, MMMM, and MMMMM; EEE and EEEE, and the field's pattern letter length is honored.

The calendar fields we support for interval formatting are: year, month, date, day-of-week, am-pm, hour, hour-of-day, minute, and second (though we do not currently have specific interval format date for skeletons with seconds). Those calendar fields can be defined in the following order: year > month > date > hour (in day) > minute > second.

The largest different calendar fields between 2 calendars is the first different calendar field in above order.

For example: the largest different calendar fields between "Jan 10, 2007" and "Feb 20, 2008" is year.

For other calendar fields, the compact interval formatting is not supported. And the interval format will be fall back to fall-back patterns, which is mostly "{date0} - {date1}".

There is a set of pre-defined static skeleton strings. There are pre-defined interval patterns for those pre-defined skeletons in locales' resource files. For example, for a skeleton I18N_UDATE_YEAR_ABBR_MONTH_DAY, which is "yMMMd", in en_US, if the largest different calendar field between date1 and date2 is "year", the date interval pattern is "MMM d, yyyy - MMM d, yyyy", such as "Jan 10, 2007 - Jan 10, 2008". If the largest different calendar field between date1 and date2 is "month", the date interval pattern is "MMM d - MMM d, yyyy", such as "Jan 10 - Feb 10, 2007". If the largest different calendar field between date1 and date2 is "day", the date interval pattern is "MMM d-d, yyyy", such as "Jan 10-20, 2007".

For date skeleton, the interval patterns when year, or month, or date is different are defined in resource files. For time skeleton, the interval patterns when am/pm, or hour, or minute is different are defined in resource files.

Functions
int	i18n_date_interval_fmt_create (const char skeleton, i18n_date_interval_fmt_h date_interval_fmt)
	Creates a date interval format object with a non-specified locale.
int	i18n_date_interval_fmt_create_from_locale (const char skeleton, const char locale, i18n_date_interval_fmt_h *date_interval_fmt)
	Creates a date interval format object for the given locale.
int	i18n_date_interval_fmt_clone (i18n_date_interval_fmt_h date_interval_fmt, i18n_date_interval_fmt_h *clone)
	Creates a clone of the given date_interval_fmt object.
int	i18n_date_interval_fmt_destroy (i18n_date_interval_fmt_h date_interval_fmt)
	Destroys the date interval format object.
int	i18n_date_interval_fmt_equals (i18n_date_interval_fmt_h date_interval_fmt_1, i18n_date_interval_fmt_h date_interval_fmt_2, bool *equals)
	Checks whether two date interval format objects are equal.
int	i18n_date_interval_fmt_set_time_zone (i18n_date_interval_fmt_h date_interval_fmt, i18n_timezone_h timezone)
	Sets the time zone for the calendar used by the i18n_date_interval_fmt_h object.
int	i18n_date_interval_fmt_get_time_zone (i18n_date_interval_fmt_h date_interval_fmt, i18n_timezone_h *timezone)
	Gets the time zone used by the i18n_date_interval_fmt_h object.
int	i18n_date_interval_fmt_adopt_time_zone (i18n_date_interval_fmt_h date_interval_fmt, i18n_timezone_h timezone)
	Adopts the time zone for the calendar used by the i18n_date_interval_fmt_h object.
int	i18n_date_interval_fmt_format_with_date_interval (i18n_date_interval_fmt_h date_interval_fmt, i18n_date_interval_h date_interval, char **append_to, i18n_field_position_h field_position)
	Formats a date interval to produce a string.
int	i18n_date_interval_fmt_format_with_calendar (i18n_date_interval_fmt_h date_interval_fmt, i18n_ucalendar_h from_cal, i18n_ucalendar_h to_cal, char **append_to, i18n_field_position_h field_position)
	Formats two calendars to produce a string.
Typedefs
typedef void *	i18n_date_interval_fmt_h
	An i18n_date_interval_fmt_h handle.

Typedef Documentation

typedef void* i18n_date_interval_fmt_h

An i18n_date_interval_fmt_h handle.

Use i18n_date_interval_fmt_* functions to operate on i18n_date_interval_fmt_h objects.

Since :: 5.0

Function Documentation

int i18n_date_interval_fmt_adopt_time_zone	(	i18n_date_interval_fmt_h	date_interval_fmt,
		i18n_timezone_h	timezone
	)

Adopts the time zone for the calendar used by the i18n_date_interval_fmt_h object.

The caller no longer owns the timezone object and should not delete it after this call.

Since :: 5.0

Parameters:

[in]	date_interval_fmt	The date interval format object
[out]	timezone	The time zone used by date_interval_fmt object

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_date_interval_fmt_clone	(	i18n_date_interval_fmt_h	date_interval_fmt,
		i18n_date_interval_fmt_h *	clone
	)

Creates a clone of the given date_interval_fmt object.

Since :: 5.0

Remarks:: The clone object should be released by the caller with the i18n_date_interval_fmt_destroy() function.

Parameters:

[in]	date_interval_fmt	The date interval format object to be cloned
[out]	clone	The created date interval format object

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_date_interval_fmt_create	(	const char *	skeleton,
		i18n_date_interval_fmt_h *	date_interval_fmt
	)

Creates a date interval format object with a non-specified locale.

Since :: 5.0

Remarks:: The created object should be released by the caller with the i18n_date_interval_fmt_destroy() function.

Parameters:

[in]	skeleton	The skeleton on which interval format based
[out]	date_interval_fmt	The created date interval format object

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_date_interval_fmt_create_from_locale	(	const char *	skeleton,
		const char *	locale,
		i18n_date_interval_fmt_h *	date_interval_fmt
	)

Creates a date interval format object for the given locale.

Since :: 5.0

Remarks:: The created object should be released by the caller with the i18n_date_interval_fmt_destroy() function.

Parameters:

[in]	skeleton	The skeleton on which interval format based
[in]	locale	The locale value
[out]	date_interval_fmt	The created date interval format object

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_OUT_OF_MEMORY	Out of memory

int i18n_date_interval_fmt_destroy ( i18n_date_interval_fmt_h date_interval_fmt )

Destroys the date interval format object.

Since :: 5.0

Parameters:

[in] date_interval_fmt The date interval format object to destroy

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_date_interval_fmt_equals	(	i18n_date_interval_fmt_h	date_interval_fmt_1,
		i18n_date_interval_fmt_h	date_interval_fmt_2,
		bool *	equals
	)

Checks whether two date interval format objects are equal.

Since :: 5.0

Parameters:

[in]	date_interval_fmt_1	The first date interval format object
[in]	date_interval_fmt_2	The second date interval format object
[out]	equals	`true` if date_interval_fmt1 is equal to `date_interval_fmt2`, `false` otherwise

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_date_interval_fmt_format_with_calendar	(	i18n_date_interval_fmt_h	date_interval_fmt,
		i18n_ucalendar_h	from_cal,
		i18n_ucalendar_h	to_cal,
		char **	append_to,
		i18n_field_position_h	field_position
	)

Formats two calendars to produce a string.

Since :: 5.0

Parameters:

[in]	date_interval_fmt	The date interval format object
[in]	from_cal	Calendar set to the 'from date' in date interval to be formatted into date interval string
[in]	to_cal	Calendar set to the 'to date' in date interval to be formatted into date interval string
[in,out]	append_to	Input/output parameter to receive the result. The result is appended to the existing contents.
[in]	field_position	The i18n_field_position_h object

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_BUFFER_OVERFLOW	Buffer overflow

int i18n_date_interval_fmt_format_with_date_interval	(	i18n_date_interval_fmt_h	date_interval_fmt,
		i18n_date_interval_h	date_interval,
		char **	append_to,
		i18n_field_position_h	field_position
	)

Formats a date interval to produce a string.

Since :: 5.0

Parameters:

[in]	date_interval_fmt	The date interval format object
[in]	date_interval	Date interval to be formatted
[in,out]	append_to	Input/output parameter to receive the result. The result is appended to the existing contents.
[in]	field_position	The i18n_field_position_h object

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter
I18N_ERROR_BUFFER_OVERFLOW	Buffer overflow

int i18n_date_interval_fmt_get_time_zone	(	i18n_date_interval_fmt_h	date_interval_fmt,
		i18n_timezone_h *	timezone
	)

Gets the time zone used by the i18n_date_interval_fmt_h object.

Since :: 5.0

Remarks:: The obtained timezone should be released by the caller with the i18n_timezone_destroy() function.

Parameters:

[in]	date_interval_fmt	The date interval format object
[out]	timezone	The time zone used by date_interval_fmt object

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

int i18n_date_interval_fmt_set_time_zone	(	i18n_date_interval_fmt_h	date_interval_fmt,
		i18n_timezone_h	timezone
	)

Sets the time zone for the calendar used by the i18n_date_interval_fmt_h object.

Since :: 5.0

Parameters:

[in]	date_interval_fmt	The date interval format object
[in]	timezone	The new time zone

Returns:: 0 on success, otherwise a negative error value

Return values:

I18N_ERROR_NONE	Successful
I18N_ERROR_INVALID_PARAMETER	Invalid function parameter

Required Header

Overview

Functions

Typedefs

Typedef Documentation

Function Documentation