X-Git-Url: https://git.saurik.com/apple/icu.git/blobdiff_plain/b75a7d8f3b4adbae880cab104ce2c6a50eee4db2..a01113dcd0f39d5da295ef82785beff9ed86fe38:/icuSources/i18n/unicode/datefmt.h diff --git a/icuSources/i18n/unicode/datefmt.h b/icuSources/i18n/unicode/datefmt.h index a53a6999..50e47b09 100644 --- a/icuSources/i18n/unicode/datefmt.h +++ b/icuSources/i18n/unicode/datefmt.h @@ -1,36 +1,60 @@ +// © 2016 and later: Unicode, Inc. and others. +// License & terms of use: http://www.unicode.org/copyright.html /* -******************************************************************************** -* Copyright (C) 1997-2003, International Business Machines -* Corporation and others. All Rights Reserved. -******************************************************************************** -* -* File DATEFMT.H -* -* Modification History: -* -* Date Name Description -* 02/19/97 aliu Converted from java. -* 04/01/97 aliu Added support for centuries. -* 07/23/98 stephen JDK 1.2 sync -* 11/15/99 weiv Added support for week of year/day of week formatting -******************************************************************************** -*/ + ******************************************************************************** + * Copyright (C) 1997-2016, International Business Machines + * Corporation and others. All Rights Reserved. + ******************************************************************************** + * + * File DATEFMT.H + * + * Modification History: + * + * Date Name Description + * 02/19/97 aliu Converted from java. + * 04/01/97 aliu Added support for centuries. + * 07/23/98 stephen JDK 1.2 sync + * 11/15/99 weiv Added support for week of year/day of week formatting + ******************************************************************************** + */ #ifndef DATEFMT_H #define DATEFMT_H - + #include "unicode/utypes.h" #if !UCONFIG_NO_FORMATTING +#include "unicode/udat.h" #include "unicode/calendar.h" #include "unicode/numfmt.h" #include "unicode/format.h" #include "unicode/locid.h" +#include "unicode/enumset.h" +#include "unicode/udisplaycontext.h" + +/** + * \file + * \brief C++ API: Abstract class for converting dates. + */ +#if U_SHOW_CPLUSPLUS_API U_NAMESPACE_BEGIN class TimeZone; +class DateTimePatternGenerator; + +/** + * \cond + * Export an explicit template instantiation. (See digitlst.h, datefmt.h, and others.) + * (When building DLLs for Windows this is required.) + */ +#if U_PF_WINDOWS <= U_PLATFORM && U_PLATFORM <= U_PF_CYGWIN && !defined(U_IN_DOXYGEN) +template class U_I18N_API EnumSet; +#endif +/** \endcond */ /** * DateFormat is an abstract class for a family of classes that convert dates and @@ -123,84 +147,20 @@ class TimeZone; *
  • Align any particular field, or find out where it is for selection * on the screen. * + * + *

    User subclasses are not supported. While clients may write + * subclasses, such code will not necessarily work and will not be + * guaranteed to work stably from release to release. */ class U_I18N_API DateFormat : public Format { public: - /** - * The following enum values are used in FieldPosition with date/time formatting. - * They are also used to index into DateFormatSymbols::fgPatternChars, which - * is the list of standard internal-representation pattern characters, and - * the resource bundle localPatternChars data. For this reason, this enum - * should be treated with care; don't change the order or contents of it - * unless you really know what you are doing. You'll probably have to change - * the code in DateFormatSymbols, SimpleDateFormat, and all the locale - * resource bundle data files. - * @draft ICU 2.4 - */ - enum EField - { - kEraField = 0, // ERA field alignment. - kYearField, // YEAR field alignment. - kMonthField, // MONTH field alignment. - kDateField, // DATE field alignment. - kHourOfDay1Field, // One-based HOUR_OF_DAY field alignment. - // kHourOfDay1Field is used for the one-based 24-hour clock. - // For example, 23:59 + 01:00 results in 24:59. - kHourOfDay0Field, // Zero-based HOUR_OF_DAY field alignment. - // HOUR_OF_DAY0_FIELD is used for the zero-based 24-hour clock. - // For example, 23:59 + 01:00 results in 00:59. - kMinuteField, // MINUTE field alignment. - kSecondField, // SECOND field alignment. - kMillisecondField, // MILLISECOND field alignment. - kDayOfWeekField, // DAY_OF_WEEK field alignment. - kDayOfYearField, // DAY_OF_YEAR field alignment. - kDayOfWeekInMonthField,// DAY_OF_WEEK_IN_MONTH field alignment. - kWeekOfYearField, // WEEK_OF_YEAR field alignment. - kWeekOfMonthField, // WEEK_OF_MONTH field alignment. - kAmPmField, // AM_PM field alignment. - kHour1Field, // One-based HOUR field alignment. - // HOUR1_FIELD is used for the one-based 12-hour clock. - // For example, 11:30 PM + 1 hour results in 12:30 AM. - kHour0Field, // Zero-based HOUR field alignment. - // HOUR0_FIELD is used for the zero-based 12-hour clock. - // For example, 11:30 PM + 1 hour results in 00:30 AM. - kTimezoneField, // TIMEZONE field alignment. - kYearWOYField, // Corrected year for week representation - kDOWLocalField, // localized day of week - - - - /** - * These constants are provided for backwards compatibility only. - * Please use the C++ style constants defined above. - */ - ERA_FIELD = kEraField, - YEAR_FIELD = kYearField, - MONTH_FIELD = kMonthField, - DATE_FIELD = kDateField, - HOUR_OF_DAY1_FIELD = kHourOfDay1Field, - HOUR_OF_DAY0_FIELD = kHourOfDay0Field, - MINUTE_FIELD = kMinuteField, - SECOND_FIELD = kSecondField, - MILLISECOND_FIELD = kMillisecondField, - DAY_OF_WEEK_FIELD = kDayOfWeekField, - DAY_OF_YEAR_FIELD = kDayOfYearField, - DAY_OF_WEEK_IN_MONTH_FIELD = kDayOfWeekInMonthField, - WEEK_OF_YEAR_FIELD = kWeekOfYearField, - WEEK_OF_MONTH_FIELD = kWeekOfMonthField, - AM_PM_FIELD = kAmPmField, - HOUR1_FIELD = kHour1Field, - HOUR0_FIELD = kHour0Field, - TIMEZONE_FIELD = kTimezoneField - - }; /** * Constants for various style patterns. These reflect the order of items in * the DateTimePatterns resource. There are 4 time patterns, 4 date patterns, - * and then the date-time pattern. Each block of 4 values in the resource occurs - * in the order full, long, medium, short. - * @draft ICU 2.4 + * the default date-time pattern, and 4 date-time patterns. Each block of 4 values + * in the resource occurs in the order full, long, medium, short. + * @stable ICU 2.4 */ enum EStyle { @@ -218,15 +178,34 @@ public: // kShort + kDateOffset = 7 kDateTime = 8, + // Default DateTime + + kDateTimeOffset = kDateTime + 1, + // kFull + kDateTimeOffset = 9 + // kLong + kDateTimeOffset = 10 + // kMedium + kDateTimeOffset = 11 + // kShort + kDateTimeOffset = 12 + + // relative dates + kRelative = (1 << 7), + + kFullRelative = (kFull | kRelative), + + kLongRelative = kLong | kRelative, + + kMediumRelative = kMedium | kRelative, + + kShortRelative = kShort | kRelative, + kDefault = kMedium, - - + + /** * These constants are provided for backwards compatibility only. * Please use the C++ style constants defined above. - */ + */ FULL = kFull, LONG = kLong, MEDIUM = kMedium, @@ -249,6 +228,9 @@ public: */ virtual UBool operator==(const Format&) const; + + using Format::format; + /** * Format an object to produce a string. This method handles Formattable * objects with a UDate type. If a the Formattable object type is not a Date, @@ -268,17 +250,36 @@ public: FieldPosition& pos, UErrorCode& status) const; + /** + * Format an object to produce a string. This method handles Formattable + * objects with a UDate type. If a the Formattable object type is not a Date, + * then it returns a failing UErrorCode. + * + * @param obj The object to format. Must be a Date. + * @param appendTo Output parameter to receive result. + * Result is appended to existing contents. + * @param posIter On return, can be used to iterate over positions + * of fields generated by this format call. Field values + * are defined in UDateFormatField. Can be NULL. + * @param status Output param filled with success/failure status. + * @return Reference to 'appendTo' parameter. + * @stable ICU 4.4 + */ + virtual UnicodeString& format(const Formattable& obj, + UnicodeString& appendTo, + FieldPositionIterator* posIter, + UErrorCode& status) const; /** * Formats a date into a date/time string. This is an abstract method which * concrete subclasses must implement. *

    * On input, the FieldPosition parameter may have its "field" member filled with * an enum value specifying a field. On output, the FieldPosition will be filled - * in with the text offsets for that field. + * in with the text offsets for that field. *

    For example, given a time text * "1996.07.10 AD at 15:08:56 PDT", if the given fieldPosition.field is - * DateFormat::kYearField, the offsets fieldPosition.beginIndex and - * statfieldPositionus.getEndIndex will be set to 0 and 4, respectively. + * UDAT_YEAR_FIELD, the offsets fieldPosition.beginIndex and + * statfieldPositionus.getEndIndex will be set to 0 and 4, respectively. *

    Notice * that if the same time field appears more than once in a pattern, the status will * be set for the first occurence of that time field. For instance, @@ -289,7 +290,11 @@ public: * occurence of the timezone pattern character 'z'. * * @param cal Calendar set to the date and time to be formatted - * into a date/time string. + * into a date/time string. When the calendar type is + * different from the internal calendar held by this + * DateFormat instance, the date and the time zone will + * be inherited from the input calendar, but other calendar + * field values will be calculated by the internal calendar. * @param appendTo Output parameter to receive result. * Result is appended to existing contents. * @param fieldPosition On input: an alignment field, if desired (see examples above) @@ -301,16 +306,38 @@ public: UnicodeString& appendTo, FieldPosition& fieldPosition) const = 0; + /** + * Formats a date into a date/time string. Subclasses should implement this method. + * + * @param cal Calendar set to the date and time to be formatted + * into a date/time string. When the calendar type is + * different from the internal calendar held by this + * DateFormat instance, the date and the time zone will + * be inherited from the input calendar, but other calendar + * field values will be calculated by the internal calendar. + * @param appendTo Output parameter to receive result. + * Result is appended to existing contents. + * @param posIter On return, can be used to iterate over positions + * of fields generated by this format call. Field values + * are defined in UDateFormatField. Can be NULL. + * @param status error status. + * @return Reference to 'appendTo' parameter. + * @stable ICU 4.4 + */ + virtual UnicodeString& format(Calendar& cal, + UnicodeString& appendTo, + FieldPositionIterator* posIter, + UErrorCode& status) const; /** * Formats a UDate into a date/time string. *

    * On input, the FieldPosition parameter may have its "field" member filled with * an enum value specifying a field. On output, the FieldPosition will be filled - * in with the text offsets for that field. + * in with the text offsets for that field. *

    For example, given a time text * "1996.07.10 AD at 15:08:56 PDT", if the given fieldPosition.field is - * DateFormat::kYearField, the offsets fieldPosition.beginIndex and - * statfieldPositionus.getEndIndex will be set to 0 and 4, respectively. + * UDAT_YEAR_FIELD, the offsets fieldPosition.beginIndex and + * statfieldPositionus.getEndIndex will be set to 0 and 4, respectively. *

    Notice * that if the same time field appears more than once in a pattern, the status will * be set for the first occurence of that time field. For instance, @@ -333,40 +360,67 @@ public: FieldPosition& fieldPosition) const; /** - * Formats a UDate into a date/time string. If there is a problem, you won't - * know, using this method. Use the overloaded format() method which takes a - * FieldPosition& to detect formatting problems. + * Formats a UDate into a date/time string. * - * @param date The UDate value to be formatted into a string. + * @param date UDate to be formatted into a date/time string. * @param appendTo Output parameter to receive result. * Result is appended to existing contents. + * @param posIter On return, can be used to iterate over positions + * of fields generated by this format call. Field values + * are defined in UDateFormatField. Can be NULL. + * @param status error status. * @return Reference to 'appendTo' parameter. - * @stable ICU 2.0 + * @stable ICU 4.4 */ - UnicodeString& format(UDate date, UnicodeString& appendTo) const; - + UnicodeString& format(UDate date, + UnicodeString& appendTo, + FieldPositionIterator* posIter, + UErrorCode& status) const; /** - * Redeclared Format method. + * Formats a UDate into a date/time string. If there is a problem, you won't + * know, using this method. Use the overloaded format() method which takes a + * FieldPosition& to detect formatting problems. * - * @param obj The object to be formatted into a string. + * @param date The UDate value to be formatted into a string. * @param appendTo Output parameter to receive result. * Result is appended to existing contents. - * @param status Output param filled with success/failure status. * @return Reference to 'appendTo' parameter. * @stable ICU 2.0 */ - UnicodeString& format(const Formattable& obj, - UnicodeString& appendTo, - UErrorCode& status) const; + UnicodeString& format(UDate date, UnicodeString& appendTo) const; /** - * Parse a date/time string. + * Parse a date/time string. For example, a time text "07/10/96 4:5 PM, PDT" + * will be parsed into a UDate that is equivalent to Date(837039928046). + * Parsing begins at the beginning of the string and proceeds as far as + * possible. Assuming no parse errors were encountered, this function + * doesn't return any information about how much of the string was consumed + * by the parsing. If you need that information, use the version of + * parse() that takes a ParsePosition. + *

    + * By default, parsing is lenient: If the input is not in the form used by + * this object's format method but can still be parsed as a date, then the + * parse succeeds. Clients may insist on strict adherence to the format by + * calling setLenient(false). + * @see DateFormat::setLenient(boolean) + *

    + * Note that the normal date formats associated with some calendars - such + * as the Chinese lunar calendar - do not specify enough fields to enable + * dates to be parsed unambiguously. In the case of the Chinese lunar + * calendar, while the year within the current 60-year cycle is specified, + * the number of such cycles since the start date of the calendar (in the + * ERA field of the Calendar object) is not normally part of the format, + * and parsing may assume the wrong era. For cases such as this it is + * recommended that clients parse using the method + * parse(const UnicodeString&, Calendar& cal, ParsePosition&) + * with the Calendar passed in set to the current date, or to a date + * within the era/cycle that should be assumed if absent in the format. * - * @param text The string to be parsed into a UDate value. + * @param text The date/time string to be parsed into a UDate value. * @param status Output param to be set to success/failure code. If * 'text' cannot be parsed, it will be set to a failure * code. - * @result The parsed UDate value, if successful. + * @return The parsed UDate value, if successful. * @stable ICU 2.0 */ virtual UDate parse( const UnicodeString& text, @@ -381,16 +435,21 @@ public: * this object's format method but can still be parsed as a date, then the * parse succeeds. Clients may insist on strict adherence to the format by * calling setLenient(false). - * * @see DateFormat::setLenient(boolean) * - * @param text The date/time string to be parsed - * @param cal a Calendar set to the date and time to be formatted - * into a date/time string. + * @param text The date/time string to be parsed. + * @param cal A Calendar set on input to the date and time to be used for + * missing values in the date/time string being parsed, and set + * on output to the parsed date/time. When the calendar type is + * different from the internal calendar held by this DateFormat + * instance, the internal calendar will be cloned to a work + * calendar set to the same milliseconds and time zone as the + * cal parameter, field values will be parsed based on the work + * calendar, then the result (milliseconds and time zone) will + * be set in this calendar. * @param pos On input, the position at which to start parsing; on * output, the position at which parsing terminated, or the * start position if the parse failed. - * @return A valid UDate if the input could be parsed. * @stable ICU 2.1 */ virtual void parse( const UnicodeString& text, @@ -406,10 +465,21 @@ public: * this object's format method but can still be parsed as a date, then the * parse succeeds. Clients may insist on strict adherence to the format by * calling setLenient(false). - * * @see DateFormat::setLenient(boolean) + *

    + * Note that the normal date formats associated with some calendars - such + * as the Chinese lunar calendar - do not specify enough fields to enable + * dates to be parsed unambiguously. In the case of the Chinese lunar + * calendar, while the year within the current 60-year cycle is specified, + * the number of such cycles since the start date of the calendar (in the + * ERA field of the Calendar object) is not normally part of the format, + * and parsing may assume the wrong era. For cases such as this it is + * recommended that clients parse using the method + * parse(const UnicodeString&, Calendar& cal, ParsePosition&) + * with the Calendar passed in set to the current date, or to a date + * within the era/cycle that should be assumed if absent in the format. * - * @param text The date/time string to be parsed + * @param text The date/time string to be parsed into a UDate value. * @param pos On input, the position at which to start parsing; on * output, the position at which parsing terminated, or the * start position if the parse failed. @@ -440,9 +510,6 @@ public: * last character successfully parsed. If the * source is not parsed successfully, this param * will remain unchanged. - * @return A newly created Formattable* object, or NULL - * on failure. The caller owns this and should - * delete it when done. * @stable ICU 2.0 */ virtual void parseObject(const UnicodeString& source, @@ -456,50 +523,133 @@ public: * @return A date/time formatter which the caller owns. * @stable ICU 2.0 */ - static DateFormat* createInstance(void); + static DateFormat* U_EXPORT2 createInstance(void); /** * Creates a time formatter with the given formatting style for the given * locale. - * + * * @param style The given formatting style. For example, - * SHORT for "h:mm a" in the US locale. + * SHORT for "h:mm a" in the US locale. Relative + * time styles are not currently supported. * @param aLocale The given locale. * @return A time formatter which the caller owns. * @stable ICU 2.0 */ - static DateFormat* createTimeInstance(EStyle style = kDefault, + static DateFormat* U_EXPORT2 createTimeInstance(EStyle style = kDefault, const Locale& aLocale = Locale::getDefault()); /** * Creates a date formatter with the given formatting style for the given * const locale. - * - * @param style The given formatting style. For example, - * SHORT for "M/d/yy" in the US locale. + * + * @param style The given formatting style. For example, SHORT for "M/d/yy" in the + * US locale. As currently implemented, relative date formatting only + * affects a limited range of calendar days before or after the + * current date, based on the CLDR <field type="day">/<relative> data: + * For example, in English, "Yesterday", "Today", and "Tomorrow". + * Outside of this range, dates are formatted using the corresponding + * non-relative style. * @param aLocale The given locale. * @return A date formatter which the caller owns. * @stable ICU 2.0 */ - static DateFormat* createDateInstance(EStyle style = kDefault, + static DateFormat* U_EXPORT2 createDateInstance(EStyle style = kDefault, const Locale& aLocale = Locale::getDefault()); /** * Creates a date/time formatter with the given formatting styles for the * given locale. - * + * * @param dateStyle The given formatting style for the date portion of the result. - * For example, SHORT for "M/d/yy" in the US locale. + * For example, SHORT for "M/d/yy" in the US locale. As currently + * implemented, relative date formatting only affects a limited range + * of calendar days before or after the current date, based on the + * CLDR <field type="day">/<relative> data: For example, in English, + * "Yesterday", "Today", and "Tomorrow". Outside of this range, dates + * are formatted using the corresponding non-relative style. * @param timeStyle The given formatting style for the time portion of the result. - * For example, SHORT for "h:mm a" in the US locale. + * For example, SHORT for "h:mm a" in the US locale. Relative + * time styles are not currently supported. * @param aLocale The given locale. * @return A date/time formatter which the caller owns. * @stable ICU 2.0 */ - static DateFormat* createDateTimeInstance(EStyle dateStyle = kDefault, + static DateFormat* U_EXPORT2 createDateTimeInstance(EStyle dateStyle = kDefault, EStyle timeStyle = kDefault, const Locale& aLocale = Locale::getDefault()); +#ifndef U_HIDE_INTERNAL_API + /** + * Returns the best pattern given a skeleton and locale. + * @param locale the locale + * @param skeleton the skeleton + * @param status ICU error returned here + * @return the best pattern. + * @internal For ICU use only. + */ + static UnicodeString getBestPattern( + const Locale &locale, + const UnicodeString &skeleton, + UErrorCode &status); +#endif /* U_HIDE_INTERNAL_API */ + + /** + * Creates a date/time formatter for the given skeleton and + * default locale. + * + * @param skeleton The skeleton e.g "yMMMMd." Fields in the skeleton can + * be in any order, and this method uses the locale to + * map the skeleton to a pattern that includes locale + * specific separators with the fields in the appropriate + * order for that locale. + * @param status Any error returned here. + * @return A date/time formatter which the caller owns. + * @stable ICU 55 + */ + static DateFormat* U_EXPORT2 createInstanceForSkeleton( + const UnicodeString& skeleton, + UErrorCode &status); + + /** + * Creates a date/time formatter for the given skeleton and locale. + * + * @param skeleton The skeleton e.g "yMMMMd." Fields in the skeleton can + * be in any order, and this method uses the locale to + * map the skeleton to a pattern that includes locale + * specific separators with the fields in the appropriate + * order for that locale. + * @param locale The given locale. + * @param status Any error returned here. + * @return A date/time formatter which the caller owns. + * @stable ICU 55 + */ + static DateFormat* U_EXPORT2 createInstanceForSkeleton( + const UnicodeString& skeleton, + const Locale &locale, + UErrorCode &status); + + /** + * Creates a date/time formatter for the given skeleton and locale. + * + * @param calendarToAdopt the calendar returned DateFormat is to use. + * @param skeleton The skeleton e.g "yMMMMd." Fields in the skeleton can + * be in any order, and this method uses the locale to + * map the skeleton to a pattern that includes locale + * specific separators with the fields in the appropriate + * order for that locale. + * @param locale The given locale. + * @param status Any error returned here. + * @return A date/time formatter which the caller owns. + * @stable ICU 55 + */ + static DateFormat* U_EXPORT2 createInstanceForSkeleton( + Calendar *calendarToAdopt, + const UnicodeString& skeleton, + const Locale &locale, + UErrorCode &status); + + /** * Gets the set of locales for which DateFormats are installed. * @param count Filled in with the number of locales in the list that is returned. @@ -507,33 +657,67 @@ public: * does NOT own this list and must not delete it. * @stable ICU 2.0 */ - static const Locale* getAvailableLocales(int32_t& count); - + static const Locale* U_EXPORT2 getAvailableLocales(int32_t& count); + /** - * Returns true if the formatter is set for lenient parsing. + * Returns whether both date/time parsing in the encapsulated Calendar object and DateFormat whitespace & + * numeric processing is lenient. * @stable ICU 2.0 */ virtual UBool isLenient(void) const; /** - * Specify whether or not date/time parsing is to be lenient. With lenient - * parsing, the parser may use heuristics to interpret inputs that do not - * precisely match this object's format. With strict parsing, inputs must - * match this object's format. + * Specifies whether date/time parsing is to be lenient. With + * lenient parsing, the parser may use heuristics to interpret inputs that + * do not precisely match this object's format. Without lenient parsing, + * inputs must match this object's format more closely. * + * Note: ICU 53 introduced finer grained control of leniency (and added + * new control points) making the preferred method a combination of + * setCalendarLenient() & setBooleanAttribute() calls. + * This method supports prior functionality but may not support all + * future leniency control & behavior of DateFormat. For control of pre 53 leniency, + * Calendar and DateFormat whitespace & numeric tolerance, this method is safe to + * use. However, mixing leniency control via this method and modification of the + * newer attributes via setBooleanAttribute() may produce undesirable + * results. + * * @param lenient True specifies date/time interpretation to be lenient. * @see Calendar::setLenient - * @stable ICU 2.0 + * @stable ICU 2.0 */ virtual void setLenient(UBool lenient); - + + + /** + * Returns whether date/time parsing in the encapsulated Calendar object processing is lenient. + * @stable ICU 53 + */ + virtual UBool isCalendarLenient(void) const; + + + /** + * Specifies whether encapsulated Calendar date/time parsing is to be lenient. With + * lenient parsing, the parser may use heuristics to interpret inputs that + * do not precisely match this object's format. Without lenient parsing, + * inputs must match this object's format more closely. + * @param lenient when true, parsing is lenient + * @see com.ibm.icu.util.Calendar#setLenient + * @stable ICU 53 + */ + virtual void setCalendarLenient(UBool lenient); + + /** * Gets the calendar associated with this date/time formatter. + * The calendar is owned by the formatter and must not be modified. + * Also, the calendar does not reflect the results of a parse operation. + * To parse to a calendar, use {@link #parse(const UnicodeString&, Calendar& cal, ParsePosition&) const parse(const UnicodeString&, Calendar& cal, ParsePosition&)} * @return the calendar associated with this date/time formatter. * @stable ICU 2.0 */ virtual const Calendar* getCalendar(void) const; - + /** * Set the calendar to be used by this date format. Initially, the default * calendar for the specified or default locale is used. The caller should @@ -554,7 +738,7 @@ public: */ virtual void setCalendar(const Calendar& newCalendar); - + /** * Gets the number formatter which this date/time formatter uses to format * and parse the numeric portions of the pattern. @@ -562,7 +746,7 @@ public: * @stable ICU 2.0 */ virtual const NumberFormat* getNumberFormat(void) const; - + /** * Allows you to set the number formatter. The caller should * not delete the NumberFormat object after it is adopted by this call. @@ -584,7 +768,7 @@ public: * @stable ICU 2.0 */ virtual const TimeZone& getTimeZone(void) const; - + /** * Sets the time zone for the calendar of this DateFormat object. The caller * no longer owns the TimeZone object and should not delete it after this call. @@ -600,7 +784,55 @@ public: */ virtual void setTimeZone(const TimeZone& zone); - + /** + * Set a particular UDisplayContext value in the formatter, such as + * UDISPCTX_CAPITALIZATION_FOR_STANDALONE. + * @param value The UDisplayContext value to set. + * @param status Input/output status. If at entry this indicates a failure + * status, the function will do nothing; otherwise this will be + * updated with any new status from the function. + * @stable ICU 53 + */ + virtual void setContext(UDisplayContext value, UErrorCode& status); + + /** + * Get the formatter's UDisplayContext value for the specified UDisplayContextType, + * such as UDISPCTX_TYPE_CAPITALIZATION. + * @param type The UDisplayContextType whose value to return + * @param status Input/output status. If at entry this indicates a failure + * status, the function will do nothing; otherwise this will be + * updated with any new status from the function. + * @return The UDisplayContextValue for the specified type. + * @stable ICU 53 + */ + virtual UDisplayContext getContext(UDisplayContextType type, UErrorCode& status) const; + + /** + * Sets an boolean attribute on this DateFormat. + * May return U_UNSUPPORTED_ERROR if this instance does not support + * the specified attribute. + * @param attr the attribute to set + * @param newvalue new value + * @param status the error type + * @return *this - for chaining (example: format.setAttribute(...).setAttribute(...) ) + * @stable ICU 53 + */ + + virtual DateFormat& U_EXPORT2 setBooleanAttribute(UDateFormatBooleanAttribute attr, + UBool newvalue, + UErrorCode &status); + + /** + * Returns a boolean from this DateFormat + * May return U_UNSUPPORTED_ERROR if this instance does not support + * the specified attribute. + * @param attr the attribute to set + * @param status the error type + * @return the attribute value. Undefined if there is an error. + * @stable ICU 53 + */ + virtual UBool U_EXPORT2 getBooleanAttribute(UDateFormatBooleanAttribute attr, UErrorCode &status) const; + protected: /** * Default constructor. Creates a DateFormat with no Calendar or NumberFormat @@ -626,7 +858,7 @@ protected: * The calendar that DateFormat uses to produce the time field values needed * to implement date/time formatting. Subclasses should generally initialize * this to the default calendar for the locale associated with this DateFormat. - * @draft ICU 2.4 + * @stable ICU 2.4 */ Calendar* fCalendar; @@ -634,11 +866,13 @@ protected: * The number formatter that DateFormat uses to format numbers in dates and * times. Subclasses should generally initialize this to the default number * format for the locale associated with this DateFormat. - * @draft ICU 2.4 + * @stable ICU 2.4 */ NumberFormat* fNumberFormat; + private: + /** * Gets the date/time formatter with the given formatting styles for the * given locale. @@ -647,16 +881,77 @@ private: * @param inLocale the given locale. * @return a date/time formatter, or 0 on failure. */ - static DateFormat* create(EStyle timeStyle, EStyle dateStyle, const Locale&); + static DateFormat* U_EXPORT2 create(EStyle timeStyle, EStyle dateStyle, const Locale& inLocale); + + + /** + * enum set of active boolean attributes for this instance + */ + EnumSet fBoolFlags; + + + UDisplayContext fCapitalizationContext; + friend class DateFmtKeyByStyle; + +public: +#ifndef U_HIDE_OBSOLETE_API + /** + * Field selector for FieldPosition for DateFormat fields. + * @obsolete ICU 3.4 use UDateFormatField instead, since this API will be + * removed in that release + */ + enum EField + { + // Obsolete; use UDateFormatField instead + kEraField = UDAT_ERA_FIELD, + kYearField = UDAT_YEAR_FIELD, + kMonthField = UDAT_MONTH_FIELD, + kDateField = UDAT_DATE_FIELD, + kHourOfDay1Field = UDAT_HOUR_OF_DAY1_FIELD, + kHourOfDay0Field = UDAT_HOUR_OF_DAY0_FIELD, + kMinuteField = UDAT_MINUTE_FIELD, + kSecondField = UDAT_SECOND_FIELD, + kMillisecondField = UDAT_FRACTIONAL_SECOND_FIELD, + kDayOfWeekField = UDAT_DAY_OF_WEEK_FIELD, + kDayOfYearField = UDAT_DAY_OF_YEAR_FIELD, + kDayOfWeekInMonthField = UDAT_DAY_OF_WEEK_IN_MONTH_FIELD, + kWeekOfYearField = UDAT_WEEK_OF_YEAR_FIELD, + kWeekOfMonthField = UDAT_WEEK_OF_MONTH_FIELD, + kAmPmField = UDAT_AM_PM_FIELD, + kHour1Field = UDAT_HOUR1_FIELD, + kHour0Field = UDAT_HOUR0_FIELD, + kTimezoneField = UDAT_TIMEZONE_FIELD, + kYearWOYField = UDAT_YEAR_WOY_FIELD, + kDOWLocalField = UDAT_DOW_LOCAL_FIELD, + kExtendedYearField = UDAT_EXTENDED_YEAR_FIELD, + kJulianDayField = UDAT_JULIAN_DAY_FIELD, + kMillisecondsInDayField = UDAT_MILLISECONDS_IN_DAY_FIELD, + + // Obsolete; use UDateFormatField instead + ERA_FIELD = UDAT_ERA_FIELD, + YEAR_FIELD = UDAT_YEAR_FIELD, + MONTH_FIELD = UDAT_MONTH_FIELD, + DATE_FIELD = UDAT_DATE_FIELD, + HOUR_OF_DAY1_FIELD = UDAT_HOUR_OF_DAY1_FIELD, + HOUR_OF_DAY0_FIELD = UDAT_HOUR_OF_DAY0_FIELD, + MINUTE_FIELD = UDAT_MINUTE_FIELD, + SECOND_FIELD = UDAT_SECOND_FIELD, + MILLISECOND_FIELD = UDAT_FRACTIONAL_SECOND_FIELD, + DAY_OF_WEEK_FIELD = UDAT_DAY_OF_WEEK_FIELD, + DAY_OF_YEAR_FIELD = UDAT_DAY_OF_YEAR_FIELD, + DAY_OF_WEEK_IN_MONTH_FIELD = UDAT_DAY_OF_WEEK_IN_MONTH_FIELD, + WEEK_OF_YEAR_FIELD = UDAT_WEEK_OF_YEAR_FIELD, + WEEK_OF_MONTH_FIELD = UDAT_WEEK_OF_MONTH_FIELD, + AM_PM_FIELD = UDAT_AM_PM_FIELD, + HOUR1_FIELD = UDAT_HOUR1_FIELD, + HOUR0_FIELD = UDAT_HOUR0_FIELD, + TIMEZONE_FIELD = UDAT_TIMEZONE_FIELD + }; +#endif /* U_HIDE_OBSOLETE_API */ }; -inline UnicodeString& -DateFormat::format(const Formattable& obj, - UnicodeString& appendTo, - UErrorCode& status) const { - return Format::format(obj, appendTo, status); -} U_NAMESPACE_END +#endif // U_SHOW_CPLUSPLUS_API #endif /* #if !UCONFIG_NO_FORMATTING */