1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/i18n/unicode/dtitvfmt.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,985 @@
1.4 +/********************************************************************************
1.5 +* Copyright (C) 2008-2013, International Business Machines Corporation and
1.6 +* others. All Rights Reserved.
1.7 +*******************************************************************************
1.8 +*
1.9 +* File DTITVFMT.H
1.10 +*
1.11 +*******************************************************************************
1.12 +*/
1.13 +
1.14 +#ifndef __DTITVFMT_H__
1.15 +#define __DTITVFMT_H__
1.16 +
1.17 +
1.18 +#include "unicode/utypes.h"
1.19 +
1.20 +/**
1.21 + * \file
1.22 + * \brief C++ API: Format and parse date interval in a language-independent manner.
1.23 + */
1.24 +
1.25 +#if !UCONFIG_NO_FORMATTING
1.26 +
1.27 +#include "unicode/ucal.h"
1.28 +#include "unicode/smpdtfmt.h"
1.29 +#include "unicode/dtintrv.h"
1.30 +#include "unicode/dtitvinf.h"
1.31 +#include "unicode/dtptngen.h"
1.32 +
1.33 +U_NAMESPACE_BEGIN
1.34 +
1.35 +
1.36 +
1.37 +/**
1.38 + * DateIntervalFormat is a class for formatting and parsing date
1.39 + * intervals in a language-independent manner.
1.40 + * Only formatting is supported, parsing is not supported.
1.41 + *
1.42 + * <P>
1.43 + * Date interval means from one date to another date,
1.44 + * for example, from "Jan 11, 2008" to "Jan 18, 2008".
1.45 + * We introduced class DateInterval to represent it.
1.46 + * DateInterval is a pair of UDate, which is
1.47 + * the standard milliseconds since 24:00 GMT, Jan 1, 1970.
1.48 + *
1.49 + * <P>
1.50 + * DateIntervalFormat formats a DateInterval into
1.51 + * text as compactly as possible.
1.52 + * For example, the date interval format from "Jan 11, 2008" to "Jan 18,. 2008"
1.53 + * is "Jan 11-18, 2008" for English.
1.54 + * And it parses text into DateInterval,
1.55 + * although initially, parsing is not supported.
1.56 + *
1.57 + * <P>
1.58 + * There is no structural information in date time patterns.
1.59 + * For any punctuations and string literals inside a date time pattern,
1.60 + * we do not know whether it is just a separator, or a prefix, or a suffix.
1.61 + * Without such information, so, it is difficult to generate a sub-pattern
1.62 + * (or super-pattern) by algorithm.
1.63 + * So, formatting a DateInterval is pattern-driven. It is very
1.64 + * similar to formatting in SimpleDateFormat.
1.65 + * We introduce class DateIntervalInfo to save date interval
1.66 + * patterns, similar to date time pattern in SimpleDateFormat.
1.67 + *
1.68 + * <P>
1.69 + * Logically, the interval patterns are mappings
1.70 + * from (skeleton, the_largest_different_calendar_field)
1.71 + * to (date_interval_pattern).
1.72 + *
1.73 + * <P>
1.74 + * A skeleton
1.75 + * <ol>
1.76 + * <li>
1.77 + * only keeps the field pattern letter and ignores all other parts
1.78 + * in a pattern, such as space, punctuations, and string literals.
1.79 + * </li>
1.80 + * <li>
1.81 + * hides the order of fields.
1.82 + * </li>
1.83 + * <li>
1.84 + * might hide a field's pattern letter length.
1.85 + * </li>
1.86 + * </ol>
1.87 + *
1.88 + * For those non-digit calendar fields, the pattern letter length is
1.89 + * important, such as MMM, MMMM, and MMMMM; EEE and EEEE,
1.90 + * and the field's pattern letter length is honored.
1.91 + *
1.92 + * For the digit calendar fields, such as M or MM, d or dd, yy or yyyy,
1.93 + * the field pattern length is ignored and the best match, which is defined
1.94 + * in date time patterns, will be returned without honor the field pattern
1.95 + * letter length in skeleton.
1.96 + *
1.97 + * <P>
1.98 + * The calendar fields we support for interval formatting are:
1.99 + * year, month, date, day-of-week, am-pm, hour, hour-of-day, and minute.
1.100 + * Those calendar fields can be defined in the following order:
1.101 + * year > month > date > hour (in day) > minute
1.102 + *
1.103 + * The largest different calendar fields between 2 calendars is the
1.104 + * first different calendar field in above order.
1.105 + *
1.106 + * For example: the largest different calendar fields between "Jan 10, 2007"
1.107 + * and "Feb 20, 2008" is year.
1.108 + *
1.109 + * <P>
1.110 + * For other calendar fields, the compact interval formatting is not
1.111 + * supported. And the interval format will be fall back to fall-back
1.112 + * patterns, which is mostly "{date0} - {date1}".
1.113 + *
1.114 + * <P>
1.115 + * There is a set of pre-defined static skeleton strings.
1.116 + * There are pre-defined interval patterns for those pre-defined skeletons
1.117 + * in locales' resource files.
1.118 + * For example, for a skeleton UDAT_YEAR_ABBR_MONTH_DAY, which is "yMMMd",
1.119 + * in en_US, if the largest different calendar field between date1 and date2
1.120 + * is "year", the date interval pattern is "MMM d, yyyy - MMM d, yyyy",
1.121 + * such as "Jan 10, 2007 - Jan 10, 2008".
1.122 + * If the largest different calendar field between date1 and date2 is "month",
1.123 + * the date interval pattern is "MMM d - MMM d, yyyy",
1.124 + * such as "Jan 10 - Feb 10, 2007".
1.125 + * If the largest different calendar field between date1 and date2 is "day",
1.126 + * the date interval pattern is "MMM d-d, yyyy", such as "Jan 10-20, 2007".
1.127 + *
1.128 + * For date skeleton, the interval patterns when year, or month, or date is
1.129 + * different are defined in resource files.
1.130 + * For time skeleton, the interval patterns when am/pm, or hour, or minute is
1.131 + * different are defined in resource files.
1.132 + *
1.133 + * <P>
1.134 + * If a skeleton is not found in a locale's DateIntervalInfo, which means
1.135 + * the interval patterns for the skeleton is not defined in resource file,
1.136 + * the interval pattern will falls back to the interval "fallback" pattern
1.137 + * defined in resource file.
1.138 + * If the interval "fallback" pattern is not defined, the default fall-back
1.139 + * is "{date0} - {data1}".
1.140 + *
1.141 + * <P>
1.142 + * For the combination of date and time,
1.143 + * The rule to generate interval patterns are:
1.144 + * <ol>
1.145 + * <li>
1.146 + * when the year, month, or day differs, falls back to fall-back
1.147 + * interval pattern, which mostly is the concatenate the two original
1.148 + * expressions with a separator between,
1.149 + * For example, interval pattern from "Jan 10, 2007 10:10 am"
1.150 + * to "Jan 11, 2007 10:10am" is
1.151 + * "Jan 10, 2007 10:10 am - Jan 11, 2007 10:10am"
1.152 + * </li>
1.153 + * <li>
1.154 + * otherwise, present the date followed by the range expression
1.155 + * for the time.
1.156 + * For example, interval pattern from "Jan 10, 2007 10:10 am"
1.157 + * to "Jan 10, 2007 11:10am" is "Jan 10, 2007 10:10 am - 11:10am"
1.158 + * </li>
1.159 + * </ol>
1.160 + *
1.161 + *
1.162 + * <P>
1.163 + * If two dates are the same, the interval pattern is the single date pattern.
1.164 + * For example, interval pattern from "Jan 10, 2007" to "Jan 10, 2007" is
1.165 + * "Jan 10, 2007".
1.166 + *
1.167 + * Or if the presenting fields between 2 dates have the exact same values,
1.168 + * the interval pattern is the single date pattern.
1.169 + * For example, if user only requests year and month,
1.170 + * the interval pattern from "Jan 10, 2007" to "Jan 20, 2007" is "Jan 2007".
1.171 + *
1.172 + * <P>
1.173 + * DateIntervalFormat needs the following information for correct
1.174 + * formatting: time zone, calendar type, pattern, date format symbols,
1.175 + * and date interval patterns.
1.176 + * It can be instantiated in 2 ways:
1.177 + * <ol>
1.178 + * <li>
1.179 + * create an instance using default or given locale plus given skeleton.
1.180 + * Users are encouraged to created date interval formatter this way and
1.181 + * to use the pre-defined skeleton macros, such as
1.182 + * UDAT_YEAR_NUM_MONTH, which consists the calendar fields and
1.183 + * the format style.
1.184 + * </li>
1.185 + * <li>
1.186 + * create an instance using default or given locale plus given skeleton
1.187 + * plus a given DateIntervalInfo.
1.188 + * This factory method is for powerful users who want to provide their own
1.189 + * interval patterns.
1.190 + * Locale provides the timezone, calendar, and format symbols information.
1.191 + * Local plus skeleton provides full pattern information.
1.192 + * DateIntervalInfo provides the date interval patterns.
1.193 + * </li>
1.194 + * </ol>
1.195 + *
1.196 + * <P>
1.197 + * For the calendar field pattern letter, such as G, y, M, d, a, h, H, m, s etc.
1.198 + * DateIntervalFormat uses the same syntax as that of
1.199 + * DateTime format.
1.200 + *
1.201 + * <P>
1.202 + * Code Sample: general usage
1.203 + * <pre>
1.204 + * \code
1.205 + * // the date interval object which the DateIntervalFormat formats on
1.206 + * // and parses into
1.207 + * DateInterval* dtInterval = new DateInterval(1000*3600*24, 1000*3600*24*2);
1.208 + * UErrorCode status = U_ZERO_ERROR;
1.209 + * DateIntervalFormat* dtIntervalFmt = DateIntervalFormat::createInstance(
1.210 + * UDAT_YEAR_MONTH_DAY,
1.211 + * Locale("en", "GB", ""), status);
1.212 + * UnicodeUnicodeString dateIntervalString;
1.213 + * FieldPosition pos = 0;
1.214 + * // formatting
1.215 + * dtIntervalFmt->format(dtInterval, dateIntervalUnicodeString, pos, status);
1.216 + * delete dtIntervalFmt;
1.217 + * \endcode
1.218 + * </pre>
1.219 + */
1.220 +
1.221 +class U_I18N_API DateIntervalFormat : public Format {
1.222 +public:
1.223 +
1.224 + /**
1.225 + * Construct a DateIntervalFormat from skeleton and the default locale.
1.226 + *
1.227 + * This is a convenient override of
1.228 + * createInstance(const UnicodeString& skeleton, const Locale& locale,
1.229 + * UErrorCode&)
1.230 + * with the value of locale as default locale.
1.231 + *
1.232 + * @param skeleton the skeleton on which interval format based.
1.233 + * @param status output param set to success/failure code on exit
1.234 + * @return a date time interval formatter which the caller owns.
1.235 + * @stable ICU 4.0
1.236 + */
1.237 + static DateIntervalFormat* U_EXPORT2 createInstance(
1.238 + const UnicodeString& skeleton,
1.239 + UErrorCode& status);
1.240 +
1.241 + /**
1.242 + * Construct a DateIntervalFormat from skeleton and a given locale.
1.243 + * <P>
1.244 + * In this factory method,
1.245 + * the date interval pattern information is load from resource files.
1.246 + * Users are encouraged to created date interval formatter this way and
1.247 + * to use the pre-defined skeleton macros.
1.248 + *
1.249 + * <P>
1.250 + * There are pre-defined skeletons (defined in udate.h) having predefined
1.251 + * interval patterns in resource files.
1.252 + * Users are encouraged to use those macros.
1.253 + * For example:
1.254 + * DateIntervalFormat::createInstance(UDAT_MONTH_DAY, status)
1.255 + *
1.256 + * The given Locale provides the interval patterns.
1.257 + * For example, for en_GB, if skeleton is UDAT_YEAR_ABBR_MONTH_WEEKDAY_DAY,
1.258 + * which is "yMMMEEEd",
1.259 + * the interval patterns defined in resource file to above skeleton are:
1.260 + * "EEE, d MMM, yyyy - EEE, d MMM, yyyy" for year differs,
1.261 + * "EEE, d MMM - EEE, d MMM, yyyy" for month differs,
1.262 + * "EEE, d - EEE, d MMM, yyyy" for day differs,
1.263 + * @param skeleton the skeleton on which the interval format is based.
1.264 + * @param locale the given locale
1.265 + * @param status output param set to success/failure code on exit
1.266 + * @return a date time interval formatter which the caller owns.
1.267 + * @stable ICU 4.0
1.268 + * <p>
1.269 + * <h4>Sample code</h4>
1.270 + * \snippet samples/dtitvfmtsample/dtitvfmtsample.cpp dtitvfmtPreDefined1
1.271 + * \snippet samples/dtitvfmtsample/dtitvfmtsample.cpp dtitvfmtPreDefined
1.272 + * <p>
1.273 + */
1.274 +
1.275 + static DateIntervalFormat* U_EXPORT2 createInstance(
1.276 + const UnicodeString& skeleton,
1.277 + const Locale& locale,
1.278 + UErrorCode& status);
1.279 +
1.280 + /**
1.281 + * Construct a DateIntervalFormat from skeleton
1.282 + * DateIntervalInfo, and default locale.
1.283 + *
1.284 + * This is a convenient override of
1.285 + * createInstance(const UnicodeString& skeleton, const Locale& locale,
1.286 + * const DateIntervalInfo& dtitvinf, UErrorCode&)
1.287 + * with the locale value as default locale.
1.288 + *
1.289 + * @param skeleton the skeleton on which interval format based.
1.290 + * @param dtitvinf the DateIntervalInfo object.
1.291 + * @param status output param set to success/failure code on exit
1.292 + * @return a date time interval formatter which the caller owns.
1.293 + * @stable ICU 4.0
1.294 + */
1.295 + static DateIntervalFormat* U_EXPORT2 createInstance(
1.296 + const UnicodeString& skeleton,
1.297 + const DateIntervalInfo& dtitvinf,
1.298 + UErrorCode& status);
1.299 +
1.300 + /**
1.301 + * Construct a DateIntervalFormat from skeleton
1.302 + * a DateIntervalInfo, and the given locale.
1.303 + *
1.304 + * <P>
1.305 + * In this factory method, user provides its own date interval pattern
1.306 + * information, instead of using those pre-defined data in resource file.
1.307 + * This factory method is for powerful users who want to provide their own
1.308 + * interval patterns.
1.309 + * <P>
1.310 + * There are pre-defined skeletons (defined in udate.h) having predefined
1.311 + * interval patterns in resource files.
1.312 + * Users are encouraged to use those macros.
1.313 + * For example:
1.314 + * DateIntervalFormat::createInstance(UDAT_MONTH_DAY, status)
1.315 + *
1.316 + * The DateIntervalInfo provides the interval patterns.
1.317 + * and the DateIntervalInfo ownership remains to the caller.
1.318 + *
1.319 + * User are encouraged to set default interval pattern in DateIntervalInfo
1.320 + * as well, if they want to set other interval patterns ( instead of
1.321 + * reading the interval patterns from resource files).
1.322 + * When the corresponding interval pattern for a largest calendar different
1.323 + * field is not found ( if user not set it ), interval format fallback to
1.324 + * the default interval pattern.
1.325 + * If user does not provide default interval pattern, it fallback to
1.326 + * "{date0} - {date1}"
1.327 + *
1.328 + * @param skeleton the skeleton on which interval format based.
1.329 + * @param locale the given locale
1.330 + * @param dtitvinf the DateIntervalInfo object.
1.331 + * @param status output param set to success/failure code on exit
1.332 + * @return a date time interval formatter which the caller owns.
1.333 + * @stable ICU 4.0
1.334 + * <p>
1.335 + * <h4>Sample code</h4>
1.336 + * \snippet samples/dtitvfmtsample/dtitvfmtsample.cpp dtitvfmtPreDefined1
1.337 + * \snippet samples/dtitvfmtsample/dtitvfmtsample.cpp dtitvfmtCustomized
1.338 + * <p>
1.339 + */
1.340 + static DateIntervalFormat* U_EXPORT2 createInstance(
1.341 + const UnicodeString& skeleton,
1.342 + const Locale& locale,
1.343 + const DateIntervalInfo& dtitvinf,
1.344 + UErrorCode& status);
1.345 +
1.346 + /**
1.347 + * Destructor.
1.348 + * @stable ICU 4.0
1.349 + */
1.350 + virtual ~DateIntervalFormat();
1.351 +
1.352 + /**
1.353 + * Clone this Format object polymorphically. The caller owns the result and
1.354 + * should delete it when done.
1.355 + * @return A copy of the object.
1.356 + * @stable ICU 4.0
1.357 + */
1.358 + virtual Format* clone(void) const;
1.359 +
1.360 + /**
1.361 + * Return true if the given Format objects are semantically equal. Objects
1.362 + * of different subclasses are considered unequal.
1.363 + * @param other the object to be compared with.
1.364 + * @return true if the given Format objects are semantically equal.
1.365 + * @stable ICU 4.0
1.366 + */
1.367 + virtual UBool operator==(const Format& other) const;
1.368 +
1.369 + /**
1.370 + * Return true if the given Format objects are not semantically equal.
1.371 + * Objects of different subclasses are considered unequal.
1.372 + * @param other the object to be compared with.
1.373 + * @return true if the given Format objects are not semantically equal.
1.374 + * @stable ICU 4.0
1.375 + */
1.376 + UBool operator!=(const Format& other) const;
1.377 +
1.378 +
1.379 + using Format::format;
1.380 +
1.381 + /**
1.382 + * Format an object to produce a string. This method handles Formattable
1.383 + * objects with a DateInterval type.
1.384 + * If a the Formattable object type is not a DateInterval,
1.385 + * then it returns a failing UErrorCode.
1.386 + *
1.387 + * @param obj The object to format.
1.388 + * Must be a DateInterval.
1.389 + * @param appendTo Output parameter to receive result.
1.390 + * Result is appended to existing contents.
1.391 + * @param fieldPosition On input: an alignment field, if desired.
1.392 + * On output: the offsets of the alignment field.
1.393 + * @param status Output param filled with success/failure status.
1.394 + * @return Reference to 'appendTo' parameter.
1.395 + * @stable ICU 4.0
1.396 + */
1.397 + virtual UnicodeString& format(const Formattable& obj,
1.398 + UnicodeString& appendTo,
1.399 + FieldPosition& fieldPosition,
1.400 + UErrorCode& status) const ;
1.401 +
1.402 +
1.403 +
1.404 + /**
1.405 + * Format a DateInterval to produce a string.
1.406 + *
1.407 + * @param dtInterval DateInterval to be formatted.
1.408 + * @param appendTo Output parameter to receive result.
1.409 + * Result is appended to existing contents.
1.410 + * @param fieldPosition On input: an alignment field, if desired.
1.411 + * On output: the offsets of the alignment field.
1.412 + * @param status Output param filled with success/failure status.
1.413 + * @return Reference to 'appendTo' parameter.
1.414 + * @stable ICU 4.0
1.415 + */
1.416 + UnicodeString& format(const DateInterval* dtInterval,
1.417 + UnicodeString& appendTo,
1.418 + FieldPosition& fieldPosition,
1.419 + UErrorCode& status) const ;
1.420 +
1.421 +
1.422 + /**
1.423 + * Format 2 Calendars to produce a string.
1.424 + *
1.425 + * Note: "fromCalendar" and "toCalendar" are not const,
1.426 + * since calendar is not const in SimpleDateFormat::format(Calendar&),
1.427 + *
1.428 + * @param fromCalendar calendar set to the from date in date interval
1.429 + * to be formatted into date interval string
1.430 + * @param toCalendar calendar set to the to date in date interval
1.431 + * to be formatted into date interval string
1.432 + * @param appendTo Output parameter to receive result.
1.433 + * Result is appended to existing contents.
1.434 + * @param fieldPosition On input: an alignment field, if desired.
1.435 + * On output: the offsets of the alignment field.
1.436 + * @param status Output param filled with success/failure status.
1.437 + * Caller needs to make sure it is SUCCESS
1.438 + * at the function entrance
1.439 + * @return Reference to 'appendTo' parameter.
1.440 + * @stable ICU 4.0
1.441 + */
1.442 + UnicodeString& format(Calendar& fromCalendar,
1.443 + Calendar& toCalendar,
1.444 + UnicodeString& appendTo,
1.445 + FieldPosition& fieldPosition,
1.446 + UErrorCode& status) const ;
1.447 +
1.448 + /**
1.449 + * Date interval parsing is not supported. Please do not use.
1.450 + * <P>
1.451 + * This method should handle parsing of
1.452 + * date time interval strings into Formattable objects with
1.453 + * DateInterval type, which is a pair of UDate.
1.454 + * <P>
1.455 + * Before calling, set parse_pos.index to the offset you want to start
1.456 + * parsing at in the source. After calling, parse_pos.index is the end of
1.457 + * the text you parsed. If error occurs, index is unchanged.
1.458 + * <P>
1.459 + * When parsing, leading whitespace is discarded (with a successful parse),
1.460 + * while trailing whitespace is left as is.
1.461 + * <P>
1.462 + * See Format::parseObject() for more.
1.463 + *
1.464 + * @param source The string to be parsed into an object.
1.465 + * @param result Formattable to be set to the parse result.
1.466 + * If parse fails, return contents are undefined.
1.467 + * @param parse_pos The position to start parsing at. Since no parsing
1.468 + * is supported, upon return this param is unchanged.
1.469 + * @return A newly created Formattable* object, or NULL
1.470 + * on failure. The caller owns this and should
1.471 + * delete it when done.
1.472 + * @internal ICU 4.0
1.473 + */
1.474 + virtual void parseObject(const UnicodeString& source,
1.475 + Formattable& result,
1.476 + ParsePosition& parse_pos) const;
1.477 +
1.478 +
1.479 + /**
1.480 + * Gets the date time interval patterns.
1.481 + * @return the date time interval patterns associated with
1.482 + * this date interval formatter.
1.483 + * @stable ICU 4.0
1.484 + */
1.485 + const DateIntervalInfo* getDateIntervalInfo(void) const;
1.486 +
1.487 +
1.488 + /**
1.489 + * Set the date time interval patterns.
1.490 + * @param newIntervalPatterns the given interval patterns to copy.
1.491 + * @param status output param set to success/failure code on exit
1.492 + * @stable ICU 4.0
1.493 + */
1.494 + void setDateIntervalInfo(const DateIntervalInfo& newIntervalPatterns,
1.495 + UErrorCode& status);
1.496 +
1.497 +
1.498 + /**
1.499 + * Gets the date formatter
1.500 + * @return the date formatter associated with this date interval formatter.
1.501 + * @stable ICU 4.0
1.502 + */
1.503 + const DateFormat* getDateFormat(void) const;
1.504 +
1.505 + /**
1.506 + * Returns a reference to the TimeZone used by this DateIntervalFormat's calendar.
1.507 + * @return the time zone associated with the calendar of DateIntervalFormat.
1.508 + * @stable ICU 4.8
1.509 + */
1.510 + virtual const TimeZone& getTimeZone(void) const;
1.511 +
1.512 + /**
1.513 + * Sets the time zone for the calendar used by this DateIntervalFormat object. The
1.514 + * caller no longer owns the TimeZone object and should not delete it after this call.
1.515 + * @param zoneToAdopt the TimeZone to be adopted.
1.516 + * @stable ICU 4.8
1.517 + */
1.518 + virtual void adoptTimeZone(TimeZone* zoneToAdopt);
1.519 +
1.520 + /**
1.521 + * Sets the time zone for the calendar used by this DateIntervalFormat object.
1.522 + * @param zone the new time zone.
1.523 + * @stable ICU 4.8
1.524 + */
1.525 + virtual void setTimeZone(const TimeZone& zone);
1.526 +
1.527 + /**
1.528 + * Return the class ID for this class. This is useful only for comparing to
1.529 + * a return value from getDynamicClassID(). For example:
1.530 + * <pre>
1.531 + * . Base* polymorphic_pointer = createPolymorphicObject();
1.532 + * . if (polymorphic_pointer->getDynamicClassID() ==
1.533 + * . erived::getStaticClassID()) ...
1.534 + * </pre>
1.535 + * @return The class ID for all objects of this class.
1.536 + * @stable ICU 4.0
1.537 + */
1.538 + static UClassID U_EXPORT2 getStaticClassID(void);
1.539 +
1.540 + /**
1.541 + * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This
1.542 + * method is to implement a simple version of RTTI, since not all C++
1.543 + * compilers support genuine RTTI. Polymorphic operator==() and clone()
1.544 + * methods call this method.
1.545 + *
1.546 + * @return The class ID for this object. All objects of a
1.547 + * given class have the same class ID. Objects of
1.548 + * other classes have different class IDs.
1.549 + * @stable ICU 4.0
1.550 + */
1.551 + virtual UClassID getDynamicClassID(void) const;
1.552 +
1.553 +protected:
1.554 +
1.555 + /**
1.556 + * Copy constructor.
1.557 + * @stable ICU 4.0
1.558 + */
1.559 + DateIntervalFormat(const DateIntervalFormat&);
1.560 +
1.561 + /**
1.562 + * Assignment operator.
1.563 + * @stable ICU 4.0
1.564 + */
1.565 + DateIntervalFormat& operator=(const DateIntervalFormat&);
1.566 +
1.567 +private:
1.568 +
1.569 + /*
1.570 + * This is for ICU internal use only. Please do not use.
1.571 + * Save the interval pattern information.
1.572 + * Interval pattern consists of 2 single date patterns and the separator.
1.573 + * For example, interval pattern "MMM d - MMM d, yyyy" consists
1.574 + * a single date pattern "MMM d", another single date pattern "MMM d, yyyy",
1.575 + * and a separator "-".
1.576 + * The pattern is divided into 2 parts. For above example,
1.577 + * the first part is "MMM d - ", and the second part is "MMM d, yyyy".
1.578 + * Also, the first date appears in an interval pattern could be
1.579 + * the earlier date or the later date.
1.580 + * And such information is saved in the interval pattern as well.
1.581 + */
1.582 + struct PatternInfo {
1.583 + UnicodeString firstPart;
1.584 + UnicodeString secondPart;
1.585 + /**
1.586 + * Whether the first date in interval pattern is later date or not.
1.587 + * Fallback format set the default ordering.
1.588 + * And for a particular interval pattern, the order can be
1.589 + * overriden by prefixing the interval pattern with "latestFirst:" or
1.590 + * "earliestFirst:"
1.591 + * For example, given 2 date, Jan 10, 2007 to Feb 10, 2007.
1.592 + * if the fallback format is "{0} - {1}",
1.593 + * and the pattern is "d MMM - d MMM yyyy", the interval format is
1.594 + * "10 Jan - 10 Feb, 2007".
1.595 + * If the pattern is "latestFirst:d MMM - d MMM yyyy",
1.596 + * the interval format is "10 Feb - 10 Jan, 2007"
1.597 + */
1.598 + UBool laterDateFirst;
1.599 + };
1.600 +
1.601 +
1.602 + /**
1.603 + * default constructor
1.604 + * @internal ICU 4.0
1.605 + */
1.606 + DateIntervalFormat();
1.607 +
1.608 + /**
1.609 + * Construct a DateIntervalFormat from DateFormat,
1.610 + * a DateIntervalInfo, and skeleton.
1.611 + * DateFormat provides the timezone, calendar,
1.612 + * full pattern, and date format symbols information.
1.613 + * It should be a SimpleDateFormat object which
1.614 + * has a pattern in it.
1.615 + * the DateIntervalInfo provides the interval patterns.
1.616 + *
1.617 + * Note: the DateIntervalFormat takes ownership of both
1.618 + * DateFormat and DateIntervalInfo objects.
1.619 + * Caller should not delete them.
1.620 + *
1.621 + * @param locale the locale of this date interval formatter.
1.622 + * @param dtItvInfo the DateIntervalInfo object to be adopted.
1.623 + * @param skeleton the skeleton of the date formatter
1.624 + * @param status output param set to success/failure code on exit
1.625 + */
1.626 + DateIntervalFormat(const Locale& locale, DateIntervalInfo* dtItvInfo,
1.627 + const UnicodeString* skeleton, UErrorCode& status);
1.628 +
1.629 +
1.630 + /**
1.631 + * Construct a DateIntervalFormat from DateFormat
1.632 + * and a DateIntervalInfo.
1.633 + *
1.634 + * It is a wrapper of the constructor.
1.635 + *
1.636 + * @param locale the locale of this date interval formatter.
1.637 + * @param dtitvinf the DateIntervalInfo object to be adopted.
1.638 + * @param skeleton the skeleton of this formatter.
1.639 + * @param status Output param set to success/failure code.
1.640 + * @return a date time interval formatter which the caller owns.
1.641 + */
1.642 + static DateIntervalFormat* U_EXPORT2 create(const Locale& locale,
1.643 + DateIntervalInfo* dtitvinf,
1.644 + const UnicodeString* skeleton,
1.645 + UErrorCode& status);
1.646 +
1.647 + /**
1.648 + * Create a simple date/time formatter from skeleton, given locale,
1.649 + * and date time pattern generator.
1.650 + *
1.651 + * @param skeleton the skeleton on which date format based.
1.652 + * @param locale the given locale.
1.653 + * @param dtpng the date time pattern generator.
1.654 + * @param status Output param to be set to success/failure code.
1.655 + * If it is failure, the returned date formatter will
1.656 + * be NULL.
1.657 + * @return a simple date formatter which the caller owns.
1.658 + */
1.659 + static SimpleDateFormat* U_EXPORT2 createSDFPatternInstance(
1.660 + const UnicodeString& skeleton,
1.661 + const Locale& locale,
1.662 + DateTimePatternGenerator* dtpng,
1.663 + UErrorCode& status);
1.664 +
1.665 +
1.666 + /**
1.667 + * Below are for generating interval patterns local to the formatter
1.668 + */
1.669 +
1.670 +
1.671 + /**
1.672 + * Format 2 Calendars using fall-back interval pattern
1.673 + *
1.674 + * The full pattern used in this fall-back format is the
1.675 + * full pattern of the date formatter.
1.676 + *
1.677 + * @param fromCalendar calendar set to the from date in date interval
1.678 + * to be formatted into date interval string
1.679 + * @param toCalendar calendar set to the to date in date interval
1.680 + * to be formatted into date interval string
1.681 + * @param appendTo Output parameter to receive result.
1.682 + * Result is appended to existing contents.
1.683 + * @param pos On input: an alignment field, if desired.
1.684 + * On output: the offsets of the alignment field.
1.685 + * @param status output param set to success/failure code on exit
1.686 + * @return Reference to 'appendTo' parameter.
1.687 + */
1.688 + UnicodeString& fallbackFormat(Calendar& fromCalendar,
1.689 + Calendar& toCalendar,
1.690 + UnicodeString& appendTo,
1.691 + FieldPosition& pos,
1.692 + UErrorCode& status) const;
1.693 +
1.694 +
1.695 +
1.696 + /**
1.697 + * Initialize interval patterns locale to this formatter
1.698 + *
1.699 + * This code is a bit complicated since
1.700 + * 1. the interval patterns saved in resource bundle files are interval
1.701 + * patterns based on date or time only.
1.702 + * It does not have interval patterns based on both date and time.
1.703 + * Interval patterns on both date and time are algorithm generated.
1.704 + *
1.705 + * For example, it has interval patterns on skeleton "dMy" and "hm",
1.706 + * but it does not have interval patterns on skeleton "dMyhm".
1.707 + *
1.708 + * The rule to generate interval patterns for both date and time skeleton are
1.709 + * 1) when the year, month, or day differs, concatenate the two original
1.710 + * expressions with a separator between,
1.711 + * For example, interval pattern from "Jan 10, 2007 10:10 am"
1.712 + * to "Jan 11, 2007 10:10am" is
1.713 + * "Jan 10, 2007 10:10 am - Jan 11, 2007 10:10am"
1.714 + *
1.715 + * 2) otherwise, present the date followed by the range expression
1.716 + * for the time.
1.717 + * For example, interval pattern from "Jan 10, 2007 10:10 am"
1.718 + * to "Jan 10, 2007 11:10am" is
1.719 + * "Jan 10, 2007 10:10 am - 11:10am"
1.720 + *
1.721 + * 2. even a pattern does not request a certain calendar field,
1.722 + * the interval pattern needs to include such field if such fields are
1.723 + * different between 2 dates.
1.724 + * For example, a pattern/skeleton is "hm", but the interval pattern
1.725 + * includes year, month, and date when year, month, and date differs.
1.726 + *
1.727 + *
1.728 + * @param status output param set to success/failure code on exit
1.729 + */
1.730 + void initializePattern(UErrorCode& status);
1.731 +
1.732 +
1.733 +
1.734 + /**
1.735 + * Set fall back interval pattern given a calendar field,
1.736 + * a skeleton, and a date time pattern generator.
1.737 + * @param field the largest different calendar field
1.738 + * @param skeleton a skeleton
1.739 + * @param status output param set to success/failure code on exit
1.740 + */
1.741 + void setFallbackPattern(UCalendarDateFields field,
1.742 + const UnicodeString& skeleton,
1.743 + UErrorCode& status);
1.744 +
1.745 +
1.746 +
1.747 + /**
1.748 + * get separated date and time skeleton from a combined skeleton.
1.749 + *
1.750 + * The difference between date skeleton and normalizedDateSkeleton are:
1.751 + * 1. both 'y' and 'd' are appeared only once in normalizeDateSkeleton
1.752 + * 2. 'E' and 'EE' are normalized into 'EEE'
1.753 + * 3. 'MM' is normalized into 'M'
1.754 + *
1.755 + ** the difference between time skeleton and normalizedTimeSkeleton are:
1.756 + * 1. both 'H' and 'h' are normalized as 'h' in normalized time skeleton,
1.757 + * 2. 'a' is omitted in normalized time skeleton.
1.758 + * 3. there is only one appearance for 'h', 'm','v', 'z' in normalized time
1.759 + * skeleton
1.760 + *
1.761 + *
1.762 + * @param skeleton given combined skeleton.
1.763 + * @param date Output parameter for date only skeleton.
1.764 + * @param normalizedDate Output parameter for normalized date only
1.765 + *
1.766 + * @param time Output parameter for time only skeleton.
1.767 + * @param normalizedTime Output parameter for normalized time only
1.768 + * skeleton.
1.769 + *
1.770 + */
1.771 + static void U_EXPORT2 getDateTimeSkeleton(const UnicodeString& skeleton,
1.772 + UnicodeString& date,
1.773 + UnicodeString& normalizedDate,
1.774 + UnicodeString& time,
1.775 + UnicodeString& normalizedTime);
1.776 +
1.777 +
1.778 +
1.779 + /**
1.780 + * Generate date or time interval pattern from resource,
1.781 + * and set them into the interval pattern locale to this formatter.
1.782 + *
1.783 + * It needs to handle the following:
1.784 + * 1. need to adjust field width.
1.785 + * For example, the interval patterns saved in DateIntervalInfo
1.786 + * includes "dMMMy", but not "dMMMMy".
1.787 + * Need to get interval patterns for dMMMMy from dMMMy.
1.788 + * Another example, the interval patterns saved in DateIntervalInfo
1.789 + * includes "hmv", but not "hmz".
1.790 + * Need to get interval patterns for "hmz' from 'hmv'
1.791 + *
1.792 + * 2. there might be no pattern for 'y' differ for skeleton "Md",
1.793 + * in order to get interval patterns for 'y' differ,
1.794 + * need to look for it from skeleton 'yMd'
1.795 + *
1.796 + * @param dateSkeleton normalized date skeleton
1.797 + * @param timeSkeleton normalized time skeleton
1.798 + * @return whether the resource is found for the skeleton.
1.799 + * TRUE if interval pattern found for the skeleton,
1.800 + * FALSE otherwise.
1.801 + */
1.802 + UBool setSeparateDateTimePtn(const UnicodeString& dateSkeleton,
1.803 + const UnicodeString& timeSkeleton);
1.804 +
1.805 +
1.806 +
1.807 +
1.808 + /**
1.809 + * Generate interval pattern from existing resource
1.810 + *
1.811 + * It not only save the interval patterns,
1.812 + * but also return the extended skeleton and its best match skeleton.
1.813 + *
1.814 + * @param field largest different calendar field
1.815 + * @param skeleton skeleton
1.816 + * @param bestSkeleton the best match skeleton which has interval pattern
1.817 + * defined in resource
1.818 + * @param differenceInfo the difference between skeleton and best skeleton
1.819 + * 0 means the best matched skeleton is the same as input skeleton
1.820 + * 1 means the fields are the same, but field width are different
1.821 + * 2 means the only difference between fields are v/z,
1.822 + * -1 means there are other fields difference
1.823 + *
1.824 + * @param extendedSkeleton extended skeleton
1.825 + * @param extendedBestSkeleton extended best match skeleton
1.826 + * @return whether the interval pattern is found
1.827 + * through extending skeleton or not.
1.828 + * TRUE if interval pattern is found by
1.829 + * extending skeleton, FALSE otherwise.
1.830 + */
1.831 + UBool setIntervalPattern(UCalendarDateFields field,
1.832 + const UnicodeString* skeleton,
1.833 + const UnicodeString* bestSkeleton,
1.834 + int8_t differenceInfo,
1.835 + UnicodeString* extendedSkeleton = NULL,
1.836 + UnicodeString* extendedBestSkeleton = NULL);
1.837 +
1.838 + /**
1.839 + * Adjust field width in best match interval pattern to match
1.840 + * the field width in input skeleton.
1.841 + *
1.842 + * TODO (xji) make a general solution
1.843 + * The adjusting rule can be:
1.844 + * 1. always adjust
1.845 + * 2. never adjust
1.846 + * 3. default adjust, which means adjust according to the following rules
1.847 + * 3.1 always adjust string, such as MMM and MMMM
1.848 + * 3.2 never adjust between string and numeric, such as MM and MMM
1.849 + * 3.3 always adjust year
1.850 + * 3.4 do not adjust 'd', 'h', or 'm' if h presents
1.851 + * 3.5 do not adjust 'M' if it is numeric(?)
1.852 + *
1.853 + * Since date interval format is well-formed format,
1.854 + * date and time skeletons are normalized previously,
1.855 + * till this stage, the adjust here is only "adjust strings, such as MMM
1.856 + * and MMMM, EEE and EEEE.
1.857 + *
1.858 + * @param inputSkeleton the input skeleton
1.859 + * @param bestMatchSkeleton the best match skeleton
1.860 + * @param bestMatchIntervalPattern the best match interval pattern
1.861 + * @param differenceInfo the difference between 2 skeletons
1.862 + * 1 means only field width differs
1.863 + * 2 means v/z exchange
1.864 + * @param adjustedIntervalPattern adjusted interval pattern
1.865 + */
1.866 + static void U_EXPORT2 adjustFieldWidth(
1.867 + const UnicodeString& inputSkeleton,
1.868 + const UnicodeString& bestMatchSkeleton,
1.869 + const UnicodeString& bestMatchIntervalPattern,
1.870 + int8_t differenceInfo,
1.871 + UnicodeString& adjustedIntervalPattern);
1.872 +
1.873 + /**
1.874 + * Concat a single date pattern with a time interval pattern,
1.875 + * set it into the intervalPatterns, while field is time field.
1.876 + * This is used to handle time interval patterns on skeleton with
1.877 + * both time and date. Present the date followed by
1.878 + * the range expression for the time.
1.879 + * @param format date and time format
1.880 + * @param formatLen format string length
1.881 + * @param datePattern date pattern
1.882 + * @param field time calendar field: AM_PM, HOUR, MINUTE
1.883 + * @param status output param set to success/failure code on exit
1.884 + */
1.885 + void concatSingleDate2TimeInterval(const UChar* format,
1.886 + int32_t formatLen,
1.887 + const UnicodeString& datePattern,
1.888 + UCalendarDateFields field,
1.889 + UErrorCode& status);
1.890 +
1.891 + /**
1.892 + * check whether a calendar field present in a skeleton.
1.893 + * @param field calendar field need to check
1.894 + * @param skeleton given skeleton on which to check the calendar field
1.895 + * @return true if field present in a skeleton.
1.896 + */
1.897 + static UBool U_EXPORT2 fieldExistsInSkeleton(UCalendarDateFields field,
1.898 + const UnicodeString& skeleton);
1.899 +
1.900 +
1.901 + /**
1.902 + * Split interval patterns into 2 part.
1.903 + * @param intervalPattern interval pattern
1.904 + * @return the index in interval pattern which split the pattern into 2 part
1.905 + */
1.906 + static int32_t U_EXPORT2 splitPatternInto2Part(const UnicodeString& intervalPattern);
1.907 +
1.908 +
1.909 + /**
1.910 + * Break interval patterns as 2 part and save them into pattern info.
1.911 + * @param field calendar field
1.912 + * @param intervalPattern interval pattern
1.913 + */
1.914 + void setIntervalPattern(UCalendarDateFields field,
1.915 + const UnicodeString& intervalPattern);
1.916 +
1.917 +
1.918 + /**
1.919 + * Break interval patterns as 2 part and save them into pattern info.
1.920 + * @param field calendar field
1.921 + * @param intervalPattern interval pattern
1.922 + * @param laterDateFirst whether later date appear first in interval pattern
1.923 + */
1.924 + void setIntervalPattern(UCalendarDateFields field,
1.925 + const UnicodeString& intervalPattern,
1.926 + UBool laterDateFirst);
1.927 +
1.928 +
1.929 + /**
1.930 + * Set pattern information.
1.931 + *
1.932 + * @param field calendar field
1.933 + * @param firstPart the first part in interval pattern
1.934 + * @param secondPart the second part in interval pattern
1.935 + * @param laterDateFirst whether the first date in intervalPattern
1.936 + * is earlier date or later date
1.937 + */
1.938 + void setPatternInfo(UCalendarDateFields field,
1.939 + const UnicodeString* firstPart,
1.940 + const UnicodeString* secondPart,
1.941 + UBool laterDateFirst);
1.942 +
1.943 +
1.944 + // from calendar field to pattern letter
1.945 + static const UChar fgCalendarFieldToPatternLetter[];
1.946 +
1.947 +
1.948 + /**
1.949 + * The interval patterns for this locale.
1.950 + */
1.951 + DateIntervalInfo* fInfo;
1.952 +
1.953 + /**
1.954 + * The DateFormat object used to format single pattern
1.955 + */
1.956 + SimpleDateFormat* fDateFormat;
1.957 +
1.958 + /**
1.959 + * The 2 calendars with the from and to date.
1.960 + * could re-use the calendar in fDateFormat,
1.961 + * but keeping 2 calendars make it clear and clean.
1.962 + */
1.963 + Calendar* fFromCalendar;
1.964 + Calendar* fToCalendar;
1.965 +
1.966 + /**
1.967 + * Date time pattern generator
1.968 + */
1.969 + DateTimePatternGenerator* fDtpng;
1.970 +
1.971 + /**
1.972 + * Following are interval information relavent (locale) to this formatter.
1.973 + */
1.974 + UnicodeString fSkeleton;
1.975 + PatternInfo fIntervalPatterns[DateIntervalInfo::kIPI_MAX_INDEX];
1.976 +};
1.977 +
1.978 +inline UBool
1.979 +DateIntervalFormat::operator!=(const Format& other) const {
1.980 + return !operator==(other);
1.981 +}
1.982 +
1.983 +U_NAMESPACE_END
1.984 +
1.985 +#endif /* #if !UCONFIG_NO_FORMATTING */
1.986 +
1.987 +#endif // _DTITVFMT_H__
1.988 +//eof
