* Date Format 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. *
* To format a date for the current Locale with default time and date style, * use one of the static factory methods: *
* \code
* UErrorCode status = U_ZERO_ERROR;
* UChar *myString;
* int32_t myStrlen = 0;
* UDateFormat* dfmt = udat_open(UDAT_DEFAULT, UDAT_DEFAULT, NULL, NULL, -1, NULL, -1, &status);
* myStrlen = udat_format(dfmt, myDate, NULL, myStrlen, NULL, &status);
* if (status==U_BUFFER_OVERFLOW_ERROR){
* status=U_ZERO_ERROR;
* myString=(UChar*)malloc(sizeof(UChar) * (myStrlen+1) );
* udat_format(dfmt, myDate, myString, myStrlen+1, NULL, &status);
* }
* \endcode
*
* 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.
*
* \code
* UErrorCode status = U_ZERO_ERROR;
* int32_t i, myStrlen = 0;
* UChar* myString;
* char buffer[1024];
* UDate myDateArr[] = { 0.0, 100000000.0, 2000000000.0 }; // test values
* UDateFormat* df = udat_open(UDAT_DEFAULT, UDAT_DEFAULT, NULL, NULL, -1, NULL, 0, &status);
* for (i = 0; i < 3; i++) {
* myStrlen = udat_format(df, myDateArr[i], NULL, myStrlen, NULL, &status);
* if(status == U_BUFFER_OVERFLOW_ERROR){
* status = U_ZERO_ERROR;
* myString = (UChar*)malloc(sizeof(UChar) * (myStrlen+1) );
* udat_format(df, myDateArr[i], myString, myStrlen+1, NULL, &status);
* printf("%s\n", u_austrcpy(buffer, myString) );
* free(myString);
* }
* }
* \endcode
*
* To get specific fields of a date, you can use UFieldPosition to
* get specific fields.
*
* \code
* UErrorCode status = U_ZERO_ERROR;
* UFieldPosition pos;
* UChar *myString;
* int32_t myStrlen = 0;
* char buffer[1024];
*
* pos.field = 1; // Same as the DateFormat::EField enum
* UDateFormat* dfmt = udat_open(UDAT_DEFAULT, UDAT_DEFAULT, NULL, -1, NULL, 0, &status);
* myStrlen = udat_format(dfmt, myDate, NULL, myStrlen, &pos, &status);
* if (status==U_BUFFER_OVERFLOW_ERROR){
* status=U_ZERO_ERROR;
* myString=(UChar*)malloc(sizeof(UChar) * (myStrlen+1) );
* udat_format(dfmt, myDate, myString, myStrlen+1, &pos, &status);
* }
* printf("date format: %s\n", u_austrcpy(buffer, myString));
* buffer[pos.endIndex] = 0; // NULL terminate the string.
* printf("UFieldPosition position equals %s\n", &buffer[pos.beginIndex]);
* \endcode
*
* To format a date for a different Locale, specify it in the call to
* udat_open()
* * \code * UDateFormat* df = udat_open(UDAT_SHORT, UDAT_SHORT, "fr_FR", NULL, -1, NULL, 0, &status); * \endcode ** You can use a DateFormat API udat_parse() to parse. *
* \code * UErrorCode status = U_ZERO_ERROR; * int32_t parsepos=0; * UDate myDate = udat_parse(df, myString, u_strlen(myString), &parsepos, &status); * \endcode ** You can pass in different options for the arguments for date and time style * to control the length of the result; from SHORT to MEDIUM to LONG to FULL. * The exact result depends on the locale, but generally: * see UDateFormatStyle for more details *
* You can also use forms of the parse and format methods with Parse Position and * UFieldPosition to allow you to *
* A skeleton *
* 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 * UCAL_ERA field of the UCalendar 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 udat_parseCalendar with the UCalendar * 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 format The formatter to use. * @param text The text to parse. * @param textLength The length of text, or -1 if null-terminated. * @param parsePos If not 0, on input a pointer to an integer specifying the offset at which * to begin parsing. If not 0, on output the offset at which parsing ended. * @param status A pointer to an UErrorCode to receive any errors * @return The value of the parsed date/time * @see udat_format * @stable ICU 2.0 */ U_STABLE UDate U_EXPORT2 udat_parse(const UDateFormat* format, const UChar* text, int32_t textLength, int32_t *parsePos, UErrorCode *status); /** * Parse a string into an date/time using a UDateFormat. * The date will be parsed using the conventions specified in {@link #udat_open }. * @param format The formatter to use. * @param calendar 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 the UDateFormat * instance, the internal calendar will be cloned to a work * calendar set to the same milliseconds and time zone as this * calendar 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 text The text to parse. * @param textLength The length of text, or -1 if null-terminated. * @param parsePos If not 0, on input a pointer to an integer specifying the offset at which * to begin parsing. If not 0, on output the offset at which parsing ended. * @param status A pointer to an UErrorCode to receive any errors * @see udat_format * @stable ICU 2.0 */ U_STABLE void U_EXPORT2 udat_parseCalendar(const UDateFormat* format, UCalendar* calendar, const UChar* text, int32_t textLength, int32_t *parsePos, UErrorCode *status); /** * Determine if an UDateFormat will perform lenient parsing. * With lenient parsing, the parser may use heuristics to interpret inputs that do not * precisely match the pattern. With strict parsing, inputs must match the pattern. * @param fmt The formatter to query * @return TRUE if fmt is set to perform lenient parsing, FALSE otherwise. * @see udat_setLenient * @stable ICU 2.0 */ U_STABLE UBool U_EXPORT2 udat_isLenient(const UDateFormat* fmt); /** * Specify whether an UDateFormat will perform lenient parsing. * With lenient parsing, the parser may use heuristics to interpret inputs that do not * precisely match the pattern. With strict parsing, inputs must match the pattern. * @param fmt The formatter to set * @param isLenient TRUE if fmt should perform lenient parsing, FALSE otherwise. * @see dat_isLenient * @stable ICU 2.0 */ U_STABLE void U_EXPORT2 udat_setLenient( UDateFormat* fmt, UBool isLenient); /** * Get the UCalendar associated with an UDateFormat. * A UDateFormat uses a UCalendar to convert a raw value to, for example, * the day of the week. * @param fmt The formatter to query. * @return A pointer to the UCalendar used by fmt. * @see udat_setCalendar * @stable ICU 2.0 */ U_STABLE const UCalendar* U_EXPORT2 udat_getCalendar(const UDateFormat* fmt); /** * Set the UCalendar associated with an UDateFormat. * A UDateFormat uses a UCalendar to convert a raw value to, for example, * the day of the week. * @param fmt The formatter to set. * @param calendarToSet A pointer to an UCalendar to be used by fmt. * @see udat_setCalendar * @stable ICU 2.0 */ U_STABLE void U_EXPORT2 udat_setCalendar( UDateFormat* fmt, const UCalendar* calendarToSet); /** * Get the UNumberFormat associated with an UDateFormat. * A UDateFormat uses a UNumberFormat to format numbers within a date, * for example the day number. * @param fmt The formatter to query. * @return A pointer to the UNumberFormat used by fmt to format numbers. * @see udat_setNumberFormat * @stable ICU 2.0 */ U_STABLE const UNumberFormat* U_EXPORT2 udat_getNumberFormat(const UDateFormat* fmt); /** * Set the UNumberFormat associated with an UDateFormat. * A UDateFormat uses a UNumberFormat to format numbers within a date, * for example the day number. * @param fmt The formatter to set. * @param numberFormatToSet A pointer to the UNumberFormat to be used by fmt to format numbers. * @see udat_getNumberFormat * @stable ICU 2.0 */ U_STABLE void U_EXPORT2 udat_setNumberFormat( UDateFormat* fmt, const UNumberFormat* numberFormatToSet); /** * Get a locale for which date/time formatting patterns are available. * A UDateFormat in a locale returned by this function will perform the correct * formatting and parsing for the locale. * @param localeIndex The index of the desired locale. * @return A locale for which date/time formatting patterns are available, or 0 if none. * @see udat_countAvailable * @stable ICU 2.0 */ U_STABLE const char* U_EXPORT2 udat_getAvailable(int32_t localeIndex); /** * Determine how many locales have date/time formatting patterns available. * This function is most useful as determining the loop ending condition for * calls to {@link #udat_getAvailable }. * @return The number of locales for which date/time formatting patterns are available. * @see udat_getAvailable * @stable ICU 2.0 */ U_STABLE int32_t U_EXPORT2 udat_countAvailable(void); /** * Get the year relative to which all 2-digit years are interpreted. * For example, if the 2-digit start year is 2100, the year 99 will be * interpreted as 2199. * @param fmt The formatter to query. * @param status A pointer to an UErrorCode to receive any errors * @return The year relative to which all 2-digit years are interpreted. * @see udat_Set2DigitYearStart * @stable ICU 2.0 */ U_STABLE UDate U_EXPORT2 udat_get2DigitYearStart( const UDateFormat *fmt, UErrorCode *status); /** * Set the year relative to which all 2-digit years will be interpreted. * For example, if the 2-digit start year is 2100, the year 99 will be * interpreted as 2199. * @param fmt The formatter to set. * @param d The year relative to which all 2-digit years will be interpreted. * @param status A pointer to an UErrorCode to receive any errors * @see udat_Set2DigitYearStart * @stable ICU 2.0 */ U_STABLE void U_EXPORT2 udat_set2DigitYearStart( UDateFormat *fmt, UDate d, UErrorCode *status); /** * Extract the pattern from a UDateFormat. * The pattern will follow the pattern syntax rules. * @param fmt The formatter to query. * @param localized TRUE if the pattern should be localized, FALSE otherwise. * @param result A pointer to a buffer to receive the pattern. * @param resultLength The maximum size of result. * @param status A pointer to an UErrorCode to receive any errors * @return The total buffer size needed; if greater than resultLength, the output was truncated. * @see udat_applyPattern * @stable ICU 2.0 */ U_STABLE int32_t U_EXPORT2 udat_toPattern( const UDateFormat *fmt, UBool localized, UChar *result, int32_t resultLength, UErrorCode *status); /** * Set the pattern used by an UDateFormat. * The pattern should follow the pattern syntax rules. * @param format The formatter to set. * @param localized TRUE if the pattern is localized, FALSE otherwise. * @param pattern The new pattern * @param patternLength The length of pattern, or -1 if null-terminated. * @see udat_toPattern * @stable ICU 2.0 */ U_STABLE void U_EXPORT2 udat_applyPattern( UDateFormat *format, UBool localized, const UChar *pattern, int32_t patternLength); /** * The possible types of date format symbols * @stable ICU 2.6 */ typedef enum UDateFormatSymbolType { /** The era names, for example AD */ UDAT_ERAS, /** The month names, for example February */ UDAT_MONTHS, /** The short month names, for example Feb. */ UDAT_SHORT_MONTHS, /** The weekday names, for example Monday */ UDAT_WEEKDAYS, /** The short weekday names, for example Mon. */ UDAT_SHORT_WEEKDAYS, /** The AM/PM names, for example AM */ UDAT_AM_PMS, /** The localized characters */ UDAT_LOCALIZED_CHARS, /** The long era names, for example Anno Domini */ UDAT_ERA_NAMES, /** The narrow month names, for example F */ UDAT_NARROW_MONTHS, /** The narrow weekday names, for example N */ UDAT_NARROW_WEEKDAYS, /** Standalone context versions of months */ UDAT_STANDALONE_MONTHS, UDAT_STANDALONE_SHORT_MONTHS, UDAT_STANDALONE_NARROW_MONTHS, /** Standalone context versions of weekdays */ UDAT_STANDALONE_WEEKDAYS, UDAT_STANDALONE_SHORT_WEEKDAYS, UDAT_STANDALONE_NARROW_WEEKDAYS, /** The quarters, for example 1st Quarter */ UDAT_QUARTERS, /** The short quarter names, for example Q1 */ UDAT_SHORT_QUARTERS, /** Standalone context versions of quarters */ UDAT_STANDALONE_QUARTERS, UDAT_STANDALONE_SHORT_QUARTERS } UDateFormatSymbolType; struct UDateFormatSymbols; /** Date format symbols. * For usage in C programs. * @stable ICU 2.6 */ typedef struct UDateFormatSymbols UDateFormatSymbols; /** * Get the symbols associated with an UDateFormat. * The symbols are what a UDateFormat uses to represent locale-specific data, * for example month or day names. * @param fmt The formatter to query. * @param type The type of symbols to get. One of UDAT_ERAS, UDAT_MONTHS, UDAT_SHORT_MONTHS, * UDAT_WEEKDAYS, UDAT_SHORT_WEEKDAYS, UDAT_AM_PMS, or UDAT_LOCALIZED_CHARS * @param symbolIndex The desired symbol of type type. * @param result A pointer to a buffer to receive the pattern. * @param resultLength The maximum size of result. * @param status A pointer to an UErrorCode to receive any errors * @return The total buffer size needed; if greater than resultLength, the output was truncated. * @see udat_countSymbols * @see udat_setSymbols * @stable ICU 2.0 */ U_STABLE int32_t U_EXPORT2 udat_getSymbols(const UDateFormat *fmt, UDateFormatSymbolType type, int32_t symbolIndex, UChar *result, int32_t resultLength, UErrorCode *status); /** * Count the number of particular symbols for an UDateFormat. * This function is most useful as for detemining the loop termination condition * for calls to {@link #udat_getSymbols }. * @param fmt The formatter to query. * @param type The type of symbols to count. One of UDAT_ERAS, UDAT_MONTHS, UDAT_SHORT_MONTHS, * UDAT_WEEKDAYS, UDAT_SHORT_WEEKDAYS, UDAT_AM_PMS, or UDAT_LOCALIZED_CHARS * @return The number of symbols of type type. * @see udat_getSymbols * @see udat_setSymbols * @stable ICU 2.0 */ U_STABLE int32_t U_EXPORT2 udat_countSymbols( const UDateFormat *fmt, UDateFormatSymbolType type); /** * Set the symbols associated with an UDateFormat. * The symbols are what a UDateFormat uses to represent locale-specific data, * for example month or day names. * @param format The formatter to set * @param type The type of symbols to set. One of UDAT_ERAS, UDAT_MONTHS, UDAT_SHORT_MONTHS, * UDAT_WEEKDAYS, UDAT_SHORT_WEEKDAYS, UDAT_AM_PMS, or UDAT_LOCALIZED_CHARS * @param symbolIndex The index of the symbol to set of type type. * @param value The new value * @param valueLength The length of value, or -1 if null-terminated * @param status A pointer to an UErrorCode to receive any errors * @see udat_getSymbols * @see udat_countSymbols * @stable ICU 2.0 */ U_STABLE void U_EXPORT2 udat_setSymbols( UDateFormat *format, UDateFormatSymbolType type, int32_t symbolIndex, UChar *value, int32_t valueLength, UErrorCode *status); /** * Get the locale for this date format object. * You can choose between valid and actual locale. * @param fmt The formatter to get the locale from * @param type type of the locale we're looking for (valid or actual) * @param status error code for the operation * @return the locale name * @stable ICU 2.8 */ U_STABLE const char* U_EXPORT2 udat_getLocaleByType(const UDateFormat *fmt, ULocDataLocaleType type, UErrorCode* status); #ifndef U_HIDE_DRAFT_API /** * Set the formatter's default value for a particular context type, * such as UDAT_CAPITALIZATION. * @param fmt The formatter for which to set a context type's default value. * @param type The context type for which the default value should be set. * @param value The default value to set for the specified context type. * @param status A pointer to an UErrorCode to receive any errors * @draft ICU 49 */ U_DRAFT void U_EXPORT2 udat_setDefaultContext(UDateFormat* fmt, UDateFormatContextType type, UDateFormatContextValue value, UErrorCode* status); /** * Get the formatter's default value for a particular context type, * such as UDAT_CAPITALIZATION. * @param fmt The formatter from which to get a context type's default value. * @param type The context type for which the default value should be obtained. * @param status A pointer to an UErrorCode to receive any errors * @return The current default value for the specified context type. * @draft ICU 49 */ U_DRAFT int32_t U_EXPORT2 udat_getDefaultContext(UDateFormat* fmt, UDateFormatContextType type, UErrorCode* status); #endif /* U_HIDE_DRAFT_API */ #ifndef U_HIDE_INTERNAL_API /** * Extract the date pattern from a UDateFormat set for relative date formatting. * The pattern will follow the pattern syntax rules. * @param fmt The formatter to query. * @param result A pointer to a buffer to receive the pattern. * @param resultLength The maximum size of result. * @param status A pointer to a UErrorCode to receive any errors * @return The total buffer size needed; if greater than resultLength, the output was truncated. * @see udat_applyPatternRelative * @internal ICU 4.2 technology preview */ U_INTERNAL int32_t U_EXPORT2 udat_toPatternRelativeDate(const UDateFormat *fmt, UChar *result, int32_t resultLength, UErrorCode *status); /** * Extract the time pattern from a UDateFormat set for relative date formatting. * The pattern will follow the pattern syntax rules. * @param fmt The formatter to query. * @param result A pointer to a buffer to receive the pattern. * @param resultLength The maximum size of result. * @param status A pointer to a UErrorCode to receive any errors * @return The total buffer size needed; if greater than resultLength, the output was truncated. * @see udat_applyPatternRelative * @internal ICU 4.2 technology preview */ U_INTERNAL int32_t U_EXPORT2 udat_toPatternRelativeTime(const UDateFormat *fmt, UChar *result, int32_t resultLength, UErrorCode *status); /** * Set the date & time patterns used by a UDateFormat set for relative date formatting. * The patterns should follow the pattern syntax rules. * @param format The formatter to set. * @param datePattern The new date pattern * @param datePatternLength The length of datePattern, or -1 if null-terminated. * @param timePattern The new time pattern * @param timePatternLength The length of timePattern, or -1 if null-terminated. * @param status A pointer to a UErrorCode to receive any errors * @see udat_toPatternRelativeDate, udat_toPatternRelativeTime * @internal ICU 4.2 technology preview */ U_INTERNAL void U_EXPORT2 udat_applyPatternRelative(UDateFormat *format, const UChar *datePattern, int32_t datePatternLength, const UChar *timePattern, int32_t timePatternLength, UErrorCode *status); #endif /* U_HIDE_INTERNAL_API */ /** * @internal * @see udat_open */ typedef UDateFormat* (U_EXPORT2 *UDateFormatOpener) (UDateFormatStyle timeStyle, UDateFormatStyle dateStyle, const char *locale, const UChar *tzID, int32_t tzIDLength, const UChar *pattern, int32_t patternLength, UErrorCode *status); /** * Register a provider factory * @internal ICU 49 */ U_INTERNAL void U_EXPORT2 udat_registerOpener(UDateFormatOpener opener, UErrorCode *status); /** * Un-Register a provider factory * @internal ICU 49 */ U_INTERNAL UDateFormatOpener U_EXPORT2 udat_unregisterOpener(UDateFormatOpener opener, UErrorCode *status); #endif /* #if !UCONFIG_NO_FORMATTING */ #endif