// © 2016 and later: Unicode, Inc. and others. // License & terms of use: http://www.unicode.org/copyright.html /******************************************************************************** * Copyright (C) 2008-2016, International Business Machines Corporation and * others. All Rights Reserved. ******************************************************************************* * * File DTITVFMT.H * ******************************************************************************* */ #ifndef __DTITVFMT_H__ #define __DTITVFMT_H__ #include "unicode/utypes.h" #if U_SHOW_CPLUSPLUS_API /** * \file * \brief C++ API: Format and parse date interval in a language-independent manner. */ #if !UCONFIG_NO_FORMATTING #include "unicode/ucal.h" #include "unicode/smpdtfmt.h" #include "unicode/dtintrv.h" #include "unicode/dtitvinf.h" #include "unicode/dtptngen.h" #include "unicode/formattedvalue.h" #include "unicode/udisplaycontext.h" U_NAMESPACE_BEGIN class FormattedDateIntervalData; class DateIntervalFormat; /** * An immutable class containing the result of a date interval formatting operation. * * Instances of this class are immutable and thread-safe. * * When calling nextPosition(): * The fields are returned from left to right. The special field category * UFIELD_CATEGORY_DATE_INTERVAL_SPAN is used to indicate which datetime * primitives came from which arguments: 0 means fromCalendar, and 1 means * toCalendar. The span category will always occur before the * corresponding fields in UFIELD_CATEGORY_DATE * in the nextPosition() iterator. * * Not intended for public subclassing. * * @stable ICU 64 */ class U_I18N_API FormattedDateInterval : public UMemory, public FormattedValue { … }; /** * DateIntervalFormat is a class for formatting and parsing date * intervals in a language-independent manner. * Only formatting is supported, parsing is not supported. * * <P> * 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. * * <P> * 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. * * <P> * 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. * * <P> * Logically, the interval patterns are mappings * from (skeleton, the_largest_different_calendar_field) * to (date_interval_pattern). * * <P> * A skeleton * <ol> * <li> * only keeps the field pattern letter and ignores all other parts * in a pattern, such as space, punctuations, and string literals. * </li> * <li> * hides the order of fields. * </li> * <li> * might hide a field's pattern letter length. * </li> * </ol> * * 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. * * <P> * 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. * * <P> * 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}". * * <P> * 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. * * <P> * 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}". * * <P> * For the combination of date and time, * The rule to generate interval patterns are: * <ol> * <li> * 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" * </li> * <li> * 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" * </li> * </ol> * * * <P> * 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". * * <P> * 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: * <ol> * <li> * 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. * </li> * <li> * 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. * </li> * </ol> * * <P> * 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. * * <P> * Code Sample: general usage * <pre> * \code * // 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; * \endcode * </pre> */ class U_I18N_API DateIntervalFormat : public Format { … }; inline bool DateIntervalFormat::operator!=(const Format& other) const { … } U_NAMESPACE_END #endif /* #if !UCONFIG_NO_FORMATTING */ #endif /* U_SHOW_CPLUSPLUS_API */ #endif // _DTITVFMT_H__ //eof
Codebase Browser
chromium