Logo Search packages:      
Sourcecode: icu version File versions

DateIntervalFormat Class Reference

#include <dtitvfmt.h>

Inheritance diagram for DateIntervalFormat:

Format UObject UMemory

List of all members.


Detailed Description

DateIntervalFormat is a class for formatting and parsing date intervals in a language-independent manner. Date interval formatting is supported in Gregorian calendar only. And 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

  1. only keeps the field pattern letter and ignores all other parts in a pattern, such as space, punctuations, and string literals.
  2. hides the order of fields.
  3. 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.

For the digit calendar fields, such as M or MM, d or dd, yy or yyyy, the field pattern length is ignored and the best match, which is defined in date time patterns, will be returned without honor the field pattern letter length in 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. There are pre-defined interval patterns for those pre-defined skeletons in locales' resource files. For example, for a skeleton UDAT_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 generate interval patterns are:

  1. when the year, month, or day differs, falls back to fall-back interval pattern, which mostly is the concatenate the two original expressions with a separator between, For example, interval pattern from "Jan 10, 2007 10:10 am" to "Jan 11, 2007 10:10am" is "Jan 10, 2007 10:10 am - Jan 11, 2007 10:10am"
  2. otherwise, present the date followed by the range expression for the time. For example, interval pattern from "Jan 10, 2007 10:10 am" to "Jan 10, 2007 11:10am" is "Jan 10, 2007 10:10 am - 11:10am"

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 2 ways:

  1. create an instance using default or given locale plus given skeleton. Users are encouraged to created date interval formatter this way and to use the pre-defined skeleton macros, such as UDAT_YEAR_NUM_MONTH, which consists the calendar fields and the format style.
  2. create an instance using default or given locale plus given skeleton plus a given DateIntervalInfo. This factory method is for powerful users who want to provide their own interval patterns. Locale provides the timezone, calendar, and format symbols information. Local plus skeleton provides full pattern information. DateIntervalInfo provides the date interval patterns.

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*24, 1000*3600*24*2);
   UErrorCode status = U_ZERO_ERROR;
   DateIntervalFormat* dtIntervalFmt = DateIntervalFormat::createInstance(
                           UDAT_YEAR_MONTH_DAY, 
                           Locale("en", "GB", ""), status);
   UnicodeUnicodeString dateIntervalString;
   FieldPosition pos = 0;
   // formatting
   dtIntervalFmt->format(dtInterval, dateIntervalUnicodeString, pos, status);
   delete dtIntervalFmt;

Definition at line 218 of file dtitvfmt.h.


Public Member Functions

virtual Formatclone (void) const
UnicodeStringformat (const Formattable &obj, UnicodeString &appendTo, UErrorCode &status) const
UnicodeStringformat (Calendar &fromCalendar, Calendar &toCalendar, UnicodeString &appendTo, FieldPosition &fieldPosition, UErrorCode &status) const
UnicodeStringformat (const DateInterval *dtInterval, UnicodeString &appendTo, FieldPosition &fieldPosition, UErrorCode &status) const
virtual UnicodeStringformat (const Formattable &obj, UnicodeString &appendTo, FieldPosition &fieldPosition, UErrorCode &status) const
const DateFormatgetDateFormat (void) const
const DateIntervalInfogetDateIntervalInfo (void) const
virtual UClassID getDynamicClassID (void) const
Locale getLocale (ULocDataLocaleType type, UErrorCode &status) const
const char * getLocaleID (ULocDataLocaleType type, UErrorCode &status) const
UBool operator!= (const Format &other) const
virtual UBool operator== (const Format &other) const
void parseObject (const UnicodeString &source, Formattable &result, UErrorCode &status) const
virtual void parseObject (const UnicodeString &source, Formattable &result, ParsePosition &parse_pos) const
void setDateIntervalInfo (const DateIntervalInfo &newIntervalPatterns, UErrorCode &status)
virtual ~DateIntervalFormat ()

Static Public Member Functions

static DateIntervalFormat
*U_EXPORT2 
createInstance (const UnicodeString &skeleton, const Locale &locale, const DateIntervalInfo &dtitvinf, UErrorCode &status)
static DateIntervalFormat
*U_EXPORT2 
createInstance (const UnicodeString &skeleton, const DateIntervalInfo &dtitvinf, UErrorCode &status)
static DateIntervalFormat
*U_EXPORT2 
createInstance (const UnicodeString &skeleton, const Locale &locale, UErrorCode &status)
static DateIntervalFormat
*U_EXPORT2 
createInstance (const UnicodeString &skeleton, UErrorCode &status)
static UClassID U_EXPORT2 getStaticClassID (void)
static void U_EXPORT2 operator delete (void *, void *) U_NO_THROW
static void U_EXPORT2 operator delete (void *p) U_NO_THROW
static void U_EXPORT2 operator delete[] (void *p) U_NO_THROW
static void *U_EXPORT2 operator new (size_t, void *ptr) U_NO_THROW
static void *U_EXPORT2 operator new (size_t size) U_NO_THROW
static void *U_EXPORT2 operator new[] (size_t size) U_NO_THROW

Protected Member Functions

 DateIntervalFormat (const DateIntervalFormat &)
DateIntervalFormatoperator= (const DateIntervalFormat &)
void setLocaleIDs (const char *valid, const char *actual)

Static Protected Member Functions

static void syntaxError (const UnicodeString &pattern, int32_t pos, UParseError &parseError)

Private Member Functions

void concatSingleDate2TimeInterval (const UChar *format, int32_t formatLen, const UnicodeString &datePattern, UCalendarDateFields field, UErrorCode &status)
 DateIntervalFormat (const Locale &locale, DateIntervalInfo *dtItvInfo, const UnicodeString *skeleton, UErrorCode &status)
 DateIntervalFormat ()
UnicodeStringfallbackFormat (Calendar &fromCalendar, Calendar &toCalendar, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const
void initializePattern (UErrorCode &status)
void setFallbackPattern (UCalendarDateFields field, const UnicodeString &skeleton, UErrorCode &status)
void setIntervalPattern (UCalendarDateFields field, const UnicodeString &intervalPattern, UBool laterDateFirst)
void setIntervalPattern (UCalendarDateFields field, const UnicodeString &intervalPattern)
UBool setIntervalPattern (UCalendarDateFields field, const UnicodeString *skeleton, const UnicodeString *bestSkeleton, int8_t differenceInfo, UnicodeString *extendedSkeleton=NULL, UnicodeString *extendedBestSkeleton=NULL)
void setPatternInfo (UCalendarDateFields field, const UnicodeString *firstPart, const UnicodeString *secondpart, UBool laterDateFirst)
UBool setSeparateDateTimePtn (const UnicodeString &dateSkeleton, const UnicodeString &timeSkeleton)

Static Private Member Functions

static void U_EXPORT2 adjustFieldWidth (const UnicodeString &inputSkeleton, const UnicodeString &bestMatchSkeleton, const UnicodeString &bestMatchIntervalPattern, int8_t differenceInfo, UnicodeString &adjustedIntervalPattern)
static DateIntervalFormat
*U_EXPORT2 
create (const Locale &locale, DateIntervalInfo *dtitvinf, const UnicodeString *skeleton, UErrorCode &status)
static SimpleDateFormat *U_EXPORT2 createSDFPatternInstance (const UnicodeString &skeleton, const Locale &locale, DateTimePatternGenerator *dtpng, UErrorCode &status)
static UBool U_EXPORT2 fieldExistsInSkeleton (UCalendarDateFields field, const UnicodeString &skeleton)
static void U_EXPORT2 getDateTimeSkeleton (const UnicodeString &skeleton, UnicodeString &date, UnicodeString &normalizedDate, UnicodeString &time, UnicodeString &normalizedTime)
static int32_t U_EXPORT2 splitPatternInto2Part (const UnicodeString &intervalPattern)

Private Attributes

SimpleDateFormatfDateFormat
DateTimePatternGeneratorfDtpng
CalendarfFromCalendar
DateIntervalInfofInfo
PatternInfo fIntervalPatterns [DateIntervalInfo::kIPI_MAX_INDEX]
UnicodeString fSkeleton
CalendarfToCalendar

Static Private Attributes

static const UChar fgCalendarFieldToPatternLetter []

Classes

struct  PatternInfo

The documentation for this class was generated from the following files:

Generated by  Doxygen 1.6.0   Back to index