]>
Commit | Line | Data |
---|---|---|
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 | */ |
35 | typedef 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 | */ |
92 | typedef 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 | */ |
182 | typedef 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 |
232 | U_NAMESPACE_BEGIN |
233 | ||
f3c0d7a5 | 234 | class BreakIterator; |
57a6839d A |
235 | class RelativeDateTimeCacheData; |
236 | class SharedNumberFormat; | |
237 | class SharedPluralRules; | |
b331163b | 238 | class SharedBreakIterator; |
57a6839d | 239 | class NumberFormat; |
b331163b | 240 | class 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 |
310 | class U_I18N_API RelativeDateTimeFormatter : public UObject { |
311 | public: | |
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 | 504 | private: |
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 | ||
519 | U_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 */ |