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
  21 /**
  22  * \file
  23  * \brief C API: URelativeDateTimeFormatter, relative date formatting of unit + numeric offset.
  24  *
  25  * Provides simple formatting of relative dates, in two ways
  26  * <ul>
  27  *   <li>relative dates with a quantity e.g "in 5 days"</li>
  28  *   <li>relative dates without a quantity e.g "next Tuesday"</li>
  29  * </ul>
  30  * <p>
  31  * This does not provide compound formatting for multiple units,
  32  * other than the ability to combine a time string with a relative date,
  33  * as in "next Tuesday at 3:45 PM". It also does not provide support
  34  * for determining which unit to use, such as deciding between "in 7 days"
  35  * and "in 1 week".
  36  *
  37  * @stable ICU 57
  38  */
  39
  40 /**
  41  * The formatting style
  42  * @stable ICU 54
  43  */
  44 typedef enum UDateRelativeDateTimeFormatterStyle {
  45   /**
  46    * Everything spelled out.
  47    * @stable ICU 54
  48    */
  49   UDAT_STYLE_LONG,
  50
  51   /**
  52    * Abbreviations used when possible.
  53    * @stable ICU 54
  54    */
  55   UDAT_STYLE_SHORT,
  56
  57   /**
  58    * Use the shortest possible form.
  59    * @stable ICU 54
  60    */
  61   UDAT_STYLE_NARROW,
  62
  63 #ifndef U_HIDE_DEPRECATED_API
  64     /**
  65      * One more than the highest normal UDateRelativeDateTimeFormatterStyle value.
  66      * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
  67      */
  68     UDAT_STYLE_COUNT
  69 #endif  /* U_HIDE_DEPRECATED_API */
  70 } UDateRelativeDateTimeFormatterStyle;
  71
  72 /**
  73  * Represents the unit for formatting a relative date. e.g "in 5 days"
  74  * or "next year"
  75  * @stable ICU 57
  76  */
  77 typedef enum URelativeDateTimeUnit {
  78     /**
  79      * Specifies that relative unit is year, e.g. "last year",
  80      * "in 5 years".
  81      * @stable ICU 57
  82      */
  83     UDAT_REL_UNIT_YEAR,
  84     /**
  85      * Specifies that relative unit is quarter, e.g. "last quarter",
  86      * "in 5 quarters".
  87      * @stable ICU 57
  88      */
  89     UDAT_REL_UNIT_QUARTER,
  90     /**
  91      * Specifies that relative unit is month, e.g. "last month",
  92      * "in 5 months".
  93      * @stable ICU 57
  94      */
  95     UDAT_REL_UNIT_MONTH,
  96     /**
  97      * Specifies that relative unit is week, e.g. "last week",
  98      * "in 5 weeks".
  99      * @stable ICU 57
 100      */
 101     UDAT_REL_UNIT_WEEK,
 102     /**
 103      * Specifies that relative unit is day, e.g. "yesterday",
 104      * "in 5 days".
 105      * @stable ICU 57
 106      */
 107     UDAT_REL_UNIT_DAY,
 108     /**
 109      * Specifies that relative unit is hour, e.g. "1 hour ago",
 110      * "in 5 hours".
 111      * @stable ICU 57
 112      */
 113     UDAT_REL_UNIT_HOUR,
 114     /**
 115      * Specifies that relative unit is minute, e.g. "1 minute ago",
 116      * "in 5 minutes".
 117      * @stable ICU 57
 118      */
 119     UDAT_REL_UNIT_MINUTE,
 120     /**
 121      * Specifies that relative unit is second, e.g. "1 second ago",
 122      * "in 5 seconds".
 123      * @stable ICU 57
 124      */
 125     UDAT_REL_UNIT_SECOND,
 126     /**
 127      * Specifies that relative unit is Sunday, e.g. "last Sunday",
 128      * "this Sunday", "next Sunday", "in 5 Sundays".
 129      * @stable ICU 57
 130      */
 131     UDAT_REL_UNIT_SUNDAY,
 132     /**
 133      * Specifies that relative unit is Monday, e.g. "last Monday",
 134      * "this Monday", "next Monday", "in 5 Mondays".
 135      * @stable ICU 57
 136      */
 137     UDAT_REL_UNIT_MONDAY,
 138     /**
 139      * Specifies that relative unit is Tuesday, e.g. "last Tuesday",
 140      * "this Tuesday", "next Tuesday", "in 5 Tuesdays".
 141      * @stable ICU 57
 142      */
 143     UDAT_REL_UNIT_TUESDAY,
 144     /**
 145      * Specifies that relative unit is Wednesday, e.g. "last Wednesday",
 146      * "this Wednesday", "next Wednesday", "in 5 Wednesdays".
 147      * @stable ICU 57
 148      */
 149     UDAT_REL_UNIT_WEDNESDAY,
 150     /**
 151      * Specifies that relative unit is Thursday, e.g. "last Thursday",
 152      * "this Thursday", "next Thursday", "in 5 Thursdays".
 153      * @stable ICU 57
 154      */
 155     UDAT_REL_UNIT_THURSDAY,
 156     /**
 157      * Specifies that relative unit is Friday, e.g. "last Friday",
 158      * "this Friday", "next Friday", "in 5 Fridays".
 159      * @stable ICU 57
 160      */
 161     UDAT_REL_UNIT_FRIDAY,
 162     /**
 163      * Specifies that relative unit is Saturday, e.g. "last Saturday",
 164      * "this Saturday", "next Saturday", "in 5 Saturdays".
 165      * @stable ICU 57
 166      */
 167     UDAT_REL_UNIT_SATURDAY,
 168 #ifndef U_HIDE_DEPRECATED_API
 169     /**
 170      * One more than the highest normal URelativeDateTimeUnit value.
 171      * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420.
 172      */
 173     UDAT_REL_UNIT_COUNT
 174 #endif  /* U_HIDE_DEPRECATED_API */
 175 } URelativeDateTimeUnit;
 176
 177 /**
 178  * Opaque URelativeDateTimeFormatter object for use in C programs.
 179  * @stable ICU 57
 180  */
 181 struct URelativeDateTimeFormatter;
 182 typedef struct URelativeDateTimeFormatter URelativeDateTimeFormatter;  /**< C typedef for struct URelativeDateTimeFormatter. @stable ICU 57 */
 183
 184
 185 /**
 186  * Open a new URelativeDateTimeFormatter object for a given locale using the
 187  * specified width and capitalizationContext, along with a number formatter
 188  * (if desired) to override the default formatter that would be used for
 189  * display of numeric field offsets. The default formatter typically rounds
 190  * toward 0 and has a minimum of 0 fraction digits and a maximum of 3
 191  * fraction digits (i.e. it will show as many decimal places as necessary
 192  * up to 3, without showing trailing 0s).
 193  *
 194  * @param locale
 195  *          The locale
 196  * @param nfToAdopt
 197  *          A number formatter to set for this URelativeDateTimeFormatter
 198  *          object (instead of the default decimal formatter). Ownership of
 199  *          this UNumberFormat object will pass to the URelativeDateTimeFormatter
 200  *          object (the URelativeDateTimeFormatter adopts the UNumberFormat),
 201  *          which becomes responsible for closing it. If the caller wishes to
 202  *          retain ownership of the UNumberFormat object, the caller must clone
 203  *          it (with unum_clone) and pass the clone to ureldatefmt_open. May be
 204  *          NULL to use the default decimal formatter.
 205  * @param width
 206  *          The width - wide, short, narrow, etc.
 207  * @param capitalizationContext
 208  *          A value from UDisplayContext that pertains to capitalization, e.g.
 209  *          UDISPCTX_CAPITALIZATION_FOR_BEGINNING_OF_SENTENCE.
 210  * @param status
 211  *          A pointer to a UErrorCode to receive any errors.
 212  * @return
 213  *          A pointer to a URelativeDateTimeFormatter object for the specified locale,
 214  *          or NULL if an error occurred.
 215  * @stable ICU 57
 216  */
 217 U_STABLE URelativeDateTimeFormatter* U_EXPORT2
 218 ureldatefmt_open( const char*          locale,
 219                   UNumberFormat*       nfToAdopt,
 220                   UDateRelativeDateTimeFormatterStyle width,
 221                   UDisplayContext      capitalizationContext,
 222                   UErrorCode*          status );
 223
 224 /**
 225  * Close a URelativeDateTimeFormatter object. Once closed it may no longer be used.
 226  * @param reldatefmt
 227  *            The URelativeDateTimeFormatter object to close.
 228  * @stable ICU 57
 229  */
 230 U_STABLE void U_EXPORT2
 231 ureldatefmt_close(URelativeDateTimeFormatter *reldatefmt);
 232
 233 #if U_SHOW_CPLUSPLUS_API
 234
 235 U_NAMESPACE_BEGIN
 236
 237 /**
 238  * \class LocalURelativeDateTimeFormatterPointer
 239  * "Smart pointer" class, closes a URelativeDateTimeFormatter via ureldatefmt_close().
 240  * For most methods see the LocalPointerBase base class.
 241  *
 242  * @see LocalPointerBase
 243  * @see LocalPointer
 244  * @stable ICU 57
 245  */
 246 U_DEFINE_LOCAL_OPEN_POINTER(LocalURelativeDateTimeFormatterPointer, URelativeDateTimeFormatter, ureldatefmt_close);
 247
 248 U_NAMESPACE_END
 249
 250 #endif // U_SHOW_CPLUSPLUS_API
 251
 252 /**
 253  * Format a combination of URelativeDateTimeUnit and numeric
 254  * offset using a numeric style, e.g. "1 week ago", "in 1 week",
 255  * "5 weeks ago", "in 5 weeks".
 256  *
 257  * @param reldatefmt
 258  *          The URelativeDateTimeFormatter object specifying the
 259  *          format conventions.
 260  * @param offset
 261  *          The signed offset for the specified unit. This will
 262  *          be formatted according to this object's UNumberFormat
 263  *          object.
 264  * @param unit
 265  *          The unit to use when formatting the relative
 266  *          date, e.g. UDAT_REL_UNIT_WEEK, UDAT_REL_UNIT_FRIDAY.
 267  * @param result
 268  *          A pointer to a buffer to receive the formatted result.
 269  * @param resultCapacity
 270  *          The maximum size of result.
 271  * @param status
 272  *          A pointer to a UErrorCode to receive any errors. In
 273  *          case of error status, the contents of result are
 274  *          undefined.
 275  * @return
 276  *          The length of the formatted result; may be greater
 277  *          than resultCapacity, in which case an error is returned.
 278  * @stable ICU 57
 279  */
 280 U_STABLE int32_t U_EXPORT2
 281 ureldatefmt_formatNumeric( const URelativeDateTimeFormatter* reldatefmt,
 282                     double                offset,
 283                     URelativeDateTimeUnit unit,
 284                     UChar*                result,
 285                     int32_t               resultCapacity,
 286                     UErrorCode*           status);
 287
 288 /**
 289  * Format a combination of URelativeDateTimeUnit and numeric offset
 290  * using a text style if possible, e.g. "last week", "this week",
 291  * "next week", "yesterday", "tomorrow". Falls back to numeric
 292  * style if no appropriate text term is available for the specified
 293  * offset in the object's locale.
 294  *
 295  * @param reldatefmt
 296  *          The URelativeDateTimeFormatter object specifying the
 297  *          format conventions.
 298  * @param offset
 299  *          The signed offset for the specified unit.
 300  * @param unit
 301  *          The unit to use when formatting the relative
 302  *          date, e.g. UDAT_REL_UNIT_WEEK, UDAT_REL_UNIT_FRIDAY.
 303  * @param result
 304  *          A pointer to a buffer to receive the formatted result.
 305  * @param resultCapacity
 306  *          The maximum size of result.
 307  * @param status
 308  *          A pointer to a UErrorCode to receive any errors. In
 309  *          case of error status, the contents of result are
 310  *          undefined.
 311  * @return
 312  *          The length of the formatted result; may be greater
 313  *          than resultCapacity, in which case an error is returned.
 314  * @stable ICU 57
 315  */
 316 U_STABLE int32_t U_EXPORT2
 317 ureldatefmt_format( const URelativeDateTimeFormatter* reldatefmt,
 318                     double                offset,
 319                     URelativeDateTimeUnit unit,
 320                     UChar*                result,
 321                     int32_t               resultCapacity,
 322                     UErrorCode*           status);
 323
 324 /**
 325  * Combines a relative date string and a time string in this object's
 326  * locale. This is done with the same date-time separator used for the
 327  * default calendar in this locale to produce a result such as
 328  * "yesterday at 3:45 PM".
 329  *
 330  * @param reldatefmt
 331  *          The URelativeDateTimeFormatter object specifying the format conventions.
 332  * @param relativeDateString
 333  *          The relative date string.
 334  * @param relativeDateStringLen
 335  *          The length of relativeDateString; may be -1 if relativeDateString
 336  *          is zero-terminated.
 337  * @param timeString
 338  *          The time string.
 339  * @param timeStringLen
 340  *          The length of timeString; may be -1 if timeString is zero-terminated.
 341  * @param result
 342  *          A pointer to a buffer to receive the formatted result.
 343  * @param resultCapacity
 344  *          The maximum size of result.
 345  * @param status
 346  *          A pointer to a UErrorCode to receive any errors. In case of error status,
 347  *          the contents of result are undefined.
 348  * @return
 349  *          The length of the formatted result; may be greater than resultCapacity,
 350  *          in which case an error is returned.
 351  * @stable ICU 57
 352  */
 353 U_STABLE int32_t U_EXPORT2
 354 ureldatefmt_combineDateAndTime( const URelativeDateTimeFormatter* reldatefmt,
 355                     const UChar *     relativeDateString,
 356                     int32_t           relativeDateStringLen,
 357                     const UChar *     timeString,
 358                     int32_t           timeStringLen,
 359                     UChar*            result,
 360                     int32_t           resultCapacity,
 361                     UErrorCode*       status );
 362
 363 #endif /* !UCONFIG_NO_FORMATTING && !UCONFIG_NO_BREAK_ITERATION */
 364
 365 #endif