include/unicode/udateintervalformat.h

0001 // © 2016 and later: Unicode, Inc. and others.
0002 // License & terms of use: http://www.unicode.org/copyright.html
0003 /*
0004 *****************************************************************************************
0005 * Copyright (C) 2010-2012,2015 International Business Machines
0006 * Corporation and others. All Rights Reserved.
0007 *****************************************************************************************
0008 */
0009
0010 #ifndef UDATEINTERVALFORMAT_H
0011 #define UDATEINTERVALFORMAT_H
0012
0013 #include "unicode/utypes.h"
0014
0015 #if !UCONFIG_NO_FORMATTING
0016
0017 #include "unicode/ucal.h"
0018 #include "unicode/umisc.h"
0019 #include "unicode/uformattedvalue.h"
0020 #include "unicode/udisplaycontext.h"
0021
0022 #if U_SHOW_CPLUSPLUS_API
0023 #include "unicode/localpointer.h"
0024 #endif   // U_SHOW_CPLUSPLUS_API
0025
0026 /**
0027  * \file
0028  * \brief C API: Format a date interval.
0029  *
0030  * A UDateIntervalFormat is used to format the range between two UDate values
0031  * in a locale-sensitive way, using a skeleton that specifies the precision and
0032  * completeness of the information to show. If the range smaller than the resolution
0033  * specified by the skeleton, a single date format will be produced. If the range
0034  * is larger than the format specified by the skeleton, a locale-specific fallback
0035  * will be used to format the items missing from the skeleton.
0036  *
0037  * For example, if the range is 2010-03-04 07:56 - 2010-03-04 19:56 (12 hours)
0038  * - The skeleton jm will produce
0039  *   for en_US, "7:56 AM - 7:56 PM"
0040  *   for en_GB, "7:56 - 19:56"
0041  * - The skeleton MMMd will produce
0042  *   for en_US, "Mar 4"
0043  *   for en_GB, "4 Mar"
0044  * If the range is 2010-03-04 07:56 - 2010-03-08 16:11 (4 days, 8 hours, 15 minutes)
0045  * - The skeleton jm will produce
0046  *   for en_US, "3/4/2010 7:56 AM - 3/8/2010 4:11 PM"
0047  *   for en_GB, "4/3/2010 7:56 - 8/3/2010 16:11"
0048  * - The skeleton MMMd will produce
0049  *   for en_US, "Mar 4-8"
0050  *   for en_GB, "4-8 Mar"
0051  *
0052  * Note:  the "-" characters in the above sample output will actually be
0053  * Unicode 2013, EN_DASH, in all but the last example.
0054  *
0055  * Note, in ICU 4.4 the standard skeletons for which date interval format data
0056  * is usually available are as follows; best results will be obtained by using
0057  * skeletons from this set, or those formed by combining these standard skeletons
0058  * (note that for these skeletons, the length of digit field such as d, y, or
0059  * M vs MM is irrelevant (but for non-digit fields such as MMM vs MMMM it is
0060  * relevant). Note that a skeleton involving h or H generally explicitly requests
0061  * that time style (12- or 24-hour time respectively). For a skeleton that
0062  * requests the locale's default time style (h or H), use 'j' instead of h or H.
0063  *   h, H, hm, Hm,
0064  *   hv, Hv, hmv, Hmv,
0065  *   d,
0066  *   M, MMM, MMMM,
0067  *   Md, MMMd,
0068  *   MEd, MMMEd,
0069  *   y,
0070  *   yM, yMMM, yMMMM,
0071  *   yMd, yMMMd,
0072  *   yMEd, yMMMEd
0073  *
0074  * Locales for which ICU 4.4 seems to have a reasonable amount of this data
0075  * include:
0076  *   af, am, ar, be, bg, bn, ca, cs, da, de (_AT), el, en (_AU,_CA,_GB,_IE,_IN...),
0077  *   eo, es (_AR,_CL,_CO,...,_US) et, fa, fi, fo, fr (_BE,_CH,_CA), fur, gsw, he,
0078  *   hr, hu, hy, is, it (_CH), ja, kk, km, ko, lt, lv, mk, ml, mt, nb, nl )_BE),
0079  *   nn, pl, pt (_PT), rm, ro, ru (_UA), sk, sl, so, sq, sr, sr_Latn, sv, th, to,
0080  *   tr, uk, ur, vi, zh (_SG), zh_Hant (_HK,_MO)
0081  */
0082
0083 /**
0084  * Opaque UDateIntervalFormat object for use in C programs.
0085  * @stable ICU 4.8
0086  */
0087 struct UDateIntervalFormat;
0088 typedef struct UDateIntervalFormat UDateIntervalFormat;  /**< C typedef for struct UDateIntervalFormat. @stable ICU 4.8 */
0089
0090 struct UFormattedDateInterval;
0091 /**
0092  * Opaque struct to contain the results of a UDateIntervalFormat operation.
0093  * @stable ICU 64
0094  */
0095 typedef struct UFormattedDateInterval UFormattedDateInterval;
0096
0097 /**
0098  * Open a new UDateIntervalFormat object using the predefined rules for a
0099  * given locale plus a specified skeleton.
0100  * @param locale
0101  *            The locale for whose rules should be used; may be NULL for
0102  *            default locale.
0103  * @param skeleton
0104  *            A pattern containing only the fields desired for the interval
0105  *            format, for example "Hm", "yMMMd", or "yMMMEdHm".
0106  * @param skeletonLength
0107  *            The length of skeleton; may be -1 if the skeleton is zero-terminated.
0108  * @param tzID
0109  *            A timezone ID specifying the timezone to use. If 0, use the default
0110  *            timezone.
0111  * @param tzIDLength
0112  *            The length of tzID, or -1 if null-terminated. If 0, use the default
0113  *            timezone.
0114  * @param status
0115  *            A pointer to a UErrorCode to receive any errors.
0116  * @return
0117  *            A pointer to a UDateIntervalFormat object for the specified locale,
0118  *            or NULL if an error occurred.
0119  * @stable ICU 4.8
0120  */
0121 U_CAPI UDateIntervalFormat* U_EXPORT2
0122 udtitvfmt_open(const char*  locale,
0123               const UChar* skeleton,
0124               int32_t      skeletonLength,
0125               const UChar* tzID,
0126               int32_t      tzIDLength,
0127               UErrorCode*  status);
0128
0129 /**
0130  * Close a UDateIntervalFormat object. Once closed it may no longer be used.
0131  * @param formatter
0132  *            The UDateIntervalFormat object to close.
0133  * @stable ICU 4.8
0134  */
0135 U_CAPI void U_EXPORT2
0136 udtitvfmt_close(UDateIntervalFormat *formatter);
0137
0138 /**
0139  * Creates an object to hold the result of a UDateIntervalFormat
0140  * operation. The object can be used repeatedly; it is cleared whenever
0141  * passed to a format function.
0142  *
0143  * @param ec Set if an error occurs.
0144  * @return A pointer needing ownership.
0145  * @stable ICU 64
0146  */
0147 U_CAPI UFormattedDateInterval* U_EXPORT2
0148 udtitvfmt_openResult(UErrorCode* ec);
0149
0150 /**
0151  * Returns a representation of a UFormattedDateInterval as a UFormattedValue,
0152  * which can be subsequently passed to any API requiring that type.
0153  *
0154  * The returned object is owned by the UFormattedDateInterval and is valid
0155  * only as long as the UFormattedDateInterval is present and unchanged in memory.
0156  *
0157  * You can think of this method as a cast between types.
0158  *
0159  * When calling ufmtval_nextPosition():
0160  * The fields are returned from left to right. The special field category
0161  * UFIELD_CATEGORY_DATE_INTERVAL_SPAN is used to indicate which datetime
0162  * primitives came from which arguments: 0 means fromCalendar, and 1 means
0163  * toCalendar. The span category will always occur before the
0164  * corresponding fields in UFIELD_CATEGORY_DATE
0165  * in the ufmtval_nextPosition() iterator.
0166  *
0167  * @param uresult The object containing the formatted string.
0168  * @param ec Set if an error occurs.
0169  * @return A UFormattedValue owned by the input object.
0170  * @stable ICU 64
0171  */
0172 U_CAPI const UFormattedValue* U_EXPORT2
0173 udtitvfmt_resultAsValue(const UFormattedDateInterval* uresult, UErrorCode* ec);
0174
0175 /**
0176  * Releases the UFormattedDateInterval created by udtitvfmt_openResult().
0177  *
0178  * @param uresult The object to release.
0179  * @stable ICU 64
0180  */
0181 U_CAPI void U_EXPORT2
0182 udtitvfmt_closeResult(UFormattedDateInterval* uresult);
0183
0184
0185 #if U_SHOW_CPLUSPLUS_API
0186
0187 U_NAMESPACE_BEGIN
0188
0189 /**
0190  * \class LocalUDateIntervalFormatPointer
0191  * "Smart pointer" class, closes a UDateIntervalFormat via udtitvfmt_close().
0192  * For most methods see the LocalPointerBase base class.
0193  *
0194  * @see LocalPointerBase
0195  * @see LocalPointer
0196  * @stable ICU 4.8
0197  */
0198 U_DEFINE_LOCAL_OPEN_POINTER(LocalUDateIntervalFormatPointer, UDateIntervalFormat, udtitvfmt_close);
0199
0200 /**
0201  * \class LocalUFormattedDateIntervalPointer
0202  * "Smart pointer" class, closes a UFormattedDateInterval via udtitvfmt_close().
0203  * For most methods see the LocalPointerBase base class.
0204  *
0205  * @see LocalPointerBase
0206  * @see LocalPointer
0207  * @stable ICU 64
0208  */
0209 U_DEFINE_LOCAL_OPEN_POINTER(LocalUFormattedDateIntervalPointer, UFormattedDateInterval, udtitvfmt_closeResult);
0210
0211 U_NAMESPACE_END
0212
0213 #endif
0214
0215
0216 /**
0217  * Formats a date/time range using the conventions established for the
0218  * UDateIntervalFormat object.
0219  * @param formatter
0220  *            The UDateIntervalFormat object specifying the format conventions.
0221  * @param fromDate
0222  *            The starting point of the range.
0223  * @param toDate
0224  *            The ending point of the range.
0225  * @param result
0226  *            A pointer to a buffer to receive the formatted range.
0227  * @param resultCapacity
0228  *            The maximum size of result.
0229  * @param position
0230  *            A pointer to a UFieldPosition. On input, position->field is read.
0231  *            On output, position->beginIndex and position->endIndex indicate
0232  *            the beginning and ending indices of field number position->field,
0233  *            if such a field exists. This parameter may be NULL, in which case
0234  *            no field position data is returned.
0235  *            There may be multiple instances of a given field type in an
0236  *            interval format; in this case the position indices refer to the
0237  *            first instance.
0238  * @param status
0239  *            A pointer to a UErrorCode to receive any errors.
0240  * @return
0241  *            The total buffer size needed; if greater than resultLength, the
0242  *            output was truncated.
0243  * @stable ICU 4.8
0244  */
0245 U_CAPI int32_t U_EXPORT2
0246 udtitvfmt_format(const UDateIntervalFormat* formatter,
0247                 UDate           fromDate,
0248                 UDate           toDate,
0249                 UChar*          result,
0250                 int32_t         resultCapacity,
0251                 UFieldPosition* position,
0252                 UErrorCode*     status);
0253
0254
0255 /**
0256  * Formats a date/time range using the conventions established for the
0257  * UDateIntervalFormat object.
0258  * @param formatter
0259  *            The UDateIntervalFormat object specifying the format conventions.
0260  * @param fromDate
0261  *            The starting point of the range.
0262  * @param toDate
0263  *            The ending point of the range.
0264  * @param result
0265  *            The UFormattedDateInterval to contain the result of the
0266  *            formatting operation.
0267  * @param status
0268  *            A pointer to a UErrorCode to receive any errors.
0269  * @stable ICU 67
0270  */
0271 U_CAPI void U_EXPORT2
0272 udtitvfmt_formatToResult(
0273                 const UDateIntervalFormat* formatter,
0274                 UDate           fromDate,
0275                 UDate           toDate,
0276                 UFormattedDateInterval* result,
0277                 UErrorCode*     status);
0278
0279 /**
0280  * Formats a date/time range using the conventions established for the
0281  * UDateIntervalFormat object.
0282  * @param formatter
0283  *            The UDateIntervalFormat object specifying the format conventions.
0284  * @param fromCalendar
0285  *            The starting point of the range.
0286  * @param toCalendar
0287  *            The ending point of the range.
0288  * @param result
0289  *            The UFormattedDateInterval to contain the result of the
0290  *            formatting operation.
0291  * @param status
0292  *            A pointer to a UErrorCode to receive any errors.
0293  * @stable ICU 67
0294  */
0295
0296 U_CAPI void U_EXPORT2
0297 udtitvfmt_formatCalendarToResult(
0298                 const UDateIntervalFormat* formatter,
0299                 UCalendar*      fromCalendar,
0300                 UCalendar*      toCalendar,
0301                 UFormattedDateInterval* result,
0302                 UErrorCode*     status);
0303
0304 /**
0305  * Set a particular UDisplayContext value in the formatter, such as
0306  * UDISPCTX_CAPITALIZATION_FOR_STANDALONE. This causes the formatted
0307  * result to be capitalized appropriately for the context in which
0308  * it is intended to be used, considering both the locale and the
0309  * type of field at the beginning of the formatted result.
0310  * @param formatter The formatter for which to set a UDisplayContext value.
0311  * @param value The UDisplayContext value to set.
0312  * @param status A pointer to an UErrorCode to receive any errors
0313  * @stable ICU 68
0314  */
0315 U_CAPI void U_EXPORT2
0316 udtitvfmt_setContext(UDateIntervalFormat* formatter, UDisplayContext value, UErrorCode* status);
0317
0318 /**
0319  * Get the formatter's UDisplayContext value for the specified UDisplayContextType,
0320  * such as UDISPCTX_TYPE_CAPITALIZATION.
0321  * @param formatter The formatter to query.
0322  * @param type The UDisplayContextType whose value to return
0323  * @param status A pointer to an UErrorCode to receive any errors
0324  * @return The UDisplayContextValue for the specified type.
0325  * @stable ICU 68
0326  */
0327 U_CAPI UDisplayContext U_EXPORT2
0328 udtitvfmt_getContext(const UDateIntervalFormat* formatter, UDisplayContextType type, UErrorCode* status);
0329
0330 #endif /* #if !UCONFIG_NO_FORMATTING */
0331
0332 #endif