1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/intl/icu/source/i18n/unicode/udateintervalformat.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,181 @@
1.4 +/*
1.5 +*****************************************************************************************
1.6 +* Copyright (C) 2010-2012, International Business Machines
1.7 +* Corporation and others. All Rights Reserved.
1.8 +*****************************************************************************************
1.9 +*/
1.10 +
1.11 +#ifndef UDATEINTERVALFORMAT_H
1.12 +#define UDATEINTERVALFORMAT_H
1.13 +
1.14 +#include "unicode/utypes.h"
1.15 +
1.16 +#if !UCONFIG_NO_FORMATTING
1.17 +
1.18 +#include "unicode/umisc.h"
1.19 +#include "unicode/localpointer.h"
1.20 +
1.21 +/**
1.22 + * \file
1.23 + * \brief C API: Format a date interval.
1.24 + *
1.25 + * A UDateIntervalFormat is used to format the range between two UDate values
1.26 + * in a locale-sensitive way, using a skeleton that specifies the precision and
1.27 + * completeness of the information to show. If the range smaller than the resolution
1.28 + * specified by the skeleton, a single date format will be produced. If the range
1.29 + * is larger than the format specified by the skeleton, a locale-specific fallback
1.30 + * will be used to format the items missing from the skeleton.
1.31 + *
1.32 + * For example, if the range is 2010-03-04 07:56 - 2010-03-04 19:56 (12 hours)
1.33 + * - The skeleton jm will produce
1.34 + * for en_US, "7:56 AM - 7:56 PM"
1.35 + * for en_GB, "7:56 - 19:56"
1.36 + * - The skeleton MMMd will produce
1.37 + * for en_US, "Mar 4"
1.38 + * for en_GB, "4 Mar"
1.39 + * If the range is 2010-03-04 07:56 - 2010-03-08 16:11 (4 days, 8 hours, 15 minutes)
1.40 + * - The skeleton jm will produce
1.41 + * for en_US, "3/4/2010 7:56 AM - 3/8/2010 4:11 PM"
1.42 + * for en_GB, "4/3/2010 7:56 - 8/3/2010 16:11"
1.43 + * - The skeleton MMMd will produce
1.44 + * for en_US, "Mar 4-8"
1.45 + * for en_GB, "4-8 Mar"
1.46 + *
1.47 + * Note: the "-" characters in the above sample output will actually be
1.48 + * Unicode 2013, EN_DASH, in all but the last example.
1.49 + *
1.50 + * Note, in ICU 4.4 the standard skeletons for which date interval format data
1.51 + * is usually available are as follows; best results will be obtained by using
1.52 + * skeletons from this set, or those formed by combining these standard skeletons
1.53 + * (note that for these skeletons, the length of digit field such as d, y, or
1.54 + * M vs MM is irrelevant (but for non-digit fields such as MMM vs MMMM it is
1.55 + * relevant). Note that a skeleton involving h or H generally explicitly requests
1.56 + * that time style (12- or 24-hour time respectively). For a skeleton that
1.57 + * requests the locale's default time style (h or H), use 'j' instead of h or H.
1.58 + * h, H, hm, Hm,
1.59 + * hv, Hv, hmv, Hmv,
1.60 + * d,
1.61 + * M, MMM, MMMM,
1.62 + * Md, MMMd,
1.63 + * MEd, MMMEd,
1.64 + * y,
1.65 + * yM, yMMM, yMMMM,
1.66 + * yMd, yMMMd,
1.67 + * yMEd, yMMMEd
1.68 + *
1.69 + * Locales for which ICU 4.4 seems to have a reasonable amount of this data
1.70 + * include:
1.71 + * af, am, ar, be, bg, bn, ca, cs, da, de (_AT), el, en (_AU,_CA,_GB,_IE,_IN...),
1.72 + * eo, es (_AR,_CL,_CO,...,_US) et, fa, fi, fo, fr (_BE,_CH,_CA), fur, gsw, he,
1.73 + * hr, hu, hy, is, it (_CH), ja, kk, km, ko, lt, lv, mk, ml, mt, nb, nl )_BE),
1.74 + * nn, pl, pt (_PT), rm, ro, ru (_UA), sk, sl, so, sq, sr, sr_Latn, sv, th, to,
1.75 + * tr, uk, ur, vi, zh (_SG), zh_Hant (_HK,_MO)
1.76 + */
1.77 +
1.78 +/**
1.79 + * Opaque UDateIntervalFormat object for use in C programs.
1.80 + * @stable ICU 4.8
1.81 + */
1.82 +struct UDateIntervalFormat;
1.83 +typedef struct UDateIntervalFormat UDateIntervalFormat; /**< C typedef for struct UDateIntervalFormat. @stable ICU 4.8 */
1.84 +
1.85 +/**
1.86 + * Open a new UDateIntervalFormat object using the predefined rules for a
1.87 + * given locale plus a specified skeleton.
1.88 + * @param locale
1.89 + * The locale for whose rules should be used; may be NULL for
1.90 + * default locale.
1.91 + * @param skeleton
1.92 + * A pattern containing only the fields desired for the interval
1.93 + * format, for example "Hm", "yMMMd", or "yMMMEdHm".
1.94 + * @param skeletonLength
1.95 + * The length of skeleton; may be -1 if the skeleton is zero-terminated.
1.96 + * @param tzID
1.97 + * A timezone ID specifying the timezone to use. If 0, use the default
1.98 + * timezone.
1.99 + * @param tzIDLength
1.100 + * The length of tzID, or -1 if null-terminated. If 0, use the default
1.101 + * timezone.
1.102 + * @param status
1.103 + * A pointer to a UErrorCode to receive any errors.
1.104 + * @return
1.105 + * A pointer to a UDateIntervalFormat object for the specified locale,
1.106 + * or NULL if an error occurred.
1.107 + * @stable ICU 4.8
1.108 + */
1.109 +U_STABLE UDateIntervalFormat* U_EXPORT2
1.110 +udtitvfmt_open(const char* locale,
1.111 + const UChar* skeleton,
1.112 + int32_t skeletonLength,
1.113 + const UChar* tzID,
1.114 + int32_t tzIDLength,
1.115 + UErrorCode* status);
1.116 +
1.117 +/**
1.118 + * Close a UDateIntervalFormat object. Once closed it may no longer be used.
1.119 + * @param formatter
1.120 + * The UDateIntervalFormat object to close.
1.121 + * @stable ICU 4.8
1.122 + */
1.123 +U_STABLE void U_EXPORT2
1.124 +udtitvfmt_close(UDateIntervalFormat *formatter);
1.125 +
1.126 +
1.127 +#if U_SHOW_CPLUSPLUS_API
1.128 +
1.129 +U_NAMESPACE_BEGIN
1.130 +
1.131 +/**
1.132 + * \class LocalUDateIntervalFormatPointer
1.133 + * "Smart pointer" class, closes a UDateIntervalFormat via udtitvfmt_close().
1.134 + * For most methods see the LocalPointerBase base class.
1.135 + *
1.136 + * @see LocalPointerBase
1.137 + * @see LocalPointer
1.138 + * @stable ICU 4.8
1.139 + */
1.140 +U_DEFINE_LOCAL_OPEN_POINTER(LocalUDateIntervalFormatPointer, UDateIntervalFormat, udtitvfmt_close);
1.141 +
1.142 +U_NAMESPACE_END
1.143 +
1.144 +#endif
1.145 +
1.146 +
1.147 +/**
1.148 + * Formats a date/time range using the conventions established for the
1.149 + * UDateIntervalFormat object.
1.150 + * @param formatter
1.151 + * The UDateIntervalFormat object specifying the format conventions.
1.152 + * @param fromDate
1.153 + * The starting point of the range.
1.154 + * @param toDate
1.155 + * The ending point of the range.
1.156 + * @param result
1.157 + * A pointer to a buffer to receive the formatted range.
1.158 + * @param resultCapacity
1.159 + * The maximum size of result.
1.160 + * @param position
1.161 + * A pointer to a UFieldPosition. On input, position->field is read.
1.162 + * On output, position->beginIndex and position->endIndex indicate
1.163 + * the beginning and ending indices of field number position->field,
1.164 + * if such a field exists. This parameter may be NULL, in which case
1.165 + * no field position data is returned.
1.166 + * @param status
1.167 + * A pointer to a UErrorCode to receive any errors.
1.168 + * @return
1.169 + * The total buffer size needed; if greater than resultLength, the
1.170 + * output was truncated.
1.171 + * @stable ICU 4.8
1.172 + */
1.173 +U_STABLE int32_t U_EXPORT2
1.174 +udtitvfmt_format(const UDateIntervalFormat* formatter,
1.175 + UDate fromDate,
1.176 + UDate toDate,
1.177 + UChar* result,
1.178 + int32_t resultCapacity,
1.179 + UFieldPosition* position,
1.180 + UErrorCode* status);
1.181 +
1.182 +#endif /* #if !UCONFIG_NO_FORMATTING */
1.183 +
1.184 +#endif
