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