Tizen Native API
8.0
|
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 todate_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