]> git.saurik.com Git - apple/icu.git/blame - icuSources/i18n/unicode/reldatefmt.h
ICU-59180.0.1.tar.gz
[apple/icu.git] / icuSources / i18n / unicode / reldatefmt.h
CommitLineData
f3c0d7a5
A
1// © 2016 and later: Unicode, Inc. and others.
2// License & terms of use: http://www.unicode.org/copyright.html
57a6839d
A
3/*
4*****************************************************************************
2ca993e8 5* Copyright (C) 2014-2016, International Business Machines Corporation and
57a6839d
A
6* others.
7* All Rights Reserved.
8*****************************************************************************
9*
10* File RELDATEFMT.H
11*****************************************************************************
12*/
13
14#ifndef __RELDATEFMT_H
15#define __RELDATEFMT_H
16
17#include "unicode/utypes.h"
b331163b
A
18#include "unicode/uobject.h"
19#include "unicode/udisplaycontext.h"
2ca993e8 20#include "unicode/ureldatefmt.h"
b331163b 21#include "unicode/locid.h"
57a6839d
A
22
23/**
24 * \file
25 * \brief C++ API: Formats relative dates such as "1 day ago" or "tomorrow"
26 */
27
f3c0d7a5 28#if !UCONFIG_NO_FORMATTING
57a6839d 29
57a6839d
A
30/**
31 * Represents the unit for formatting a relative date. e.g "in 5 days"
32 * or "in 3 months"
b331163b 33 * @stable ICU 53
57a6839d
A
34 */
35typedef enum UDateRelativeUnit {
36
37 /**
38 * Seconds
b331163b 39 * @stable ICU 53
57a6839d
A
40 */
41 UDAT_RELATIVE_SECONDS,
42
43 /**
44 * Minutes
b331163b 45 * @stable ICU 53
57a6839d
A
46 */
47 UDAT_RELATIVE_MINUTES,
48
49 /**
50 * Hours
b331163b 51 * @stable ICU 53
57a6839d
A
52 */
53 UDAT_RELATIVE_HOURS,
54
55 /**
56 * Days
b331163b 57 * @stable ICU 53
57a6839d
A
58 */
59 UDAT_RELATIVE_DAYS,
60
61 /**
62 * Weeks
b331163b 63 * @stable ICU 53
57a6839d
A
64 */
65 UDAT_RELATIVE_WEEKS,
66
67 /**
68 * Months
b331163b 69 * @stable ICU 53
57a6839d
A
70 */
71 UDAT_RELATIVE_MONTHS,
72
73 /**
74 * Years
b331163b 75 * @stable ICU 53
57a6839d
A
76 */
77 UDAT_RELATIVE_YEARS,
78
f3c0d7a5 79#ifndef U_HIDE_DEPRECATED_API
57a6839d 80 /**
f3c0d7a5
A
81 * One more than the highest normal UDateRelativeUnit value.
82 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
57a6839d
A
83 */
84 UDAT_RELATIVE_UNIT_COUNT
f3c0d7a5 85#endif // U_HIDE_DEPRECATED_API
57a6839d
A
86} UDateRelativeUnit;
87
88/**
89 * Represents an absolute unit.
b331163b 90 * @stable ICU 53
57a6839d
A
91 */
92typedef enum UDateAbsoluteUnit {
93
94 // Days of week have to remain together and in order from Sunday to
95 // Saturday.
96 /**
97 * Sunday
b331163b 98 * @stable ICU 53
57a6839d
A
99 */
100 UDAT_ABSOLUTE_SUNDAY,
101
102 /**
103 * Monday
b331163b 104 * @stable ICU 53
57a6839d
A
105 */
106 UDAT_ABSOLUTE_MONDAY,
107
108 /**
109 * Tuesday
b331163b 110 * @stable ICU 53
57a6839d
A
111 */
112 UDAT_ABSOLUTE_TUESDAY,
113
114 /**
115 * Wednesday
b331163b 116 * @stable ICU 53
57a6839d
A
117 */
118 UDAT_ABSOLUTE_WEDNESDAY,
119
120 /**
121 * Thursday
b331163b 122 * @stable ICU 53
57a6839d
A
123 */
124 UDAT_ABSOLUTE_THURSDAY,
125
126 /**
127 * Friday
b331163b 128 * @stable ICU 53
57a6839d
A
129 */
130 UDAT_ABSOLUTE_FRIDAY,
131
132 /**
133 * Saturday
b331163b 134 * @stable ICU 53
57a6839d
A
135 */
136 UDAT_ABSOLUTE_SATURDAY,
137
138 /**
139 * Day
b331163b 140 * @stable ICU 53
57a6839d
A
141 */
142 UDAT_ABSOLUTE_DAY,
143
144 /**
145 * Week
b331163b 146 * @stable ICU 53
57a6839d
A
147 */
148 UDAT_ABSOLUTE_WEEK,
149
150 /**
151 * Month
b331163b 152 * @stable ICU 53
57a6839d
A
153 */
154 UDAT_ABSOLUTE_MONTH,
155
156 /**
157 * Year
b331163b 158 * @stable ICU 53
57a6839d
A
159 */
160 UDAT_ABSOLUTE_YEAR,
161
162 /**
163 * Now
b331163b 164 * @stable ICU 53
57a6839d
A
165 */
166 UDAT_ABSOLUTE_NOW,
167
f3c0d7a5 168#ifndef U_HIDE_DEPRECATED_API
57a6839d 169 /**
f3c0d7a5
A
170 * One more than the highest normal UDateAbsoluteUnit value.
171 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
57a6839d
A
172 */
173 UDAT_ABSOLUTE_UNIT_COUNT
f3c0d7a5 174#endif // U_HIDE_DEPRECATED_API
57a6839d
A
175} UDateAbsoluteUnit;
176
177/**
178 * Represents a direction for an absolute unit e.g "Next Tuesday"
179 * or "Last Tuesday"
b331163b 180 * @stable ICU 53
57a6839d
A
181 */
182typedef enum UDateDirection {
183
184 /**
185 * Two before. Not fully supported in every locale.
b331163b 186 * @stable ICU 53
57a6839d
A
187 */
188 UDAT_DIRECTION_LAST_2,
189
190 /**
191 * Last
b331163b 192 * @stable ICU 53
57a6839d
A
193 */
194 UDAT_DIRECTION_LAST,
195
196 /**
197 * This
b331163b 198 * @stable ICU 53
57a6839d
A
199 */
200 UDAT_DIRECTION_THIS,
201
202 /**
203 * Next
b331163b 204 * @stable ICU 53
57a6839d
A
205 */
206 UDAT_DIRECTION_NEXT,
207
208 /**
209 * Two after. Not fully supported in every locale.
b331163b 210 * @stable ICU 53
57a6839d
A
211 */
212 UDAT_DIRECTION_NEXT_2,
213
214 /**
215 * Plain, which means the absence of a qualifier.
b331163b 216 * @stable ICU 53
57a6839d
A
217 */
218 UDAT_DIRECTION_PLAIN,
219
f3c0d7a5 220#ifndef U_HIDE_DEPRECATED_API
57a6839d 221 /**
f3c0d7a5
A
222 * One more than the highest normal UDateDirection value.
223 * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
57a6839d
A
224 */
225 UDAT_DIRECTION_COUNT
f3c0d7a5 226#endif // U_HIDE_DEPRECATED_API
57a6839d
A
227} UDateDirection;
228
f3c0d7a5 229#if !UCONFIG_NO_BREAK_ITERATION
57a6839d 230
f3c0d7a5 231#if U_SHOW_CPLUSPLUS_API
57a6839d
A
232U_NAMESPACE_BEGIN
233
f3c0d7a5 234class BreakIterator;
57a6839d
A
235class RelativeDateTimeCacheData;
236class SharedNumberFormat;
237class SharedPluralRules;
b331163b 238class SharedBreakIterator;
57a6839d 239class NumberFormat;
b331163b 240class UnicodeString;
57a6839d
A
241
242/**
243 * Formats simple relative dates. There are two types of relative dates that
244 * it handles:
245 * <ul>
246 * <li>relative dates with a quantity e.g "in 5 days"</li>
247 * <li>relative dates without a quantity e.g "next Tuesday"</li>
248 * </ul>
249 * <p>
250 * This API is very basic and is intended to be a building block for more
251 * fancy APIs. The caller tells it exactly what to display in a locale
252 * independent way. While this class automatically provides the correct plural
253 * forms, the grammatical form is otherwise as neutral as possible. It is the
254 * caller's responsibility to handle cut-off logic such as deciding between
255 * displaying "in 7 days" or "in 1 week." This API supports relative dates
256 * involving one single unit. This API does not support relative dates
257 * involving compound units,
258 * e.g "in 5 days and 4 hours" nor does it support parsing.
259 * <p>
260 * This class is mostly thread safe and immutable with the following caveats:
261 * 1. The assignment operator violates Immutability. It must not be used
262 * concurrently with other operations.
263 * 2. Caller must not hold onto adopted pointers.
264 * <p>
265 * This class is not intended for public subclassing.
266 * <p>
267 * Here are some examples of use:
268 * <blockquote>
269 * <pre>
270 * UErrorCode status = U_ZERO_ERROR;
271 * UnicodeString appendTo;
272 * RelativeDateTimeFormatter fmt(status);
273 * // Appends "in 1 day"
274 * fmt.format(
275 * 1, UDAT_DIRECTION_NEXT, UDAT_RELATIVE_DAYS, appendTo, status);
276 * // Appends "in 3 days"
277 * fmt.format(
278 * 3, UDAT_DIRECTION_NEXT, UDAT_RELATIVE_DAYS, appendTo, status);
279 * // Appends "3.2 years ago"
280 * fmt.format(
281 * 3.2, UDAT_DIRECTION_LAST, UDAT_RELATIVE_YEARS, appendTo, status);
282 * // Appends "last Sunday"
283 * fmt.format(UDAT_DIRECTION_LAST, UDAT_ABSOLUTE_SUNDAY, appendTo, status);
284 * // Appends "this Sunday"
285 * fmt.format(UDAT_DIRECTION_THIS, UDAT_ABSOLUTE_SUNDAY, appendTo, status);
286 * // Appends "next Sunday"
287 * fmt.format(UDAT_DIRECTION_NEXT, UDAT_ABSOLUTE_SUNDAY, appendTo, status);
288 * // Appends "Sunday"
289 * fmt.format(UDAT_DIRECTION_PLAIN, UDAT_ABSOLUTE_SUNDAY, appendTo, status);
290 *
291 * // Appends "yesterday"
292 * fmt.format(UDAT_DIRECTION_LAST, UDAT_ABSOLUTE_DAY, appendTo, status);
293 * // Appends "today"
294 * fmt.format(UDAT_DIRECTION_THIS, UDAT_ABSOLUTE_DAY, appendTo, status);
295 * // Appends "tomorrow"
296 * fmt.format(UDAT_DIRECTION_NEXT, UDAT_ABSOLUTE_DAY, appendTo, status);
297 * // Appends "now"
298 * fmt.format(UDAT_DIRECTION_PLAIN, UDAT_ABSOLUTE_NOW, appendTo, status);
299 *
300 * </pre>
301 * </blockquote>
302 * <p>
303 * In the future, we may add more forms, such as abbreviated/short forms
304 * (3 secs ago), and relative day periods ("yesterday afternoon"), etc.
305 *
306 * The RelativeDateTimeFormatter class is not intended for public subclassing.
307 *
b331163b 308 * @stable ICU 53
57a6839d 309 */
57a6839d
A
310class U_I18N_API RelativeDateTimeFormatter : public UObject {
311public:
312
313 /**
314 * Create RelativeDateTimeFormatter with default locale.
b331163b 315 * @stable ICU 53
57a6839d
A
316 */
317 RelativeDateTimeFormatter(UErrorCode& status);
318
319 /**
320 * Create RelativeDateTimeFormatter with given locale.
b331163b 321 * @stable ICU 53
57a6839d
A
322 */
323 RelativeDateTimeFormatter(const Locale& locale, UErrorCode& status);
324
325 /**
326 * Create RelativeDateTimeFormatter with given locale and NumberFormat.
327 *
328 * @param locale the locale
329 * @param nfToAdopt Constructed object takes ownership of this pointer.
330 * It is an error for caller to delete this pointer or change its
331 * contents after calling this constructor.
332 * @status Any error is returned here.
b331163b 333 * @stable ICU 53
57a6839d
A
334 */
335 RelativeDateTimeFormatter(
336 const Locale& locale, NumberFormat *nfToAdopt, UErrorCode& status);
337
b331163b
A
338 /**
339 * Create RelativeDateTimeFormatter with given locale, NumberFormat,
340 * and capitalization context.
341 *
342 * @param locale the locale
343 * @param nfToAdopt Constructed object takes ownership of this pointer.
344 * It is an error for caller to delete this pointer or change its
345 * contents after calling this constructor. Caller may pass NULL for
346 * this argument if they want default number format behavior.
347 * @param style the format style. The UDAT_RELATIVE bit field has no effect.
348 * @param capitalizationContext A value from UDisplayContext that pertains to
349 * capitalization.
350 * @status Any error is returned here.
2ca993e8 351 * @stable ICU 54
b331163b
A
352 */
353 RelativeDateTimeFormatter(
354 const Locale& locale,
355 NumberFormat *nfToAdopt,
356 UDateRelativeDateTimeFormatterStyle style,
357 UDisplayContext capitalizationContext,
358 UErrorCode& status);
b331163b 359
57a6839d
A
360 /**
361 * Copy constructor.
b331163b 362 * @stable ICU 53
57a6839d
A
363 */
364 RelativeDateTimeFormatter(const RelativeDateTimeFormatter& other);
365
366 /**
367 * Assignment operator.
b331163b 368 * @stable ICU 53
57a6839d
A
369 */
370 RelativeDateTimeFormatter& operator=(
371 const RelativeDateTimeFormatter& other);
372
373 /**
374 * Destructor.
b331163b 375 * @stable ICU 53
57a6839d
A
376 */
377 virtual ~RelativeDateTimeFormatter();
378
379 /**
380 * Formats a relative date with a quantity such as "in 5 days" or
381 * "3 months ago"
382 * @param quantity The numerical amount e.g 5. This value is formatted
383 * according to this object's NumberFormat object.
384 * @param direction NEXT means a future relative date; LAST means a past
385 * relative date. If direction is anything else, this method sets
386 * status to U_ILLEGAL_ARGUMENT_ERROR.
387 * @param unit the unit e.g day? month? year?
388 * @param appendTo The string to which the formatted result will be
389 * appended
390 * @param status ICU error code returned here.
391 * @return appendTo
b331163b 392 * @stable ICU 53
57a6839d
A
393 */
394 UnicodeString& format(
395 double quantity,
396 UDateDirection direction,
397 UDateRelativeUnit unit,
398 UnicodeString& appendTo,
399 UErrorCode& status) const;
400
401 /**
402 * Formats a relative date without a quantity.
403 * @param direction NEXT, LAST, THIS, etc.
404 * @param unit e.g SATURDAY, DAY, MONTH
405 * @param appendTo The string to which the formatted result will be
406 * appended. If the value of direction is documented as not being fully
407 * supported in all locales then this method leaves appendTo unchanged if
408 * no format string is available.
409 * @param status ICU error code returned here.
410 * @return appendTo
b331163b 411 * @stable ICU 53
57a6839d
A
412 */
413 UnicodeString& format(
414 UDateDirection direction,
415 UDateAbsoluteUnit unit,
416 UnicodeString& appendTo,
417 UErrorCode& status) const;
418
2ca993e8
A
419 /**
420 * Format a combination of URelativeDateTimeUnit and numeric offset
421 * using a numeric style, e.g. "1 week ago", "in 1 week",
422 * "5 weeks ago", "in 5 weeks".
423 *
424 * @param offset The signed offset for the specified unit. This
425 * will be formatted according to this object's
426 * NumberFormat object.
427 * @param unit The unit to use when formatting the relative
428 * date, e.g. UDAT_REL_UNIT_WEEK,
429 * UDAT_REL_UNIT_FRIDAY.
430 * @param appendTo The string to which the formatted result will be
431 * appended.
432 * @param status ICU error code returned here.
433 * @return appendTo
f3c0d7a5 434 * @stable ICU 57
2ca993e8
A
435 */
436 UnicodeString& formatNumeric(
437 double offset,
438 URelativeDateTimeUnit unit,
439 UnicodeString& appendTo,
440 UErrorCode& status) const;
441
442 /**
443 * Format a combination of URelativeDateTimeUnit and numeric offset
444 * using a text style if possible, e.g. "last week", "this week",
445 * "next week", "yesterday", "tomorrow". Falls back to numeric
446 * style if no appropriate text term is available for the specified
447 * offset in the object's locale.
448 *
449 * @param offset The signed offset for the specified unit.
450 * @param unit The unit to use when formatting the relative
451 * date, e.g. UDAT_REL_UNIT_WEEK,
452 * UDAT_REL_UNIT_FRIDAY.
453 * @param appendTo The string to which the formatted result will be
454 * appended.
455 * @param status ICU error code returned here.
456 * @return appendTo
f3c0d7a5 457 * @stable ICU 57
2ca993e8
A
458 */
459 UnicodeString& format(
460 double offset,
461 URelativeDateTimeUnit unit,
462 UnicodeString& appendTo,
463 UErrorCode& status) const;
2ca993e8 464
57a6839d
A
465 /**
466 * Combines a relative date string and a time string in this object's
467 * locale. This is done with the same date-time separator used for the
468 * default calendar in this locale.
469 *
470 * @param relativeDateString the relative date, e.g 'yesterday'
471 * @param timeString the time e.g '3:45'
472 * @param appendTo concatenated date and time appended here
473 * @param status ICU error code returned here.
474 * @return appendTo
b331163b 475 * @stable ICU 53
57a6839d
A
476 */
477 UnicodeString& combineDateAndTime(
478 const UnicodeString& relativeDateString,
479 const UnicodeString& timeString,
480 UnicodeString& appendTo,
481 UErrorCode& status) const;
482
483 /**
484 * Returns the NumberFormat this object is using.
485 *
b331163b 486 * @stable ICU 53
57a6839d
A
487 */
488 const NumberFormat& getNumberFormat() const;
489
b331163b
A
490 /**
491 * Returns the capitalization context.
492 *
2ca993e8 493 * @stable ICU 54
b331163b
A
494 */
495 UDisplayContext getCapitalizationContext() const;
496
497 /**
498 * Returns the format style.
499 *
2ca993e8 500 * @stable ICU 54
b331163b
A
501 */
502 UDateRelativeDateTimeFormatterStyle getFormatStyle() const;
b331163b 503
57a6839d 504private:
b331163b
A
505 const RelativeDateTimeCacheData* fCache;
506 const SharedNumberFormat *fNumberFormat;
507 const SharedPluralRules *fPluralRules;
508 UDateRelativeDateTimeFormatterStyle fStyle;
509 UDisplayContext fContext;
510 const SharedBreakIterator *fOptBreakIterator;
511 Locale fLocale;
512 void init(
513 NumberFormat *nfToAdopt,
514 BreakIterator *brkIter,
515 UErrorCode &status);
516 void adjustForContext(UnicodeString &) const;
57a6839d
A
517};
518
519U_NAMESPACE_END
f3c0d7a5 520#endif // U_SHOW_CPLUSPLUS_API
57a6839d 521
f3c0d7a5
A
522#endif /* !UCONFIG_NO_BREAK_ITERATION */
523#endif /* !UCONFIG_NO_FORMATTING */
524#endif /* __RELDATEFMT_H */