Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/dtitvfmt.h @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
rev   line source
jpayne@69 1 // © 2016 and later: Unicode, Inc. and others.
jpayne@69 2 // License & terms of use: http://www.unicode.org/copyright.html
jpayne@69 3 /********************************************************************************
jpayne@69 4 * Copyright (C) 2008-2016, International Business Machines Corporation and
jpayne@69 5 * others. All Rights Reserved.
jpayne@69 6 *******************************************************************************
jpayne@69 7 *
jpayne@69 8 * File DTITVFMT.H
jpayne@69 9 *
jpayne@69 10 *******************************************************************************
jpayne@69 11 */
jpayne@69 12
jpayne@69 13 #ifndef __DTITVFMT_H__
jpayne@69 14 #define __DTITVFMT_H__
jpayne@69 15
jpayne@69 16
jpayne@69 17 #include "unicode/utypes.h"
jpayne@69 18
jpayne@69 19 #if U_SHOW_CPLUSPLUS_API
jpayne@69 20
jpayne@69 21 /**
jpayne@69 22 * \file
jpayne@69 23 * \brief C++ API: Format and parse date interval in a language-independent manner.
jpayne@69 24 */
jpayne@69 25
jpayne@69 26 #if !UCONFIG_NO_FORMATTING
jpayne@69 27
jpayne@69 28 #include "unicode/ucal.h"
jpayne@69 29 #include "unicode/smpdtfmt.h"
jpayne@69 30 #include "unicode/dtintrv.h"
jpayne@69 31 #include "unicode/dtitvinf.h"
jpayne@69 32 #include "unicode/dtptngen.h"
jpayne@69 33 #include "unicode/formattedvalue.h"
jpayne@69 34
jpayne@69 35 U_NAMESPACE_BEGIN
jpayne@69 36
jpayne@69 37
jpayne@69 38 class FormattedDateIntervalData;
jpayne@69 39 class DateIntervalFormat;
jpayne@69 40
jpayne@69 41 /**
jpayne@69 42 * An immutable class containing the result of a date interval formatting operation.
jpayne@69 43 *
jpayne@69 44 * Instances of this class are immutable and thread-safe.
jpayne@69 45 *
jpayne@69 46 * When calling nextPosition():
jpayne@69 47 * The fields are returned from left to right. The special field category
jpayne@69 48 * UFIELD_CATEGORY_DATE_INTERVAL_SPAN is used to indicate which datetime
jpayne@69 49 * primitives came from which arguments: 0 means fromCalendar, and 1 means
jpayne@69 50 * toCalendar. The span category will always occur before the
jpayne@69 51 * corresponding fields in UFIELD_CATEGORY_DATE
jpayne@69 52 * in the nextPosition() iterator.
jpayne@69 53 *
jpayne@69 54 * Not intended for public subclassing.
jpayne@69 55 *
jpayne@69 56 * @stable ICU 64
jpayne@69 57 */
jpayne@69 58 class U_I18N_API FormattedDateInterval : public UMemory, public FormattedValue {
jpayne@69 59 public:
jpayne@69 60 /**
jpayne@69 61 * Default constructor; makes an empty FormattedDateInterval.
jpayne@69 62 * @stable ICU 64
jpayne@69 63 */
jpayne@69 64 FormattedDateInterval() : fData(nullptr), fErrorCode(U_INVALID_STATE_ERROR) {}
jpayne@69 65
jpayne@69 66 /**
jpayne@69 67 * Move constructor: Leaves the source FormattedDateInterval in an undefined state.
jpayne@69 68 * @stable ICU 64
jpayne@69 69 */
jpayne@69 70 FormattedDateInterval(FormattedDateInterval&& src) U_NOEXCEPT;
jpayne@69 71
jpayne@69 72 /**
jpayne@69 73 * Destruct an instance of FormattedDateInterval.
jpayne@69 74 * @stable ICU 64
jpayne@69 75 */
jpayne@69 76 virtual ~FormattedDateInterval() U_OVERRIDE;
jpayne@69 77
jpayne@69 78 /** Copying not supported; use move constructor instead. */
jpayne@69 79 FormattedDateInterval(const FormattedDateInterval&) = delete;
jpayne@69 80
jpayne@69 81 /** Copying not supported; use move assignment instead. */
jpayne@69 82 FormattedDateInterval& operator=(const FormattedDateInterval&) = delete;
jpayne@69 83
jpayne@69 84 /**
jpayne@69 85 * Move assignment: Leaves the source FormattedDateInterval in an undefined state.
jpayne@69 86 * @stable ICU 64
jpayne@69 87 */
jpayne@69 88 FormattedDateInterval& operator=(FormattedDateInterval&& src) U_NOEXCEPT;
jpayne@69 89
jpayne@69 90 /** @copydoc FormattedValue::toString() */
jpayne@69 91 UnicodeString toString(UErrorCode& status) const U_OVERRIDE;
jpayne@69 92
jpayne@69 93 /** @copydoc FormattedValue::toTempString() */
jpayne@69 94 UnicodeString toTempString(UErrorCode& status) const U_OVERRIDE;
jpayne@69 95
jpayne@69 96 /** @copydoc FormattedValue::appendTo() */
jpayne@69 97 Appendable &appendTo(Appendable& appendable, UErrorCode& status) const U_OVERRIDE;
jpayne@69 98
jpayne@69 99 /** @copydoc FormattedValue::nextPosition() */
jpayne@69 100 UBool nextPosition(ConstrainedFieldPosition& cfpos, UErrorCode& status) const U_OVERRIDE;
jpayne@69 101
jpayne@69 102 private:
jpayne@69 103 FormattedDateIntervalData *fData;
jpayne@69 104 UErrorCode fErrorCode;
jpayne@69 105 explicit FormattedDateInterval(FormattedDateIntervalData *results)
jpayne@69 106 : fData(results), fErrorCode(U_ZERO_ERROR) {}
jpayne@69 107 explicit FormattedDateInterval(UErrorCode errorCode)
jpayne@69 108 : fData(nullptr), fErrorCode(errorCode) {}
jpayne@69 109 friend class DateIntervalFormat;
jpayne@69 110 };
jpayne@69 111
jpayne@69 112
jpayne@69 113 /**
jpayne@69 114 * DateIntervalFormat is a class for formatting and parsing date
jpayne@69 115 * intervals in a language-independent manner.
jpayne@69 116 * Only formatting is supported, parsing is not supported.
jpayne@69 117 *
jpayne@69 118 * <P>
jpayne@69 119 * Date interval means from one date to another date,
jpayne@69 120 * for example, from "Jan 11, 2008" to "Jan 18, 2008".
jpayne@69 121 * We introduced class DateInterval to represent it.
jpayne@69 122 * DateInterval is a pair of UDate, which is
jpayne@69 123 * the standard milliseconds since 24:00 GMT, Jan 1, 1970.
jpayne@69 124 *
jpayne@69 125 * <P>
jpayne@69 126 * DateIntervalFormat formats a DateInterval into
jpayne@69 127 * text as compactly as possible.
jpayne@69 128 * For example, the date interval format from "Jan 11, 2008" to "Jan 18,. 2008"
jpayne@69 129 * is "Jan 11-18, 2008" for English.
jpayne@69 130 * And it parses text into DateInterval,
jpayne@69 131 * although initially, parsing is not supported.
jpayne@69 132 *
jpayne@69 133 * <P>
jpayne@69 134 * There is no structural information in date time patterns.
jpayne@69 135 * For any punctuations and string literals inside a date time pattern,
jpayne@69 136 * we do not know whether it is just a separator, or a prefix, or a suffix.
jpayne@69 137 * Without such information, so, it is difficult to generate a sub-pattern
jpayne@69 138 * (or super-pattern) by algorithm.
jpayne@69 139 * So, formatting a DateInterval is pattern-driven. It is very
jpayne@69 140 * similar to formatting in SimpleDateFormat.
jpayne@69 141 * We introduce class DateIntervalInfo to save date interval
jpayne@69 142 * patterns, similar to date time pattern in SimpleDateFormat.
jpayne@69 143 *
jpayne@69 144 * <P>
jpayne@69 145 * Logically, the interval patterns are mappings
jpayne@69 146 * from (skeleton, the_largest_different_calendar_field)
jpayne@69 147 * to (date_interval_pattern).
jpayne@69 148 *
jpayne@69 149 * <P>
jpayne@69 150 * A skeleton
jpayne@69 151 * <ol>
jpayne@69 152 * <li>
jpayne@69 153 * only keeps the field pattern letter and ignores all other parts
jpayne@69 154 * in a pattern, such as space, punctuations, and string literals.
jpayne@69 155 * </li>
jpayne@69 156 * <li>
jpayne@69 157 * hides the order of fields.
jpayne@69 158 * </li>
jpayne@69 159 * <li>
jpayne@69 160 * might hide a field's pattern letter length.
jpayne@69 161 * </li>
jpayne@69 162 * </ol>
jpayne@69 163 *
jpayne@69 164 * For those non-digit calendar fields, the pattern letter length is
jpayne@69 165 * important, such as MMM, MMMM, and MMMMM; EEE and EEEE,
jpayne@69 166 * and the field's pattern letter length is honored.
jpayne@69 167 *
jpayne@69 168 * For the digit calendar fields, such as M or MM, d or dd, yy or yyyy,
jpayne@69 169 * the field pattern length is ignored and the best match, which is defined
jpayne@69 170 * in date time patterns, will be returned without honor the field pattern
jpayne@69 171 * letter length in skeleton.
jpayne@69 172 *
jpayne@69 173 * <P>
jpayne@69 174 * The calendar fields we support for interval formatting are:
jpayne@69 175 * year, month, date, day-of-week, am-pm, hour, hour-of-day, minute, second,
jpayne@69 176 * and millisecond.
jpayne@69 177 * (though we do not currently have specific intervalFormat date for skeletons
jpayne@69 178 * with seconds and millisecond).
jpayne@69 179 * Those calendar fields can be defined in the following order:
jpayne@69 180 * year > month > date > hour (in day) > minute > second > millisecond
jpayne@69 181 *
jpayne@69 182 * The largest different calendar fields between 2 calendars is the
jpayne@69 183 * first different calendar field in above order.
jpayne@69 184 *
jpayne@69 185 * For example: the largest different calendar fields between "Jan 10, 2007"
jpayne@69 186 * and "Feb 20, 2008" is year.
jpayne@69 187 *
jpayne@69 188 * <P>
jpayne@69 189 * For other calendar fields, the compact interval formatting is not
jpayne@69 190 * supported. And the interval format will be fall back to fall-back
jpayne@69 191 * patterns, which is mostly "{date0} - {date1}".
jpayne@69 192 *
jpayne@69 193 * <P>
jpayne@69 194 * There is a set of pre-defined static skeleton strings.
jpayne@69 195 * There are pre-defined interval patterns for those pre-defined skeletons
jpayne@69 196 * in locales' resource files.
jpayne@69 197 * For example, for a skeleton UDAT_YEAR_ABBR_MONTH_DAY, which is &quot;yMMMd&quot;,
jpayne@69 198 * in en_US, if the largest different calendar field between date1 and date2
jpayne@69 199 * is &quot;year&quot;, the date interval pattern is &quot;MMM d, yyyy - MMM d, yyyy&quot;,
jpayne@69 200 * such as &quot;Jan 10, 2007 - Jan 10, 2008&quot;.
jpayne@69 201 * If the largest different calendar field between date1 and date2 is &quot;month&quot;,
jpayne@69 202 * the date interval pattern is &quot;MMM d - MMM d, yyyy&quot;,
jpayne@69 203 * such as &quot;Jan 10 - Feb 10, 2007&quot;.
jpayne@69 204 * If the largest different calendar field between date1 and date2 is &quot;day&quot;,
jpayne@69 205 * the date interval pattern is &quot;MMM d-d, yyyy&quot;, such as &quot;Jan 10-20, 2007&quot;.
jpayne@69 206 *
jpayne@69 207 * For date skeleton, the interval patterns when year, or month, or date is
jpayne@69 208 * different are defined in resource files.
jpayne@69 209 * For time skeleton, the interval patterns when am/pm, or hour, or minute is
jpayne@69 210 * different are defined in resource files.
jpayne@69 211 *
jpayne@69 212 * <P>
jpayne@69 213 * If a skeleton is not found in a locale's DateIntervalInfo, which means
jpayne@69 214 * the interval patterns for the skeleton is not defined in resource file,
jpayne@69 215 * the interval pattern will falls back to the interval "fallback" pattern
jpayne@69 216 * defined in resource file.
jpayne@69 217 * If the interval "fallback" pattern is not defined, the default fall-back
jpayne@69 218 * is "{date0} - {data1}".
jpayne@69 219 *
jpayne@69 220 * <P>
jpayne@69 221 * For the combination of date and time,
jpayne@69 222 * The rule to generate interval patterns are:
jpayne@69 223 * <ol>
jpayne@69 224 * <li>
jpayne@69 225 * when the year, month, or day differs, falls back to fall-back
jpayne@69 226 * interval pattern, which mostly is the concatenate the two original
jpayne@69 227 * expressions with a separator between,
jpayne@69 228 * For example, interval pattern from "Jan 10, 2007 10:10 am"
jpayne@69 229 * to "Jan 11, 2007 10:10am" is
jpayne@69 230 * "Jan 10, 2007 10:10 am - Jan 11, 2007 10:10am"
jpayne@69 231 * </li>
jpayne@69 232 * <li>
jpayne@69 233 * otherwise, present the date followed by the range expression
jpayne@69 234 * for the time.
jpayne@69 235 * For example, interval pattern from "Jan 10, 2007 10:10 am"
jpayne@69 236 * to "Jan 10, 2007 11:10am" is "Jan 10, 2007 10:10 am - 11:10am"
jpayne@69 237 * </li>
jpayne@69 238 * </ol>
jpayne@69 239 *
jpayne@69 240 *
jpayne@69 241 * <P>
jpayne@69 242 * If two dates are the same, the interval pattern is the single date pattern.
jpayne@69 243 * For example, interval pattern from "Jan 10, 2007" to "Jan 10, 2007" is
jpayne@69 244 * "Jan 10, 2007".
jpayne@69 245 *
jpayne@69 246 * Or if the presenting fields between 2 dates have the exact same values,
jpayne@69 247 * the interval pattern is the single date pattern.
jpayne@69 248 * For example, if user only requests year and month,
jpayne@69 249 * the interval pattern from "Jan 10, 2007" to "Jan 20, 2007" is "Jan 2007".
jpayne@69 250 *
jpayne@69 251 * <P>
jpayne@69 252 * DateIntervalFormat needs the following information for correct
jpayne@69 253 * formatting: time zone, calendar type, pattern, date format symbols,
jpayne@69 254 * and date interval patterns.
jpayne@69 255 * It can be instantiated in 2 ways:
jpayne@69 256 * <ol>
jpayne@69 257 * <li>
jpayne@69 258 * create an instance using default or given locale plus given skeleton.
jpayne@69 259 * Users are encouraged to created date interval formatter this way and
jpayne@69 260 * to use the pre-defined skeleton macros, such as
jpayne@69 261 * UDAT_YEAR_NUM_MONTH, which consists the calendar fields and
jpayne@69 262 * the format style.
jpayne@69 263 * </li>
jpayne@69 264 * <li>
jpayne@69 265 * create an instance using default or given locale plus given skeleton
jpayne@69 266 * plus a given DateIntervalInfo.
jpayne@69 267 * This factory method is for powerful users who want to provide their own
jpayne@69 268 * interval patterns.
jpayne@69 269 * Locale provides the timezone, calendar, and format symbols information.
jpayne@69 270 * Local plus skeleton provides full pattern information.
jpayne@69 271 * DateIntervalInfo provides the date interval patterns.
jpayne@69 272 * </li>
jpayne@69 273 * </ol>
jpayne@69 274 *
jpayne@69 275 * <P>
jpayne@69 276 * For the calendar field pattern letter, such as G, y, M, d, a, h, H, m, s etc.
jpayne@69 277 * DateIntervalFormat uses the same syntax as that of
jpayne@69 278 * DateTime format.
jpayne@69 279 *
jpayne@69 280 * <P>
jpayne@69 281 * Code Sample: general usage
jpayne@69 282 * <pre>
jpayne@69 283 * \code
jpayne@69 284 * // the date interval object which the DateIntervalFormat formats on
jpayne@69 285 * // and parses into
jpayne@69 286 * DateInterval* dtInterval = new DateInterval(1000*3600*24, 1000*3600*24*2);
jpayne@69 287 * UErrorCode status = U_ZERO_ERROR;
jpayne@69 288 * DateIntervalFormat* dtIntervalFmt = DateIntervalFormat::createInstance(
jpayne@69 289 * UDAT_YEAR_MONTH_DAY,
jpayne@69 290 * Locale("en", "GB", ""), status);
jpayne@69 291 * UnicodeUnicodeString dateIntervalString;
jpayne@69 292 * FieldPosition pos = 0;
jpayne@69 293 * // formatting
jpayne@69 294 * dtIntervalFmt->format(dtInterval, dateIntervalUnicodeString, pos, status);
jpayne@69 295 * delete dtIntervalFmt;
jpayne@69 296 * \endcode
jpayne@69 297 * </pre>
jpayne@69 298 */
jpayne@69 299 class U_I18N_API DateIntervalFormat : public Format {
jpayne@69 300 public:
jpayne@69 301
jpayne@69 302 /**
jpayne@69 303 * Construct a DateIntervalFormat from skeleton and the default locale.
jpayne@69 304 *
jpayne@69 305 * This is a convenient override of
jpayne@69 306 * createInstance(const UnicodeString& skeleton, const Locale& locale,
jpayne@69 307 * UErrorCode&)
jpayne@69 308 * with the value of locale as default locale.
jpayne@69 309 *
jpayne@69 310 * @param skeleton the skeleton on which interval format based.
jpayne@69 311 * @param status output param set to success/failure code on exit
jpayne@69 312 * @return a date time interval formatter which the caller owns.
jpayne@69 313 * @stable ICU 4.0
jpayne@69 314 */
jpayne@69 315 static DateIntervalFormat* U_EXPORT2 createInstance(
jpayne@69 316 const UnicodeString& skeleton,
jpayne@69 317 UErrorCode& status);
jpayne@69 318
jpayne@69 319 /**
jpayne@69 320 * Construct a DateIntervalFormat from skeleton and a given locale.
jpayne@69 321 * <P>
jpayne@69 322 * In this factory method,
jpayne@69 323 * the date interval pattern information is load from resource files.
jpayne@69 324 * Users are encouraged to created date interval formatter this way and
jpayne@69 325 * to use the pre-defined skeleton macros.
jpayne@69 326 *
jpayne@69 327 * <P>
jpayne@69 328 * There are pre-defined skeletons (defined in udate.h) having predefined
jpayne@69 329 * interval patterns in resource files.
jpayne@69 330 * Users are encouraged to use those macros.
jpayne@69 331 * For example:
jpayne@69 332 * DateIntervalFormat::createInstance(UDAT_MONTH_DAY, status)
jpayne@69 333 *
jpayne@69 334 * The given Locale provides the interval patterns.
jpayne@69 335 * For example, for en_GB, if skeleton is UDAT_YEAR_ABBR_MONTH_WEEKDAY_DAY,
jpayne@69 336 * which is "yMMMEEEd",
jpayne@69 337 * the interval patterns defined in resource file to above skeleton are:
jpayne@69 338 * "EEE, d MMM, yyyy - EEE, d MMM, yyyy" for year differs,
jpayne@69 339 * "EEE, d MMM - EEE, d MMM, yyyy" for month differs,
jpayne@69 340 * "EEE, d - EEE, d MMM, yyyy" for day differs,
jpayne@69 341 * @param skeleton the skeleton on which the interval format is based.
jpayne@69 342 * @param locale the given locale
jpayne@69 343 * @param status output param set to success/failure code on exit
jpayne@69 344 * @return a date time interval formatter which the caller owns.
jpayne@69 345 * @stable ICU 4.0
jpayne@69 346 * <p>
jpayne@69 347 * <h4>Sample code</h4>
jpayne@69 348 * \snippet samples/dtitvfmtsample/dtitvfmtsample.cpp dtitvfmtPreDefined1
jpayne@69 349 * \snippet samples/dtitvfmtsample/dtitvfmtsample.cpp dtitvfmtPreDefined
jpayne@69 350 * <p>
jpayne@69 351 */
jpayne@69 352
jpayne@69 353 static DateIntervalFormat* U_EXPORT2 createInstance(
jpayne@69 354 const UnicodeString& skeleton,
jpayne@69 355 const Locale& locale,
jpayne@69 356 UErrorCode& status);
jpayne@69 357
jpayne@69 358 /**
jpayne@69 359 * Construct a DateIntervalFormat from skeleton
jpayne@69 360 * DateIntervalInfo, and default locale.
jpayne@69 361 *
jpayne@69 362 * This is a convenient override of
jpayne@69 363 * createInstance(const UnicodeString& skeleton, const Locale& locale,
jpayne@69 364 * const DateIntervalInfo& dtitvinf, UErrorCode&)
jpayne@69 365 * with the locale value as default locale.
jpayne@69 366 *
jpayne@69 367 * @param skeleton the skeleton on which interval format based.
jpayne@69 368 * @param dtitvinf the DateIntervalInfo object.
jpayne@69 369 * @param status output param set to success/failure code on exit
jpayne@69 370 * @return a date time interval formatter which the caller owns.
jpayne@69 371 * @stable ICU 4.0
jpayne@69 372 */
jpayne@69 373 static DateIntervalFormat* U_EXPORT2 createInstance(
jpayne@69 374 const UnicodeString& skeleton,
jpayne@69 375 const DateIntervalInfo& dtitvinf,
jpayne@69 376 UErrorCode& status);
jpayne@69 377
jpayne@69 378 /**
jpayne@69 379 * Construct a DateIntervalFormat from skeleton
jpayne@69 380 * a DateIntervalInfo, and the given locale.
jpayne@69 381 *
jpayne@69 382 * <P>
jpayne@69 383 * In this factory method, user provides its own date interval pattern
jpayne@69 384 * information, instead of using those pre-defined data in resource file.
jpayne@69 385 * This factory method is for powerful users who want to provide their own
jpayne@69 386 * interval patterns.
jpayne@69 387 * <P>
jpayne@69 388 * There are pre-defined skeletons (defined in udate.h) having predefined
jpayne@69 389 * interval patterns in resource files.
jpayne@69 390 * Users are encouraged to use those macros.
jpayne@69 391 * For example:
jpayne@69 392 * DateIntervalFormat::createInstance(UDAT_MONTH_DAY, status)
jpayne@69 393 *
jpayne@69 394 * The DateIntervalInfo provides the interval patterns.
jpayne@69 395 * and the DateIntervalInfo ownership remains to the caller.
jpayne@69 396 *
jpayne@69 397 * User are encouraged to set default interval pattern in DateIntervalInfo
jpayne@69 398 * as well, if they want to set other interval patterns ( instead of
jpayne@69 399 * reading the interval patterns from resource files).
jpayne@69 400 * When the corresponding interval pattern for a largest calendar different
jpayne@69 401 * field is not found ( if user not set it ), interval format fallback to
jpayne@69 402 * the default interval pattern.
jpayne@69 403 * If user does not provide default interval pattern, it fallback to
jpayne@69 404 * "{date0} - {date1}"
jpayne@69 405 *
jpayne@69 406 * @param skeleton the skeleton on which interval format based.
jpayne@69 407 * @param locale the given locale
jpayne@69 408 * @param dtitvinf the DateIntervalInfo object.
jpayne@69 409 * @param status output param set to success/failure code on exit
jpayne@69 410 * @return a date time interval formatter which the caller owns.
jpayne@69 411 * @stable ICU 4.0
jpayne@69 412 * <p>
jpayne@69 413 * <h4>Sample code</h4>
jpayne@69 414 * \snippet samples/dtitvfmtsample/dtitvfmtsample.cpp dtitvfmtPreDefined1
jpayne@69 415 * \snippet samples/dtitvfmtsample/dtitvfmtsample.cpp dtitvfmtCustomized
jpayne@69 416 * <p>
jpayne@69 417 */
jpayne@69 418 static DateIntervalFormat* U_EXPORT2 createInstance(
jpayne@69 419 const UnicodeString& skeleton,
jpayne@69 420 const Locale& locale,
jpayne@69 421 const DateIntervalInfo& dtitvinf,
jpayne@69 422 UErrorCode& status);
jpayne@69 423
jpayne@69 424 /**
jpayne@69 425 * Destructor.
jpayne@69 426 * @stable ICU 4.0
jpayne@69 427 */
jpayne@69 428 virtual ~DateIntervalFormat();
jpayne@69 429
jpayne@69 430 /**
jpayne@69 431 * Clone this Format object polymorphically. The caller owns the result and
jpayne@69 432 * should delete it when done.
jpayne@69 433 * @return A copy of the object.
jpayne@69 434 * @stable ICU 4.0
jpayne@69 435 */
jpayne@69 436 virtual DateIntervalFormat* clone() const;
jpayne@69 437
jpayne@69 438 /**
jpayne@69 439 * Return true if the given Format objects are semantically equal. Objects
jpayne@69 440 * of different subclasses are considered unequal.
jpayne@69 441 * @param other the object to be compared with.
jpayne@69 442 * @return true if the given Format objects are semantically equal.
jpayne@69 443 * @stable ICU 4.0
jpayne@69 444 */
jpayne@69 445 virtual UBool operator==(const Format& other) const;
jpayne@69 446
jpayne@69 447 /**
jpayne@69 448 * Return true if the given Format objects are not semantically equal.
jpayne@69 449 * Objects of different subclasses are considered unequal.
jpayne@69 450 * @param other the object to be compared with.
jpayne@69 451 * @return true if the given Format objects are not semantically equal.
jpayne@69 452 * @stable ICU 4.0
jpayne@69 453 */
jpayne@69 454 UBool operator!=(const Format& other) const;
jpayne@69 455
jpayne@69 456
jpayne@69 457 using Format::format;
jpayne@69 458
jpayne@69 459 /**
jpayne@69 460 * Format an object to produce a string. This method handles Formattable
jpayne@69 461 * objects with a DateInterval type.
jpayne@69 462 * If a the Formattable object type is not a DateInterval,
jpayne@69 463 * then it returns a failing UErrorCode.
jpayne@69 464 *
jpayne@69 465 * @param obj The object to format.
jpayne@69 466 * Must be a DateInterval.
jpayne@69 467 * @param appendTo Output parameter to receive result.
jpayne@69 468 * Result is appended to existing contents.
jpayne@69 469 * @param fieldPosition On input: an alignment field, if desired.
jpayne@69 470 * On output: the offsets of the alignment field.
jpayne@69 471 * There may be multiple instances of a given field type
jpayne@69 472 * in an interval format; in this case the fieldPosition
jpayne@69 473 * offsets refer to the first instance.
jpayne@69 474 * @param status Output param filled with success/failure status.
jpayne@69 475 * @return Reference to 'appendTo' parameter.
jpayne@69 476 * @stable ICU 4.0
jpayne@69 477 */
jpayne@69 478 virtual UnicodeString& format(const Formattable& obj,
jpayne@69 479 UnicodeString& appendTo,
jpayne@69 480 FieldPosition& fieldPosition,
jpayne@69 481 UErrorCode& status) const ;
jpayne@69 482
jpayne@69 483
jpayne@69 484
jpayne@69 485 /**
jpayne@69 486 * Format a DateInterval to produce a string.
jpayne@69 487 *
jpayne@69 488 * @param dtInterval DateInterval to be formatted.
jpayne@69 489 * @param appendTo Output parameter to receive result.
jpayne@69 490 * Result is appended to existing contents.
jpayne@69 491 * @param fieldPosition On input: an alignment field, if desired.
jpayne@69 492 * On output: the offsets of the alignment field.
jpayne@69 493 * There may be multiple instances of a given field type
jpayne@69 494 * in an interval format; in this case the fieldPosition
jpayne@69 495 * offsets refer to the first instance.
jpayne@69 496 * @param status Output param filled with success/failure status.
jpayne@69 497 * @return Reference to 'appendTo' parameter.
jpayne@69 498 * @stable ICU 4.0
jpayne@69 499 */
jpayne@69 500 UnicodeString& format(const DateInterval* dtInterval,
jpayne@69 501 UnicodeString& appendTo,
jpayne@69 502 FieldPosition& fieldPosition,
jpayne@69 503 UErrorCode& status) const ;
jpayne@69 504
jpayne@69 505 /**
jpayne@69 506 * Format a DateInterval to produce a FormattedDateInterval.
jpayne@69 507 *
jpayne@69 508 * The FormattedDateInterval exposes field information about the formatted string.
jpayne@69 509 *
jpayne@69 510 * @param dtInterval DateInterval to be formatted.
jpayne@69 511 * @param status Set if an error occurs.
jpayne@69 512 * @return A FormattedDateInterval containing the format result.
jpayne@69 513 * @stable ICU 64
jpayne@69 514 */
jpayne@69 515 FormattedDateInterval formatToValue(
jpayne@69 516 const DateInterval& dtInterval,
jpayne@69 517 UErrorCode& status) const;
jpayne@69 518
jpayne@69 519 /**
jpayne@69 520 * Format 2 Calendars to produce a string.
jpayne@69 521 *
jpayne@69 522 * Note: "fromCalendar" and "toCalendar" are not const,
jpayne@69 523 * since calendar is not const in SimpleDateFormat::format(Calendar&),
jpayne@69 524 *
jpayne@69 525 * @param fromCalendar calendar set to the from date in date interval
jpayne@69 526 * to be formatted into date interval string
jpayne@69 527 * @param toCalendar calendar set to the to date in date interval
jpayne@69 528 * to be formatted into date interval string
jpayne@69 529 * @param appendTo Output parameter to receive result.
jpayne@69 530 * Result is appended to existing contents.
jpayne@69 531 * @param fieldPosition On input: an alignment field, if desired.
jpayne@69 532 * On output: the offsets of the alignment field.
jpayne@69 533 * There may be multiple instances of a given field type
jpayne@69 534 * in an interval format; in this case the fieldPosition
jpayne@69 535 * offsets refer to the first instance.
jpayne@69 536 * @param status Output param filled with success/failure status.
jpayne@69 537 * Caller needs to make sure it is SUCCESS
jpayne@69 538 * at the function entrance
jpayne@69 539 * @return Reference to 'appendTo' parameter.
jpayne@69 540 * @stable ICU 4.0
jpayne@69 541 */
jpayne@69 542 UnicodeString& format(Calendar& fromCalendar,
jpayne@69 543 Calendar& toCalendar,
jpayne@69 544 UnicodeString& appendTo,
jpayne@69 545 FieldPosition& fieldPosition,
jpayne@69 546 UErrorCode& status) const ;
jpayne@69 547
jpayne@69 548 /**
jpayne@69 549 * Format 2 Calendars to produce a FormattedDateInterval.
jpayne@69 550 *
jpayne@69 551 * The FormattedDateInterval exposes field information about the formatted string.
jpayne@69 552 *
jpayne@69 553 * Note: "fromCalendar" and "toCalendar" are not const,
jpayne@69 554 * since calendar is not const in SimpleDateFormat::format(Calendar&),
jpayne@69 555 *
jpayne@69 556 * @param fromCalendar calendar set to the from date in date interval
jpayne@69 557 * to be formatted into date interval string
jpayne@69 558 * @param toCalendar calendar set to the to date in date interval
jpayne@69 559 * to be formatted into date interval string
jpayne@69 560 * @param status Set if an error occurs.
jpayne@69 561 * @return A FormattedDateInterval containing the format result.
jpayne@69 562 * @stable ICU 64
jpayne@69 563 */
jpayne@69 564 FormattedDateInterval formatToValue(
jpayne@69 565 Calendar& fromCalendar,
jpayne@69 566 Calendar& toCalendar,
jpayne@69 567 UErrorCode& status) const;
jpayne@69 568
jpayne@69 569 /**
jpayne@69 570 * Date interval parsing is not supported. Please do not use.
jpayne@69 571 * <P>
jpayne@69 572 * This method should handle parsing of
jpayne@69 573 * date time interval strings into Formattable objects with
jpayne@69 574 * DateInterval type, which is a pair of UDate.
jpayne@69 575 * <P>
jpayne@69 576 * Before calling, set parse_pos.index to the offset you want to start
jpayne@69 577 * parsing at in the source. After calling, parse_pos.index is the end of
jpayne@69 578 * the text you parsed. If error occurs, index is unchanged.
jpayne@69 579 * <P>
jpayne@69 580 * When parsing, leading whitespace is discarded (with a successful parse),
jpayne@69 581 * while trailing whitespace is left as is.
jpayne@69 582 * <P>
jpayne@69 583 * See Format::parseObject() for more.
jpayne@69 584 *
jpayne@69 585 * @param source The string to be parsed into an object.
jpayne@69 586 * @param result Formattable to be set to the parse result.
jpayne@69 587 * If parse fails, return contents are undefined.
jpayne@69 588 * @param parse_pos The position to start parsing at. Since no parsing
jpayne@69 589 * is supported, upon return this param is unchanged.
jpayne@69 590 * @return A newly created Formattable* object, or NULL
jpayne@69 591 * on failure. The caller owns this and should
jpayne@69 592 * delete it when done.
jpayne@69 593 * @internal ICU 4.0
jpayne@69 594 */
jpayne@69 595 virtual void parseObject(const UnicodeString& source,
jpayne@69 596 Formattable& result,
jpayne@69 597 ParsePosition& parse_pos) const;
jpayne@69 598
jpayne@69 599
jpayne@69 600 /**
jpayne@69 601 * Gets the date time interval patterns.
jpayne@69 602 * @return the date time interval patterns associated with
jpayne@69 603 * this date interval formatter.
jpayne@69 604 * @stable ICU 4.0
jpayne@69 605 */
jpayne@69 606 const DateIntervalInfo* getDateIntervalInfo(void) const;
jpayne@69 607
jpayne@69 608
jpayne@69 609 /**
jpayne@69 610 * Set the date time interval patterns.
jpayne@69 611 * @param newIntervalPatterns the given interval patterns to copy.
jpayne@69 612 * @param status output param set to success/failure code on exit
jpayne@69 613 * @stable ICU 4.0
jpayne@69 614 */
jpayne@69 615 void setDateIntervalInfo(const DateIntervalInfo& newIntervalPatterns,
jpayne@69 616 UErrorCode& status);
jpayne@69 617
jpayne@69 618
jpayne@69 619 /**
jpayne@69 620 * Gets the date formatter. The DateIntervalFormat instance continues to own
jpayne@69 621 * the returned DateFormatter object, and will use and possibly modify it
jpayne@69 622 * during format operations. In a multi-threaded environment, the returned
jpayne@69 623 * DateFormat can only be used if it is certain that no other threads are
jpayne@69 624 * concurrently using this DateIntervalFormatter, even for nominally const
jpayne@69 625 * functions.
jpayne@69 626 *
jpayne@69 627 * @return the date formatter associated with this date interval formatter.
jpayne@69 628 * @stable ICU 4.0
jpayne@69 629 */
jpayne@69 630 const DateFormat* getDateFormat(void) const;
jpayne@69 631
jpayne@69 632 /**
jpayne@69 633 * Returns a reference to the TimeZone used by this DateIntervalFormat's calendar.
jpayne@69 634 * @return the time zone associated with the calendar of DateIntervalFormat.
jpayne@69 635 * @stable ICU 4.8
jpayne@69 636 */
jpayne@69 637 virtual const TimeZone& getTimeZone(void) const;
jpayne@69 638
jpayne@69 639 /**
jpayne@69 640 * Sets the time zone for the calendar used by this DateIntervalFormat object. The
jpayne@69 641 * caller no longer owns the TimeZone object and should not delete it after this call.
jpayne@69 642 * @param zoneToAdopt the TimeZone to be adopted.
jpayne@69 643 * @stable ICU 4.8
jpayne@69 644 */
jpayne@69 645 virtual void adoptTimeZone(TimeZone* zoneToAdopt);
jpayne@69 646
jpayne@69 647 /**
jpayne@69 648 * Sets the time zone for the calendar used by this DateIntervalFormat object.
jpayne@69 649 * @param zone the new time zone.
jpayne@69 650 * @stable ICU 4.8
jpayne@69 651 */
jpayne@69 652 virtual void setTimeZone(const TimeZone& zone);
jpayne@69 653
jpayne@69 654 /**
jpayne@69 655 * Return the class ID for this class. This is useful only for comparing to
jpayne@69 656 * a return value from getDynamicClassID(). For example:
jpayne@69 657 * <pre>
jpayne@69 658 * . Base* polymorphic_pointer = createPolymorphicObject();
jpayne@69 659 * . if (polymorphic_pointer->getDynamicClassID() ==
jpayne@69 660 * . erived::getStaticClassID()) ...
jpayne@69 661 * </pre>
jpayne@69 662 * @return The class ID for all objects of this class.
jpayne@69 663 * @stable ICU 4.0
jpayne@69 664 */
jpayne@69 665 static UClassID U_EXPORT2 getStaticClassID(void);
jpayne@69 666
jpayne@69 667 /**
jpayne@69 668 * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This
jpayne@69 669 * method is to implement a simple version of RTTI, since not all C++
jpayne@69 670 * compilers support genuine RTTI. Polymorphic operator==() and clone()
jpayne@69 671 * methods call this method.
jpayne@69 672 *
jpayne@69 673 * @return The class ID for this object. All objects of a
jpayne@69 674 * given class have the same class ID. Objects of
jpayne@69 675 * other classes have different class IDs.
jpayne@69 676 * @stable ICU 4.0
jpayne@69 677 */
jpayne@69 678 virtual UClassID getDynamicClassID(void) const;
jpayne@69 679
jpayne@69 680 protected:
jpayne@69 681
jpayne@69 682 /**
jpayne@69 683 * Copy constructor.
jpayne@69 684 * @stable ICU 4.0
jpayne@69 685 */
jpayne@69 686 DateIntervalFormat(const DateIntervalFormat&);
jpayne@69 687
jpayne@69 688 /**
jpayne@69 689 * Assignment operator.
jpayne@69 690 * @stable ICU 4.0
jpayne@69 691 */
jpayne@69 692 DateIntervalFormat& operator=(const DateIntervalFormat&);
jpayne@69 693
jpayne@69 694 private:
jpayne@69 695
jpayne@69 696 /*
jpayne@69 697 * This is for ICU internal use only. Please do not use.
jpayne@69 698 * Save the interval pattern information.
jpayne@69 699 * Interval pattern consists of 2 single date patterns and the separator.
jpayne@69 700 * For example, interval pattern "MMM d - MMM d, yyyy" consists
jpayne@69 701 * a single date pattern "MMM d", another single date pattern "MMM d, yyyy",
jpayne@69 702 * and a separator "-".
jpayne@69 703 * The pattern is divided into 2 parts. For above example,
jpayne@69 704 * the first part is "MMM d - ", and the second part is "MMM d, yyyy".
jpayne@69 705 * Also, the first date appears in an interval pattern could be
jpayne@69 706 * the earlier date or the later date.
jpayne@69 707 * And such information is saved in the interval pattern as well.
jpayne@69 708 */
jpayne@69 709 struct PatternInfo {
jpayne@69 710 UnicodeString firstPart;
jpayne@69 711 UnicodeString secondPart;
jpayne@69 712 /**
jpayne@69 713 * Whether the first date in interval pattern is later date or not.
jpayne@69 714 * Fallback format set the default ordering.
jpayne@69 715 * And for a particular interval pattern, the order can be
jpayne@69 716 * overriden by prefixing the interval pattern with "latestFirst:" or
jpayne@69 717 * "earliestFirst:"
jpayne@69 718 * For example, given 2 date, Jan 10, 2007 to Feb 10, 2007.
jpayne@69 719 * if the fallback format is "{0} - {1}",
jpayne@69 720 * and the pattern is "d MMM - d MMM yyyy", the interval format is
jpayne@69 721 * "10 Jan - 10 Feb, 2007".
jpayne@69 722 * If the pattern is "latestFirst:d MMM - d MMM yyyy",
jpayne@69 723 * the interval format is "10 Feb - 10 Jan, 2007"
jpayne@69 724 */
jpayne@69 725 UBool laterDateFirst;
jpayne@69 726 };
jpayne@69 727
jpayne@69 728
jpayne@69 729 /**
jpayne@69 730 * default constructor
jpayne@69 731 * @internal (private)
jpayne@69 732 */
jpayne@69 733 DateIntervalFormat();
jpayne@69 734
jpayne@69 735 /**
jpayne@69 736 * Construct a DateIntervalFormat from DateFormat,
jpayne@69 737 * a DateIntervalInfo, and skeleton.
jpayne@69 738 * DateFormat provides the timezone, calendar,
jpayne@69 739 * full pattern, and date format symbols information.
jpayne@69 740 * It should be a SimpleDateFormat object which
jpayne@69 741 * has a pattern in it.
jpayne@69 742 * the DateIntervalInfo provides the interval patterns.
jpayne@69 743 *
jpayne@69 744 * Note: the DateIntervalFormat takes ownership of both
jpayne@69 745 * DateFormat and DateIntervalInfo objects.
jpayne@69 746 * Caller should not delete them.
jpayne@69 747 *
jpayne@69 748 * @param locale the locale of this date interval formatter.
jpayne@69 749 * @param dtItvInfo the DateIntervalInfo object to be adopted.
jpayne@69 750 * @param skeleton the skeleton of the date formatter
jpayne@69 751 * @param status output param set to success/failure code on exit
jpayne@69 752 */
jpayne@69 753 DateIntervalFormat(const Locale& locale, DateIntervalInfo* dtItvInfo,
jpayne@69 754 const UnicodeString* skeleton, UErrorCode& status);
jpayne@69 755
jpayne@69 756
jpayne@69 757 /**
jpayne@69 758 * Construct a DateIntervalFormat from DateFormat
jpayne@69 759 * and a DateIntervalInfo.
jpayne@69 760 *
jpayne@69 761 * It is a wrapper of the constructor.
jpayne@69 762 *
jpayne@69 763 * @param locale the locale of this date interval formatter.
jpayne@69 764 * @param dtitvinf the DateIntervalInfo object to be adopted.
jpayne@69 765 * @param skeleton the skeleton of this formatter.
jpayne@69 766 * @param status Output param set to success/failure code.
jpayne@69 767 * @return a date time interval formatter which the caller owns.
jpayne@69 768 */
jpayne@69 769 static DateIntervalFormat* U_EXPORT2 create(const Locale& locale,
jpayne@69 770 DateIntervalInfo* dtitvinf,
jpayne@69 771 const UnicodeString* skeleton,
jpayne@69 772 UErrorCode& status);
jpayne@69 773
jpayne@69 774 /**
jpayne@69 775 * Below are for generating interval patterns local to the formatter
jpayne@69 776 */
jpayne@69 777
jpayne@69 778 /** Like fallbackFormat, but only formats the range part of the fallback. */
jpayne@69 779 void fallbackFormatRange(
jpayne@69 780 Calendar& fromCalendar,
jpayne@69 781 Calendar& toCalendar,
jpayne@69 782 UnicodeString& appendTo,
jpayne@69 783 int8_t& firstIndex,
jpayne@69 784 FieldPositionHandler& fphandler,
jpayne@69 785 UErrorCode& status) const;
jpayne@69 786
jpayne@69 787 /**
jpayne@69 788 * Format 2 Calendars using fall-back interval pattern
jpayne@69 789 *
jpayne@69 790 * The full pattern used in this fall-back format is the
jpayne@69 791 * full pattern of the date formatter.
jpayne@69 792 *
jpayne@69 793 * gFormatterMutex must already be locked when calling this function.
jpayne@69 794 *
jpayne@69 795 * @param fromCalendar calendar set to the from date in date interval
jpayne@69 796 * to be formatted into date interval string
jpayne@69 797 * @param toCalendar calendar set to the to date in date interval
jpayne@69 798 * to be formatted into date interval string
jpayne@69 799 * @param fromToOnSameDay TRUE iff from and to dates are on the same day
jpayne@69 800 * (any difference is in ampm/hours or below)
jpayne@69 801 * @param appendTo Output parameter to receive result.
jpayne@69 802 * Result is appended to existing contents.
jpayne@69 803 * @param firstIndex See formatImpl for more information.
jpayne@69 804 * @param fphandler See formatImpl for more information.
jpayne@69 805 * @param status output param set to success/failure code on exit
jpayne@69 806 * @return Reference to 'appendTo' parameter.
jpayne@69 807 * @internal (private)
jpayne@69 808 */
jpayne@69 809 UnicodeString& fallbackFormat(Calendar& fromCalendar,
jpayne@69 810 Calendar& toCalendar,
jpayne@69 811 UBool fromToOnSameDay,
jpayne@69 812 UnicodeString& appendTo,
jpayne@69 813 int8_t& firstIndex,
jpayne@69 814 FieldPositionHandler& fphandler,
jpayne@69 815 UErrorCode& status) const;
jpayne@69 816
jpayne@69 817
jpayne@69 818
jpayne@69 819 /**
jpayne@69 820 * Initialize interval patterns locale to this formatter
jpayne@69 821 *
jpayne@69 822 * This code is a bit complicated since
jpayne@69 823 * 1. the interval patterns saved in resource bundle files are interval
jpayne@69 824 * patterns based on date or time only.
jpayne@69 825 * It does not have interval patterns based on both date and time.
jpayne@69 826 * Interval patterns on both date and time are algorithm generated.
jpayne@69 827 *
jpayne@69 828 * For example, it has interval patterns on skeleton "dMy" and "hm",
jpayne@69 829 * but it does not have interval patterns on skeleton "dMyhm".
jpayne@69 830 *
jpayne@69 831 * The rule to generate interval patterns for both date and time skeleton are
jpayne@69 832 * 1) when the year, month, or day differs, concatenate the two original
jpayne@69 833 * expressions with a separator between,
jpayne@69 834 * For example, interval pattern from "Jan 10, 2007 10:10 am"
jpayne@69 835 * to "Jan 11, 2007 10:10am" is
jpayne@69 836 * "Jan 10, 2007 10:10 am - Jan 11, 2007 10:10am"
jpayne@69 837 *
jpayne@69 838 * 2) otherwise, present the date followed by the range expression
jpayne@69 839 * for the time.
jpayne@69 840 * For example, interval pattern from "Jan 10, 2007 10:10 am"
jpayne@69 841 * to "Jan 10, 2007 11:10am" is
jpayne@69 842 * "Jan 10, 2007 10:10 am - 11:10am"
jpayne@69 843 *
jpayne@69 844 * 2. even a pattern does not request a certain calendar field,
jpayne@69 845 * the interval pattern needs to include such field if such fields are
jpayne@69 846 * different between 2 dates.
jpayne@69 847 * For example, a pattern/skeleton is "hm", but the interval pattern
jpayne@69 848 * includes year, month, and date when year, month, and date differs.
jpayne@69 849 *
jpayne@69 850 *
jpayne@69 851 * @param status output param set to success/failure code on exit
jpayne@69 852 */
jpayne@69 853 void initializePattern(UErrorCode& status);
jpayne@69 854
jpayne@69 855
jpayne@69 856
jpayne@69 857 /**
jpayne@69 858 * Set fall back interval pattern given a calendar field,
jpayne@69 859 * a skeleton, and a date time pattern generator.
jpayne@69 860 * @param field the largest different calendar field
jpayne@69 861 * @param skeleton a skeleton
jpayne@69 862 * @param status output param set to success/failure code on exit
jpayne@69 863 */
jpayne@69 864 void setFallbackPattern(UCalendarDateFields field,
jpayne@69 865 const UnicodeString& skeleton,
jpayne@69 866 UErrorCode& status);
jpayne@69 867
jpayne@69 868
jpayne@69 869
jpayne@69 870 /**
jpayne@69 871 * get separated date and time skeleton from a combined skeleton.
jpayne@69 872 *
jpayne@69 873 * The difference between date skeleton and normalizedDateSkeleton are:
jpayne@69 874 * 1. both 'y' and 'd' are appeared only once in normalizeDateSkeleton
jpayne@69 875 * 2. 'E' and 'EE' are normalized into 'EEE'
jpayne@69 876 * 3. 'MM' is normalized into 'M'
jpayne@69 877 *
jpayne@69 878 ** the difference between time skeleton and normalizedTimeSkeleton are:
jpayne@69 879 * 1. both 'H' and 'h' are normalized as 'h' in normalized time skeleton,
jpayne@69 880 * 2. 'a' is omitted in normalized time skeleton.
jpayne@69 881 * 3. there is only one appearance for 'h', 'm','v', 'z' in normalized time
jpayne@69 882 * skeleton
jpayne@69 883 *
jpayne@69 884 *
jpayne@69 885 * @param skeleton given combined skeleton.
jpayne@69 886 * @param date Output parameter for date only skeleton.
jpayne@69 887 * @param normalizedDate Output parameter for normalized date only
jpayne@69 888 *
jpayne@69 889 * @param time Output parameter for time only skeleton.
jpayne@69 890 * @param normalizedTime Output parameter for normalized time only
jpayne@69 891 * skeleton.
jpayne@69 892 *
jpayne@69 893 */
jpayne@69 894 static void U_EXPORT2 getDateTimeSkeleton(const UnicodeString& skeleton,
jpayne@69 895 UnicodeString& date,
jpayne@69 896 UnicodeString& normalizedDate,
jpayne@69 897 UnicodeString& time,
jpayne@69 898 UnicodeString& normalizedTime);
jpayne@69 899
jpayne@69 900
jpayne@69 901
jpayne@69 902 /**
jpayne@69 903 * Generate date or time interval pattern from resource,
jpayne@69 904 * and set them into the interval pattern locale to this formatter.
jpayne@69 905 *
jpayne@69 906 * It needs to handle the following:
jpayne@69 907 * 1. need to adjust field width.
jpayne@69 908 * For example, the interval patterns saved in DateIntervalInfo
jpayne@69 909 * includes "dMMMy", but not "dMMMMy".
jpayne@69 910 * Need to get interval patterns for dMMMMy from dMMMy.
jpayne@69 911 * Another example, the interval patterns saved in DateIntervalInfo
jpayne@69 912 * includes "hmv", but not "hmz".
jpayne@69 913 * Need to get interval patterns for "hmz' from 'hmv'
jpayne@69 914 *
jpayne@69 915 * 2. there might be no pattern for 'y' differ for skeleton "Md",
jpayne@69 916 * in order to get interval patterns for 'y' differ,
jpayne@69 917 * need to look for it from skeleton 'yMd'
jpayne@69 918 *
jpayne@69 919 * @param dateSkeleton normalized date skeleton
jpayne@69 920 * @param timeSkeleton normalized time skeleton
jpayne@69 921 * @return whether the resource is found for the skeleton.
jpayne@69 922 * TRUE if interval pattern found for the skeleton,
jpayne@69 923 * FALSE otherwise.
jpayne@69 924 */
jpayne@69 925 UBool setSeparateDateTimePtn(const UnicodeString& dateSkeleton,
jpayne@69 926 const UnicodeString& timeSkeleton);
jpayne@69 927
jpayne@69 928
jpayne@69 929
jpayne@69 930
jpayne@69 931 /**
jpayne@69 932 * Generate interval pattern from existing resource
jpayne@69 933 *
jpayne@69 934 * It not only save the interval patterns,
jpayne@69 935 * but also return the extended skeleton and its best match skeleton.
jpayne@69 936 *
jpayne@69 937 * @param field largest different calendar field
jpayne@69 938 * @param skeleton skeleton
jpayne@69 939 * @param bestSkeleton the best match skeleton which has interval pattern
jpayne@69 940 * defined in resource
jpayne@69 941 * @param differenceInfo the difference between skeleton and best skeleton
jpayne@69 942 * 0 means the best matched skeleton is the same as input skeleton
jpayne@69 943 * 1 means the fields are the same, but field width are different
jpayne@69 944 * 2 means the only difference between fields are v/z,
jpayne@69 945 * -1 means there are other fields difference
jpayne@69 946 *
jpayne@69 947 * @param extendedSkeleton extended skeleton
jpayne@69 948 * @param extendedBestSkeleton extended best match skeleton
jpayne@69 949 * @return whether the interval pattern is found
jpayne@69 950 * through extending skeleton or not.
jpayne@69 951 * TRUE if interval pattern is found by
jpayne@69 952 * extending skeleton, FALSE otherwise.
jpayne@69 953 */
jpayne@69 954 UBool setIntervalPattern(UCalendarDateFields field,
jpayne@69 955 const UnicodeString* skeleton,
jpayne@69 956 const UnicodeString* bestSkeleton,
jpayne@69 957 int8_t differenceInfo,
jpayne@69 958 UnicodeString* extendedSkeleton = NULL,
jpayne@69 959 UnicodeString* extendedBestSkeleton = NULL);
jpayne@69 960
jpayne@69 961 /**
jpayne@69 962 * Adjust field width in best match interval pattern to match
jpayne@69 963 * the field width in input skeleton.
jpayne@69 964 *
jpayne@69 965 * TODO (xji) make a general solution
jpayne@69 966 * The adjusting rule can be:
jpayne@69 967 * 1. always adjust
jpayne@69 968 * 2. never adjust
jpayne@69 969 * 3. default adjust, which means adjust according to the following rules
jpayne@69 970 * 3.1 always adjust string, such as MMM and MMMM
jpayne@69 971 * 3.2 never adjust between string and numeric, such as MM and MMM
jpayne@69 972 * 3.3 always adjust year
jpayne@69 973 * 3.4 do not adjust 'd', 'h', or 'm' if h presents
jpayne@69 974 * 3.5 do not adjust 'M' if it is numeric(?)
jpayne@69 975 *
jpayne@69 976 * Since date interval format is well-formed format,
jpayne@69 977 * date and time skeletons are normalized previously,
jpayne@69 978 * till this stage, the adjust here is only "adjust strings, such as MMM
jpayne@69 979 * and MMMM, EEE and EEEE.
jpayne@69 980 *
jpayne@69 981 * @param inputSkeleton the input skeleton
jpayne@69 982 * @param bestMatchSkeleton the best match skeleton
jpayne@69 983 * @param bestMatchIntervalPattern the best match interval pattern
jpayne@69 984 * @param differenceInfo the difference between 2 skeletons
jpayne@69 985 * 1 means only field width differs
jpayne@69 986 * 2 means v/z exchange
jpayne@69 987 * @param adjustedIntervalPattern adjusted interval pattern
jpayne@69 988 */
jpayne@69 989 static void U_EXPORT2 adjustFieldWidth(
jpayne@69 990 const UnicodeString& inputSkeleton,
jpayne@69 991 const UnicodeString& bestMatchSkeleton,
jpayne@69 992 const UnicodeString& bestMatchIntervalPattern,
jpayne@69 993 int8_t differenceInfo,
jpayne@69 994 UnicodeString& adjustedIntervalPattern);
jpayne@69 995
jpayne@69 996 /**
jpayne@69 997 * Concat a single date pattern with a time interval pattern,
jpayne@69 998 * set it into the intervalPatterns, while field is time field.
jpayne@69 999 * This is used to handle time interval patterns on skeleton with
jpayne@69 1000 * both time and date. Present the date followed by
jpayne@69 1001 * the range expression for the time.
jpayne@69 1002 * @param format date and time format
jpayne@69 1003 * @param datePattern date pattern
jpayne@69 1004 * @param field time calendar field: AM_PM, HOUR, MINUTE
jpayne@69 1005 * @param status output param set to success/failure code on exit
jpayne@69 1006 */
jpayne@69 1007 void concatSingleDate2TimeInterval(UnicodeString& format,
jpayne@69 1008 const UnicodeString& datePattern,
jpayne@69 1009 UCalendarDateFields field,
jpayne@69 1010 UErrorCode& status);
jpayne@69 1011
jpayne@69 1012 /**
jpayne@69 1013 * check whether a calendar field present in a skeleton.
jpayne@69 1014 * @param field calendar field need to check
jpayne@69 1015 * @param skeleton given skeleton on which to check the calendar field
jpayne@69 1016 * @return true if field present in a skeleton.
jpayne@69 1017 */
jpayne@69 1018 static UBool U_EXPORT2 fieldExistsInSkeleton(UCalendarDateFields field,
jpayne@69 1019 const UnicodeString& skeleton);
jpayne@69 1020
jpayne@69 1021
jpayne@69 1022 /**
jpayne@69 1023 * Split interval patterns into 2 part.
jpayne@69 1024 * @param intervalPattern interval pattern
jpayne@69 1025 * @return the index in interval pattern which split the pattern into 2 part
jpayne@69 1026 */
jpayne@69 1027 static int32_t U_EXPORT2 splitPatternInto2Part(const UnicodeString& intervalPattern);
jpayne@69 1028
jpayne@69 1029
jpayne@69 1030 /**
jpayne@69 1031 * Break interval patterns as 2 part and save them into pattern info.
jpayne@69 1032 * @param field calendar field
jpayne@69 1033 * @param intervalPattern interval pattern
jpayne@69 1034 */
jpayne@69 1035 void setIntervalPattern(UCalendarDateFields field,
jpayne@69 1036 const UnicodeString& intervalPattern);
jpayne@69 1037
jpayne@69 1038
jpayne@69 1039 /**
jpayne@69 1040 * Break interval patterns as 2 part and save them into pattern info.
jpayne@69 1041 * @param field calendar field
jpayne@69 1042 * @param intervalPattern interval pattern
jpayne@69 1043 * @param laterDateFirst whether later date appear first in interval pattern
jpayne@69 1044 */
jpayne@69 1045 void setIntervalPattern(UCalendarDateFields field,
jpayne@69 1046 const UnicodeString& intervalPattern,
jpayne@69 1047 UBool laterDateFirst);
jpayne@69 1048
jpayne@69 1049
jpayne@69 1050 /**
jpayne@69 1051 * Set pattern information.
jpayne@69 1052 *
jpayne@69 1053 * @param field calendar field
jpayne@69 1054 * @param firstPart the first part in interval pattern
jpayne@69 1055 * @param secondPart the second part in interval pattern
jpayne@69 1056 * @param laterDateFirst whether the first date in intervalPattern
jpayne@69 1057 * is earlier date or later date
jpayne@69 1058 */
jpayne@69 1059 void setPatternInfo(UCalendarDateFields field,
jpayne@69 1060 const UnicodeString* firstPart,
jpayne@69 1061 const UnicodeString* secondPart,
jpayne@69 1062 UBool laterDateFirst);
jpayne@69 1063
jpayne@69 1064 /**
jpayne@69 1065 * Format 2 Calendars to produce a string.
jpayne@69 1066 * Implementation of the similar public format function.
jpayne@69 1067 * Must be called with gFormatterMutex already locked.
jpayne@69 1068 *
jpayne@69 1069 * Note: "fromCalendar" and "toCalendar" are not const,
jpayne@69 1070 * since calendar is not const in SimpleDateFormat::format(Calendar&),
jpayne@69 1071 *
jpayne@69 1072 * @param fromCalendar calendar set to the from date in date interval
jpayne@69 1073 * to be formatted into date interval string
jpayne@69 1074 * @param toCalendar calendar set to the to date in date interval
jpayne@69 1075 * to be formatted into date interval string
jpayne@69 1076 * @param appendTo Output parameter to receive result.
jpayne@69 1077 * Result is appended to existing contents.
jpayne@69 1078 * @param firstIndex 0 if the first output date is fromCalendar;
jpayne@69 1079 * 1 if it corresponds to toCalendar;
jpayne@69 1080 * -1 if there is only one date printed.
jpayne@69 1081 * @param fphandler Handler for field position information.
jpayne@69 1082 * The fields will be from the UDateFormatField enum.
jpayne@69 1083 * @param status Output param filled with success/failure status.
jpayne@69 1084 * Caller needs to make sure it is SUCCESS
jpayne@69 1085 * at the function entrance
jpayne@69 1086 * @return Reference to 'appendTo' parameter.
jpayne@69 1087 * @internal (private)
jpayne@69 1088 */
jpayne@69 1089 UnicodeString& formatImpl(Calendar& fromCalendar,
jpayne@69 1090 Calendar& toCalendar,
jpayne@69 1091 UnicodeString& appendTo,
jpayne@69 1092 int8_t& firstIndex,
jpayne@69 1093 FieldPositionHandler& fphandler,
jpayne@69 1094 UErrorCode& status) const ;
jpayne@69 1095
jpayne@69 1096 /** Version of formatImpl for DateInterval. */
jpayne@69 1097 UnicodeString& formatIntervalImpl(const DateInterval& dtInterval,
jpayne@69 1098 UnicodeString& appendTo,
jpayne@69 1099 int8_t& firstIndex,
jpayne@69 1100 FieldPositionHandler& fphandler,
jpayne@69 1101 UErrorCode& status) const;
jpayne@69 1102
jpayne@69 1103
jpayne@69 1104 // from calendar field to pattern letter
jpayne@69 1105 static const char16_t fgCalendarFieldToPatternLetter[];
jpayne@69 1106
jpayne@69 1107
jpayne@69 1108 /**
jpayne@69 1109 * The interval patterns for this locale.
jpayne@69 1110 */
jpayne@69 1111 DateIntervalInfo* fInfo;
jpayne@69 1112
jpayne@69 1113 /**
jpayne@69 1114 * The DateFormat object used to format single pattern
jpayne@69 1115 */
jpayne@69 1116 SimpleDateFormat* fDateFormat;
jpayne@69 1117
jpayne@69 1118 /**
jpayne@69 1119 * The 2 calendars with the from and to date.
jpayne@69 1120 * could re-use the calendar in fDateFormat,
jpayne@69 1121 * but keeping 2 calendars make it clear and clean.
jpayne@69 1122 */
jpayne@69 1123 Calendar* fFromCalendar;
jpayne@69 1124 Calendar* fToCalendar;
jpayne@69 1125
jpayne@69 1126 Locale fLocale;
jpayne@69 1127
jpayne@69 1128 /**
jpayne@69 1129 * Following are interval information relevant (locale) to this formatter.
jpayne@69 1130 */
jpayne@69 1131 UnicodeString fSkeleton;
jpayne@69 1132 PatternInfo fIntervalPatterns[DateIntervalInfo::kIPI_MAX_INDEX];
jpayne@69 1133
jpayne@69 1134 /**
jpayne@69 1135 * Patterns for fallback formatting.
jpayne@69 1136 */
jpayne@69 1137 UnicodeString* fDatePattern;
jpayne@69 1138 UnicodeString* fTimePattern;
jpayne@69 1139 UnicodeString* fDateTimeFormat;
jpayne@69 1140 };
jpayne@69 1141
jpayne@69 1142 inline UBool
jpayne@69 1143 DateIntervalFormat::operator!=(const Format& other) const {
jpayne@69 1144 return !operator==(other);
jpayne@69 1145 }
jpayne@69 1146
jpayne@69 1147 U_NAMESPACE_END
jpayne@69 1148
jpayne@69 1149 #endif /* #if !UCONFIG_NO_FORMATTING */
jpayne@69 1150
jpayne@69 1151 #endif /* U_SHOW_CPLUSPLUS_API */
jpayne@69 1152
jpayne@69 1153 #endif // _DTITVFMT_H__
jpayne@69 1154 //eof