|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object java.text.Format com.ibm.icu.text.UFormat com.ibm.icu.text.DateIntervalFormat
public class DateIntervalFormat
DateIntervalFormat is a class for formatting and parsing date intervals in a language-independent manner. Only formatting is supported. Parsing is not supported.
Date interval means from one date to another date, for example, from "Jan 11, 2008" to "Jan 18, 2008". We introduced class DateInterval to represent it. DateInterval is a pair of UDate, which is the standard milliseconds since 24:00 GMT, Jan 1, 1970.
DateIntervalFormat formats a DateInterval 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. And it parses text into DateInterval, although initially, parsing is not supported.
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 DateInterval is pattern-driven. It is very similar to formatting in SimpleDateFormat. We introduce class DateIntervalInfo to save date interval patterns, similar to date time pattern in SimpleDateFormat.
Logically, the interval patterns are mappings from (skeleton, the_largest_different_calendar_field) to (date_interval_pattern).
A skeleton
The calendar fields we support for interval formatting are: year, month, date, day-of-week, am-pm, hour, hour-of-day, and minute. Those calendar fields can be defined in the following order: year > month > date > hour (in day) > minute 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 in DateFormat, There are pre-defined interval patterns for those pre-defined skeletons in locales' resource files. For example, for a skeleton 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.
If a skeleton is not found in a locale's DateIntervalInfo, which means the interval patterns for the skeleton is not defined in resource file, the interval pattern will falls back to the interval "fallback" pattern defined in resource file. If the interval "fallback" pattern is not defined, the default fall-back is "{date0} - {data1}".
For the combination of date and time, The rule to genearte interval patterns are:
If two dates are the same, the interval pattern is the single date pattern. For example, interval pattern from "Jan 10, 2007" to "Jan 10, 2007" is "Jan 10, 2007". Or if the presenting fields between 2 dates have the exact same values, the interval pattern is the single date pattern. For example, if user only requests year and month, the interval pattern from "Jan 10, 2007" to "Jan 20, 2007" is "Jan 2007".
DateIntervalFormat needs the following information for correct formatting: time zone, calendar type, pattern, date format symbols, and date interval patterns. It can be instantiated in several ways:
For the calendar field pattern letter, such as G, y, M, d, a, h, H, m, s etc. DateIntervalFormat uses the same syntax as that of DateTime format.
Code Sample: general usage
// the date interval object which the DateIntervalFormat formats on // and parses into DateInterval dtInterval = new DateInterval(1000*3600*24L, 1000*3600*24*2L); DateIntervalFormat dtIntervalFmt = DateIntervalFormat.getInstance( YEAR_MONTH_DAY, Locale("en", "GB", "")); StringBuffer str = new StringBuffer(""); FieldPosition pos = new FieldPosition(0); // formatting dtIntervalFmt.format(dtInterval, dateIntervalString, pos);
Code Sample: for powerful users who wants to use their own interval pattern
import com.ibm.icu.text.DateIntervalInfo; import com.ibm.icu.text.DateIntervalFormat; .................... // Get DateIntervalFormat instance using default locale DateIntervalFormat dtitvfmt = DateIntervalFormat.getInstance(YEAR_MONTH_DAY); // Create an empty DateIntervalInfo object, which does not have any interval patterns inside. dtitvinf = new DateIntervalInfo(); // a series of set interval patterns. // Only ERA, YEAR, MONTH, DATE, DAY_OF_MONTH, DAY_OF_WEEK, AM_PM, HOUR, HOUR_OF_DAY, and MINUTE are supported. dtitvinf.setIntervalPattern("yMMMd", Calendar.YEAR, "'y ~ y'"); dtitvinf.setIntervalPattern("yMMMd", Calendar.MONTH, "yyyy 'diff' MMM d - MMM d"); dtitvinf.setIntervalPattern("yMMMd", Calendar.DATE, "yyyy MMM d ~ d"); dtitvinf.setIntervalPattern("yMMMd", Calendar.HOUR_OF_DAY, "yyyy MMM d HH:mm ~ HH:mm"); // Set fallback interval pattern. Fallback pattern is used when interval pattern is not found. // If the fall-back pattern is not set, falls back to {date0} - {date1} if interval pattern is not found. dtitvinf.setFallbackIntervalPattern("{0} - {1}"); // Set above DateIntervalInfo object as the interval patterns of date interval formatter dtitvfmt.setDateIntervalInfo(dtitvinf); // Prepare to format pos = new FieldPosition(0); str = new StringBuffer(""); // The 2 calendars should be equivalent, otherwise, IllegalArgumentException will be thrown by format() Calendar fromCalendar = (Calendar) dtfmt.getCalendar().clone(); Calendar toCalendar = (Calendar) dtfmt.getCalendar().clone(); fromCalendar.setTimeInMillis(....); toCalendar.setTimeInMillis(...); //Formatting given 2 calendars dtitvfmt.format(fromCalendar, toCalendar, str, pos);
Nested Class Summary |
---|
Nested classes/interfaces inherited from class java.text.Format |
---|
Format.Field |
Method Summary | |
---|---|
Object |
clone()
Clone this Format object polymorphically. |
StringBuffer |
format(Calendar fromCalendar,
Calendar toCalendar,
StringBuffer appendTo,
FieldPosition pos)
Format 2 Calendars to produce a string. |
StringBuffer |
format(DateInterval dtInterval,
StringBuffer appendTo,
FieldPosition fieldPosition)
Format a DateInterval to produce a string. |
StringBuffer |
format(Object obj,
StringBuffer appendTo,
FieldPosition fieldPosition)
Format an object to produce a string. |
DateFormat |
getDateFormat()
Gets the date formatter |
DateIntervalInfo |
getDateIntervalInfo()
Gets the date time interval patterns. |
static DateIntervalFormat |
getInstance(String skeleton)
Construct a DateIntervalFormat from skeleton and the default locale. |
static DateIntervalFormat |
getInstance(String skeleton,
DateIntervalInfo dtitvinf)
Construct a DateIntervalFormat from skeleton DateIntervalInfo, and default locale. |
static DateIntervalFormat |
getInstance(String skeleton,
Locale locale)
Construct a DateIntervalFormat from skeleton and a given locale. |
static DateIntervalFormat |
getInstance(String skeleton,
Locale locale,
DateIntervalInfo dtitvinf)
Construct a DateIntervalFormat from skeleton a DateIntervalInfo, and the given locale. |
static DateIntervalFormat |
getInstance(String skeleton,
ULocale locale)
Construct a DateIntervalFormat from skeleton and a given locale. |
static DateIntervalFormat |
getInstance(String skeleton,
ULocale locale,
DateIntervalInfo dtitvinf)
Construct a DateIntervalFormat from skeleton a DateIntervalInfo, and the given locale. |
Object |
parseObject(String source,
ParsePosition parse_pos)
Deprecated. This API is ICU internal only. |
void |
setDateIntervalInfo(DateIntervalInfo newItvPattern)
Set the date time interval patterns. |
Methods inherited from class com.ibm.icu.text.UFormat |
---|
getLocale |
Methods inherited from class java.text.Format |
---|
format, formatToCharacterIterator, parseObject |
Methods inherited from class java.lang.Object |
---|
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Method Detail |
---|
public static final DateIntervalFormat getInstance(String skeleton)
skeleton
- the skeleton on which interval format based.
public static final DateIntervalFormat getInstance(String skeleton, Locale locale)
skeleton
- the skeleton on which interval format based.locale
- the given locale
public static final DateIntervalFormat getInstance(String skeleton, ULocale locale)
In this factory method, the date interval pattern information is load from resource files. Users are encouraged to created date interval formatter this way and to use the pre-defined skeleton macros.
There are pre-defined skeletons in DateFormat, such as MONTH_DAY, YEAR_MONTH_WEEKDAY_DAY etc. Those skeletons have pre-defined interval patterns in resource files. Users are encouraged to use them. For example: DateIntervalFormat.getInstance(DateFormat.MONTH_DAY, false, loc); The given Locale provides the interval patterns. For example, for en_GB, if skeleton is YEAR_ABBR_MONTH_WEEKDAY_DAY, which is "yMMMEEEd", the interval patterns defined in resource file to above skeleton are: "EEE, d MMM, yyyy - EEE, d MMM, yyyy" for year differs, "EEE, d MMM - EEE, d MMM, yyyy" for month differs, "EEE, d - EEE, d MMM, yyyy" for day differs,
skeleton
- the skeleton on which interval format based.locale
- the given locale
public static final DateIntervalFormat getInstance(String skeleton, DateIntervalInfo dtitvinf)
skeleton
- the skeleton on which interval format based.dtitvinf
- the DateIntervalInfo object to be adopted.
public static final DateIntervalFormat getInstance(String skeleton, Locale locale, DateIntervalInfo dtitvinf)
skeleton
- the skeleton on which interval format based.locale
- the given localedtitvinf
- the DateIntervalInfo object to be adopted.
public static final DateIntervalFormat getInstance(String skeleton, ULocale locale, DateIntervalInfo dtitvinf)
In this factory method, user provides its own date interval pattern information, instead of using those pre-defined data in resource file. This factory method is for powerful users who want to provide their own interval patterns.
There are pre-defined skeleton in DateFormat, such as MONTH_DAY, YEAR_MONTH_WEEKDAY_DAY etc. Those skeletons have pre-defined interval patterns in resource files. Users are encouraged to use them. For example: DateIntervalFormat.getInstance(DateFormat.MONTH_DAY, false, loc,itvinf); the DateIntervalInfo provides the interval patterns. User are encouraged to set default interval pattern in DateIntervalInfo as well, if they want to set other interval patterns ( instead of reading the interval patterns from resource files). When the corresponding interval pattern for a largest calendar different field is not found ( if user not set it ), interval format fallback to the default interval pattern. If user does not provide default interval pattern, it fallback to "{date0} - {date1}"
skeleton
- the skeleton on which interval format based.locale
- the given localedtitvinf
- the DateIntervalInfo object to be adopted.
public Object clone()
clone
in class Format
public final StringBuffer format(Object obj, StringBuffer appendTo, FieldPosition fieldPosition)
format
in class Format
obj
- The object to format.
Must be a DateInterval.appendTo
- Output parameter to receive result.
Result is appended to existing contents.fieldPosition
- On input: an alignment field, if desired.
On output: the offsets of the alignment field.
IllegalArgumentException
- if the formatted object is not
DateInterval objectpublic final StringBuffer format(DateInterval dtInterval, StringBuffer appendTo, FieldPosition fieldPosition)
dtInterval
- DateInterval to be formatted.appendTo
- Output parameter to receive result.
Result is appended to existing contents.fieldPosition
- On input: an alignment field, if desired.
On output: the offsets of the alignment field.
public final StringBuffer format(Calendar fromCalendar, Calendar toCalendar, StringBuffer appendTo, FieldPosition pos)
fromCalendar
- calendar set to the from date in date interval
to be formatted into date interval stringtoCalendar
- calendar set to the to date in date interval
to be formatted into date interval stringappendTo
- Output parameter to receive result.
Result is appended to existing contents.pos
- On input: an alignment field, if desired.
On output: the offsets of the alignment field.
IllegalArgumentException
- if the two calendars are not equivalent.public Object parseObject(String source, ParsePosition parse_pos)
This method should handle parsing of date time interval strings into Formattable objects with DateInterval type, which is a pair of UDate.
Before calling, set parse_pos.index to the offset you want to start parsing at in the source. After calling, parse_pos.index is the end of the text you parsed. If error occurs, index is unchanged.
When parsing, leading whitespace is discarded (with a successful parse), while trailing whitespace is left as is.
See Format.parseObject() for more.
parseObject
in class Format
source
- The string to be parsed into an object.parse_pos
- The position to start parsing at. Since no parsing
is supported, upon return this param is unchanged.
public DateIntervalInfo getDateIntervalInfo()
public void setDateIntervalInfo(DateIntervalInfo newItvPattern)
newItvPattern
- the given interval patterns to copy.public DateFormat getDateFormat()
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |