1 // Copyright (C) 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 * @draft 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 #ifndef U_HIDE_DRAFT_API 73 /** 74 * Represents the unit for formatting a relative date. e.g "in 5 days" 75 * or "next year" 76 * @draft ICU 57 77 */ 78 typedef enum URelativeDateTimeUnit { 79 /** 80 * Specifies that relative unit is year, e.g. "last year", 81 * "in 5 years". 82 * @draft 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 * @draft 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 * @draft 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 * @draft ICU 57 101 */ 102 UDAT_REL_UNIT_WEEK, 103 /** 104 * Specifies that relative unit is day, e.g. "yesterday", 105 * "in 5 days". 106 * @draft 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 * @draft 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 * @draft 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 * @draft 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 * @draft 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 * @draft 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 * @draft 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 * @draft 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 * @draft 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 * @draft 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 * @draft 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 #endif /* U_HIDE_DRAFT_API */ 178 179 #ifndef U_HIDE_DRAFT_API 180 181 /** 182 * Opaque URelativeDateTimeFormatter object for use in C programs. 183 * @draft ICU 57 184 */ 185 struct URelativeDateTimeFormatter; 186 typedef struct URelativeDateTimeFormatter URelativeDateTimeFormatter; /**< C typedef for struct URelativeDateTimeFormatter. @draft ICU 57 */ 187 188 189 /** 190 * Open a new URelativeDateTimeFormatter object for a given locale using the 191 * specified width and capitalizationContext, along with a number formatter 192 * (if desired) to override the default formatter that would be used for 193 * display of numeric field offsets. The default formatter typically rounds 194 * toward 0 and has a minimum of 0 fraction digits and a maximum of 3 195 * fraction digits (i.e. it will show as many decimal places as necessary 196 * up to 3, without showing trailing 0s). 197 * 198 * @param locale 199 * The locale 200 * @param nfToAdopt 201 * A number formatter to set for this URelativeDateTimeFormatter 202 * object (instead of the default decimal formatter). Ownership of 203 * this UNumberFormat object will pass to the URelativeDateTimeFormatter 204 * object (the URelativeDateTimeFormatter adopts the UNumberFormat), 205 * which becomes responsible for closing it. If the caller wishes to 206 * retain ownership of the UNumberFormat object, the caller must clone 207 * it (with unum_clone) and pass the clone to ureldatefmt_open. May be 208 * NULL to use the default decimal formatter. 209 * @param width 210 * The width - wide, short, narrow, etc. 211 * @param capitalizationContext 212 * A value from UDisplayContext that pertains to capitalization, e.g. 213 * UDISPCTX_CAPITALIZATION_FOR_BEGINNING_OF_SENTENCE. 214 * @param status 215 * A pointer to a UErrorCode to receive any errors. 216 * @return 217 * A pointer to a URelativeDateTimeFormatter object for the specified locale, 218 * or NULL if an error occurred. 219 * @draft ICU 57 220 */ 221 U_DRAFT URelativeDateTimeFormatter* U_EXPORT2 222 ureldatefmt_open( const char* locale, 223 UNumberFormat* nfToAdopt, 224 UDateRelativeDateTimeFormatterStyle width, 225 UDisplayContext capitalizationContext, 226 UErrorCode* status ); 227 228 /** 229 * Close a URelativeDateTimeFormatter object. Once closed it may no longer be used. 230 * @param reldatefmt 231 * The URelativeDateTimeFormatter object to close. 232 * @draft ICU 57 233 */ 234 U_DRAFT void U_EXPORT2 235 ureldatefmt_close(URelativeDateTimeFormatter *reldatefmt); 236 237 #if U_SHOW_CPLUSPLUS_API 238 239 U_NAMESPACE_BEGIN 240 241 /** 242 * \class LocalURelativeDateTimeFormatterPointer 243 * "Smart pointer" class, closes a URelativeDateTimeFormatter via ureldatefmt_close(). 244 * For most methods see the LocalPointerBase base class. 245 * 246 * @see LocalPointerBase 247 * @see LocalPointer 248 * @draft ICU 57 249 */ 250 U_DEFINE_LOCAL_OPEN_POINTER(LocalURelativeDateTimeFormatterPointer, URelativeDateTimeFormatter, ureldatefmt_close); 251 252 U_NAMESPACE_END 253 254 #endif 255 256 /** 257 * Format a combination of URelativeDateTimeUnit and numeric 258 * offset using a numeric style, e.g. "1 week ago", "in 1 week", 259 * "5 weeks ago", "in 5 weeks". 260 * 261 * @param reldatefmt 262 * The URelativeDateTimeFormatter object specifying the 263 * format conventions. 264 * @param offset 265 * The signed offset for the specified unit. This will 266 * be formatted according to this object's UNumberFormat 267 * object. 268 * @param unit 269 * The unit to use when formatting the relative 270 * date, e.g. UDAT_REL_UNIT_WEEK, UDAT_REL_UNIT_FRIDAY. 271 * @param result 272 * A pointer to a buffer to receive the formatted result. 273 * @param resultCapacity 274 * The maximum size of result. 275 * @param status 276 * A pointer to a UErrorCode to receive any errors. In 277 * case of error status, the contents of result are 278 * undefined. 279 * @return 280 * The length of the formatted result; may be greater 281 * than resultCapacity, in which case an error is returned. 282 * @draft ICU 57 283 */ 284 U_DRAFT int32_t U_EXPORT2 285 ureldatefmt_formatNumeric( const URelativeDateTimeFormatter* reldatefmt, 286 double offset, 287 URelativeDateTimeUnit unit, 288 UChar* result, 289 int32_t resultCapacity, 290 UErrorCode* status); 291 292 /** 293 * Format a combination of URelativeDateTimeUnit and numeric offset 294 * using a text style if possible, e.g. "last week", "this week", 295 * "next week", "yesterday", "tomorrow". Falls back to numeric 296 * style if no appropriate text term is available for the specified 297 * offset in the object's locale. 298 * 299 * @param reldatefmt 300 * The URelativeDateTimeFormatter object specifying the 301 * format conventions. 302 * @param offset 303 * The signed offset for the specified unit. 304 * @param unit 305 * The unit to use when formatting the relative 306 * date, e.g. UDAT_REL_UNIT_WEEK, UDAT_REL_UNIT_FRIDAY. 307 * @param result 308 * A pointer to a buffer to receive the formatted result. 309 * @param resultCapacity 310 * The maximum size of result. 311 * @param status 312 * A pointer to a UErrorCode to receive any errors. In 313 * case of error status, the contents of result are 314 * undefined. 315 * @return 316 * The length of the formatted result; may be greater 317 * than resultCapacity, in which case an error is returned. 318 * @draft ICU 57 319 */ 320 U_DRAFT int32_t U_EXPORT2 321 ureldatefmt_format( const URelativeDateTimeFormatter* reldatefmt, 322 double offset, 323 URelativeDateTimeUnit unit, 324 UChar* result, 325 int32_t resultCapacity, 326 UErrorCode* status); 327 328 /** 329 * Combines a relative date string and a time string in this object's 330 * locale. This is done with the same date-time separator used for the 331 * default calendar in this locale to produce a result such as 332 * "yesterday at 3:45 PM". 333 * 334 * @param reldatefmt 335 * The URelativeDateTimeFormatter object specifying the format conventions. 336 * @param relativeDateString 337 * The relative date string. 338 * @param relativeDateStringLen 339 * The length of relativeDateString; may be -1 if relativeDateString 340 * is zero-terminated. 341 * @param timeString 342 * The time string. 343 * @param timeStringLen 344 * The length of timeString; may be -1 if timeString is zero-terminated. 345 * @param result 346 * A pointer to a buffer to receive the formatted result. 347 * @param resultCapacity 348 * The maximum size of result. 349 * @param status 350 * A pointer to a UErrorCode to receive any errors. In case of error status, 351 * the contents of result are undefined. 352 * @return 353 * The length of the formatted result; may be greater than resultCapacity, 354 * in which case an error is returned. 355 * @draft ICU 57 356 */ 357 U_DRAFT int32_t U_EXPORT2 358 ureldatefmt_combineDateAndTime( const URelativeDateTimeFormatter* reldatefmt, 359 const UChar * relativeDateString, 360 int32_t relativeDateStringLen, 361 const UChar * timeString, 362 int32_t timeStringLen, 363 UChar* result, 364 int32_t resultCapacity, 365 UErrorCode* status ); 366 367 #endif /* U_HIDE_DRAFT_API */ 368 369 #endif /* !UCONFIG_NO_FORMATTING && !UCONFIG_NO_BREAK_ITERATION */ 370 371 #endif 372