// © 2016 and later: Unicode, Inc. and others. // License & terms of use: http://www.unicode.org/copyright.html /* ******************************************************************************** * 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 U_SHOW_CPLUSPLUS_API #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. */ 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<UDateFormatBooleanAttribute, 0, UDAT_BOOLEAN_ATTRIBUTE_COUNT>; #endif /** \endcond */ /** * DateFormat is an abstract class for a family of classes that convert dates and * times from their internal representations to textual form and back again in a * language-independent manner. Converting from the internal representation (milliseconds * since midnight, January 1, 1970) to text is known as "formatting," and converting * from text to millis is known as "parsing." We currently define only one concrete * subclass of DateFormat: SimpleDateFormat, which can handle pretty much all normal * date formatting and parsing actions. * <P> * DateFormat helps you to format and parse dates for any locale. Your code can * be completely independent of the locale conventions for months, days of the * week, or even the calendar format: lunar vs. solar. * <P> * To format a date for the current Locale, use one of the static factory * methods: * <pre> * \code * DateFormat* dfmt = DateFormat::createDateInstance(); * UDate myDate = Calendar::getNow(); * UnicodeString myString; * myString = dfmt->format( myDate, myString ); * \endcode * </pre> * If you are formatting multiple numbers, it is more efficient to get the * format and use it multiple times so that the system doesn't have to fetch the * information about the local language and country conventions multiple times. * <pre> * \code * DateFormat* df = DateFormat::createDateInstance(); * UnicodeString myString; * UDate myDateArr[] = { 0.0, 100000000.0, 2000000000.0 }; // test values * for (int32_t i = 0; i < 3; ++i) { * myString.remove(); * cout << df->format( myDateArr[i], myString ) << endl; * } * \endcode * </pre> * To get specific fields of a date, you can use UFieldPosition to * get specific fields. * <pre> * \code * DateFormat* dfmt = DateFormat::createDateInstance(); * FieldPosition pos(DateFormat::YEAR_FIELD); * UnicodeString myString; * myString = dfmt->format( myDate, myString ); * cout << myString << endl; * cout << pos.getBeginIndex() << "," << pos. getEndIndex() << endl; * \endcode * </pre> * To format a date for a different Locale, specify it in the call to * createDateInstance(). * <pre> * \code * DateFormat* df = * DateFormat::createDateInstance( DateFormat::SHORT, Locale::getFrance()); * \endcode * </pre> * You can use a DateFormat to parse also. * <pre> * \code * UErrorCode status = U_ZERO_ERROR; * UDate myDate = df->parse(myString, status); * \endcode * </pre> * Use createDateInstance() to produce the normal date format for that country. * There are other static factory methods available. Use createTimeInstance() * to produce the normal time format for that country. Use createDateTimeInstance() * to produce a DateFormat that formats both date and time. You can pass in * different options to these factory methods to control the length of the * result; from SHORT to MEDIUM to LONG to FULL. The exact result depends on the * locale, but generally: * <ul type=round> * <li> SHORT is completely numeric, such as 12/13/52 or 3:30pm * <li> MEDIUM is longer, such as Jan 12, 1952 * <li> LONG is longer, such as January 12, 1952 or 3:30:32pm * <li> FULL is pretty completely specified, such as * Tuesday, April 12, 1952 AD or 3:30:42pm PST. * </ul> * You can also set the time zone on the format if you wish. If you want even * more control over the format or parsing, (or want to give your users more * control), you can try casting the DateFormat you get from the factory methods * to a SimpleDateFormat. This will work for the majority of countries; just * remember to check getDynamicClassID() before carrying out the cast. * <P> * You can also use forms of the parse and format methods with ParsePosition and * FieldPosition to allow you to * <ul type=round> * <li> Progressively parse through pieces of a string. * <li> Align any particular field, or find out where it is for selection * on the screen. * </ul> * * <p><em>User subclasses are not supported.</em> 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 { … }; U_NAMESPACE_END #endif /* #if !UCONFIG_NO_FORMATTING */ #endif /* U_SHOW_CPLUSPLUS_API */ #endif // _DATEFMT //eof