// © 2016 and later: Unicode, Inc. and others. // License & terms of use: http://www.unicode.org/copyright.html /* ***************************************************************************************** * Copyright (C) 2010-2012,2015-2016 International Business Machines * Corporation and others. All Rights Reserved. ***************************************************************************************** */ #ifndef UDATEINTERVALFORMAT_H #define UDATEINTERVALFORMAT_H #include "unicode/utypes.h" #if !UCONFIG_NO_FORMATTING #include "unicode/umisc.h" #include "unicode/localpointer.h" #include "unicode/uformattedvalue.h" #include "unicode/udisplaycontext.h" /** * \file * \brief C API: Format a date interval. * * A UDateIntervalFormat is used to format the range between two UDate values * in a locale-sensitive way, using a skeleton that specifies the precision and * completeness of the information to show. If the range smaller than the resolution * specified by the skeleton, a single date format will be produced. If the range * is larger than the format specified by the skeleton, a locale-specific fallback * will be used to format the items missing from the skeleton. * * For example, if the range is 2010-03-04 07:56 - 2010-03-04 19:56 (12 hours) * - The skeleton jm will produce * for en_US, "7:56 AM - 7:56 PM" * for en_GB, "7:56 - 19:56" * - The skeleton MMMd will produce * for en_US, "Mar 4" * for en_GB, "4 Mar" * If the range is 2010-03-04 07:56 - 2010-03-08 16:11 (4 days, 8 hours, 15 minutes) * - The skeleton jm will produce * for en_US, "3/4/2010 7:56 AM - 3/8/2010 4:11 PM" * for en_GB, "4/3/2010 7:56 - 8/3/2010 16:11" * - The skeleton MMMd will produce * for en_US, "Mar 4-8" * for en_GB, "4-8 Mar" * * Note: the "-" characters in the above sample output will actually be * Unicode 2013, EN_DASH, in all but the last example. * * Note, in ICU 4.4 the standard skeletons for which date interval format data * is usually available are as follows; best results will be obtained by using * skeletons from this set, or those formed by combining these standard skeletons * (note that for these skeletons, the length of digit field such as d, y, or * M vs MM is irrelevant (but for non-digit fields such as MMM vs MMMM it is * relevant). Note that a skeleton involving h or H generally explicitly requests * that time style (12- or 24-hour time respectively). For a skeleton that * requests the locale's default time style (h or H), use 'j' instead of h or H. * h, H, hm, Hm, * hv, Hv, hmv, Hmv, * d, * M, MMM, MMMM, * Md, MMMd, * MEd, MMMEd, * y, * yM, yMMM, yMMMM, * yMd, yMMMd, * yMEd, yMMMEd * * Locales for which ICU 4.4 seems to have a reasonable amount of this data * include: * af, am, ar, be, bg, bn, ca, cs, da, de (_AT), el, en (_AU,_CA,_GB,_IE,_IN...), * eo, es (_AR,_CL,_CO,...,_US) et, fa, fi, fo, fr (_BE,_CH,_CA), fur, gsw, he, * hr, hu, hy, is, it (_CH), ja, kk, km, ko, lt, lv, mk, ml, mt, nb, nl )_BE), * nn, pl, pt (_PT), rm, ro, ru (_UA), sk, sl, so, sq, sr, sr_Latn, sv, th, to, * tr, uk, ur, vi, zh (_SG), zh_Hant (_HK,_MO) */ /** * Opaque UDateIntervalFormat object for use in C programs. * @stable ICU 4.8 */ struct UDateIntervalFormat; typedef struct UDateIntervalFormat UDateIntervalFormat; /**< C typedef for struct UDateIntervalFormat. @stable ICU 4.8 */ #ifndef U_HIDE_DRAFT_API struct UFormattedDateInterval; /** * Opaque struct to contain the results of a UDateIntervalFormat operation. * @draft ICU 64 */ typedef struct UFormattedDateInterval UFormattedDateInterval; #endif /* U_HIDE_DRAFT_API */ /** * Open a new UDateIntervalFormat object using the predefined rules for a * given locale plus a specified skeleton. * @param locale * The locale for whose rules should be used; may be NULL for * default locale. * @param skeleton * A pattern containing only the fields desired for the interval * format, for example "Hm", "yMMMd", or "yMMMEdHm". * @param skeletonLength * The length of skeleton; may be -1 if the skeleton is zero-terminated. * @param tzID * A timezone ID specifying the timezone to use. If 0, use the default * timezone. * @param tzIDLength * The length of tzID, or -1 if null-terminated. If 0, use the default * timezone. * @param status * A pointer to a UErrorCode to receive any errors. * @return * A pointer to a UDateIntervalFormat object for the specified locale, * or NULL if an error occurred. * @stable ICU 4.8 */ U_STABLE UDateIntervalFormat* U_EXPORT2 udtitvfmt_open(const char* locale, const UChar* skeleton, int32_t skeletonLength, const UChar* tzID, int32_t tzIDLength, UErrorCode* status); /** * Close a UDateIntervalFormat object. Once closed it may no longer be used. * @param formatter * The UDateIntervalFormat object to close. * @stable ICU 4.8 */ U_STABLE void U_EXPORT2 udtitvfmt_close(UDateIntervalFormat *formatter); #ifndef U_HIDE_DRAFT_API /** * Creates an object to hold the result of a UDateIntervalFormat * operation. The object can be used repeatedly; it is cleared whenever * passed to a format function. * * @param ec Set if an error occurs. * @return A pointer needing ownership. * @draft ICU 64 */ U_CAPI UFormattedDateInterval* U_EXPORT2 udtitvfmt_openResult(UErrorCode* ec); /** * Returns a representation of a UFormattedDateInterval as a UFormattedValue, * which can be subsequently passed to any API requiring that type. * * The returned object is owned by the UFormattedDateInterval and is valid * only as long as the UFormattedDateInterval is present and unchanged in memory. * * You can think of this method as a cast between types. * * When calling ufmtval_nextPosition(): * The fields are returned from left to right. The special field category * UFIELD_CATEGORY_DATE_INTERVAL_SPAN is used to indicate which datetime * primitives came from which arguments: 0 means fromCalendar, and 1 means * toCalendar. The span category will always occur before the * corresponding fields in UFIELD_CATEGORY_DATE * in the ufmtval_nextPosition() iterator. * * @param uresult The object containing the formatted string. * @param ec Set if an error occurs. * @return A UFormattedValue owned by the input object. * @draft ICU 64 */ U_CAPI const UFormattedValue* U_EXPORT2 udtitvfmt_resultAsValue(const UFormattedDateInterval* uresult, UErrorCode* ec); /** * Releases the UFormattedDateInterval created by udtitvfmt_openResult(). * * @param uresult The object to release. * @draft ICU 64 */ U_CAPI void U_EXPORT2 udtitvfmt_closeResult(UFormattedDateInterval* uresult); #endif /* U_HIDE_DRAFT_API */ #if U_SHOW_CPLUSPLUS_API U_NAMESPACE_BEGIN /** * \class LocalUDateIntervalFormatPointer * "Smart pointer" class, closes a UDateIntervalFormat via udtitvfmt_close(). * For most methods see the LocalPointerBase base class. * * @see LocalPointerBase * @see LocalPointer * @stable ICU 4.8 */ U_DEFINE_LOCAL_OPEN_POINTER(LocalUDateIntervalFormatPointer, UDateIntervalFormat, udtitvfmt_close); #ifndef U_HIDE_DRAFT_API /** * \class LocalUFormattedDateIntervalPointer * "Smart pointer" class, closes a UFormattedDateInterval via udtitvfmt_close(). * For most methods see the LocalPointerBase base class. * * @see LocalPointerBase * @see LocalPointer * @draft ICU 64 */ U_DEFINE_LOCAL_OPEN_POINTER(LocalUFormattedDateIntervalPointer, UFormattedDateInterval, udtitvfmt_closeResult); #endif /* U_HIDE_DRAFT_API */ U_NAMESPACE_END #endif /** * Formats a date/time range using the conventions established for the * UDateIntervalFormat object. * @param formatter * The UDateIntervalFormat object specifying the format conventions. * @param fromDate * The starting point of the range. * @param toDate * The ending point of the range. * @param result * A pointer to a buffer to receive the formatted range. * @param resultCapacity * The maximum size of result. * @param position * A pointer to a UFieldPosition. On input, position->field is read. * On output, position->beginIndex and position->endIndex indicate * the beginning and ending indices of field number position->field, * if such a field exists. This parameter may be NULL, in which case * no field position data is returned. * There may be multiple instances of a given field type in an * interval format; in this case the position indices refer to the * first instance. * @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. * @stable ICU 4.8 */ U_STABLE int32_t U_EXPORT2 udtitvfmt_format(const UDateIntervalFormat* formatter, UDate fromDate, UDate toDate, UChar* result, int32_t resultCapacity, UFieldPosition* position, UErrorCode* status); #ifndef U_HIDE_DRAFT_API /** * Attributes and values to control the behavior of udtitvfmt_format. * @internal */ typedef enum UDateIntervalFormatAttribute { /** * @internal */ UDTITVFMT_MINIMIZE_TYPE } UDateIntervalFormatAttribute; typedef enum UDateIntervalFormatAttributeValue { /** * Standard behavior, no additional minimization. * @internal */ UDTITVFMT_MINIMIZE_NONE = 0, /** * For intervals of less than 1 month that cross month boundaries, * only show one month (use format for greatestDifference=d). * @internal */ UDTITVFMT_MINIMIZE_ADJACENT_MONTHS, /** * For intervals of less than 12 hours that cross day boundaries, * only show one day (use format for greatestDifference=h). * @internal */ UDTITVFMT_MINIMIZE_ADJACENT_DAYS } UDateIntervalFormatAttributeValue; /** * Change attributes for the UDateIntervalFormat object. * @param formatter * The UDateIntervalFormat object whose attributes are to be changed. * @param attr * The attribute to change. * @param value * The new value for the attribute. * @param status * A pointer to a UErrorCode to receive any errors. * @internal */ U_INTERNAL void U_EXPORT2 udtitvfmt_setAttribute(UDateIntervalFormat* formatter, UDateIntervalFormatAttribute attr, UDateIntervalFormatAttributeValue value, UErrorCode* status); #endif /* U_HIDE_DRAFT_API */ #ifndef U_HIDE_DRAFT_API /** * Formats a date/time range using the conventions established for the * UDateIntervalFormat object. * @param formatter * The UDateIntervalFormat object specifying the format conventions. * @param result * The UFormattedDateInterval to contain the result of the * formatting operation. * @param fromDate * The starting point of the range. * @param toDate * The ending point of the range. * @param status * A pointer to a UErrorCode to receive any errors. * @draft ICU 64 */ U_DRAFT void U_EXPORT2 udtitvfmt_formatToResult( const UDateIntervalFormat* formatter, UFormattedDateInterval* result, UDate fromDate, UDate toDate, UErrorCode* status); #endif /* U_HIDE_DRAFT_API */ #ifndef U_HIDE_DRAFT_API /** * Set a particular UDisplayContext value in the formatter, such as * UDISPCTX_CAPITALIZATION_FOR_STANDALONE. This causes the formatted * result to be capitalized appropriately for the context in which * it is intended to be used, considering both the locale and the * type of field at the beginning of the formatted result. * @param formatter The formatter for which to set a UDisplayContext value. * @param value The UDisplayContext value to set. * @param status A pointer to an UErrorCode to receive any errors * @draft ICU 65 */ U_DRAFT void U_EXPORT2 udtitvfmt_setContext(UDateIntervalFormat* formatter, UDisplayContext value, UErrorCode* status); /** * Get the formatter's UDisplayContext value for the specified UDisplayContextType, * such as UDISPCTX_TYPE_CAPITALIZATION. * @param formatter The formatter to query. * @param type The UDisplayContextType whose value to return * @param status A pointer to an UErrorCode to receive any errors * @return The UDisplayContextValue for the specified type. * @draft ICU 65 */ U_DRAFT UDisplayContext U_EXPORT2 udtitvfmt_getContext(const UDateIntervalFormat* formatter, UDisplayContextType type, UErrorCode* status); #endif /* U_HIDE_DRAFT_API */ #endif /* #if !UCONFIG_NO_FORMATTING */ #endif