icuSources/i18n/unicode/reldatefmt.h

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