icuSources/i18n/unicode/reldatefmt.h

   1 // © 2016 and later: Unicode, Inc. and others.
   2 // License & terms of use: http://www.unicode.org/copyright.html
   3 /*
   4 *****************************************************************************
   5 * Copyright (C) 2014-2016, International Business Machines Corporation and
   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"
  18 #include "unicode/uobject.h"
  19 #include "unicode/udisplaycontext.h"
  20 #include "unicode/ureldatefmt.h"
  21 #include "unicode/locid.h"
  22
  23 /**
  24  * \file
  25  * \brief C++ API: Formats relative dates such as "1 day ago" or "tomorrow"
  26  */
  27
  28 #if !UCONFIG_NO_FORMATTING
  29
  30 /**
  31  * Represents the unit for formatting a relative date. e.g "in 5 days"
  32  * or "in 3 months"
  33  * @stable ICU 53
  34  */
  35 typedef enum UDateRelativeUnit {
  36
  37     /**
  38      * Seconds
  39      * @stable ICU 53
  40      */
  41     UDAT_RELATIVE_SECONDS,
  42
  43     /**
  44      * Minutes
  45      * @stable ICU 53
  46      */
  47     UDAT_RELATIVE_MINUTES,
  48
  49     /**
  50      * Hours
  51      * @stable ICU 53
  52      */
  53     UDAT_RELATIVE_HOURS,
  54
  55     /**
  56      * Days
  57      * @stable ICU 53
  58      */
  59     UDAT_RELATIVE_DAYS,
  60
  61     /**
  62      * Weeks
  63      * @stable ICU 53
  64      */
  65     UDAT_RELATIVE_WEEKS,
  66
  67     /**
  68      * Months
  69      * @stable ICU 53
  70      */
  71     UDAT_RELATIVE_MONTHS,
  72
  73     /**
  74      * Years
  75      * @stable ICU 53
  76      */
  77     UDAT_RELATIVE_YEARS,
  78
  79 #ifndef U_HIDE_DEPRECATED_API
  80     /**
  81      * One more than the highest normal UDateRelativeUnit value.
  82      * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
  83      */
  84     UDAT_RELATIVE_UNIT_COUNT
  85 #endif  // U_HIDE_DEPRECATED_API
  86 } UDateRelativeUnit;
  87
  88 /**
  89  * Represents an absolute unit.
  90  * @stable ICU 53
  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
  98      * @stable ICU 53
  99      */
 100     UDAT_ABSOLUTE_SUNDAY,
 101
 102     /**
 103      * Monday
 104      * @stable ICU 53
 105      */
 106     UDAT_ABSOLUTE_MONDAY,
 107
 108     /**
 109      * Tuesday
 110      * @stable ICU 53
 111      */
 112     UDAT_ABSOLUTE_TUESDAY,
 113
 114     /**
 115      * Wednesday
 116      * @stable ICU 53
 117      */
 118     UDAT_ABSOLUTE_WEDNESDAY,
 119
 120     /**
 121      * Thursday
 122      * @stable ICU 53
 123      */
 124     UDAT_ABSOLUTE_THURSDAY,
 125
 126     /**
 127      * Friday
 128      * @stable ICU 53
 129      */
 130     UDAT_ABSOLUTE_FRIDAY,
 131
 132     /**
 133      * Saturday
 134      * @stable ICU 53
 135      */
 136     UDAT_ABSOLUTE_SATURDAY,
 137
 138     /**
 139      * Day
 140      * @stable ICU 53
 141      */
 142     UDAT_ABSOLUTE_DAY,
 143
 144     /**
 145      * Week
 146      * @stable ICU 53
 147      */
 148     UDAT_ABSOLUTE_WEEK,
 149
 150     /**
 151      * Month
 152      * @stable ICU 53
 153      */
 154     UDAT_ABSOLUTE_MONTH,
 155
 156     /**
 157      * Year
 158      * @stable ICU 53
 159      */
 160     UDAT_ABSOLUTE_YEAR,
 161
 162     /**
 163      * Now
 164      * @stable ICU 53
 165      */
 166     UDAT_ABSOLUTE_NOW,
 167
 168 #ifndef U_HIDE_DEPRECATED_API
 169     /**
 170      * One more than the highest normal UDateAbsoluteUnit value.
 171      * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
 172      */
 173     UDAT_ABSOLUTE_UNIT_COUNT
 174 #endif  // U_HIDE_DEPRECATED_API
 175 } UDateAbsoluteUnit;
 176
 177 /**
 178  * Represents a direction for an absolute unit e.g "Next Tuesday"
 179  * or "Last Tuesday"
 180  * @stable ICU 53
 181  */
 182 typedef enum UDateDirection {
 183
 184     /**
 185      * Two before. Not fully supported in every locale.
 186      * @stable ICU 53
 187      */
 188     UDAT_DIRECTION_LAST_2,
 189
 190     /**
 191      * Last
 192      * @stable ICU 53
 193      */
 194     UDAT_DIRECTION_LAST,
 195
 196     /**
 197      * This
 198      * @stable ICU 53
 199      */
 200     UDAT_DIRECTION_THIS,
 201
 202     /**
 203      * Next
 204      * @stable ICU 53
 205      */
 206     UDAT_DIRECTION_NEXT,
 207
 208     /**
 209      * Two after. Not fully supported in every locale.
 210      * @stable ICU 53
 211      */
 212     UDAT_DIRECTION_NEXT_2,
 213
 214     /**
 215      * Plain, which means the absence of a qualifier.
 216      * @stable ICU 53
 217      */
 218     UDAT_DIRECTION_PLAIN,
 219
 220 #ifndef U_HIDE_DEPRECATED_API
 221     /**
 222      * One more than the highest normal UDateDirection value.
 223      * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
 224      */
 225     UDAT_DIRECTION_COUNT
 226 #endif  // U_HIDE_DEPRECATED_API
 227 } UDateDirection;
 228
 229 #if !UCONFIG_NO_BREAK_ITERATION
 230
 231 #if U_SHOW_CPLUSPLUS_API
 232 U_NAMESPACE_BEGIN
 233
 234 class BreakIterator;
 235 class RelativeDateTimeCacheData;
 236 class SharedNumberFormat;
 237 class SharedPluralRules;
 238 class SharedBreakIterator;
 239 class NumberFormat;
 240 class UnicodeString;
 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  *
 308  * @stable ICU 53
 309  */
 310 class U_I18N_API RelativeDateTimeFormatter : public UObject {
 311 public:
 312
 313     /**
 314      * Create RelativeDateTimeFormatter with default locale.
 315      * @stable ICU 53
 316      */
 317     RelativeDateTimeFormatter(UErrorCode& status);
 318
 319     /**
 320      * Create RelativeDateTimeFormatter with given locale.
 321      * @stable ICU 53
 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.
 333      * @stable ICU 53
 334      */
 335     RelativeDateTimeFormatter(
 336         const Locale& locale, NumberFormat *nfToAdopt, UErrorCode& status);
 337
 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.
 351      * @stable ICU 54
 352      */
 353     RelativeDateTimeFormatter(
 354             const Locale& locale,
 355             NumberFormat *nfToAdopt,
 356             UDateRelativeDateTimeFormatterStyle style,
 357             UDisplayContext capitalizationContext,
 358             UErrorCode& status);
 359
 360     /**
 361      * Copy constructor.
 362      * @stable ICU 53
 363      */
 364     RelativeDateTimeFormatter(const RelativeDateTimeFormatter& other);
 365
 366     /**
 367      * Assignment operator.
 368      * @stable ICU 53
 369      */
 370     RelativeDateTimeFormatter& operator=(
 371             const RelativeDateTimeFormatter& other);
 372
 373     /**
 374      * Destructor.
 375      * @stable ICU 53
 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
 392      * @stable ICU 53
 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
 411      * @stable ICU 53
 412      */
 413     UnicodeString& format(
 414             UDateDirection direction,
 415             UDateAbsoluteUnit unit,
 416             UnicodeString& appendTo,
 417             UErrorCode& status) const;
 418
 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
 434      * @stable ICU 57
 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
 457      * @stable ICU 57
 458      */
 459     UnicodeString& format(
 460             double offset,
 461             URelativeDateTimeUnit unit,
 462             UnicodeString& appendTo,
 463             UErrorCode& status) const;
 464
 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
 475      * @stable ICU 53
 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      *
 486      * @stable ICU 53
 487      */
 488     const NumberFormat& getNumberFormat() const;
 489
 490     /**
 491      * Returns the capitalization context.
 492      *
 493      * @stable ICU 54
 494      */
 495     UDisplayContext getCapitalizationContext() const;
 496
 497     /**
 498      * Returns the format style.
 499      *
 500      * @stable ICU 54
 501      */
 502     UDateRelativeDateTimeFormatterStyle getFormatStyle() const;
 503
 504 private:
 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;
 517 };
 518
 519 U_NAMESPACE_END
 520 #endif // U_SHOW_CPLUSPLUS_API
 521
 522 #endif /* !UCONFIG_NO_BREAK_ITERATION */
 523 #endif /* !UCONFIG_NO_FORMATTING */
 524 #endif /* __RELDATEFMT_H */