ICU 74.1 74.1

Data Structures | Public Member Functions | Static Public Member Functions | Protected Member Functions
icu::DateIntervalFormat Class Reference

DateIntervalFormat is a class for formatting and parsing date intervals in a language-independent manner. More...

`#include <dtitvfmt.h>`

Inheritance diagram for icu::DateIntervalFormat:

## Public Member Functions
virtual | ~DateIntervalFormat ()
| Destructor. More...
virtual DateIntervalFormat * | clone () const override
| Clone this Format object polymorphically. More...
virtual bool | operator== (const Format &other) const override
| Return true if the given Format objects are semantically equal. More...
bool | operator!= (const Format &other) const
| Return true if the given Format objects are not semantically equal. More...
virtual UnicodeString & | format (const Formattable &obj, UnicodeString &appendTo, FieldPosition &fieldPosition, UErrorCode &status) const override
| Format an object to produce a string. More...
UnicodeString & | format (const DateInterval *dtInterval, UnicodeString &appendTo, FieldPosition &fieldPosition, UErrorCode &status) const
| Format a DateInterval to produce a string. More...
FormattedDateInterval | formatToValue (const DateInterval &dtInterval, UErrorCode &status) const
| Format a DateInterval to produce a FormattedDateInterval. More...
UnicodeString & | format (Calendar &fromCalendar, Calendar &toCalendar, UnicodeString &appendTo, FieldPosition &fieldPosition, UErrorCode &status) const
| Format 2 Calendars to produce a string. More...
FormattedDateInterval | formatToValue (Calendar &fromCalendar, Calendar &toCalendar, UErrorCode &status) const
| Format 2 Calendars to produce a FormattedDateInterval. More...
virtual void | parseObject (const UnicodeString &source, Formattable &result, ParsePosition &parse_pos) const override
| Date interval parsing is not supported. More...
const DateIntervalInfo * | getDateIntervalInfo (void) const
| Gets the date time interval patterns. More...
void | setDateIntervalInfo (const DateIntervalInfo &newIntervalPatterns, UErrorCode &status)
| Set the date time interval patterns. More...
const DateFormat * | getDateFormat (void) const
| Gets the date formatter. More...
virtual const TimeZone & | getTimeZone (void) const
| Returns a reference to the TimeZone used by this DateIntervalFormat's calendar. More...
virtual void | adoptTimeZone (TimeZone *zoneToAdopt)
| Sets the time zone for the calendar used by this DateIntervalFormat object. More...
virtual void | setTimeZone (const TimeZone &zone)
| Sets the time zone for the calendar used by this DateIntervalFormat object. More...
virtual void | setContext (UDisplayContext value, UErrorCode &status)
| Set a particular UDisplayContext value in the formatter, such as UDISPCTX_CAPITALIZATION_FOR_STANDALONE. More...
virtual UDisplayContext | getContext (UDisplayContextType type, UErrorCode &status) const
| Get the formatter's UDisplayContext value for the specified UDisplayContextType, such as UDISPCTX_TYPE_CAPITALIZATION. More...
virtual UClassID | getDynamicClassID (void) const override
| Returns a unique class ID POLYMORPHICALLY. More...
UnicodeString & | format (const Formattable &obj, UnicodeString &appendTo, UErrorCode &status) const
| Formats an object to produce a string. More...
virtual UnicodeString & | format (const Formattable &obj, UnicodeString &appendTo, FieldPosition &pos, UErrorCode &status) const=0
| Format an object to produce a string. More...
virtual UnicodeString & | format (const Formattable &obj, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const
| Format an object to produce a string. More...
Public Member Functions inherited from icu::Format
virtual | ~Format ()
| Destructor. More...
bool | operator!= (const Format &other) const
| Return true if the given Format objects are not semantically equal. More...
UnicodeString & | format (const Formattable &obj, UnicodeString &appendTo, UErrorCode &status) const
| Formats an object to produce a string. More...
virtual UnicodeString & | format (const Formattable &obj, UnicodeString &appendTo, FieldPositionIterator *posIter, UErrorCode &status) const
| Format an object to produce a string. More...
void | parseObject (const UnicodeString &source, Formattable &result, UErrorCode &status) const
| Parses a string to produce an object. More...
Locale | getLocale (ULocDataLocaleType type, UErrorCode &status) const
| Get the locale for this format object. More...
const char * | getLocaleID (ULocDataLocaleType type, UErrorCode &status) const
| Get the locale for this format object. More...
Public Member Functions inherited from icu::UObject
virtual | ~UObject ()
| Destructor. More...

## Static Public Member Functions
static DateIntervalFormat * | createInstance (const UnicodeString &skeleton, UErrorCode &status)
| Construct a DateIntervalFormat from skeleton and the default locale. More...
static DateIntervalFormat * | createInstance (const UnicodeString &skeleton, const Locale &locale, UErrorCode &status)
| Construct a DateIntervalFormat from skeleton and a given locale. More...
static DateIntervalFormat * | createInstance (const UnicodeString &skeleton, const DateIntervalInfo &dtitvinf, UErrorCode &status)
| Construct a DateIntervalFormat from skeleton DateIntervalInfo, and default locale. More...
static DateIntervalFormat * | createInstance (const UnicodeString &skeleton, const Locale &locale, const DateIntervalInfo &dtitvinf, UErrorCode &status)
| Construct a DateIntervalFormat from skeleton a DateIntervalInfo, and the given locale. More...
static UClassID | getStaticClassID (void)
| Return the class ID for this class. More...

## Protected Member Functions
| DateIntervalFormat (const DateIntervalFormat &)
| Copy constructor. More...
DateIntervalFormat & | operator= (const DateIntervalFormat &)
| Assignment operator. More...
Protected Member Functions inherited from icu::Format
void | setLocaleIDs (const char *valid, const char *actual)
| Format ()
| Default constructor for subclass use only. More...
| Format (const Format &)
Format & | operator= (const Format &)

## Additional Inherited Members
Static Protected Member Functions inherited from icu::Format
static void | syntaxError (const UnicodeString &pattern, int32_t pos, UParseError &parseError)
| Simple function for initializing a UParseError from a UnicodeString. More...

## Detailed Description

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

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, minute, second, and millisecond. (though we do not currently have specific intervalFormat date for skeletons with seconds and millisecond). Those calendar fields can be defined in the following order: year > month > date > hour (in day) > minute > second > millisecond

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;
    icu::DateIntervalFormat::createInstancestatic DateIntervalFormat * createInstance(const UnicodeString &skeleton, UErrorCode &status)Construct a DateIntervalFormat from skeleton and the default locale.
    icu::DateIntervalFormat::DateIntervalFormatDateIntervalFormat(const DateIntervalFormat &)Copy constructor.
    UDAT_YEAR_MONTH_DAY#define UDAT_YEAR_MONTH_DAYConstant for date skeleton with year, month, and day.Definition: udat.h:269
    UErrorCodeUErrorCodeStandard ICU4C error code type, a substitute for exceptions.Definition: utypes.h:415
    U_ZERO_ERROR@ U_ZERO_ERRORNo error, no warning.Definition: utypes.h:449

Definition at line 300 of file dtitvfmt.h.

## Constructor & Destructor Documentation

## ◆ ~DateIntervalFormat()

virtual icu::DateIntervalFormat::~DateIntervalFormat | ( |  | ) |
| virtual

Destructor.

Stable:
  ICU 4.0

## ◆ DateIntervalFormat()

icu::DateIntervalFormat::DateIntervalFormat | ( | const DateIntervalFormat & |  | ) |
| protected

Copy constructor.

Stable:
  ICU 4.0

## Member Function Documentation

## ◆ adoptTimeZone()

virtual void icu::DateIntervalFormat::adoptTimeZone | ( | TimeZone * | zoneToAdopt | ) |
| virtual

Sets the time zone for the calendar used by this DateIntervalFormat object.

The caller no longer owns the TimeZone object and should not delete it after this call.

Parameters

  zoneToAdopt | the TimeZone to be adopted.

Stable:
  ICU 4.8

## ◆ clone()

virtual DateIntervalFormat* icu::DateIntervalFormat::clone | ( |  | ) | const
| override virtual

Clone this Format object polymorphically.

The caller owns the result and should delete it when done.

Returns
  A copy of the object.

Stable:
  ICU 4.0

Implements icu::Format.

## ◆ createInstance() [1/4]

static DateIntervalFormat* icu::DateIntervalFormat::createInstance | ( | const UnicodeString & | skeleton,
|  | const DateIntervalInfo & | dtitvinf,
|  | UErrorCode & | status
| ) |  |
| static

Construct a DateIntervalFormat from skeleton DateIntervalInfo, and default locale.

This is a convenient override of createInstance(const UnicodeString& skeleton, const Locale& locale, const DateIntervalInfo& dtitvinf, UErrorCode&) with the locale value as default locale.

Parameters

  skeleton | the skeleton on which interval format based.
  dtitvinf | the DateIntervalInfo object.
  status | output param set to success/failure code on exit

Returns
  a date time interval formatter which the caller owns.

Stable:
  ICU 4.0

## ◆ createInstance() [2/4]

static DateIntervalFormat* icu::DateIntervalFormat::createInstance | ( | const UnicodeString & | skeleton,
|  | const Locale & | locale,
|  | const DateIntervalInfo & | dtitvinf,
|  | UErrorCode & | status
| ) |  |
| static

Construct a DateIntervalFormat from skeleton a DateIntervalInfo, and the given locale.

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 skeletons (defined in udate.h) having predefined interval patterns in resource files. Users are encouraged to use those macros. For example: DateIntervalFormat::createInstance(UDAT_MONTH_DAY, status)

The DateIntervalInfo provides the interval patterns. and the DateIntervalInfo ownership remains to the caller.

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}"

Parameters

  skeleton | the skeleton on which interval format based.
  locale | the given locale
  dtitvinf | the DateIntervalInfo object.
  status | output param set to success/failure code on exit

Returns
  a date time interval formatter which the caller owns.

Stable:
  ICU 4.0

#### Sample code

#include <iostream>
#include "unicode/dtitvfmt.h"
#include "unicode/ustdio.h"
dtitvfmt.h
C++ API: Format and parse date interval in a language-independent manner.
ustdio.h
C API: Unicode stdio-like API.
UFILE *out = u_finit(stdout, nullptr, "UTF-8");
UErrorCode status =U_ZERO_ERROR;
UnicodeString data[] = {
UnicodeString("2007-9-10 10:10:10"),
UnicodeString("2007-10-10 10:10:10"),
UnicodeString("2007-10-10 22:10:10")
};
// to create 2 Date Intervals
Calendar *cal1 = Calendar::createInstance(status);
cal1->set(2007,9,10,10,10,10);
Calendar *cal2 = Calendar::createInstance(status);
cal2->set(2007,10,10,10,10,10);
Calendar *cal3 = Calendar::createInstance(status);
cal3->set(2007,10,10,22,10,10);
DateInterval* dtitvsample[] = {
new DateInterval(cal1->getTime(status),cal2->getTime(status)),
new DateInterval(cal2->getTime(status),cal3->getTime(status))
};
UnicodeString skeletons[] = {
UnicodeString("yMMMd"),
UnicodeString("Hm"),
UnicodeString("")
};
u_printf("%-10s%-22s%-22s%-45s%-35s\n", "Skeleton", "from","to", "Date Interval in en_US","Date Interval in Ja");
// Create an empty DateIntervalInfo object
DateIntervalInfo dtitvinf = DateIntervalInfo(status);
// Set Date Time internal pattern for MONTH, HOUR_OF_DAY
dtitvinf.setIntervalPattern("yMMMd", UCAL_MONTH, "y 'Diff' MMM d --- MMM d",status);
dtitvinf.setIntervalPattern("Hm", UCAL_HOUR_OF_DAY, "yyyy MMM d HH:mm ~ HH:mm",status);
// Set fallback interval pattern
dtitvinf.setFallbackIntervalPattern("{0} ~~~ {1}",status);
// Get the DateIntervalFormat with the custom pattern
UnicodeString formatEn,formatJa;
FieldPosition pos=0;
for (int i=0;i<2;i++){
for (int j=0;!skeletons[j].isEmpty();j++) {
u_fprintf(out,"%-10S%-22S%-22S", skeletons[i].getTerminatedBuffer(),data[j].getTerminatedBuffer(), data[j+1].getTerminatedBuffer());
DateIntervalFormat* dtitvfmtEn = DateIntervalFormat::createInstance(skeletons[i],Locale::getEnglish(),dtitvinf,status);
DateIntervalFormat* dtitvfmtJa = DateIntervalFormat::createInstance(skeletons[i],Locale::getJapanese(),dtitvinf,status);
formatEn.remove();
formatJa.remove();
dtitvfmtEn->format(dtitvsample[j],formatEn,pos,status);
dtitvfmtJa->format(dtitvsample[j],formatJa,pos,status);
u_fprintf(out,"%-45S%-35S\n", formatEn.getTerminatedBuffer(),formatJa.getTerminatedBuffer());
}
}
u_fclose(out);
icu::Calendar::createInstance
static Calendar * createInstance(UErrorCode &success)
Creates a Calendar using the default timezone and locale.
icu::Locale::getJapanese
static const Locale & getJapanese(void)
Useful constant for this language.
icu::Locale::getEnglish
static const Locale & getEnglish(void)
Useful constant for this language.
UCAL_HOUR_OF_DAY
@ UCAL_HOUR_OF_DAY
Field number indicating the hour of the day.
Definition: ucal.h:351
UCAL_MONTH
@ UCAL_MONTH
Field number indicating the month.
Definition: ucal.h:235
u_fclose
U_CAPI void u_fclose(UFILE *file)
Close a UFILE.
u_printf
U_CAPI int32_t u_printf(const char *patternSpecification,...)
Write formatted data to stdout.
u_finit
U_CAPI UFILE * u_finit(FILE *f, const char *locale, const char *codepage)
Open a UFILE on top of an existing FILE* stream.
u_fprintf
U_CAPI int32_t u_fprintf(UFILE *f, const char *patternSpecification,...)
Write formatted data to a UFILE.
UFILE
struct UFILE UFILE
Forward declaration of a Unicode-aware file.
Definition: ustdio.h:215

## ◆ createInstance() [3/4]

static DateIntervalFormat* icu::DateIntervalFormat::createInstance | ( | const UnicodeString & | skeleton,
|  | const Locale & | locale,
|  | UErrorCode & | status
| ) |  |
| static

Construct a DateIntervalFormat from skeleton and a given 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 (defined in udate.h) having predefined interval patterns in resource files. Users are encouraged to use those macros. For example: DateIntervalFormat::createInstance(UDAT_MONTH_DAY, status)

The given Locale provides the interval patterns. For example, for en_GB, if skeleton is UDAT_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,

Parameters

  skeleton | the skeleton on which the interval format is based.
  locale | the given locale
  status | output param set to success/failure code on exit

Returns
  a date time interval formatter which the caller owns.

Stable:
  ICU 4.0

#### Sample code

#include <iostream>
#include "unicode/dtitvfmt.h"
#include "unicode/ustdio.h"
UFILE *out = u_finit(stdout, nullptr, "UTF-8");
UErrorCode status =U_ZERO_ERROR;
// create 3 Date Intervals
UnicodeString data[] = {
UnicodeString("2007-10-10 10:10:10"),
UnicodeString("2008-10-10 10:10:10"),
UnicodeString("2008-11-10 10:10:10"),
UnicodeString("2008-11-10 15:10:10")
};
Calendar *cal = Calendar::createInstance(status);
cal->set(2007,10,10,10,10,10);
UDate date1 = cal->getTime(status);
cal->set(2008,10,10,10,10,10);
UDate date2 = cal->getTime(status);
cal->set(2008,11,10,10,10,10);
UDate date3 = cal->getTime(status);
cal->set(2008,11,10,15,10,10);
UDate date4 = cal->getTime(status);
DateInterval* dtitvsample[] = {
new DateInterval(date1,date2),
new DateInterval(date2,date3),
new DateInterval(date3,date4),
};
UnicodeString skeletons[] = {
UnicodeString("yMMMd"),
UnicodeString("MMMMd"),
UnicodeString("jm"),
UnicodeString("")
};
u_fprintf(out,"%-10s%-22s%-22s%-35s%-35s\n", "Skeleton","from","to","Date Interval in en_US","Date Interval in Ja");
int i=0;
UnicodeString formatEn,formatJa;
FieldPosition pos=0;
for (int j=0; !skeletons[j].isEmpty() ;j++) {
u_fprintf(out,"%-10S%-22S%-22S",skeletons[j].getTerminatedBuffer(),data[i].getTerminatedBuffer(),data[i+1].getTerminatedBuffer());
//create a DateIntervalFormat instance for given skeleton, locale
DateIntervalFormat* dtitvfmtEn = DateIntervalFormat::createInstance(skeletons[j], Locale::getEnglish(),status);
DateIntervalFormat* dtitvfmtJa = DateIntervalFormat::createInstance(skeletons[j], Locale::getJapanese(),status);
formatEn.remove();
formatJa.remove();
//get the DateIntervalFormat
dtitvfmtEn->format(dtitvsample[i],formatEn,pos,status);
dtitvfmtJa->format(dtitvsample[i],formatJa,pos,status);
u_fprintf(out,"%-35S%-35S\n", formatEn.getTerminatedBuffer(),formatJa.getTerminatedBuffer());
delete dtitvfmtEn;
delete dtitvfmtJa;
i++;
}
u_fclose(out);
UDate
double UDate
Date and Time data type.
Definition: utypes.h:203

## ◆ createInstance() [4/4]

static DateIntervalFormat* icu::DateIntervalFormat::createInstance | ( | const UnicodeString & | skeleton,
|  | UErrorCode & | status
| ) |  |
| static

Construct a DateIntervalFormat from skeleton and the default locale.

This is a convenient override of createInstance(const UnicodeString& skeleton, const Locale& locale, UErrorCode&) with the value of locale as default locale.

Parameters

  skeleton | the skeleton on which interval format based.
  status | output param set to success/failure code on exit

Returns
  a date time interval formatter which the caller owns.

Stable:
  ICU 4.0

## ◆ format() [1/6]

UnicodeString& icu::DateIntervalFormat::format | ( | Calendar & | fromCalendar,
|  | Calendar & | toCalendar,
|  | UnicodeString & | appendTo,
|  | FieldPosition & | fieldPosition,
|  | UErrorCode & | status
| ) |  | const

Format 2 Calendars to produce a string.

Note: "fromCalendar" and "toCalendar" are not const, since calendar is not const in SimpleDateFormat::format(Calendar&),

Parameters

  fromCalendar | calendar set to the from date in date interval to be formatted into date interval string
  toCalendar | calendar set to the to date in date interval to be formatted into date interval string
  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. There may be multiple instances of a given field type in an interval format; in this case the fieldPosition offsets refer to the first instance.
  status | Output param filled with success/failure status. Caller needs to make sure it is SUCCESS at the function entrance

Returns
  Reference to 'appendTo' parameter.

Stable:
  ICU 4.0

## ◆ format() [2/6]

UnicodeString& icu::DateIntervalFormat::format | ( | const DateInterval * | dtInterval,
|  | UnicodeString & | appendTo,
|  | FieldPosition & | fieldPosition,
|  | UErrorCode & | status
| ) |  | const

Format a DateInterval to produce a string.

Parameters

  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. There may be multiple instances of a given field type in an interval format; in this case the fieldPosition offsets refer to the first instance.
  status | Output param filled with success/failure status.

Returns
  Reference to 'appendTo' parameter.

Stable:
  ICU 4.0

## ◆ format() [3/6]

virtual UnicodeString& icu::DateIntervalFormat::format | ( | const Formattable & | obj,
|  | UnicodeString & | appendTo,
|  | FieldPosition & | fieldPosition,
|  | UErrorCode & | status
| ) |  | const
| override virtual

Format an object to produce a string.

This method handles Formattable objects with a DateInterval type. If a the Formattable object type is not a DateInterval, then it returns a failing UErrorCode.

Parameters

  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. There may be multiple instances of a given field type in an interval format; in this case the fieldPosition offsets refer to the first instance.
  status | Output param filled with success/failure status.

Returns
  Reference to 'appendTo' parameter.

Stable:
  ICU 4.0

Implements icu::Format.

## ◆ format() [4/6]

virtual UnicodeString& icu::Format::format

Format an object to produce a string.

This is a pure virtual method which subclasses must implement. This method allows polymorphic formatting of Formattable objects. If a subclass of Format receives a Formattable object type it doesn't handle (e.g., if a numeric Formattable is passed to a DateFormat object) then it returns a failing UErrorCode.

Parameters

  obj | The object to format.
  appendTo | 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.
  status | Output param filled with success/failure status.

Returns
  Reference to 'appendTo' parameter.

Stable:
  ICU 2.0

## ◆ format() [5/6]

virtual UnicodeString& icu::Format::format

Format an object to produce a string.

Subclasses should override this method. This method allows polymorphic formatting of Formattable objects. If a subclass of Format receives a Formattable object type it doesn't handle (e.g., if a numeric Formattable is passed to a DateFormat object) then it returns a failing UErrorCode.

Parameters

  obj | The object to format.
  appendTo | Output parameter to receive result. Result is appended to existing contents.
  posIter | On return, can be used to iterate over positions of fields generated by this format call.
  status | Output param filled with success/failure status.

Returns
  Reference to 'appendTo' parameter.

Stable:
  ICU 4.4

## ◆ format() [6/6]

UnicodeString& icu::Format::format

Formats an object to produce a string.

Parameters

  obj | The object to format.
  appendTo | Output parameter to receive result. Result is appended to existing contents.
  status | Output parameter filled in with success or failure status.

Returns
  Reference to 'appendTo' parameter.

Stable:
  ICU 2.0

## ◆ formatToValue() [1/2]

FormattedDateInterval icu::DateIntervalFormat::formatToValue | ( | Calendar & | fromCalendar,
|  | Calendar & | toCalendar,
|  | UErrorCode & | status
| ) |  | const

Format 2 Calendars to produce a FormattedDateInterval.

The FormattedDateInterval exposes field information about the formatted string.

Note: "fromCalendar" and "toCalendar" are not const, since calendar is not const in SimpleDateFormat::format(Calendar&),

Parameters

  fromCalendar | calendar set to the from date in date interval to be formatted into date interval string
  toCalendar | calendar set to the to date in date interval to be formatted into date interval string
  status | Set if an error occurs.

Returns
  A FormattedDateInterval containing the format result.

Stable:
  ICU 64

## ◆ formatToValue() [2/2]

FormattedDateInterval icu::DateIntervalFormat::formatToValue | ( | const DateInterval & | dtInterval,
|  | UErrorCode & | status
| ) |  | const

Format a DateInterval to produce a FormattedDateInterval.

The FormattedDateInterval exposes field information about the formatted string.

Parameters

  dtInterval | DateInterval to be formatted.
  status | Set if an error occurs.

Returns
  A FormattedDateInterval containing the format result.

Stable:
  ICU 64

## ◆ getContext()

virtual UDisplayContext icu::DateIntervalFormat::getContext | ( | UDisplayContextType | type,
|  | UErrorCode & | status
| ) |  | const
| virtual

Get the formatter's UDisplayContext value for the specified UDisplayContextType, such as UDISPCTX_TYPE_CAPITALIZATION.

Parameters

  type | The UDisplayContextType whose value to return
  status | Input/output status. If at entry this indicates a failure status, the function will do nothing; otherwise this will be updated with any new status from the function.

Returns
  The UDisplayContextValue for the specified type.

Stable:
  ICU 68

## ◆ getDateFormat()

const DateFormat* icu::DateIntervalFormat::getDateFormat | ( | void |  | ) | const

Gets the date formatter.

The DateIntervalFormat instance continues to own the returned DateFormatter object, and will use and possibly modify it during format operations. In a multi-threaded environment, the returned DateFormat can only be used if it is certain that no other threads are concurrently using this DateIntervalFormatter, even for nominally const functions.

Returns
  the date formatter associated with this date interval formatter.

Stable:
  ICU 4.0

## ◆ getDateIntervalInfo()

const DateIntervalInfo* icu::DateIntervalFormat::getDateIntervalInfo | ( | void |  | ) | const

Gets the date time interval patterns.

Returns
  the date time interval patterns associated with this date interval formatter.

Stable:
  ICU 4.0

## ◆ getDynamicClassID()

virtual UClassID icu::DateIntervalFormat::getDynamicClassID | ( | void |  | ) | const
| override virtual

Returns a unique class ID POLYMORPHICALLY.

Pure virtual override. This method is to implement a simple version of RTTI, since not all C++ compilers support genuine RTTI. Polymorphic operator==() and clone() methods call this method.

Returns
  The class ID for this object. All objects of a given class have the same class ID. Objects of other classes have different class IDs.

Stable:
  ICU 4.0

Reimplemented from icu::UObject.

## ◆ getStaticClassID()

static UClassID icu::DateIntervalFormat::getStaticClassID | ( | void |  | ) |
| static

Return the class ID for this class.

This is useful only for comparing to a return value from getDynamicClassID(). For example:

    .   Base* polymorphic_pointer = createPolymorphicObject();
    .   if (polymorphic_pointer->getDynamicClassID() ==
    .       erived::getStaticClassID()) ...

Returns
  The class ID for all objects of this class.

Stable:
  ICU 4.0

## ◆ getTimeZone()

virtual const TimeZone& icu::DateIntervalFormat::getTimeZone | ( | void |  | ) | const
| virtual

Returns a reference to the TimeZone used by this DateIntervalFormat's calendar.

Returns
  the time zone associated with the calendar of DateIntervalFormat.

Stable:
  ICU 4.8

## ◆ operator!=()

bool icu::DateIntervalFormat::operator!= | ( | const Format & | other | ) | const
| inline

Return true if the given Format objects are not semantically equal.

Objects of different subclasses are considered unequal.

Parameters

  other | the object to be compared with.

Returns
  true if the given Format objects are not semantically equal.

Stable:
  ICU 4.0

Definition at line 1201 of file dtitvfmt.h.

References icu::operator==().

## ◆ operator=()

DateIntervalFormat& icu::DateIntervalFormat::operator= | ( | const DateIntervalFormat & |  | ) |
| protected

Assignment operator.

Stable:
  ICU 4.0

## ◆ operator==()

virtual bool icu::DateIntervalFormat::operator== | ( | const Format & | other | ) | const
| override virtual

Return true if the given Format objects are semantically equal.

Objects of different subclasses are considered unequal.

Parameters

  other | the object to be compared with.

Returns
  true if the given Format objects are semantically equal.

Stable:
  ICU 4.0

Implements icu::Format.

## ◆ parseObject()

virtual void icu::DateIntervalFormat::parseObject | ( | const UnicodeString & | source,
|  | Formattable & | result,
|  | ParsePosition & | parse_pos
| ) |  | const
| override virtual

Date interval parsing is not supported.

Please do not use.

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.

Parameters

  source | The string to be parsed into an object.
  result | Formattable to be set to the parse result. If parse fails, return contents are undefined.
  parse_pos | The position to start parsing at. Since no parsing is supported, upon return this param is unchanged.

Returns
  A newly created Formattable* object, or nullptr on failure. The caller owns this and should delete it when done.

Internal:
  Do not use. This API is for internal use only. ICU 4.0

Implements icu::Format.

## ◆ setContext()

virtual void icu::DateIntervalFormat::setContext | ( | UDisplayContext | value,
|  | UErrorCode & | status
| ) |  |
| virtual

Set a particular UDisplayContext value in the formatter, such as UDISPCTX_CAPITALIZATION_FOR_STANDALONE.

This causes the formatted result to be capitalized appropriately for the context in which it is intended to be used, considering both the locale and the type of field at the beginning of the formatted result.

Parameters

  value | The UDisplayContext value to set.
  status | Input/output status. If at entry this indicates a failure status, the function will do nothing; otherwise this will be updated with any new status from the function.

Stable:
  ICU 68

## ◆ setDateIntervalInfo()

void icu::DateIntervalFormat::setDateIntervalInfo | ( | const DateIntervalInfo & | newIntervalPatterns,
|  | UErrorCode & | status
| ) |  |

Set the date time interval patterns.

Parameters

  newIntervalPatterns | the given interval patterns to copy.
  status | output param set to success/failure code on exit

Stable:
  ICU 4.0

## ◆ setTimeZone()

virtual void icu::DateIntervalFormat::setTimeZone | ( | const TimeZone & | zone | ) |
| virtual

Sets the time zone for the calendar used by this DateIntervalFormat object.

Parameters

  zone | the new time zone.

Stable:
  ICU 4.8

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

- i18n/unicode/dtitvfmt.h