icuSources/i18n/unicode/udateintervalformat.h

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