icuSources/i18n/unicode/udateintervalformat.h

   1 // © 2016 and later: Unicode, Inc. and others.
   2 // License & terms of use: http://www.unicode.org/copyright.html
   3 /*
   4 *****************************************************************************************
   5 * Copyright (C) 2010-2012,2015-2016 International Business Machines
   6 * Corporation and others. All Rights Reserved.
   7 *****************************************************************************************
   8 */
   9
  10 #ifndef UDATEINTERVALFORMAT_H
  11 #define UDATEINTERVALFORMAT_H
  12
  13 #include "unicode/utypes.h"
  14
  15 #if !UCONFIG_NO_FORMATTING
  16
  17 #include "unicode/umisc.h"
  18 #include "unicode/localpointer.h"
  19
  20 /**
  21  * \file
  22  * \brief C API: Format a date interval.
  23  *
  24  * A UDateIntervalFormat is used to format the range between two UDate values
  25  * in a locale-sensitive way, using a skeleton that specifies the precision and
  26  * completeness of the information to show. If the range smaller than the resolution
  27  * specified by the skeleton, a single date format will be produced. If the range
  28  * is larger than the format specified by the skeleton, a locale-specific fallback
  29  * will be used to format the items missing from the skeleton.
  30  *
  31  * For example, if the range is 2010-03-04 07:56 - 2010-03-04 19:56 (12 hours)
  32  * - The skeleton jm will produce
  33  *   for en_US, "7:56 AM - 7:56 PM"
  34  *   for en_GB, "7:56 - 19:56"
  35  * - The skeleton MMMd will produce
  36  *   for en_US, "Mar 4"
  37  *   for en_GB, "4 Mar"
  38  * If the range is 2010-03-04 07:56 - 2010-03-08 16:11 (4 days, 8 hours, 15 minutes)
  39  * - The skeleton jm will produce
  40  *   for en_US, "3/4/2010 7:56 AM - 3/8/2010 4:11 PM"
  41  *   for en_GB, "4/3/2010 7:56 - 8/3/2010 16:11"
  42  * - The skeleton MMMd will produce
  43  *   for en_US, "Mar 4-8"
  44  *   for en_GB, "4-8 Mar"
  45  *
  46  * Note:  the "-" characters in the above sample output will actually be
  47  * Unicode 2013, EN_DASH, in all but the last example.
  48  *
  49  * Note, in ICU 4.4 the standard skeletons for which date interval format data
  50  * is usually available are as follows; best results will be obtained by using
  51  * skeletons from this set, or those formed by combining these standard skeletons
  52  * (note that for these skeletons, the length of digit field such as d, y, or
  53  * M vs MM is irrelevant (but for non-digit fields such as MMM vs MMMM it is
  54  * relevant). Note that a skeleton involving h or H generally explicitly requests
  55  * that time style (12- or 24-hour time respectively). For a skeleton that
  56  * requests the locale's default time style (h or H), use 'j' instead of h or H.
  57  *   h, H, hm, Hm,
  58  *   hv, Hv, hmv, Hmv,
  59  *   d,
  60  *   M, MMM, MMMM,
  61  *   Md, MMMd,
  62  *   MEd, MMMEd,
  63  *   y,
  64  *   yM, yMMM, yMMMM,
  65  *   yMd, yMMMd,
  66  *   yMEd, yMMMEd
  67  *
  68  * Locales for which ICU 4.4 seems to have a reasonable amount of this data
  69  * include:
  70  *   af, am, ar, be, bg, bn, ca, cs, da, de (_AT), el, en (_AU,_CA,_GB,_IE,_IN...),
  71  *   eo, es (_AR,_CL,_CO,...,_US) et, fa, fi, fo, fr (_BE,_CH,_CA), fur, gsw, he,
  72  *   hr, hu, hy, is, it (_CH), ja, kk, km, ko, lt, lv, mk, ml, mt, nb, nl )_BE),
  73  *   nn, pl, pt (_PT), rm, ro, ru (_UA), sk, sl, so, sq, sr, sr_Latn, sv, th, to,
  74  *   tr, uk, ur, vi, zh (_SG), zh_Hant (_HK,_MO)
  75  */
  76
  77 /**
  78  * Opaque UDateIntervalFormat object for use in C programs.
  79  * @stable ICU 4.8
  80  */
  81 struct UDateIntervalFormat;
  82 typedef struct UDateIntervalFormat UDateIntervalFormat;  /**< C typedef for struct UDateIntervalFormat. @stable ICU 4.8 */
  83
  84 /**
  85  * Open a new UDateIntervalFormat object using the predefined rules for a
  86  * given locale plus a specified skeleton.
  87  * @param locale
  88  *            The locale for whose rules should be used; may be NULL for
  89  *            default locale.
  90  * @param skeleton
  91  *            A pattern containing only the fields desired for the interval
  92  *            format, for example "Hm", "yMMMd", or "yMMMEdHm".
  93  * @param skeletonLength
  94  *            The length of skeleton; may be -1 if the skeleton is zero-terminated.
  95  * @param tzID
  96  *            A timezone ID specifying the timezone to use. If 0, use the default
  97  *            timezone.
  98  * @param tzIDLength
  99  *            The length of tzID, or -1 if null-terminated. If 0, use the default
 100  *            timezone.
 101  * @param status
 102  *            A pointer to a UErrorCode to receive any errors.
 103  * @return
 104  *            A pointer to a UDateIntervalFormat object for the specified locale,
 105  *            or NULL if an error occurred.
 106  * @stable ICU 4.8
 107  */
 108 U_STABLE UDateIntervalFormat* U_EXPORT2
 109 udtitvfmt_open(const char*  locale,
 110               const UChar* skeleton,
 111               int32_t      skeletonLength,
 112               const UChar* tzID,
 113               int32_t      tzIDLength,
 114               UErrorCode*  status);
 115
 116 /**
 117  * Close a UDateIntervalFormat object. Once closed it may no longer be used.
 118  * @param formatter
 119  *            The UDateIntervalFormat object to close.
 120  * @stable ICU 4.8
 121  */
 122 U_STABLE void U_EXPORT2
 123 udtitvfmt_close(UDateIntervalFormat *formatter);
 124
 125
 126 #if U_SHOW_CPLUSPLUS_API
 127
 128 U_NAMESPACE_BEGIN
 129
 130 /**
 131  * \class LocalUDateIntervalFormatPointer
 132  * "Smart pointer" class, closes a UDateIntervalFormat via udtitvfmt_close().
 133  * For most methods see the LocalPointerBase base class.
 134  *
 135  * @see LocalPointerBase
 136  * @see LocalPointer
 137  * @stable ICU 4.8
 138  */
 139 U_DEFINE_LOCAL_OPEN_POINTER(LocalUDateIntervalFormatPointer, UDateIntervalFormat, udtitvfmt_close);
 140
 141 U_NAMESPACE_END
 142
 143 #endif // U_SHOW_CPLUSPLUS_API
 144
 145
 146 /**
 147  * Formats a date/time range using the conventions established for the
 148  * UDateIntervalFormat object.
 149  * @param formatter
 150  *            The UDateIntervalFormat object specifying the format conventions.
 151  * @param fromDate
 152  *            The starting point of the range.
 153  * @param toDate
 154  *            The ending point of the range.
 155  * @param result
 156  *            A pointer to a buffer to receive the formatted range.
 157  * @param resultCapacity
 158  *            The maximum size of result.
 159  * @param position
 160  *            A pointer to a UFieldPosition. On input, position->field is read.
 161  *            On output, position->beginIndex and position->endIndex indicate
 162  *            the beginning and ending indices of field number position->field,
 163  *            if such a field exists. This parameter may be NULL, in which case
 164  *            no field position data is returned.
 165  *            There may be multiple instances of a given field type in an
 166  *            interval format; in this case the position indices refer to the
 167  *            first instance.
 168  * @param status
 169  *            A pointer to a UErrorCode to receive any errors.
 170  * @return
 171  *            The total buffer size needed; if greater than resultLength, the
 172  *            output was truncated.
 173  * @stable ICU 4.8
 174  */
 175 U_STABLE int32_t U_EXPORT2
 176 udtitvfmt_format(const UDateIntervalFormat* formatter,
 177                 UDate           fromDate,
 178                 UDate           toDate,
 179                 UChar*          result,
 180                 int32_t         resultCapacity,
 181                 UFieldPosition* position,
 182                 UErrorCode*     status);
 183
 184 #ifndef U_HIDE_DRAFT_API
 185 /**
 186  * Attributes and values to control the behavior of udtitvfmt_format.
 187  * @internal
 188  */
 189 typedef enum UDateIntervalFormatAttribute {
 190     /**
 191      * @internal
 192      */
 193     UDTITVFMT_MINIMIZE_TYPE
 194 } UDateIntervalFormatAttribute;
 195
 196 typedef enum UDateIntervalFormatAttributeValue {
 197     /**
 198      * Standard behavior, no additional minimization.
 199      * @internal
 200      */
 201     UDTITVFMT_MINIMIZE_NONE = 0,
 202     /**
 203      * For intervals of less than 1 month that cross month boundaries,
 204      * only show one month (use format for greatestDifference=d).
 205      * @internal
 206      */
 207     UDTITVFMT_MINIMIZE_ADJACENT_MONTHS,
 208     /**
 209      * For intervals of less than 12 hours that cross day boundaries,
 210      * only show one day (use format for greatestDifference=h).
 211      * @internal
 212      */
 213     UDTITVFMT_MINIMIZE_ADJACENT_DAYS
 214 } UDateIntervalFormatAttributeValue;
 215
 216 /**
 217  * Change attributes for the UDateIntervalFormat object.
 218  * @param formatter
 219  *            The UDateIntervalFormat object whose attributes are to be changed.
 220  * @param attr
 221  *            The attribute to change.
 222  * @param value
 223  *            The new value for the attribute.
 224  * @param status
 225  *            A pointer to a UErrorCode to receive any errors.
 226  * @internal
 227  */
 228 U_INTERNAL void U_EXPORT2
 229 udtitvfmt_setAttribute(UDateIntervalFormat*             formatter,
 230                       UDateIntervalFormatAttribute      attr,
 231                       UDateIntervalFormatAttributeValue value,
 232                       UErrorCode*                       status);
 233
 234 #endif  /* U_HIDE_DRAFT_API */
 235 #endif /* #if !UCONFIG_NO_FORMATTING */
 236
 237 #endif