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
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_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:
-
Creates a clone of the given date_interval_fmt object.
- Since :
- 5.0
- 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:
-
Creates a date interval format object with a non-specified locale.
- Since :
- 5.0
- 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:
-
Creates a date interval format object for the given locale.
- Since :
- 5.0
- 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:
-
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:
-
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:
-
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:
-
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:
-
Gets the time zone used by the i18n_date_interval_fmt_h object.
- 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:
-
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:
-