git.saurik.com Git - apple/icu.git/blob - icuSources/i18n/unicode/udateintervalformat.h

2 // License & terms of use: http://www.unicode.org/copyright.html

3 /*

4 *****************************************************************************************

7 *****************************************************************************************

8 */

10 #ifndef UDATEINTERVALFORMAT_H

11 #define UDATEINTERVALFORMAT_H

13 #include "unicode/utypes.h"

15 #if !UCONFIG_NO_FORMATTING

17 #include "unicode/umisc.h"

18 #include "unicode/localpointer.h"

19 #include "unicode/uformattedvalue.h"

20 #include "unicode/udisplaycontext.h"

22 /**

23 * \file

24 * \brief C API: Format a date interval.

25 *

26 * A UDateIntervalFormat is used to format the range between two UDate values

27 * in a locale-sensitive way, using a skeleton that specifies the precision and

28 * completeness of the information to show. If the range smaller than the resolution

29 * specified by the skeleton, a single date format will be produced. If the range

30 * is larger than the format specified by the skeleton, a locale-specific fallback

31 * will be used to format the items missing from the skeleton.

32 *

33 * For example, if the range is 2010-03-04 07:56 - 2010-03-04 19:56 (12 hours)

34 * - The skeleton jm will produce

35 * for en_US, "7:56 AM - 7:56 PM"

36 * for en_GB, "7:56 - 19:56"

37 * - The skeleton MMMd will produce

38 * for en_US, "Mar 4"

39 * for en_GB, "4 Mar"

40 * If the range is 2010-03-04 07:56 - 2010-03-08 16:11 (4 days, 8 hours, 15 minutes)

41 * - The skeleton jm will produce

42 * for en_US, "3/4/2010 7:56 AM - 3/8/2010 4:11 PM"

43 * for en_GB, "4/3/2010 7:56 - 8/3/2010 16:11"

44 * - The skeleton MMMd will produce

45 * for en_US, "Mar 4-8"

46 * for en_GB, "4-8 Mar"

47 *

48 * Note: the "-" characters in the above sample output will actually be

49 * Unicode 2013, EN_DASH, in all but the last example.

50 *

51 * Note, in ICU 4.4 the standard skeletons for which date interval format data

52 * is usually available are as follows; best results will be obtained by using

53 * skeletons from this set, or those formed by combining these standard skeletons

54 * (note that for these skeletons, the length of digit field such as d, y, or

55 * M vs MM is irrelevant (but for non-digit fields such as MMM vs MMMM it is

56 * relevant). Note that a skeleton involving h or H generally explicitly requests

57 * that time style (12- or 24-hour time respectively). For a skeleton that

58 * requests the locale's default time style (h or H), use 'j' instead of h or H.

59 * h, H, hm, Hm,

60 * hv, Hv, hmv, Hmv,

61 * d,

62 * M, MMM, MMMM,

63 * Md, MMMd,

64 * MEd, MMMEd,

65 * y,

66 * yM, yMMM, yMMMM,

67 * yMd, yMMMd,

68 * yMEd, yMMMEd

69 *

70 * Locales for which ICU 4.4 seems to have a reasonable amount of this data

71 * include:

72 * af, am, ar, be, bg, bn, ca, cs, da, de (_AT), el, en (_AU,_CA,_GB,_IE,_IN...),

73 * eo, es (_AR,_CL,_CO,...,_US) et, fa, fi, fo, fr (_BE,_CH,_CA), fur, gsw, he,

74 * hr, hu, hy, is, it (_CH), ja, kk, km, ko, lt, lv, mk, ml, mt, nb, nl )_BE),

75 * nn, pl, pt (_PT), rm, ro, ru (_UA), sk, sl, so, sq, sr, sr_Latn, sv, th, to,

76 * tr, uk, ur, vi, zh (_SG), zh_Hant (_HK,_MO)

77 */

79 /**

80 * Opaque UDateIntervalFormat object for use in C programs.

81 * @stable ICU 4.8

82 */

83 struct UDateIntervalFormat;

84 typedef struct UDateIntervalFormat UDateIntervalFormat; /**< C typedef for struct UDateIntervalFormat. @stable ICU 4.8 */

86 #ifndef U_HIDE_DRAFT_API

87 struct UFormattedDateInterval;

88 /**

89 * Opaque struct to contain the results of a UDateIntervalFormat operation.

90 * @draft ICU 64

91 */

92 typedef struct UFormattedDateInterval UFormattedDateInterval;

93 #endif /* U_HIDE_DRAFT_API */

95 /**

96 * Open a new UDateIntervalFormat object using the predefined rules for a

97 * given locale plus a specified skeleton.

98 * @param locale

99 * The locale for whose rules should be used; may be NULL for

100 * default locale.

101 * @param skeleton

102 * A pattern containing only the fields desired for the interval

103 * format, for example "Hm", "yMMMd", or "yMMMEdHm".

104 * @param skeletonLength

105 * The length of skeleton; may be -1 if the skeleton is zero-terminated.

106 * @param tzID

107 * A timezone ID specifying the timezone to use. If 0, use the default

108 * timezone.

109 * @param tzIDLength

110 * The length of tzID, or -1 if null-terminated. If 0, use the default

111 * timezone.

112 * @param status

113 * A pointer to a UErrorCode to receive any errors.

114 * @return

115 * A pointer to a UDateIntervalFormat object for the specified locale,

116 * or NULL if an error occurred.

117 * @stable ICU 4.8

118 */

119 U_STABLE UDateIntervalFormat* U_EXPORT2

 udtitvfmt_open(const char*  locale,

121 const UChar* skeleton,

122 int32_t skeletonLength,

123 const UChar* tzID,

124 int32_t tzIDLength,

125 UErrorCode* status);

126

127 /**

128 * Close a UDateIntervalFormat object. Once closed it may no longer be used.

129 * @param formatter

130 * The UDateIntervalFormat object to close.

131 * @stable ICU 4.8

132 */

133 U_STABLE void U_EXPORT2

134 udtitvfmt_close(UDateIntervalFormat *formatter);

135

136

137 #ifndef U_HIDE_DRAFT_API

138 /**

139 * Creates an object to hold the result of a UDateIntervalFormat

140 * operation. The object can be used repeatedly; it is cleared whenever

141 * passed to a format function.

142 *

143 * @param ec Set if an error occurs.

144 * @return A pointer needing ownership.

145 * @draft ICU 64

146 */

147 U_CAPI UFormattedDateInterval* U_EXPORT2

148 udtitvfmt_openResult(UErrorCode* ec);

149

150 /**

151 * Returns a representation of a UFormattedDateInterval as a UFormattedValue,

152 * which can be subsequently passed to any API requiring that type.

153 *

154 * The returned object is owned by the UFormattedDateInterval and is valid

155 * only as long as the UFormattedDateInterval is present and unchanged in memory.

156 *

157 * You can think of this method as a cast between types.

158 *

159 * When calling ufmtval_nextPosition():

160 * The fields are returned from left to right. The special field category

161 * UFIELD_CATEGORY_DATE_INTERVAL_SPAN is used to indicate which datetime

162 * primitives came from which arguments: 0 means fromCalendar, and 1 means

163 * toCalendar. The span category will always occur before the

164 * corresponding fields in UFIELD_CATEGORY_DATE

165 * in the ufmtval_nextPosition() iterator.

166 *

167 * @param uresult The object containing the formatted string.

168 * @param ec Set if an error occurs.

169 * @return A UFormattedValue owned by the input object.

170 * @draft ICU 64

171 */

172 U_CAPI const UFormattedValue* U_EXPORT2

 udtitvfmt_resultAsValue(const UFormattedDateInterval* uresult, UErrorCode* ec);

174

175 /**

176 * Releases the UFormattedDateInterval created by udtitvfmt_openResult().

177 *

178 * @param uresult The object to release.

179 * @draft ICU 64

180 */

181 U_CAPI void U_EXPORT2

182 udtitvfmt_closeResult(UFormattedDateInterval* uresult);

183 #endif /* U_HIDE_DRAFT_API */

184

185

186 #if U_SHOW_CPLUSPLUS_API

187

188 U_NAMESPACE_BEGIN

189

190 /**

191 * \class LocalUDateIntervalFormatPointer

192 * "Smart pointer" class, closes a UDateIntervalFormat via udtitvfmt_close().

193 * For most methods see the LocalPointerBase base class.

194 *

195 * @see LocalPointerBase

196 * @see LocalPointer

197 * @stable ICU 4.8

198 */

 U_DEFINE_LOCAL_OPEN_POINTER(LocalUDateIntervalFormatPointer, UDateIntervalFormat, udtitvfmt_close);

200

201 #ifndef U_HIDE_DRAFT_API

202 /**

203 * \class LocalUFormattedDateIntervalPointer

204 * "Smart pointer" class, closes a UFormattedDateInterval via udtitvfmt_close().

205 * For most methods see the LocalPointerBase base class.

206 *

207 * @see LocalPointerBase

208 * @see LocalPointer

209 * @draft ICU 64

210 */

 U_DEFINE_LOCAL_OPEN_POINTER(LocalUFormattedDateIntervalPointer, UFormattedDateInterval, udtitvfmt_closeResult);

212 #endif /* U_HIDE_DRAFT_API */

214 U_NAMESPACE_END

216 #endif

219 /**

220 * Formats a date/time range using the conventions established for the

221 * UDateIntervalFormat object.

222 * @param formatter

223 * The UDateIntervalFormat object specifying the format conventions.

224 * @param fromDate

225 * The starting point of the range.

226 * @param toDate

227 * The ending point of the range.

228 * @param result

229 * A pointer to a buffer to receive the formatted range.

230 * @param resultCapacity

231 * The maximum size of result.

232 * @param position

233 * A pointer to a UFieldPosition. On input, position->field is read.

234 * On output, position->beginIndex and position->endIndex indicate

235 * the beginning and ending indices of field number position->field,

236 * if such a field exists. This parameter may be NULL, in which case

237 * no field position data is returned.

238 * There may be multiple instances of a given field type in an

239 * interval format; in this case the position indices refer to the

240 * first instance.

241 * @param status

242 * A pointer to a UErrorCode to receive any errors.

243 * @return

244 * The total buffer size needed; if greater than resultLength, the

245 * output was truncated.

246 * @stable ICU 4.8

247 */

248 U_STABLE int32_t U_EXPORT2

 udtitvfmt_format(const UDateIntervalFormat* formatter,

250 UDate fromDate,

251 UDate toDate,

252 UChar* result,

253 int32_t resultCapacity,

254 UFieldPosition* position,

255 UErrorCode* status);

256

257 #ifndef U_HIDE_DRAFT_API

258 /**

259 * Attributes and values to control the behavior of udtitvfmt_format.

260 * @internal

261 */

262 typedef enum UDateIntervalFormatAttribute {

263 /**

264 * @internal

265 */

266 UDTITVFMT_MINIMIZE_TYPE

267 } UDateIntervalFormatAttribute;

268

269 typedef enum UDateIntervalFormatAttributeValue {

270 /**

271 * Standard behavior, no additional minimization.

272 * @internal

273 */

274 UDTITVFMT_MINIMIZE_NONE = 0,

275 /**

276 * For intervals of less than 1 month that cross month boundaries,

277 * only show one month (use format for greatestDifference=d).

278 * @internal

279 */

280 UDTITVFMT_MINIMIZE_ADJACENT_MONTHS,

281 /**

282 * For intervals of less than 12 hours that cross day boundaries,

283 * only show one day (use format for greatestDifference=h).

284 * @internal

285 */

286 UDTITVFMT_MINIMIZE_ADJACENT_DAYS

287 } UDateIntervalFormatAttributeValue;

288

289 /**

290 * Change attributes for the UDateIntervalFormat object.

291 * @param formatter

292 * The UDateIntervalFormat object whose attributes are to be changed.

293 * @param attr

294 * The attribute to change.

295 * @param value

296 * The new value for the attribute.

297 * @param status

298 * A pointer to a UErrorCode to receive any errors.

299 * @internal

300 */

301 U_INTERNAL void U_EXPORT2

302 udtitvfmt_setAttribute(UDateIntervalFormat* formatter,

303 UDateIntervalFormatAttribute attr,

304 UDateIntervalFormatAttributeValue value,

305 UErrorCode* status);

306

307 #endif /* U_HIDE_DRAFT_API */

308

309 #ifndef U_HIDE_DRAFT_API

310 /**

311 * Formats a date/time range using the conventions established for the

312 * UDateIntervalFormat object.

313 * @param formatter

314 * The UDateIntervalFormat object specifying the format conventions.

315 * @param result

316 * The UFormattedDateInterval to contain the result of the

317 * formatting operation.

318 * @param fromDate

319 * The starting point of the range.

320 * @param toDate

321 * The ending point of the range.

322 * @param status

323 * A pointer to a UErrorCode to receive any errors.

324 * @draft ICU 64

325 */

326 U_DRAFT void U_EXPORT2

327 udtitvfmt_formatToResult(

328 const UDateIntervalFormat* formatter,

329 UFormattedDateInterval* result,

330 UDate fromDate,

331 UDate toDate,

332 UErrorCode* status);

333 #endif /* U_HIDE_DRAFT_API */

334

335 #ifndef U_HIDE_DRAFT_API

336 /**

337 * Set a particular UDisplayContext value in the formatter, such as

338 * UDISPCTX_CAPITALIZATION_FOR_STANDALONE. This causes the formatted

339 * result to be capitalized appropriately for the context in which

340 * it is intended to be used, considering both the locale and the

341 * type of field at the beginning of the formatted result.

342 * @param formatter The formatter for which to set a UDisplayContext value.

343 * @param value The UDisplayContext value to set.

344 * @param status A pointer to an UErrorCode to receive any errors

345 * @draft ICU 65

346 */

347 U_DRAFT void U_EXPORT2

 udtitvfmt_setContext(UDateIntervalFormat* formatter, UDisplayContext value, UErrorCode* status);

349

350 /**

351 * Get the formatter's UDisplayContext value for the specified UDisplayContextType,

352 * such as UDISPCTX_TYPE_CAPITALIZATION.

353 * @param formatter The formatter to query.

354 * @param type The UDisplayContextType whose value to return

355 * @param status A pointer to an UErrorCode to receive any errors

356 * @return The UDisplayContextValue for the specified type.

357 * @draft ICU 65

358 */

359 U_DRAFT UDisplayContext U_EXPORT2

 udtitvfmt_getContext(const UDateIntervalFormat* formatter, UDisplayContextType type, UErrorCode* status);

361

362 #endif /* U_HIDE_DRAFT_API */

363

364 #endif /* #if !UCONFIG_NO_FORMATTING */

365

366 #endif