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