1// © 2016 and later: Unicode, Inc. and others.
2// License & terms of use: http://www.unicode.org/copyright.html
3/*
4*****************************************************************************************
5* Copyright (C) 2016, International Business Machines
6* Corporation and others. All Rights Reserved.
7*****************************************************************************************
8*/
9
10#ifndef URELDATEFMT_H
11#define URELDATEFMT_H
12
13#include "unicode/utypes.h"
14
15#if !UCONFIG_NO_FORMATTING && !UCONFIG_NO_BREAK_ITERATION
16
17#include "unicode/unum.h"
18#include "unicode/udisplaycontext.h"
19#include "unicode/localpointer.h"
20#include "unicode/uformattedvalue.h"
21
22/**
23 * \file
24 * \brief C API: URelativeDateTimeFormatter, relative date formatting of unit + numeric offset.
25 *
26 * Provides simple formatting of relative dates, in two ways
27 * <ul>
28 * <li>relative dates with a quantity e.g "in 5 days"</li>
29 * <li>relative dates without a quantity e.g "next Tuesday"</li>
30 * </ul>
31 * <p>
32 * This does not provide compound formatting for multiple units,
33 * other than the ability to combine a time string with a relative date,
34 * as in "next Tuesday at 3:45 PM". It also does not provide support
35 * for determining which unit to use, such as deciding between "in 7 days"
36 * and "in 1 week".
37 *
38 * @stable ICU 57
39 */
40
41/**
42 * The formatting style
43 * @stable ICU 54
44 */
45typedef enum UDateRelativeDateTimeFormatterStyle {
46 /**
47 * Everything spelled out.
48 * @stable ICU 54
49 */
50 UDAT_STYLE_LONG,
51
52 /**
53 * Abbreviations used when possible.
54 * @stable ICU 54
55 */
56 UDAT_STYLE_SHORT,
57
58 /**
59 * Use the shortest possible form.
60 * @stable ICU 54
61 */
62 UDAT_STYLE_NARROW,
63
64#ifndef U_HIDE_DEPRECATED_API
65 /**
66 * One more than the highest normal UDateRelativeDateTimeFormatterStyle value.
67 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
68 */
69 UDAT_STYLE_COUNT
70#endif /* U_HIDE_DEPRECATED_API */
71} UDateRelativeDateTimeFormatterStyle;
72
73/**
74 * Represents the unit for formatting a relative date. e.g "in 5 days"
75 * or "next year"
76 * @stable ICU 57
77 */
78typedef enum URelativeDateTimeUnit {
79 /**
80 * Specifies that relative unit is year, e.g. "last year",
81 * "in 5 years".
82 * @stable ICU 57
83 */
84 UDAT_REL_UNIT_YEAR,
85 /**
86 * Specifies that relative unit is quarter, e.g. "last quarter",
87 * "in 5 quarters".
88 * @stable ICU 57
89 */
90 UDAT_REL_UNIT_QUARTER,
91 /**
92 * Specifies that relative unit is month, e.g. "last month",
93 * "in 5 months".
94 * @stable ICU 57
95 */
96 UDAT_REL_UNIT_MONTH,
97 /**
98 * Specifies that relative unit is week, e.g. "last week",
99 * "in 5 weeks".
100 * @stable ICU 57
101 */
102 UDAT_REL_UNIT_WEEK,
103 /**
104 * Specifies that relative unit is day, e.g. "yesterday",
105 * "in 5 days".
106 * @stable ICU 57
107 */
108 UDAT_REL_UNIT_DAY,
109 /**
110 * Specifies that relative unit is hour, e.g. "1 hour ago",
111 * "in 5 hours".
112 * @stable ICU 57
113 */
114 UDAT_REL_UNIT_HOUR,
115 /**
116 * Specifies that relative unit is minute, e.g. "1 minute ago",
117 * "in 5 minutes".
118 * @stable ICU 57
119 */
120 UDAT_REL_UNIT_MINUTE,
121 /**
122 * Specifies that relative unit is second, e.g. "1 second ago",
123 * "in 5 seconds".
124 * @stable ICU 57
125 */
126 UDAT_REL_UNIT_SECOND,
127 /**
128 * Specifies that relative unit is Sunday, e.g. "last Sunday",
129 * "this Sunday", "next Sunday", "in 5 Sundays".
130 * @stable ICU 57
131 */
132 UDAT_REL_UNIT_SUNDAY,
133 /**
134 * Specifies that relative unit is Monday, e.g. "last Monday",
135 * "this Monday", "next Monday", "in 5 Mondays".
136 * @stable ICU 57
137 */
138 UDAT_REL_UNIT_MONDAY,
139 /**
140 * Specifies that relative unit is Tuesday, e.g. "last Tuesday",
141 * "this Tuesday", "next Tuesday", "in 5 Tuesdays".
142 * @stable ICU 57
143 */
144 UDAT_REL_UNIT_TUESDAY,
145 /**
146 * Specifies that relative unit is Wednesday, e.g. "last Wednesday",
147 * "this Wednesday", "next Wednesday", "in 5 Wednesdays".
148 * @stable ICU 57
149 */
150 UDAT_REL_UNIT_WEDNESDAY,
151 /**
152 * Specifies that relative unit is Thursday, e.g. "last Thursday",
153 * "this Thursday", "next Thursday", "in 5 Thursdays".
154 * @stable ICU 57
155 */
156 UDAT_REL_UNIT_THURSDAY,
157 /**
158 * Specifies that relative unit is Friday, e.g. "last Friday",
159 * "this Friday", "next Friday", "in 5 Fridays".
160 * @stable ICU 57
161 */
162 UDAT_REL_UNIT_FRIDAY,
163 /**
164 * Specifies that relative unit is Saturday, e.g. "last Saturday",
165 * "this Saturday", "next Saturday", "in 5 Saturdays".
166 * @stable ICU 57
167 */
168 UDAT_REL_UNIT_SATURDAY,
169#ifndef U_HIDE_DEPRECATED_API
170 /**
171 * One more than the highest normal URelativeDateTimeUnit value.
172 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
173 */
174 UDAT_REL_UNIT_COUNT
175#endif /* U_HIDE_DEPRECATED_API */
176} URelativeDateTimeUnit;
177
178#ifndef U_HIDE_DRAFT_API
179/**
180 * FieldPosition and UFieldPosition selectors for format fields
181 * defined by RelativeDateTimeFormatter.
182 * @draft ICU 64
183 */
184typedef enum URelativeDateTimeFormatterField {
185 /**
186 * Represents a literal text string, like "tomorrow" or "days ago".
187 * @draft ICU 64
188 */
189 UDAT_REL_LITERAL_FIELD,
190 /**
191 * Represents a number quantity, like "3" in "3 days ago".
192 * @draft ICU 64
193 */
194 UDAT_REL_NUMERIC_FIELD,
195} URelativeDateTimeFormatterField;
196#endif // U_HIDE_DRAFT_API
197
198
199/**
200 * Opaque URelativeDateTimeFormatter object for use in C programs.
201 * @stable ICU 57
202 */
203struct URelativeDateTimeFormatter;
204typedef struct URelativeDateTimeFormatter URelativeDateTimeFormatter; /**< C typedef for struct URelativeDateTimeFormatter. @stable ICU 57 */
205
206
207/**
208 * Open a new URelativeDateTimeFormatter object for a given locale using the
209 * specified width and capitalizationContext, along with a number formatter
210 * (if desired) to override the default formatter that would be used for
211 * display of numeric field offsets. The default formatter typically rounds
212 * toward 0 and has a minimum of 0 fraction digits and a maximum of 3
213 * fraction digits (i.e. it will show as many decimal places as necessary
214 * up to 3, without showing trailing 0s).
215 *
216 * @param locale
217 * The locale
218 * @param nfToAdopt
219 * A number formatter to set for this URelativeDateTimeFormatter
220 * object (instead of the default decimal formatter). Ownership of
221 * this UNumberFormat object will pass to the URelativeDateTimeFormatter
222 * object (the URelativeDateTimeFormatter adopts the UNumberFormat),
223 * which becomes responsible for closing it. If the caller wishes to
224 * retain ownership of the UNumberFormat object, the caller must clone
225 * it (with unum_clone) and pass the clone to ureldatefmt_open. May be
226 * NULL to use the default decimal formatter.
227 * @param width
228 * The width - wide, short, narrow, etc.
229 * @param capitalizationContext
230 * A value from UDisplayContext that pertains to capitalization, e.g.
231 * UDISPCTX_CAPITALIZATION_FOR_BEGINNING_OF_SENTENCE.
232 * @param status
233 * A pointer to a UErrorCode to receive any errors.
234 * @return
235 * A pointer to a URelativeDateTimeFormatter object for the specified locale,
236 * or NULL if an error occurred.
237 * @stable ICU 57
238 */
239U_STABLE URelativeDateTimeFormatter* U_EXPORT2
240ureldatefmt_open( const char* locale,
241 UNumberFormat* nfToAdopt,
242 UDateRelativeDateTimeFormatterStyle width,
243 UDisplayContext capitalizationContext,
244 UErrorCode* status );
245
246/**
247 * Close a URelativeDateTimeFormatter object. Once closed it may no longer be used.
248 * @param reldatefmt
249 * The URelativeDateTimeFormatter object to close.
250 * @stable ICU 57
251 */
252U_STABLE void U_EXPORT2
253ureldatefmt_close(URelativeDateTimeFormatter *reldatefmt);
254
255#ifndef U_HIDE_DRAFT_API
256struct UFormattedRelativeDateTime;
257/**
258 * Opaque struct to contain the results of a URelativeDateTimeFormatter operation.
259 * @draft ICU 64
260 */
261typedef struct UFormattedRelativeDateTime UFormattedRelativeDateTime;
262
263/**
264 * Creates an object to hold the result of a URelativeDateTimeFormatter
265 * operation. The object can be used repeatedly; it is cleared whenever
266 * passed to a format function.
267 *
268 * @param ec Set if an error occurs.
269 * @return A pointer needing ownership.
270 * @draft ICU 64
271 */
272U_DRAFT UFormattedRelativeDateTime* U_EXPORT2
273ureldatefmt_openResult(UErrorCode* ec);
274
275/**
276 * Returns a representation of a UFormattedRelativeDateTime as a UFormattedValue,
277 * which can be subsequently passed to any API requiring that type.
278 *
279 * The returned object is owned by the UFormattedRelativeDateTime and is valid
280 * only as long as the UFormattedRelativeDateTime is present and unchanged in memory.
281 *
282 * You can think of this method as a cast between types.
283 *
284 * @param ufrdt The object containing the formatted string.
285 * @param ec Set if an error occurs.
286 * @return A UFormattedValue owned by the input object.
287 * @draft ICU 64
288 */
289U_DRAFT const UFormattedValue* U_EXPORT2
290ureldatefmt_resultAsValue(const UFormattedRelativeDateTime* ufrdt, UErrorCode* ec);
291
292/**
293 * Releases the UFormattedRelativeDateTime created by ureldatefmt_openResult.
294 *
295 * @param ufrdt The object to release.
296 * @draft ICU 64
297 */
298U_DRAFT void U_EXPORT2
299ureldatefmt_closeResult(UFormattedRelativeDateTime* ufrdt);
300#endif /* U_HIDE_DRAFT_API */
301
302
303#if U_SHOW_CPLUSPLUS_API
304
305U_NAMESPACE_BEGIN
306
307/**
308 * \class LocalURelativeDateTimeFormatterPointer
309 * "Smart pointer" class, closes a URelativeDateTimeFormatter via ureldatefmt_close().
310 * For most methods see the LocalPointerBase base class.
311 *
312 * @see LocalPointerBase
313 * @see LocalPointer
314 * @stable ICU 57
315 */
316U_DEFINE_LOCAL_OPEN_POINTER(LocalURelativeDateTimeFormatterPointer, URelativeDateTimeFormatter, ureldatefmt_close);
317
318#ifndef U_HIDE_DRAFT_API
319/**
320 * \class LocalUFormattedRelativeDateTimePointer
321 * "Smart pointer" class, closes a UFormattedRelativeDateTime via ureldatefmt_closeResult().
322 * For most methods see the LocalPointerBase base class.
323 *
324 * @see LocalPointerBase
325 * @see LocalPointer
326 * @draft ICU 64
327 */
328U_DEFINE_LOCAL_OPEN_POINTER(LocalUFormattedRelativeDateTimePointer, UFormattedRelativeDateTime, ureldatefmt_closeResult);
329#endif /* U_HIDE_DRAFT_API */
330
331U_NAMESPACE_END
332
333#endif
334
335/**
336 * Format a combination of URelativeDateTimeUnit and numeric
337 * offset using a numeric style, e.g. "1 week ago", "in 1 week",
338 * "5 weeks ago", "in 5 weeks".
339 *
340 * @param reldatefmt
341 * The URelativeDateTimeFormatter object specifying the
342 * format conventions.
343 * @param offset
344 * The signed offset for the specified unit. This will
345 * be formatted according to this object's UNumberFormat
346 * object.
347 * @param unit
348 * The unit to use when formatting the relative
349 * date, e.g. UDAT_REL_UNIT_WEEK, UDAT_REL_UNIT_FRIDAY.
350 * @param result
351 * A pointer to a buffer to receive the formatted result.
352 * @param resultCapacity
353 * The maximum size of result.
354 * @param status
355 * A pointer to a UErrorCode to receive any errors. In
356 * case of error status, the contents of result are
357 * undefined.
358 * @return
359 * The length of the formatted result; may be greater
360 * than resultCapacity, in which case an error is returned.
361 * @stable ICU 57
362 */
363U_STABLE int32_t U_EXPORT2
364ureldatefmt_formatNumeric( const URelativeDateTimeFormatter* reldatefmt,
365 double offset,
366 URelativeDateTimeUnit unit,
367 UChar* result,
368 int32_t resultCapacity,
369 UErrorCode* status);
370
371#ifndef U_HIDE_DRAFT_API
372/**
373 * Format a combination of URelativeDateTimeUnit and numeric
374 * offset using a numeric style, e.g. "1 week ago", "in 1 week",
375 * "5 weeks ago", "in 5 weeks".
376 *
377 * @param reldatefmt
378 * The URelativeDateTimeFormatter object specifying the
379 * format conventions.
380 * @param offset
381 * The signed offset for the specified unit. This will
382 * be formatted according to this object's UNumberFormat
383 * object.
384 * @param unit
385 * The unit to use when formatting the relative
386 * date, e.g. UDAT_REL_UNIT_WEEK, UDAT_REL_UNIT_FRIDAY.
387 * @param result
388 * A pointer to a UFormattedRelativeDateTime to populate.
389 * @param status
390 * A pointer to a UErrorCode to receive any errors. In
391 * case of error status, the contents of result are
392 * undefined.
393 * @draft ICU 64
394 */
395U_DRAFT void U_EXPORT2
396ureldatefmt_formatNumericToResult(
397 const URelativeDateTimeFormatter* reldatefmt,
398 double offset,
399 URelativeDateTimeUnit unit,
400 UFormattedRelativeDateTime* result,
401 UErrorCode* status);
402#endif /* U_HIDE_DRAFT_API */
403
404/**
405 * Format a combination of URelativeDateTimeUnit and numeric offset
406 * using a text style if possible, e.g. "last week", "this week",
407 * "next week", "yesterday", "tomorrow". Falls back to numeric
408 * style if no appropriate text term is available for the specified
409 * offset in the object's locale.
410 *
411 * @param reldatefmt
412 * The URelativeDateTimeFormatter object specifying the
413 * format conventions.
414 * @param offset
415 * The signed offset for the specified unit.
416 * @param unit
417 * The unit to use when formatting the relative
418 * date, e.g. UDAT_REL_UNIT_WEEK, UDAT_REL_UNIT_FRIDAY.
419 * @param result
420 * A pointer to a buffer to receive the formatted result.
421 * @param resultCapacity
422 * The maximum size of result.
423 * @param status
424 * A pointer to a UErrorCode to receive any errors. In
425 * case of error status, the contents of result are
426 * undefined.
427 * @return
428 * The length of the formatted result; may be greater
429 * than resultCapacity, in which case an error is returned.
430 * @stable ICU 57
431 */
432U_STABLE int32_t U_EXPORT2
433ureldatefmt_format( const URelativeDateTimeFormatter* reldatefmt,
434 double offset,
435 URelativeDateTimeUnit unit,
436 UChar* result,
437 int32_t resultCapacity,
438 UErrorCode* status);
439
440#ifndef U_HIDE_DRAFT_API
441/**
442 * Format a combination of URelativeDateTimeUnit and numeric offset
443 * using a text style if possible, e.g. "last week", "this week",
444 * "next week", "yesterday", "tomorrow". Falls back to numeric
445 * style if no appropriate text term is available for the specified
446 * offset in the object's locale.
447 *
448 * This method populates a UFormattedRelativeDateTime, which exposes more
449 * information than the string populated by format().
450 *
451 * @param reldatefmt
452 * The URelativeDateTimeFormatter object specifying the
453 * format conventions.
454 * @param offset
455 * The signed offset for the specified unit.
456 * @param unit
457 * The unit to use when formatting the relative
458 * date, e.g. UDAT_REL_UNIT_WEEK, UDAT_REL_UNIT_FRIDAY.
459 * @param result
460 * A pointer to a UFormattedRelativeDateTime to populate.
461 * @param status
462 * A pointer to a UErrorCode to receive any errors. In
463 * case of error status, the contents of result are
464 * undefined.
465 * @draft ICU 64
466 */
467U_DRAFT void U_EXPORT2
468ureldatefmt_formatToResult(
469 const URelativeDateTimeFormatter* reldatefmt,
470 double offset,
471 URelativeDateTimeUnit unit,
472 UFormattedRelativeDateTime* result,
473 UErrorCode* status);
474#endif /* U_HIDE_DRAFT_API */
475
476/**
477 * Combines a relative date string and a time string in this object's
478 * locale. This is done with the same date-time separator used for the
479 * default calendar in this locale to produce a result such as
480 * "yesterday at 3:45 PM".
481 *
482 * @param reldatefmt
483 * The URelativeDateTimeFormatter object specifying the format conventions.
484 * @param relativeDateString
485 * The relative date string.
486 * @param relativeDateStringLen
487 * The length of relativeDateString; may be -1 if relativeDateString
488 * is zero-terminated.
489 * @param timeString
490 * The time string.
491 * @param timeStringLen
492 * The length of timeString; may be -1 if timeString is zero-terminated.
493 * @param result
494 * A pointer to a buffer to receive the formatted result.
495 * @param resultCapacity
496 * The maximum size of result.
497 * @param status
498 * A pointer to a UErrorCode to receive any errors. In case of error status,
499 * the contents of result are undefined.
500 * @return
501 * The length of the formatted result; may be greater than resultCapacity,
502 * in which case an error is returned.
503 * @stable ICU 57
504 */
505U_STABLE int32_t U_EXPORT2
506ureldatefmt_combineDateAndTime( const URelativeDateTimeFormatter* reldatefmt,
507 const UChar * relativeDateString,
508 int32_t relativeDateStringLen,
509 const UChar * timeString,
510 int32_t timeStringLen,
511 UChar* result,
512 int32_t resultCapacity,
513 UErrorCode* status );
514
515#endif /* !UCONFIG_NO_FORMATTING && !UCONFIG_NO_BREAK_ITERATION */
516
517#endif
518