Tizen Native API  6.5
DateIntervalFormat

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

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_fmtThe date interval format object
[out]timezoneThe time zone used by date_interval_fmt object
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter

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_fmtThe date interval format object to be cloned
[out]cloneThe created date interval format object
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut 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]skeletonThe skeleton on which interval format based
[out]date_interval_fmtThe created date interval format object
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut 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]skeletonThe skeleton on which interval format based
[in]localeThe locale value
[out]date_interval_fmtThe created date interval format object
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_OUT_OF_MEMORYOut of memory

Destroys the date interval format object.

Since :
5.0
Parameters:
[in]date_interval_fmtThe date interval format object to destroy
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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_1The first date interval format object
[in]date_interval_fmt_2The second date interval format object
[out]equalstrue 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_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid 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_fmtThe date interval format object
[in]from_calCalendar set to the 'from date' in date interval to be formatted into date interval string
[in]to_calCalendar set to the 'to date' in date interval to be formatted into date interval string
[in,out]append_toInput/output parameter to receive the result. The result is appended to the existing contents.
[in]field_positionThe i18n_field_position_h object
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_BUFFER_OVERFLOWBuffer 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_fmtThe date interval format object
[in]date_intervalDate interval to be formatted
[in,out]append_toInput/output parameter to receive the result. The result is appended to the existing contents.
[in]field_positionThe i18n_field_position_h object
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter
I18N_ERROR_BUFFER_OVERFLOWBuffer overflow

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_fmtThe date interval format object
[out]timezoneThe time zone used by date_interval_fmt object
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter

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

Since :
5.0
Parameters:
[in]date_interval_fmtThe date interval format object
[in]timezoneThe new time zone
Returns:
0 on success, otherwise a negative error value
Return values:
I18N_ERROR_NONESuccessful
I18N_ERROR_INVALID_PARAMETERInvalid function parameter