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 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 366