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/**
179 * FieldPosition and UFieldPosition selectors for format fields
180 * defined by RelativeDateTimeFormatter.
181 * @stable ICU 64
182 */
183typedef enum URelativeDateTimeFormatterField {
184 /**
185 * Represents a literal text string, like "tomorrow" or "days ago".
186 * @stable ICU 64
187 */
188 UDAT_REL_LITERAL_FIELD,
189 /**
190 * Represents a number quantity, like "3" in "3 days ago".
191 * @stable ICU 64
192 */
193 UDAT_REL_NUMERIC_FIELD,
194} URelativeDateTimeFormatterField;
195
196
197/**
198 * Opaque URelativeDateTimeFormatter object for use in C programs.
199 * @stable ICU 57
200 */
201struct URelativeDateTimeFormatter;
202typedef struct URelativeDateTimeFormatter URelativeDateTimeFormatter; /**< C typedef for struct URelativeDateTimeFormatter. @stable ICU 57 */
203
204
205/**
206 * Open a new URelativeDateTimeFormatter object for a given locale using the
207 * specified width and capitalizationContext, along with a number formatter
208 * (if desired) to override the default formatter that would be used for
209 * display of numeric field offsets. The default formatter typically rounds
210 * toward 0 and has a minimum of 0 fraction digits and a maximum of 3
211 * fraction digits (i.e. it will show as many decimal places as necessary
212 * up to 3, without showing trailing 0s).
213 *
214 * @param locale
215 * The locale
216 * @param nfToAdopt
217 * A number formatter to set for this URelativeDateTimeFormatter
218 * object (instead of the default decimal formatter). Ownership of
219 * this UNumberFormat object will pass to the URelativeDateTimeFormatter
220 * object (the URelativeDateTimeFormatter adopts the UNumberFormat),
221 * which becomes responsible for closing it. If the caller wishes to
222 * retain ownership of the UNumberFormat object, the caller must clone
223 * it (with unum_clone) and pass the clone to ureldatefmt_open. May be
224 * NULL to use the default decimal formatter.
225 * @param width
226 * The width - wide, short, narrow, etc.
227 * @param capitalizationContext
228 * A value from UDisplayContext that pertains to capitalization, e.g.
229 * UDISPCTX_CAPITALIZATION_FOR_BEGINNING_OF_SENTENCE.
230 * @param status
231 * A pointer to a UErrorCode to receive any errors.
232 * @return
233 * A pointer to a URelativeDateTimeFormatter object for the specified locale,
234 * or NULL if an error occurred.
235 * @stable ICU 57
236 */
237U_STABLE URelativeDateTimeFormatter* U_EXPORT2
238ureldatefmt_open( const char* locale,
239 UNumberFormat* nfToAdopt,
240 UDateRelativeDateTimeFormatterStyle width,
241 UDisplayContext capitalizationContext,
242 UErrorCode* status );
243
244/**
245 * Close a URelativeDateTimeFormatter object. Once closed it may no longer be used.
246 * @param reldatefmt
247 * The URelativeDateTimeFormatter object to close.
248 * @stable ICU 57
249 */
250U_STABLE void U_EXPORT2
251ureldatefmt_close(URelativeDateTimeFormatter *reldatefmt);
252
253struct UFormattedRelativeDateTime;
254/**
255 * Opaque struct to contain the results of a URelativeDateTimeFormatter operation.
256 * @stable ICU 64
257 */
258typedef struct UFormattedRelativeDateTime UFormattedRelativeDateTime;
259
260/**
261 * Creates an object to hold the result of a URelativeDateTimeFormatter
262 * operation. The object can be used repeatedly; it is cleared whenever
263 * passed to a format function.
264 *
265 * @param ec Set if an error occurs.
266 * @return A pointer needing ownership.
267 * @stable ICU 64
268 */
269U_STABLE UFormattedRelativeDateTime* U_EXPORT2
270ureldatefmt_openResult(UErrorCode* ec);
271
272/**
273 * Returns a representation of a UFormattedRelativeDateTime as a UFormattedValue,
274 * which can be subsequently passed to any API requiring that type.
275 *
276 * The returned object is owned by the UFormattedRelativeDateTime and is valid
277 * only as long as the UFormattedRelativeDateTime is present and unchanged in memory.
278 *
279 * You can think of this method as a cast between types.
280 *
281 * @param ufrdt The object containing the formatted string.
282 * @param ec Set if an error occurs.
283 * @return A UFormattedValue owned by the input object.
284 * @stable ICU 64
285 */
286U_STABLE const UFormattedValue* U_EXPORT2
287ureldatefmt_resultAsValue(const UFormattedRelativeDateTime* ufrdt, UErrorCode* ec);
288
289/**
290 * Releases the UFormattedRelativeDateTime created by ureldatefmt_openResult.
291 *
292 * @param ufrdt The object to release.
293 * @stable ICU 64
294 */
295U_STABLE void U_EXPORT2
296ureldatefmt_closeResult(UFormattedRelativeDateTime* ufrdt);
297
298
299#if U_SHOW_CPLUSPLUS_API
300
301U_NAMESPACE_BEGIN
302
303/**
304 * \class LocalURelativeDateTimeFormatterPointer
305 * "Smart pointer" class, closes a URelativeDateTimeFormatter via ureldatefmt_close().
306 * For most methods see the LocalPointerBase base class.
307 *
308 * @see LocalPointerBase
309 * @see LocalPointer
310 * @stable ICU 57
311 */
312U_DEFINE_LOCAL_OPEN_POINTER(LocalURelativeDateTimeFormatterPointer, URelativeDateTimeFormatter, ureldatefmt_close);
313
314/**
315 * \class LocalUFormattedRelativeDateTimePointer
316 * "Smart pointer" class, closes a UFormattedRelativeDateTime via ureldatefmt_closeResult().
317 * For most methods see the LocalPointerBase base class.
318 *
319 * @see LocalPointerBase
320 * @see LocalPointer
321 * @stable ICU 64
322 */
323U_DEFINE_LOCAL_OPEN_POINTER(LocalUFormattedRelativeDateTimePointer, UFormattedRelativeDateTime, ureldatefmt_closeResult);
324
325U_NAMESPACE_END
326
327#endif
328
329/**
330 * Format a combination of URelativeDateTimeUnit and numeric
331 * offset using a numeric style, e.g. "1 week ago", "in 1 week",
332 * "5 weeks ago", "in 5 weeks".
333 *
334 * @param reldatefmt
335 * The URelativeDateTimeFormatter object specifying the
336 * format conventions.
337 * @param offset
338 * The signed offset for the specified unit. This will
339 * be formatted according to this object's UNumberFormat
340 * object.
341 * @param unit
342 * The unit to use when formatting the relative
343 * date, e.g. UDAT_REL_UNIT_WEEK, UDAT_REL_UNIT_FRIDAY.
344 * @param result
345 * A pointer to a buffer to receive the formatted result.
346 * @param resultCapacity
347 * The maximum size of result.
348 * @param status
349 * A pointer to a UErrorCode to receive any errors. In
350 * case of error status, the contents of result are
351 * undefined.
352 * @return
353 * The length of the formatted result; may be greater
354 * than resultCapacity, in which case an error is returned.
355 * @stable ICU 57
356 */
357U_STABLE int32_t U_EXPORT2
358ureldatefmt_formatNumeric( const URelativeDateTimeFormatter* reldatefmt,
359 double offset,
360 URelativeDateTimeUnit unit,
361 UChar* result,
362 int32_t resultCapacity,
363 UErrorCode* status);
364
365/**
366 * Format a combination of URelativeDateTimeUnit and numeric
367 * offset using a numeric style, e.g. "1 week ago", "in 1 week",
368 * "5 weeks ago", "in 5 weeks".
369 *
370 * @param reldatefmt
371 * The URelativeDateTimeFormatter object specifying the
372 * format conventions.
373 * @param offset
374 * The signed offset for the specified unit. This will
375 * be formatted according to this object's UNumberFormat
376 * object.
377 * @param unit
378 * The unit to use when formatting the relative
379 * date, e.g. UDAT_REL_UNIT_WEEK, UDAT_REL_UNIT_FRIDAY.
380 * @param result
381 * A pointer to a UFormattedRelativeDateTime to populate.
382 * @param status
383 * A pointer to a UErrorCode to receive any errors. In
384 * case of error status, the contents of result are
385 * undefined.
386 * @stable ICU 64
387 */
388U_STABLE void U_EXPORT2
389ureldatefmt_formatNumericToResult(
390 const URelativeDateTimeFormatter* reldatefmt,
391 double offset,
392 URelativeDateTimeUnit unit,
393 UFormattedRelativeDateTime* result,
394 UErrorCode* status);
395
396/**
397 * Format a combination of URelativeDateTimeUnit and numeric offset
398 * using a text style if possible, e.g. "last week", "this week",
399 * "next week", "yesterday", "tomorrow". Falls back to numeric
400 * style if no appropriate text term is available for the specified
401 * offset in the object's locale.
402 *
403 * @param reldatefmt
404 * The URelativeDateTimeFormatter object specifying the
405 * format conventions.
406 * @param offset
407 * The signed offset for the specified unit.
408 * @param unit
409 * The unit to use when formatting the relative
410 * date, e.g. UDAT_REL_UNIT_WEEK, UDAT_REL_UNIT_FRIDAY.
411 * @param result
412 * A pointer to a buffer to receive the formatted result.
413 * @param resultCapacity
414 * The maximum size of result.
415 * @param status
416 * A pointer to a UErrorCode to receive any errors. In
417 * case of error status, the contents of result are
418 * undefined.
419 * @return
420 * The length of the formatted result; may be greater
421 * than resultCapacity, in which case an error is returned.
422 * @stable ICU 57
423 */
424U_STABLE int32_t U_EXPORT2
425ureldatefmt_format( const URelativeDateTimeFormatter* reldatefmt,
426 double offset,
427 URelativeDateTimeUnit unit,
428 UChar* result,
429 int32_t resultCapacity,
430 UErrorCode* status);
431
432/**
433 * Format a combination of URelativeDateTimeUnit and numeric offset
434 * using a text style if possible, e.g. "last week", "this week",
435 * "next week", "yesterday", "tomorrow". Falls back to numeric
436 * style if no appropriate text term is available for the specified
437 * offset in the object's locale.
438 *
439 * This method populates a UFormattedRelativeDateTime, which exposes more
440 * information than the string populated by format().
441 *
442 * @param reldatefmt
443 * The URelativeDateTimeFormatter object specifying the
444 * format conventions.
445 * @param offset
446 * The signed offset for the specified unit.
447 * @param unit
448 * The unit to use when formatting the relative
449 * date, e.g. UDAT_REL_UNIT_WEEK, UDAT_REL_UNIT_FRIDAY.
450 * @param result
451 * A pointer to a UFormattedRelativeDateTime to populate.
452 * @param status
453 * A pointer to a UErrorCode to receive any errors. In
454 * case of error status, the contents of result are
455 * undefined.
456 * @stable ICU 64
457 */
458U_STABLE void U_EXPORT2
459ureldatefmt_formatToResult(
460 const URelativeDateTimeFormatter* reldatefmt,
461 double offset,
462 URelativeDateTimeUnit unit,
463 UFormattedRelativeDateTime* result,
464 UErrorCode* status);
465
466/**
467 * Combines a relative date string and a time string in this object's
468 * locale. This is done with the same date-time separator used for the
469 * default calendar in this locale to produce a result such as
470 * "yesterday at 3:45 PM".
471 *
472 * @param reldatefmt
473 * The URelativeDateTimeFormatter object specifying the format conventions.
474 * @param relativeDateString
475 * The relative date string.
476 * @param relativeDateStringLen
477 * The length of relativeDateString; may be -1 if relativeDateString
478 * is zero-terminated.
479 * @param timeString
480 * The time string.
481 * @param timeStringLen
482 * The length of timeString; may be -1 if timeString is zero-terminated.
483 * @param result
484 * A pointer to a buffer to receive the formatted result.
485 * @param resultCapacity
486 * The maximum size of result.
487 * @param status
488 * A pointer to a UErrorCode to receive any errors. In case of error status,
489 * the contents of result are undefined.
490 * @return
491 * The length of the formatted result; may be greater than resultCapacity,
492 * in which case an error is returned.
493 * @stable ICU 57
494 */
495U_STABLE int32_t U_EXPORT2
496ureldatefmt_combineDateAndTime( const URelativeDateTimeFormatter* reldatefmt,
497 const UChar * relativeDateString,
498 int32_t relativeDateStringLen,
499 const UChar * timeString,
500 int32_t timeStringLen,
501 UChar* result,
502 int32_t resultCapacity,
503 UErrorCode* status );
504
505#endif /* !UCONFIG_NO_FORMATTING && !UCONFIG_NO_BREAK_ITERATION */
506
507#endif
508