icuSources/i18n/unicode/udatintv.h

   1 /*
   2 ******************************************************************************
   3 * Copyright (C) 2010 Apple Inc. All Rights Reserved.
   4 ******************************************************************************
   5 */
   6
   7 #ifndef UDATINTV_H
   8 #define UDATINTV_H
   9
  10 #include "unicode/utypes.h"
  11 #include "unicode/umisc.h"
  12
  13 #if !UCONFIG_NO_FORMATTING
  14
  15 struct UDateIntervalFormat;
  16 /**
  17  * A UDateIntervalFormat object for use in C programs.
  18  * @internal
  19  */
  20 typedef struct UDateIntervalFormat UDateIntervalFormat;
  21
  22 /**
  23  * A UDateIntervalFormat is used to format the range between two UDate values
  24  * in a locale-sensitive way, using a skeleton that specifies the precision and
  25  * completeness of the information to show. If the range smaller than the resolution
  26  * specified by the skeleton, a single date format will be produced. If the range
  27  * is larger than the format specified by the skeleton, a locale-specific fallback
  28  * will be used to format the items missing from the skeleton.
  29  *
  30  * For example, if the range is 2010-03-04 07:56 - 2010-03-04 19:56 (12 hours)
  31  * - The skeleton jm will produce
  32  *   for en_US, "7:56 AM – 7:56 PM"
  33  *   for en_GB, "7:56 – 19:56"
  34  * - The skeleton MMMd will produce
  35  *   for en_US, "Mar 4"
  36  *   for en_GB, "4 Mar"
  37  * If the range is 2010-03-04 07:56 - 2010-03-08 16:11 (4 days, 8 hours, 15 minutes)
  38  * - The skeleton jm will produce
  39  *   for en_US, "3/4/2010 7:56 AM – 3/8/2010 4:11 PM"
  40  *   for en_GB, "4/3/2010 7:56 – 8/3/2010 16:11"
  41  * - The skeleton MMMd will produce
  42  *   for en_US, "Mar 4–8"
  43  *   for en_GB, "4-8 Mar"
  44  *
  45  * Note, in ICU 4.4 the standard skeletons for which date interval format data
  46  * is usually available are as follows; best results will be obtained by using
  47  * skeletons from this set, or those formed by combining these standard skeletons
  48  * (note that for these skeletons, the length of digit field such as d, y, or
  49  * M vs MM is irrelevant (but for non-digit fields such as MMM vs MMMM it is
  50  * relevant). Note that a skeleton involving h or H generally explicitly requests
  51  * that time style (12- or 24-hour time respectively). For a skeleton that
  52  * requests the locale's default time style (h or H), use 'j' instead of h or H.
  53  *   h, H, hm, Hm,
  54  *   hv, Hv, hmv, Hmv,
  55  *   d,
  56  *   M, MMM, MMMM,
  57  *   Md, MMMd,
  58  *   MEd, MMMEd,
  59  *   y,
  60  *   yM, yMMM, yMMMM,
  61  *   yMd, yMMMd,
  62  *   yMEd, yMMMEd
  63  *
  64  * Locales for which ICU 4.4 seems to have a reasonable amount of this data
  65  * include:
  66  *   af, am, ar, be, bg, bn, ca, cs, da, de (_AT), el, en (_AU,_CA,_GB,_IE,_IN...),
  67  *   eo, es (_AR,_CL,_CO,...,_US) et, fa, fi, fo, fr (_BE,_CH,_CA), fur, gsw, he,
  68  *   hr, hu, hy, is, it (_CH), ja, kk, km, ko, lt, lv, mk, ml, mt, nb, nl )_BE),
  69  *   nn, pl, pt (_PT), rm, ro, ru (_UA), sk, sl, so, sq, sr, sr_Latn, sv, th, to,
  70  *   tr, uk, ur, vi, zh (_SG), zh_Hant (_HK,_MO)
  71  */
  72
  73 /**
  74  * Open a new UDateIntervalFormat object using the predefined rules for a
  75  * given locale plus a specified skeleton.
  76  * @param locale
  77  *            The locale for whose rules should be used; may be NULL for
  78  *            default locale.
  79  * @param skeleton
  80  *            A pattern containing only the fields desired for the interval
  81  *            format, for example "Hm", "yMMMd", or "yMMMEdHm".
  82  * @param length
  83  *            The length of skeleton; may be -1 if the skeleton is zero-terminated.
  84  * @param status
  85  *            A pointer to a UErrorCode to receive any errors.
  86  * @return
  87  *            A UDateIntervalFormat object for the specified locale, or NULL
  88  *            if an error occurred.
  89  * @internal
  90  */
  91 U_INTERNAL UDateIntervalFormat* U_EXPORT2
  92 udatintv_open(const char*  locale,
  93               const UChar* skeleton,
  94               int32_t      skeletonLength,
  95               UErrorCode*  status);
  96
  97 /**
  98  * Close a UDateIntervalFormat object. Once closed it may no longer be used.
  99  * @param datintv
 100  *            The UDateIntervalFormat object to close.
 101  * @internal
 102  */
 103 U_INTERNAL void U_EXPORT2
 104 udatintv_close(UDateIntervalFormat *datintv);
 105
 106 /**
 107  * Formats a date/time range using the conventions established for the
 108  * UDateIntervalFormat object.
 109  * @param datintv
 110  *            The UDateIntervalFormat object specifying the format conventions.
 111  * @param fromDate
 112  *            The starting point of the range.
 113  * @param fromDate
 114  *            The ending point of the range.
 115  * @param result
 116  *            A pointer to a buffer to receive the formatted range.
 117  * @param resultCapacity
 118  *            The maximum size of result.
 119  * @param position
 120  *            A pointer to a UFieldPosition. On input, position->field is read.
 121  *            On output, position->beginIndex and position->endIndex indicate
 122  *            the beginning and ending indices of field number position->field,
 123  *            if such a field exists. This parameter may be NULL, in which case
 124  *            no field position data is returned.
 125  * @param status
 126  *            A pointer to a UErrorCode to receive any errors.
 127  * @return
 128  *            The total buffer size needed; if greater than resultLength, the
 129  *            output was truncated.
 130  * @internal
 131  */
 132 U_INTERNAL int32_t U_EXPORT2
 133 udatintv_format(const UDateIntervalFormat* datintv,
 134                 UDate           fromDate,
 135                 UDate           toDate,
 136                 UChar*          result,
 137                 int32_t         resultCapacity,
 138                 UFieldPosition* position,
 139                 UErrorCode*     status);
 140
 141 #endif /* #if !UCONFIG_NO_FORMATTING */
 142
 143 #endif