1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/i18n/unicode/datefmt.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,820 @@
1.4 +/*
1.5 + ********************************************************************************
1.6 + * Copyright (C) 1997-2013, International Business Machines
1.7 + * Corporation and others. All Rights Reserved.
1.8 + ********************************************************************************
1.9 + *
1.10 + * File DATEFMT.H
1.11 + *
1.12 + * Modification History:
1.13 + *
1.14 + * Date Name Description
1.15 + * 02/19/97 aliu Converted from java.
1.16 + * 04/01/97 aliu Added support for centuries.
1.17 + * 07/23/98 stephen JDK 1.2 sync
1.18 + * 11/15/99 weiv Added support for week of year/day of week formatting
1.19 + ********************************************************************************
1.20 + */
1.21 +
1.22 +#ifndef DATEFMT_H
1.23 +#define DATEFMT_H
1.24 +
1.25 +#include "unicode/utypes.h"
1.26 +
1.27 +#if !UCONFIG_NO_FORMATTING
1.28 +
1.29 +#include "unicode/udat.h"
1.30 +#include "unicode/calendar.h"
1.31 +#include "unicode/numfmt.h"
1.32 +#include "unicode/format.h"
1.33 +#include "unicode/locid.h"
1.34 +#include "unicode/enumset.h"
1.35 +
1.36 +/**
1.37 + * \file
1.38 + * \brief C++ API: Abstract class for converting dates.
1.39 + */
1.40 +
1.41 +U_NAMESPACE_BEGIN
1.42 +
1.43 +class TimeZone;
1.44 +class DateTimePatternGenerator;
1.45 +
1.46 +// explicit template instantiation. see digitlst.h
1.47 +#if defined (_MSC_VER)
1.48 +template class U_I18N_API EnumSet<UDateFormatBooleanAttribute,
1.49 + 0,
1.50 + UDAT_BOOLEAN_ATTRIBUTE_COUNT>;
1.51 +#endif
1.52 +
1.53 +/**
1.54 + * DateFormat is an abstract class for a family of classes that convert dates and
1.55 + * times from their internal representations to textual form and back again in a
1.56 + * language-independent manner. Converting from the internal representation (milliseconds
1.57 + * since midnight, January 1, 1970) to text is known as "formatting," and converting
1.58 + * from text to millis is known as "parsing." We currently define only one concrete
1.59 + * subclass of DateFormat: SimpleDateFormat, which can handle pretty much all normal
1.60 + * date formatting and parsing actions.
1.61 + * <P>
1.62 + * DateFormat helps you to format and parse dates for any locale. Your code can
1.63 + * be completely independent of the locale conventions for months, days of the
1.64 + * week, or even the calendar format: lunar vs. solar.
1.65 + * <P>
1.66 + * To format a date for the current Locale, use one of the static factory
1.67 + * methods:
1.68 + * <pre>
1.69 + * \code
1.70 + * DateFormat* dfmt = DateFormat::createDateInstance();
1.71 + * UDate myDate = Calendar::getNow();
1.72 + * UnicodeString myString;
1.73 + * myString = dfmt->format( myDate, myString );
1.74 + * \endcode
1.75 + * </pre>
1.76 + * If you are formatting multiple numbers, it is more efficient to get the
1.77 + * format and use it multiple times so that the system doesn't have to fetch the
1.78 + * information about the local language and country conventions multiple times.
1.79 + * <pre>
1.80 + * \code
1.81 + * DateFormat* df = DateFormat::createDateInstance();
1.82 + * UnicodeString myString;
1.83 + * UDate myDateArr[] = { 0.0, 100000000.0, 2000000000.0 }; // test values
1.84 + * for (int32_t i = 0; i < 3; ++i) {
1.85 + * myString.remove();
1.86 + * cout << df->format( myDateArr[i], myString ) << endl;
1.87 + * }
1.88 + * \endcode
1.89 + * </pre>
1.90 + * To get specific fields of a date, you can use UFieldPosition to
1.91 + * get specific fields.
1.92 + * <pre>
1.93 + * \code
1.94 + * DateFormat* dfmt = DateFormat::createDateInstance();
1.95 + * FieldPosition pos(DateFormat::YEAR_FIELD);
1.96 + * UnicodeString myString;
1.97 + * myString = dfmt->format( myDate, myString );
1.98 + * cout << myString << endl;
1.99 + * cout << pos.getBeginIndex() << "," << pos. getEndIndex() << endl;
1.100 + * \endcode
1.101 + * </pre>
1.102 + * To format a date for a different Locale, specify it in the call to
1.103 + * createDateInstance().
1.104 + * <pre>
1.105 + * \code
1.106 + * DateFormat* df =
1.107 + * DateFormat::createDateInstance( DateFormat::SHORT, Locale::getFrance());
1.108 + * \endcode
1.109 + * </pre>
1.110 + * You can use a DateFormat to parse also.
1.111 + * <pre>
1.112 + * \code
1.113 + * UErrorCode status = U_ZERO_ERROR;
1.114 + * UDate myDate = df->parse(myString, status);
1.115 + * \endcode
1.116 + * </pre>
1.117 + * Use createDateInstance() to produce the normal date format for that country.
1.118 + * There are other static factory methods available. Use createTimeInstance()
1.119 + * to produce the normal time format for that country. Use createDateTimeInstance()
1.120 + * to produce a DateFormat that formats both date and time. You can pass in
1.121 + * different options to these factory methods to control the length of the
1.122 + * result; from SHORT to MEDIUM to LONG to FULL. The exact result depends on the
1.123 + * locale, but generally:
1.124 + * <ul type=round>
1.125 + * <li> SHORT is completely numeric, such as 12/13/52 or 3:30pm
1.126 + * <li> MEDIUM is longer, such as Jan 12, 1952
1.127 + * <li> LONG is longer, such as January 12, 1952 or 3:30:32pm
1.128 + * <li> FULL is pretty completely specified, such as
1.129 + * Tuesday, April 12, 1952 AD or 3:30:42pm PST.
1.130 + * </ul>
1.131 + * You can also set the time zone on the format if you wish. If you want even
1.132 + * more control over the format or parsing, (or want to give your users more
1.133 + * control), you can try casting the DateFormat you get from the factory methods
1.134 + * to a SimpleDateFormat. This will work for the majority of countries; just
1.135 + * remember to chck getDynamicClassID() before carrying out the cast.
1.136 + * <P>
1.137 + * You can also use forms of the parse and format methods with ParsePosition and
1.138 + * FieldPosition to allow you to
1.139 + * <ul type=round>
1.140 + * <li> Progressively parse through pieces of a string.
1.141 + * <li> Align any particular field, or find out where it is for selection
1.142 + * on the screen.
1.143 + * </ul>
1.144 + *
1.145 + * <p><em>User subclasses are not supported.</em> While clients may write
1.146 + * subclasses, such code will not necessarily work and will not be
1.147 + * guaranteed to work stably from release to release.
1.148 + */
1.149 +class U_I18N_API DateFormat : public Format {
1.150 +public:
1.151 +
1.152 + /**
1.153 + * Constants for various style patterns. These reflect the order of items in
1.154 + * the DateTimePatterns resource. There are 4 time patterns, 4 date patterns,
1.155 + * the default date-time pattern, and 4 date-time patterns. Each block of 4 values
1.156 + * in the resource occurs in the order full, long, medium, short.
1.157 + * @stable ICU 2.4
1.158 + */
1.159 + enum EStyle
1.160 + {
1.161 + kNone = -1,
1.162 +
1.163 + kFull = 0,
1.164 + kLong = 1,
1.165 + kMedium = 2,
1.166 + kShort = 3,
1.167 +
1.168 + kDateOffset = kShort + 1,
1.169 + // kFull + kDateOffset = 4
1.170 + // kLong + kDateOffset = 5
1.171 + // kMedium + kDateOffset = 6
1.172 + // kShort + kDateOffset = 7
1.173 +
1.174 + kDateTime = 8,
1.175 + // Default DateTime
1.176 +
1.177 + kDateTimeOffset = kDateTime + 1,
1.178 + // kFull + kDateTimeOffset = 9
1.179 + // kLong + kDateTimeOffset = 10
1.180 + // kMedium + kDateTimeOffset = 11
1.181 + // kShort + kDateTimeOffset = 12
1.182 +
1.183 + // relative dates
1.184 + kRelative = (1 << 7),
1.185 +
1.186 + kFullRelative = (kFull | kRelative),
1.187 +
1.188 + kLongRelative = kLong | kRelative,
1.189 +
1.190 + kMediumRelative = kMedium | kRelative,
1.191 +
1.192 + kShortRelative = kShort | kRelative,
1.193 +
1.194 +
1.195 + kDefault = kMedium,
1.196 +
1.197 +
1.198 +
1.199 + /**
1.200 + * These constants are provided for backwards compatibility only.
1.201 + * Please use the C++ style constants defined above.
1.202 + */
1.203 + FULL = kFull,
1.204 + LONG = kLong,
1.205 + MEDIUM = kMedium,
1.206 + SHORT = kShort,
1.207 + DEFAULT = kDefault,
1.208 + DATE_OFFSET = kDateOffset,
1.209 + NONE = kNone,
1.210 + DATE_TIME = kDateTime
1.211 + };
1.212 +
1.213 + /**
1.214 + * Destructor.
1.215 + * @stable ICU 2.0
1.216 + */
1.217 + virtual ~DateFormat();
1.218 +
1.219 + /**
1.220 + * Equality operator. Returns true if the two formats have the same behavior.
1.221 + * @stable ICU 2.0
1.222 + */
1.223 + virtual UBool operator==(const Format&) const;
1.224 +
1.225 +
1.226 + using Format::format;
1.227 +
1.228 + /**
1.229 + * Format an object to produce a string. This method handles Formattable
1.230 + * objects with a UDate type. If a the Formattable object type is not a Date,
1.231 + * then it returns a failing UErrorCode.
1.232 + *
1.233 + * @param obj The object to format. Must be a Date.
1.234 + * @param appendTo Output parameter to receive result.
1.235 + * Result is appended to existing contents.
1.236 + * @param pos On input: an alignment field, if desired.
1.237 + * On output: the offsets of the alignment field.
1.238 + * @param status Output param filled with success/failure status.
1.239 + * @return Reference to 'appendTo' parameter.
1.240 + * @stable ICU 2.0
1.241 + */
1.242 + virtual UnicodeString& format(const Formattable& obj,
1.243 + UnicodeString& appendTo,
1.244 + FieldPosition& pos,
1.245 + UErrorCode& status) const;
1.246 +
1.247 + /**
1.248 + * Format an object to produce a string. This method handles Formattable
1.249 + * objects with a UDate type. If a the Formattable object type is not a Date,
1.250 + * then it returns a failing UErrorCode.
1.251 + *
1.252 + * @param obj The object to format. Must be a Date.
1.253 + * @param appendTo Output parameter to receive result.
1.254 + * Result is appended to existing contents.
1.255 + * @param posIter On return, can be used to iterate over positions
1.256 + * of fields generated by this format call. Field values
1.257 + * are defined in UDateFormatField. Can be NULL.
1.258 + * @param status Output param filled with success/failure status.
1.259 + * @return Reference to 'appendTo' parameter.
1.260 + * @stable ICU 4.4
1.261 + */
1.262 + virtual UnicodeString& format(const Formattable& obj,
1.263 + UnicodeString& appendTo,
1.264 + FieldPositionIterator* posIter,
1.265 + UErrorCode& status) const;
1.266 + /**
1.267 + * Formats a date into a date/time string. This is an abstract method which
1.268 + * concrete subclasses must implement.
1.269 + * <P>
1.270 + * On input, the FieldPosition parameter may have its "field" member filled with
1.271 + * an enum value specifying a field. On output, the FieldPosition will be filled
1.272 + * in with the text offsets for that field.
1.273 + * <P> For example, given a time text
1.274 + * "1996.07.10 AD at 15:08:56 PDT", if the given fieldPosition.field is
1.275 + * UDAT_YEAR_FIELD, the offsets fieldPosition.beginIndex and
1.276 + * statfieldPositionus.getEndIndex will be set to 0 and 4, respectively.
1.277 + * <P> Notice
1.278 + * that if the same time field appears more than once in a pattern, the status will
1.279 + * be set for the first occurence of that time field. For instance,
1.280 + * formatting a UDate to the time string "1 PM PDT (Pacific Daylight Time)"
1.281 + * using the pattern "h a z (zzzz)" and the alignment field
1.282 + * DateFormat::TIMEZONE_FIELD, the offsets fieldPosition.beginIndex and
1.283 + * fieldPosition.getEndIndex will be set to 5 and 8, respectively, for the first
1.284 + * occurence of the timezone pattern character 'z'.
1.285 + *
1.286 + * @param cal Calendar set to the date and time to be formatted
1.287 + * into a date/time string. When the calendar type is
1.288 + * different from the internal calendar held by this
1.289 + * DateFormat instance, the date and the time zone will
1.290 + * be inherited from the input calendar, but other calendar
1.291 + * field values will be calculated by the internal calendar.
1.292 + * @param appendTo Output parameter to receive result.
1.293 + * Result is appended to existing contents.
1.294 + * @param fieldPosition On input: an alignment field, if desired (see examples above)
1.295 + * On output: the offsets of the alignment field (see examples above)
1.296 + * @return Reference to 'appendTo' parameter.
1.297 + * @stable ICU 2.1
1.298 + */
1.299 + virtual UnicodeString& format( Calendar& cal,
1.300 + UnicodeString& appendTo,
1.301 + FieldPosition& fieldPosition) const = 0;
1.302 +
1.303 + /**
1.304 + * Formats a date into a date/time string. Subclasses should implement this method.
1.305 + *
1.306 + * @param cal Calendar set to the date and time to be formatted
1.307 + * into a date/time string. When the calendar type is
1.308 + * different from the internal calendar held by this
1.309 + * DateFormat instance, the date and the time zone will
1.310 + * be inherited from the input calendar, but other calendar
1.311 + * field values will be calculated by the internal calendar.
1.312 + * @param appendTo Output parameter to receive result.
1.313 + * Result is appended to existing contents.
1.314 + * @param posIter On return, can be used to iterate over positions
1.315 + * of fields generated by this format call. Field values
1.316 + * are defined in UDateFormatField. Can be NULL.
1.317 + * @param status error status.
1.318 + * @return Reference to 'appendTo' parameter.
1.319 + * @stable ICU 4.4
1.320 + */
1.321 + virtual UnicodeString& format(Calendar& cal,
1.322 + UnicodeString& appendTo,
1.323 + FieldPositionIterator* posIter,
1.324 + UErrorCode& status) const;
1.325 + /**
1.326 + * Formats a UDate into a date/time string.
1.327 + * <P>
1.328 + * On input, the FieldPosition parameter may have its "field" member filled with
1.329 + * an enum value specifying a field. On output, the FieldPosition will be filled
1.330 + * in with the text offsets for that field.
1.331 + * <P> For example, given a time text
1.332 + * "1996.07.10 AD at 15:08:56 PDT", if the given fieldPosition.field is
1.333 + * UDAT_YEAR_FIELD, the offsets fieldPosition.beginIndex and
1.334 + * statfieldPositionus.getEndIndex will be set to 0 and 4, respectively.
1.335 + * <P> Notice
1.336 + * that if the same time field appears more than once in a pattern, the status will
1.337 + * be set for the first occurence of that time field. For instance,
1.338 + * formatting a UDate to the time string "1 PM PDT (Pacific Daylight Time)"
1.339 + * using the pattern "h a z (zzzz)" and the alignment field
1.340 + * DateFormat::TIMEZONE_FIELD, the offsets fieldPosition.beginIndex and
1.341 + * fieldPosition.getEndIndex will be set to 5 and 8, respectively, for the first
1.342 + * occurence of the timezone pattern character 'z'.
1.343 + *
1.344 + * @param date UDate to be formatted into a date/time string.
1.345 + * @param appendTo Output parameter to receive result.
1.346 + * Result is appended to existing contents.
1.347 + * @param fieldPosition On input: an alignment field, if desired (see examples above)
1.348 + * On output: the offsets of the alignment field (see examples above)
1.349 + * @return Reference to 'appendTo' parameter.
1.350 + * @stable ICU 2.0
1.351 + */
1.352 + UnicodeString& format( UDate date,
1.353 + UnicodeString& appendTo,
1.354 + FieldPosition& fieldPosition) const;
1.355 +
1.356 + /**
1.357 + * Formats a UDate into a date/time string.
1.358 + *
1.359 + * @param date UDate to be formatted into a date/time string.
1.360 + * @param appendTo Output parameter to receive result.
1.361 + * Result is appended to existing contents.
1.362 + * @param posIter On return, can be used to iterate over positions
1.363 + * of fields generated by this format call. Field values
1.364 + * are defined in UDateFormatField. Can be NULL.
1.365 + * @param status error status.
1.366 + * @return Reference to 'appendTo' parameter.
1.367 + * @stable ICU 4.4
1.368 + */
1.369 + UnicodeString& format(UDate date,
1.370 + UnicodeString& appendTo,
1.371 + FieldPositionIterator* posIter,
1.372 + UErrorCode& status) const;
1.373 + /**
1.374 + * Formats a UDate into a date/time string. If there is a problem, you won't
1.375 + * know, using this method. Use the overloaded format() method which takes a
1.376 + * FieldPosition& to detect formatting problems.
1.377 + *
1.378 + * @param date The UDate value to be formatted into a string.
1.379 + * @param appendTo Output parameter to receive result.
1.380 + * Result is appended to existing contents.
1.381 + * @return Reference to 'appendTo' parameter.
1.382 + * @stable ICU 2.0
1.383 + */
1.384 + UnicodeString& format(UDate date, UnicodeString& appendTo) const;
1.385 +
1.386 + /**
1.387 + * Parse a date/time string. For example, a time text "07/10/96 4:5 PM, PDT"
1.388 + * will be parsed into a UDate that is equivalent to Date(837039928046).
1.389 + * Parsing begins at the beginning of the string and proceeds as far as
1.390 + * possible. Assuming no parse errors were encountered, this function
1.391 + * doesn't return any information about how much of the string was consumed
1.392 + * by the parsing. If you need that information, use the version of
1.393 + * parse() that takes a ParsePosition.
1.394 + * <P>
1.395 + * By default, parsing is lenient: If the input is not in the form used by
1.396 + * this object's format method but can still be parsed as a date, then the
1.397 + * parse succeeds. Clients may insist on strict adherence to the format by
1.398 + * calling setLenient(false).
1.399 + * @see DateFormat::setLenient(boolean)
1.400 + * <P>
1.401 + * Note that the normal date formats associated with some calendars - such
1.402 + * as the Chinese lunar calendar - do not specify enough fields to enable
1.403 + * dates to be parsed unambiguously. In the case of the Chinese lunar
1.404 + * calendar, while the year within the current 60-year cycle is specified,
1.405 + * the number of such cycles since the start date of the calendar (in the
1.406 + * ERA field of the Calendar object) is not normally part of the format,
1.407 + * and parsing may assume the wrong era. For cases such as this it is
1.408 + * recommended that clients parse using the method
1.409 + * parse(const UnicodeString&, Calendar& cal, ParsePosition&)
1.410 + * with the Calendar passed in set to the current date, or to a date
1.411 + * within the era/cycle that should be assumed if absent in the format.
1.412 + *
1.413 + * @param text The date/time string to be parsed into a UDate value.
1.414 + * @param status Output param to be set to success/failure code. If
1.415 + * 'text' cannot be parsed, it will be set to a failure
1.416 + * code.
1.417 + * @return The parsed UDate value, if successful.
1.418 + * @stable ICU 2.0
1.419 + */
1.420 + virtual UDate parse( const UnicodeString& text,
1.421 + UErrorCode& status) const;
1.422 +
1.423 + /**
1.424 + * Parse a date/time string beginning at the given parse position. For
1.425 + * example, a time text "07/10/96 4:5 PM, PDT" will be parsed into a Date
1.426 + * that is equivalent to Date(837039928046).
1.427 + * <P>
1.428 + * By default, parsing is lenient: If the input is not in the form used by
1.429 + * this object's format method but can still be parsed as a date, then the
1.430 + * parse succeeds. Clients may insist on strict adherence to the format by
1.431 + * calling setLenient(false).
1.432 + * @see DateFormat::setLenient(boolean)
1.433 + *
1.434 + * @param text The date/time string to be parsed.
1.435 + * @param cal A Calendar set on input to the date and time to be used for
1.436 + * missing values in the date/time string being parsed, and set
1.437 + * on output to the parsed date/time. When the calendar type is
1.438 + * different from the internal calendar held by this DateFormat
1.439 + * instance, the internal calendar will be cloned to a work
1.440 + * calendar set to the same milliseconds and time zone as the
1.441 + * cal parameter, field values will be parsed based on the work
1.442 + * calendar, then the result (milliseconds and time zone) will
1.443 + * be set in this calendar.
1.444 + * @param pos On input, the position at which to start parsing; on
1.445 + * output, the position at which parsing terminated, or the
1.446 + * start position if the parse failed.
1.447 + * @stable ICU 2.1
1.448 + */
1.449 + virtual void parse( const UnicodeString& text,
1.450 + Calendar& cal,
1.451 + ParsePosition& pos) const = 0;
1.452 +
1.453 + /**
1.454 + * Parse a date/time string beginning at the given parse position. For
1.455 + * example, a time text "07/10/96 4:5 PM, PDT" will be parsed into a Date
1.456 + * that is equivalent to Date(837039928046).
1.457 + * <P>
1.458 + * By default, parsing is lenient: If the input is not in the form used by
1.459 + * this object's format method but can still be parsed as a date, then the
1.460 + * parse succeeds. Clients may insist on strict adherence to the format by
1.461 + * calling setLenient(false).
1.462 + * @see DateFormat::setLenient(boolean)
1.463 + * <P>
1.464 + * Note that the normal date formats associated with some calendars - such
1.465 + * as the Chinese lunar calendar - do not specify enough fields to enable
1.466 + * dates to be parsed unambiguously. In the case of the Chinese lunar
1.467 + * calendar, while the year within the current 60-year cycle is specified,
1.468 + * the number of such cycles since the start date of the calendar (in the
1.469 + * ERA field of the Calendar object) is not normally part of the format,
1.470 + * and parsing may assume the wrong era. For cases such as this it is
1.471 + * recommended that clients parse using the method
1.472 + * parse(const UnicodeString&, Calendar& cal, ParsePosition&)
1.473 + * with the Calendar passed in set to the current date, or to a date
1.474 + * within the era/cycle that should be assumed if absent in the format.
1.475 + *
1.476 + * @param text The date/time string to be parsed into a UDate value.
1.477 + * @param pos On input, the position at which to start parsing; on
1.478 + * output, the position at which parsing terminated, or the
1.479 + * start position if the parse failed.
1.480 + * @return A valid UDate if the input could be parsed.
1.481 + * @stable ICU 2.0
1.482 + */
1.483 + UDate parse( const UnicodeString& text,
1.484 + ParsePosition& pos) const;
1.485 +
1.486 + /**
1.487 + * Parse a string to produce an object. This methods handles parsing of
1.488 + * date/time strings into Formattable objects with UDate types.
1.489 + * <P>
1.490 + * Before calling, set parse_pos.index to the offset you want to start
1.491 + * parsing at in the source. After calling, parse_pos.index is the end of
1.492 + * the text you parsed. If error occurs, index is unchanged.
1.493 + * <P>
1.494 + * When parsing, leading whitespace is discarded (with a successful parse),
1.495 + * while trailing whitespace is left as is.
1.496 + * <P>
1.497 + * See Format::parseObject() for more.
1.498 + *
1.499 + * @param source The string to be parsed into an object.
1.500 + * @param result Formattable to be set to the parse result.
1.501 + * If parse fails, return contents are undefined.
1.502 + * @param parse_pos The position to start parsing at. Upon return
1.503 + * this param is set to the position after the
1.504 + * last character successfully parsed. If the
1.505 + * source is not parsed successfully, this param
1.506 + * will remain unchanged.
1.507 + * @stable ICU 2.0
1.508 + */
1.509 + virtual void parseObject(const UnicodeString& source,
1.510 + Formattable& result,
1.511 + ParsePosition& parse_pos) const;
1.512 +
1.513 + /**
1.514 + * Create a default date/time formatter that uses the SHORT style for both
1.515 + * the date and the time.
1.516 + *
1.517 + * @return A date/time formatter which the caller owns.
1.518 + * @stable ICU 2.0
1.519 + */
1.520 + static DateFormat* U_EXPORT2 createInstance(void);
1.521 +
1.522 + /**
1.523 + * Creates a time formatter with the given formatting style for the given
1.524 + * locale.
1.525 + *
1.526 + * @param style The given formatting style. For example,
1.527 + * SHORT for "h:mm a" in the US locale. Relative
1.528 + * time styles are not currently supported.
1.529 + * @param aLocale The given locale.
1.530 + * @return A time formatter which the caller owns.
1.531 + * @stable ICU 2.0
1.532 + */
1.533 + static DateFormat* U_EXPORT2 createTimeInstance(EStyle style = kDefault,
1.534 + const Locale& aLocale = Locale::getDefault());
1.535 +
1.536 + /**
1.537 + * Creates a date formatter with the given formatting style for the given
1.538 + * const locale.
1.539 + *
1.540 + * @param style The given formatting style. For example, SHORT for "M/d/yy" in the
1.541 + * US locale. As currently implemented, relative date formatting only
1.542 + * affects a limited range of calendar days before or after the
1.543 + * current date, based on the CLDR <field type="day">/<relative> data:
1.544 + * For example, in English, "Yesterday", "Today", and "Tomorrow".
1.545 + * Outside of this range, dates are formatted using the corresponding
1.546 + * non-relative style.
1.547 + * @param aLocale The given locale.
1.548 + * @return A date formatter which the caller owns.
1.549 + * @stable ICU 2.0
1.550 + */
1.551 + static DateFormat* U_EXPORT2 createDateInstance(EStyle style = kDefault,
1.552 + const Locale& aLocale = Locale::getDefault());
1.553 +
1.554 + /**
1.555 + * Creates a date/time formatter with the given formatting styles for the
1.556 + * given locale.
1.557 + *
1.558 + * @param dateStyle The given formatting style for the date portion of the result.
1.559 + * For example, SHORT for "M/d/yy" in the US locale. As currently
1.560 + * implemented, relative date formatting only affects a limited range
1.561 + * of calendar days before or after the current date, based on the
1.562 + * CLDR <field type="day">/<relative> data: For example, in English,
1.563 + * "Yesterday", "Today", and "Tomorrow". Outside of this range, dates
1.564 + * are formatted using the corresponding non-relative style.
1.565 + * @param timeStyle The given formatting style for the time portion of the result.
1.566 + * For example, SHORT for "h:mm a" in the US locale. Relative
1.567 + * time styles are not currently supported.
1.568 + * @param aLocale The given locale.
1.569 + * @return A date/time formatter which the caller owns.
1.570 + * @stable ICU 2.0
1.571 + */
1.572 + static DateFormat* U_EXPORT2 createDateTimeInstance(EStyle dateStyle = kDefault,
1.573 + EStyle timeStyle = kDefault,
1.574 + const Locale& aLocale = Locale::getDefault());
1.575 +
1.576 + /**
1.577 + * Gets the set of locales for which DateFormats are installed.
1.578 + * @param count Filled in with the number of locales in the list that is returned.
1.579 + * @return the set of locales for which DateFormats are installed. The caller
1.580 + * does NOT own this list and must not delete it.
1.581 + * @stable ICU 2.0
1.582 + */
1.583 + static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count);
1.584 +
1.585 + /**
1.586 + * Returns true if the encapsulated Calendar object is set for lenient parsing.
1.587 + * @stable ICU 2.0
1.588 + */
1.589 + virtual UBool isLenient(void) const;
1.590 +
1.591 + /**
1.592 + * Specify whether or not date/time parsing is to be lenient. With lenient
1.593 + * parsing, the parser may use heuristics to interpret inputs that do not
1.594 + * precisely match this object's format. With strict parsing, inputs must
1.595 + * match this object's format.
1.596 + *
1.597 + * Note: This method is specific to the encapsulated Calendar object. DateFormat
1.598 + * leniency aspects are controlled by setBooleanAttribute.
1.599 + *
1.600 + * @param lenient True specifies date/time interpretation to be lenient.
1.601 + * @see Calendar::setLenient
1.602 + * @stable ICU 2.0
1.603 + */
1.604 + virtual void setLenient(UBool lenient);
1.605 +
1.606 + /**
1.607 + * Gets the calendar associated with this date/time formatter.
1.608 + * @return the calendar associated with this date/time formatter.
1.609 + * @stable ICU 2.0
1.610 + */
1.611 + virtual const Calendar* getCalendar(void) const;
1.612 +
1.613 + /**
1.614 + * Set the calendar to be used by this date format. Initially, the default
1.615 + * calendar for the specified or default locale is used. The caller should
1.616 + * not delete the Calendar object after it is adopted by this call.
1.617 + * Adopting a new calendar will change to the default symbols.
1.618 + *
1.619 + * @param calendarToAdopt Calendar object to be adopted.
1.620 + * @stable ICU 2.0
1.621 + */
1.622 + virtual void adoptCalendar(Calendar* calendarToAdopt);
1.623 +
1.624 + /**
1.625 + * Set the calendar to be used by this date format. Initially, the default
1.626 + * calendar for the specified or default locale is used.
1.627 + *
1.628 + * @param newCalendar Calendar object to be set.
1.629 + * @stable ICU 2.0
1.630 + */
1.631 + virtual void setCalendar(const Calendar& newCalendar);
1.632 +
1.633 +
1.634 + /**
1.635 + * Gets the number formatter which this date/time formatter uses to format
1.636 + * and parse the numeric portions of the pattern.
1.637 + * @return the number formatter which this date/time formatter uses.
1.638 + * @stable ICU 2.0
1.639 + */
1.640 + virtual const NumberFormat* getNumberFormat(void) const;
1.641 +
1.642 + /**
1.643 + * Allows you to set the number formatter. The caller should
1.644 + * not delete the NumberFormat object after it is adopted by this call.
1.645 + * @param formatToAdopt NumberFormat object to be adopted.
1.646 + * @stable ICU 2.0
1.647 + */
1.648 + virtual void adoptNumberFormat(NumberFormat* formatToAdopt);
1.649 +
1.650 + /**
1.651 + * Allows you to set the number formatter.
1.652 + * @param newNumberFormat NumberFormat object to be set.
1.653 + * @stable ICU 2.0
1.654 + */
1.655 + virtual void setNumberFormat(const NumberFormat& newNumberFormat);
1.656 +
1.657 + /**
1.658 + * Returns a reference to the TimeZone used by this DateFormat's calendar.
1.659 + * @return the time zone associated with the calendar of DateFormat.
1.660 + * @stable ICU 2.0
1.661 + */
1.662 + virtual const TimeZone& getTimeZone(void) const;
1.663 +
1.664 + /**
1.665 + * Sets the time zone for the calendar of this DateFormat object. The caller
1.666 + * no longer owns the TimeZone object and should not delete it after this call.
1.667 + * @param zoneToAdopt the TimeZone to be adopted.
1.668 + * @stable ICU 2.0
1.669 + */
1.670 + virtual void adoptTimeZone(TimeZone* zoneToAdopt);
1.671 +
1.672 + /**
1.673 + * Sets the time zone for the calendar of this DateFormat object.
1.674 + * @param zone the new time zone.
1.675 + * @stable ICU 2.0
1.676 + */
1.677 + virtual void setTimeZone(const TimeZone& zone);
1.678 +
1.679 + /**
1.680 + * Set an boolean attribute on this DateFormat.
1.681 + * May return U_UNSUPPORTED_ERROR if this instance does not support
1.682 + * the specified attribute.
1.683 + * @param attr the attribute to set
1.684 + * @param newvalue new value
1.685 + * @param status the error type
1.686 + * @return *this - for chaining (example: format.setAttribute(...).setAttribute(...) )
1.687 + * @internal ICU technology preview
1.688 + */
1.689 +
1.690 + virtual DateFormat& U_EXPORT2 setBooleanAttribute(UDateFormatBooleanAttribute attr,
1.691 + UBool newvalue,
1.692 + UErrorCode &status);
1.693 +
1.694 + /**
1.695 + * Get an boolean from this DateFormat
1.696 + * May return U_UNSUPPORTED_ERROR if this instance does not support
1.697 + * the specified attribute.
1.698 + * @param attr the attribute to set
1.699 + * @param status the error type
1.700 + * @return the attribute value. Undefined if there is an error.
1.701 + * @internal ICU technology preview
1.702 + */
1.703 + virtual UBool U_EXPORT2 getBooleanAttribute(UDateFormatBooleanAttribute attr, UErrorCode &status) const;
1.704 +
1.705 +protected:
1.706 + /**
1.707 + * Default constructor. Creates a DateFormat with no Calendar or NumberFormat
1.708 + * associated with it. This constructor depends on the subclasses to fill in
1.709 + * the calendar and numberFormat fields.
1.710 + * @stable ICU 2.0
1.711 + */
1.712 + DateFormat();
1.713 +
1.714 + /**
1.715 + * Copy constructor.
1.716 + * @stable ICU 2.0
1.717 + */
1.718 + DateFormat(const DateFormat&);
1.719 +
1.720 + /**
1.721 + * Default assignment operator.
1.722 + * @stable ICU 2.0
1.723 + */
1.724 + DateFormat& operator=(const DateFormat&);
1.725 +
1.726 + /**
1.727 + * The calendar that DateFormat uses to produce the time field values needed
1.728 + * to implement date/time formatting. Subclasses should generally initialize
1.729 + * this to the default calendar for the locale associated with this DateFormat.
1.730 + * @stable ICU 2.4
1.731 + */
1.732 + Calendar* fCalendar;
1.733 +
1.734 + /**
1.735 + * The number formatter that DateFormat uses to format numbers in dates and
1.736 + * times. Subclasses should generally initialize this to the default number
1.737 + * format for the locale associated with this DateFormat.
1.738 + * @stable ICU 2.4
1.739 + */
1.740 + NumberFormat* fNumberFormat;
1.741 +
1.742 +
1.743 +private:
1.744 + /**
1.745 + * Gets the date/time formatter with the given formatting styles for the
1.746 + * given locale.
1.747 + * @param dateStyle the given date formatting style.
1.748 + * @param timeStyle the given time formatting style.
1.749 + * @param inLocale the given locale.
1.750 + * @return a date/time formatter, or 0 on failure.
1.751 + */
1.752 + static DateFormat* U_EXPORT2 create(EStyle timeStyle, EStyle dateStyle, const Locale& inLocale);
1.753 +
1.754 +
1.755 + /**
1.756 + * enum set of active boolean attributes for this instance
1.757 + */
1.758 + EnumSet<UDateFormatBooleanAttribute, 0, UDAT_BOOLEAN_ATTRIBUTE_COUNT> fBoolFlags;
1.759 +
1.760 +
1.761 +public:
1.762 +#ifndef U_HIDE_OBSOLETE_API
1.763 + /**
1.764 + * Field selector for FieldPosition for DateFormat fields.
1.765 + * @obsolete ICU 3.4 use UDateFormatField instead, since this API will be
1.766 + * removed in that release
1.767 + */
1.768 + enum EField
1.769 + {
1.770 + // Obsolete; use UDateFormatField instead
1.771 + kEraField = UDAT_ERA_FIELD,
1.772 + kYearField = UDAT_YEAR_FIELD,
1.773 + kMonthField = UDAT_MONTH_FIELD,
1.774 + kDateField = UDAT_DATE_FIELD,
1.775 + kHourOfDay1Field = UDAT_HOUR_OF_DAY1_FIELD,
1.776 + kHourOfDay0Field = UDAT_HOUR_OF_DAY0_FIELD,
1.777 + kMinuteField = UDAT_MINUTE_FIELD,
1.778 + kSecondField = UDAT_SECOND_FIELD,
1.779 + kMillisecondField = UDAT_FRACTIONAL_SECOND_FIELD,
1.780 + kDayOfWeekField = UDAT_DAY_OF_WEEK_FIELD,
1.781 + kDayOfYearField = UDAT_DAY_OF_YEAR_FIELD,
1.782 + kDayOfWeekInMonthField = UDAT_DAY_OF_WEEK_IN_MONTH_FIELD,
1.783 + kWeekOfYearField = UDAT_WEEK_OF_YEAR_FIELD,
1.784 + kWeekOfMonthField = UDAT_WEEK_OF_MONTH_FIELD,
1.785 + kAmPmField = UDAT_AM_PM_FIELD,
1.786 + kHour1Field = UDAT_HOUR1_FIELD,
1.787 + kHour0Field = UDAT_HOUR0_FIELD,
1.788 + kTimezoneField = UDAT_TIMEZONE_FIELD,
1.789 + kYearWOYField = UDAT_YEAR_WOY_FIELD,
1.790 + kDOWLocalField = UDAT_DOW_LOCAL_FIELD,
1.791 + kExtendedYearField = UDAT_EXTENDED_YEAR_FIELD,
1.792 + kJulianDayField = UDAT_JULIAN_DAY_FIELD,
1.793 + kMillisecondsInDayField = UDAT_MILLISECONDS_IN_DAY_FIELD,
1.794 +
1.795 + // Obsolete; use UDateFormatField instead
1.796 + ERA_FIELD = UDAT_ERA_FIELD,
1.797 + YEAR_FIELD = UDAT_YEAR_FIELD,
1.798 + MONTH_FIELD = UDAT_MONTH_FIELD,
1.799 + DATE_FIELD = UDAT_DATE_FIELD,
1.800 + HOUR_OF_DAY1_FIELD = UDAT_HOUR_OF_DAY1_FIELD,
1.801 + HOUR_OF_DAY0_FIELD = UDAT_HOUR_OF_DAY0_FIELD,
1.802 + MINUTE_FIELD = UDAT_MINUTE_FIELD,
1.803 + SECOND_FIELD = UDAT_SECOND_FIELD,
1.804 + MILLISECOND_FIELD = UDAT_FRACTIONAL_SECOND_FIELD,
1.805 + DAY_OF_WEEK_FIELD = UDAT_DAY_OF_WEEK_FIELD,
1.806 + DAY_OF_YEAR_FIELD = UDAT_DAY_OF_YEAR_FIELD,
1.807 + DAY_OF_WEEK_IN_MONTH_FIELD = UDAT_DAY_OF_WEEK_IN_MONTH_FIELD,
1.808 + WEEK_OF_YEAR_FIELD = UDAT_WEEK_OF_YEAR_FIELD,
1.809 + WEEK_OF_MONTH_FIELD = UDAT_WEEK_OF_MONTH_FIELD,
1.810 + AM_PM_FIELD = UDAT_AM_PM_FIELD,
1.811 + HOUR1_FIELD = UDAT_HOUR1_FIELD,
1.812 + HOUR0_FIELD = UDAT_HOUR0_FIELD,
1.813 + TIMEZONE_FIELD = UDAT_TIMEZONE_FIELD
1.814 + };
1.815 +#endif /* U_HIDE_OBSOLETE_API */
1.816 +};
1.817 +
1.818 +U_NAMESPACE_END
1.819 +
1.820 +#endif /* #if !UCONFIG_NO_FORMATTING */
1.821 +
1.822 +#endif // _DATEFMT
1.823 +//eof
