jpayne@69: * This does not provide compound formatting for multiple units, jpayne@69: * other than the ability to combine a time string with a relative date, jpayne@69: * as in "next Tuesday at 3:45 PM". It also does not provide support jpayne@69: * for determining which unit to use, such as deciding between "in 7 days" jpayne@69: * and "in 1 week". jpayne@69: * jpayne@69: * @stable ICU 57 jpayne@69: */ jpayne@69: jpayne@69: /** jpayne@69: * The formatting style jpayne@69: * @stable ICU 54 jpayne@69: */ jpayne@69: typedef enum UDateRelativeDateTimeFormatterStyle { jpayne@69: /** jpayne@69: * Everything spelled out. jpayne@69: * @stable ICU 54 jpayne@69: */ jpayne@69: UDAT_STYLE_LONG, jpayne@69: jpayne@69: /** jpayne@69: * Abbreviations used when possible. jpayne@69: * @stable ICU 54 jpayne@69: */ jpayne@69: UDAT_STYLE_SHORT, jpayne@69: jpayne@69: /** jpayne@69: * Use the shortest possible form. jpayne@69: * @stable ICU 54 jpayne@69: */ jpayne@69: UDAT_STYLE_NARROW, jpayne@69: jpayne@69: #ifndef U_HIDE_DEPRECATED_API jpayne@69: /** jpayne@69: * One more than the highest normal UDateRelativeDateTimeFormatterStyle value. jpayne@69: * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. jpayne@69: */ jpayne@69: UDAT_STYLE_COUNT jpayne@69: #endif /* U_HIDE_DEPRECATED_API */ jpayne@69: } UDateRelativeDateTimeFormatterStyle; jpayne@69: jpayne@69: /** jpayne@69: * Represents the unit for formatting a relative date. e.g "in 5 days" jpayne@69: * or "next year" jpayne@69: * @stable ICU 57 jpayne@69: */ jpayne@69: typedef enum URelativeDateTimeUnit { jpayne@69: /** jpayne@69: * Specifies that relative unit is year, e.g. "last year", jpayne@69: * "in 5 years". jpayne@69: * @stable ICU 57 jpayne@69: */ jpayne@69: UDAT_REL_UNIT_YEAR, jpayne@69: /** jpayne@69: * Specifies that relative unit is quarter, e.g. "last quarter", jpayne@69: * "in 5 quarters". jpayne@69: * @stable ICU 57 jpayne@69: */ jpayne@69: UDAT_REL_UNIT_QUARTER, jpayne@69: /** jpayne@69: * Specifies that relative unit is month, e.g. "last month", jpayne@69: * "in 5 months". jpayne@69: * @stable ICU 57 jpayne@69: */ jpayne@69: UDAT_REL_UNIT_MONTH, jpayne@69: /** jpayne@69: * Specifies that relative unit is week, e.g. "last week", jpayne@69: * "in 5 weeks". jpayne@69: * @stable ICU 57 jpayne@69: */ jpayne@69: UDAT_REL_UNIT_WEEK, jpayne@69: /** jpayne@69: * Specifies that relative unit is day, e.g. "yesterday", jpayne@69: * "in 5 days". jpayne@69: * @stable ICU 57 jpayne@69: */ jpayne@69: UDAT_REL_UNIT_DAY, jpayne@69: /** jpayne@69: * Specifies that relative unit is hour, e.g. "1 hour ago", jpayne@69: * "in 5 hours". jpayne@69: * @stable ICU 57 jpayne@69: */ jpayne@69: UDAT_REL_UNIT_HOUR, jpayne@69: /** jpayne@69: * Specifies that relative unit is minute, e.g. "1 minute ago", jpayne@69: * "in 5 minutes". jpayne@69: * @stable ICU 57 jpayne@69: */ jpayne@69: UDAT_REL_UNIT_MINUTE, jpayne@69: /** jpayne@69: * Specifies that relative unit is second, e.g. "1 second ago", jpayne@69: * "in 5 seconds". jpayne@69: * @stable ICU 57 jpayne@69: */ jpayne@69: UDAT_REL_UNIT_SECOND, jpayne@69: /** jpayne@69: * Specifies that relative unit is Sunday, e.g. "last Sunday", jpayne@69: * "this Sunday", "next Sunday", "in 5 Sundays". jpayne@69: * @stable ICU 57 jpayne@69: */ jpayne@69: UDAT_REL_UNIT_SUNDAY, jpayne@69: /** jpayne@69: * Specifies that relative unit is Monday, e.g. "last Monday", jpayne@69: * "this Monday", "next Monday", "in 5 Mondays". jpayne@69: * @stable ICU 57 jpayne@69: */ jpayne@69: UDAT_REL_UNIT_MONDAY, jpayne@69: /** jpayne@69: * Specifies that relative unit is Tuesday, e.g. "last Tuesday", jpayne@69: * "this Tuesday", "next Tuesday", "in 5 Tuesdays". jpayne@69: * @stable ICU 57 jpayne@69: */ jpayne@69: UDAT_REL_UNIT_TUESDAY, jpayne@69: /** jpayne@69: * Specifies that relative unit is Wednesday, e.g. "last Wednesday", jpayne@69: * "this Wednesday", "next Wednesday", "in 5 Wednesdays". jpayne@69: * @stable ICU 57 jpayne@69: */ jpayne@69: UDAT_REL_UNIT_WEDNESDAY, jpayne@69: /** jpayne@69: * Specifies that relative unit is Thursday, e.g. "last Thursday", jpayne@69: * "this Thursday", "next Thursday", "in 5 Thursdays". jpayne@69: * @stable ICU 57 jpayne@69: */ jpayne@69: UDAT_REL_UNIT_THURSDAY, jpayne@69: /** jpayne@69: * Specifies that relative unit is Friday, e.g. "last Friday", jpayne@69: * "this Friday", "next Friday", "in 5 Fridays". jpayne@69: * @stable ICU 57 jpayne@69: */ jpayne@69: UDAT_REL_UNIT_FRIDAY, jpayne@69: /** jpayne@69: * Specifies that relative unit is Saturday, e.g. "last Saturday", jpayne@69: * "this Saturday", "next Saturday", "in 5 Saturdays". jpayne@69: * @stable ICU 57 jpayne@69: */ jpayne@69: UDAT_REL_UNIT_SATURDAY, jpayne@69: #ifndef U_HIDE_DEPRECATED_API jpayne@69: /** jpayne@69: * One more than the highest normal URelativeDateTimeUnit value. jpayne@69: * @deprecated ICU 58 The numeric value may change over time, see ICU ticket #12420. jpayne@69: */ jpayne@69: UDAT_REL_UNIT_COUNT jpayne@69: #endif /* U_HIDE_DEPRECATED_API */ jpayne@69: } URelativeDateTimeUnit; jpayne@69: jpayne@69: /** jpayne@69: * FieldPosition and UFieldPosition selectors for format fields jpayne@69: * defined by RelativeDateTimeFormatter. jpayne@69: * @stable ICU 64 jpayne@69: */ jpayne@69: typedef enum URelativeDateTimeFormatterField { jpayne@69: /** jpayne@69: * Represents a literal text string, like "tomorrow" or "days ago". jpayne@69: * @stable ICU 64 jpayne@69: */ jpayne@69: UDAT_REL_LITERAL_FIELD, jpayne@69: /** jpayne@69: * Represents a number quantity, like "3" in "3 days ago". jpayne@69: * @stable ICU 64 jpayne@69: */ jpayne@69: UDAT_REL_NUMERIC_FIELD, jpayne@69: } URelativeDateTimeFormatterField; jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * Opaque URelativeDateTimeFormatter object for use in C programs. jpayne@69: * @stable ICU 57 jpayne@69: */ jpayne@69: struct URelativeDateTimeFormatter; jpayne@69: typedef struct URelativeDateTimeFormatter URelativeDateTimeFormatter; /**< C typedef for struct URelativeDateTimeFormatter. @stable ICU 57 */ jpayne@69: jpayne@69: jpayne@69: /** jpayne@69: * Open a new URelativeDateTimeFormatter object for a given locale using the jpayne@69: * specified width and capitalizationContext, along with a number formatter jpayne@69: * (if desired) to override the default formatter that would be used for jpayne@69: * display of numeric field offsets. The default formatter typically rounds jpayne@69: * toward 0 and has a minimum of 0 fraction digits and a maximum of 3 jpayne@69: * fraction digits (i.e. it will show as many decimal places as necessary jpayne@69: * up to 3, without showing trailing 0s). jpayne@69: * jpayne@69: * @param locale jpayne@69: * The locale jpayne@69: * @param nfToAdopt jpayne@69: * A number formatter to set for this URelativeDateTimeFormatter jpayne@69: * object (instead of the default decimal formatter). Ownership of jpayne@69: * this UNumberFormat object will pass to the URelativeDateTimeFormatter jpayne@69: * object (the URelativeDateTimeFormatter adopts the UNumberFormat), jpayne@69: * which becomes responsible for closing it. If the caller wishes to jpayne@69: * retain ownership of the UNumberFormat object, the caller must clone jpayne@69: * it (with unum_clone) and pass the clone to ureldatefmt_open. May be jpayne@69: * NULL to use the default decimal formatter. jpayne@69: * @param width jpayne@69: * The width - wide, short, narrow, etc. jpayne@69: * @param capitalizationContext jpayne@69: * A value from UDisplayContext that pertains to capitalization, e.g. jpayne@69: * UDISPCTX_CAPITALIZATION_FOR_BEGINNING_OF_SENTENCE. jpayne@69: * @param status jpayne@69: * A pointer to a UErrorCode to receive any errors. jpayne@69: * @return jpayne@69: * A pointer to a URelativeDateTimeFormatter object for the specified locale, jpayne@69: * or NULL if an error occurred. jpayne@69: * @stable ICU 57 jpayne@69: */ jpayne@69: U_STABLE URelativeDateTimeFormatter* U_EXPORT2 jpayne@69: ureldatefmt_open( const char* locale, jpayne@69: UNumberFormat* nfToAdopt, jpayne@69: UDateRelativeDateTimeFormatterStyle width, jpayne@69: UDisplayContext capitalizationContext, jpayne@69: UErrorCode* status ); jpayne@69: jpayne@69: /** jpayne@69: * Close a URelativeDateTimeFormatter object. Once closed it may no longer be used. jpayne@69: * @param reldatefmt jpayne@69: * The URelativeDateTimeFormatter object to close. jpayne@69: * @stable ICU 57 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: ureldatefmt_close(URelativeDateTimeFormatter *reldatefmt); jpayne@69: jpayne@69: struct UFormattedRelativeDateTime; jpayne@69: /** jpayne@69: * Opaque struct to contain the results of a URelativeDateTimeFormatter operation. jpayne@69: * @stable ICU 64 jpayne@69: */ jpayne@69: typedef struct UFormattedRelativeDateTime UFormattedRelativeDateTime; jpayne@69: jpayne@69: /** jpayne@69: * Creates an object to hold the result of a URelativeDateTimeFormatter jpayne@69: * operation. The object can be used repeatedly; it is cleared whenever jpayne@69: * passed to a format function. jpayne@69: * jpayne@69: * @param ec Set if an error occurs. jpayne@69: * @return A pointer needing ownership. jpayne@69: * @stable ICU 64 jpayne@69: */ jpayne@69: U_STABLE UFormattedRelativeDateTime* U_EXPORT2 jpayne@69: ureldatefmt_openResult(UErrorCode* ec); jpayne@69: jpayne@69: /** jpayne@69: * Returns a representation of a UFormattedRelativeDateTime as a UFormattedValue, jpayne@69: * which can be subsequently passed to any API requiring that type. jpayne@69: * jpayne@69: * The returned object is owned by the UFormattedRelativeDateTime and is valid jpayne@69: * only as long as the UFormattedRelativeDateTime is present and unchanged in memory. jpayne@69: * jpayne@69: * You can think of this method as a cast between types. jpayne@69: * jpayne@69: * @param ufrdt The object containing the formatted string. jpayne@69: * @param ec Set if an error occurs. jpayne@69: * @return A UFormattedValue owned by the input object. jpayne@69: * @stable ICU 64 jpayne@69: */ jpayne@69: U_STABLE const UFormattedValue* U_EXPORT2 jpayne@69: ureldatefmt_resultAsValue(const UFormattedRelativeDateTime* ufrdt, UErrorCode* ec); jpayne@69: jpayne@69: /** jpayne@69: * Releases the UFormattedRelativeDateTime created by ureldatefmt_openResult. jpayne@69: * jpayne@69: * @param ufrdt The object to release. jpayne@69: * @stable ICU 64 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: ureldatefmt_closeResult(UFormattedRelativeDateTime* ufrdt); jpayne@69: jpayne@69: jpayne@69: #if U_SHOW_CPLUSPLUS_API jpayne@69: jpayne@69: U_NAMESPACE_BEGIN jpayne@69: jpayne@69: /** jpayne@69: * \class LocalURelativeDateTimeFormatterPointer jpayne@69: * "Smart pointer" class, closes a URelativeDateTimeFormatter via ureldatefmt_close(). jpayne@69: * For most methods see the LocalPointerBase base class. jpayne@69: * jpayne@69: * @see LocalPointerBase jpayne@69: * @see LocalPointer jpayne@69: * @stable ICU 57 jpayne@69: */ jpayne@69: U_DEFINE_LOCAL_OPEN_POINTER(LocalURelativeDateTimeFormatterPointer, URelativeDateTimeFormatter, ureldatefmt_close); jpayne@69: jpayne@69: /** jpayne@69: * \class LocalUFormattedRelativeDateTimePointer jpayne@69: * "Smart pointer" class, closes a UFormattedRelativeDateTime via ureldatefmt_closeResult(). jpayne@69: * For most methods see the LocalPointerBase base class. jpayne@69: * jpayne@69: * @see LocalPointerBase jpayne@69: * @see LocalPointer jpayne@69: * @stable ICU 64 jpayne@69: */ jpayne@69: U_DEFINE_LOCAL_OPEN_POINTER(LocalUFormattedRelativeDateTimePointer, UFormattedRelativeDateTime, ureldatefmt_closeResult); jpayne@69: jpayne@69: U_NAMESPACE_END jpayne@69: jpayne@69: #endif jpayne@69: jpayne@69: /** jpayne@69: * Format a combination of URelativeDateTimeUnit and numeric jpayne@69: * offset using a numeric style, e.g. "1 week ago", "in 1 week", jpayne@69: * "5 weeks ago", "in 5 weeks". jpayne@69: * jpayne@69: * @param reldatefmt jpayne@69: * The URelativeDateTimeFormatter object specifying the jpayne@69: * format conventions. jpayne@69: * @param offset jpayne@69: * The signed offset for the specified unit. This will jpayne@69: * be formatted according to this object's UNumberFormat jpayne@69: * object. jpayne@69: * @param unit jpayne@69: * The unit to use when formatting the relative jpayne@69: * date, e.g. UDAT_REL_UNIT_WEEK, UDAT_REL_UNIT_FRIDAY. jpayne@69: * @param result jpayne@69: * A pointer to a buffer to receive the formatted result. jpayne@69: * @param resultCapacity jpayne@69: * The maximum size of result. jpayne@69: * @param status jpayne@69: * A pointer to a UErrorCode to receive any errors. In jpayne@69: * case of error status, the contents of result are jpayne@69: * undefined. jpayne@69: * @return jpayne@69: * The length of the formatted result; may be greater jpayne@69: * than resultCapacity, in which case an error is returned. jpayne@69: * @stable ICU 57 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: ureldatefmt_formatNumeric( const URelativeDateTimeFormatter* reldatefmt, jpayne@69: double offset, jpayne@69: URelativeDateTimeUnit unit, jpayne@69: UChar* result, jpayne@69: int32_t resultCapacity, jpayne@69: UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Format a combination of URelativeDateTimeUnit and numeric jpayne@69: * offset using a numeric style, e.g. "1 week ago", "in 1 week", jpayne@69: * "5 weeks ago", "in 5 weeks". jpayne@69: * jpayne@69: * @param reldatefmt jpayne@69: * The URelativeDateTimeFormatter object specifying the jpayne@69: * format conventions. jpayne@69: * @param offset jpayne@69: * The signed offset for the specified unit. This will jpayne@69: * be formatted according to this object's UNumberFormat jpayne@69: * object. jpayne@69: * @param unit jpayne@69: * The unit to use when formatting the relative jpayne@69: * date, e.g. UDAT_REL_UNIT_WEEK, UDAT_REL_UNIT_FRIDAY. jpayne@69: * @param result jpayne@69: * A pointer to a UFormattedRelativeDateTime to populate. jpayne@69: * @param status jpayne@69: * A pointer to a UErrorCode to receive any errors. In jpayne@69: * case of error status, the contents of result are jpayne@69: * undefined. jpayne@69: * @stable ICU 64 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: ureldatefmt_formatNumericToResult( jpayne@69: const URelativeDateTimeFormatter* reldatefmt, jpayne@69: double offset, jpayne@69: URelativeDateTimeUnit unit, jpayne@69: UFormattedRelativeDateTime* result, jpayne@69: UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Format a combination of URelativeDateTimeUnit and numeric offset jpayne@69: * using a text style if possible, e.g. "last week", "this week", jpayne@69: * "next week", "yesterday", "tomorrow". Falls back to numeric jpayne@69: * style if no appropriate text term is available for the specified jpayne@69: * offset in the object's locale. jpayne@69: * jpayne@69: * @param reldatefmt jpayne@69: * The URelativeDateTimeFormatter object specifying the jpayne@69: * format conventions. jpayne@69: * @param offset jpayne@69: * The signed offset for the specified unit. jpayne@69: * @param unit jpayne@69: * The unit to use when formatting the relative jpayne@69: * date, e.g. UDAT_REL_UNIT_WEEK, UDAT_REL_UNIT_FRIDAY. jpayne@69: * @param result jpayne@69: * A pointer to a buffer to receive the formatted result. jpayne@69: * @param resultCapacity jpayne@69: * The maximum size of result. jpayne@69: * @param status jpayne@69: * A pointer to a UErrorCode to receive any errors. In jpayne@69: * case of error status, the contents of result are jpayne@69: * undefined. jpayne@69: * @return jpayne@69: * The length of the formatted result; may be greater jpayne@69: * than resultCapacity, in which case an error is returned. jpayne@69: * @stable ICU 57 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: ureldatefmt_format( const URelativeDateTimeFormatter* reldatefmt, jpayne@69: double offset, jpayne@69: URelativeDateTimeUnit unit, jpayne@69: UChar* result, jpayne@69: int32_t resultCapacity, jpayne@69: UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Format a combination of URelativeDateTimeUnit and numeric offset jpayne@69: * using a text style if possible, e.g. "last week", "this week", jpayne@69: * "next week", "yesterday", "tomorrow". Falls back to numeric jpayne@69: * style if no appropriate text term is available for the specified jpayne@69: * offset in the object's locale. jpayne@69: * jpayne@69: * This method populates a UFormattedRelativeDateTime, which exposes more jpayne@69: * information than the string populated by format(). jpayne@69: * jpayne@69: * @param reldatefmt jpayne@69: * The URelativeDateTimeFormatter object specifying the jpayne@69: * format conventions. jpayne@69: * @param offset jpayne@69: * The signed offset for the specified unit. jpayne@69: * @param unit jpayne@69: * The unit to use when formatting the relative jpayne@69: * date, e.g. UDAT_REL_UNIT_WEEK, UDAT_REL_UNIT_FRIDAY. jpayne@69: * @param result jpayne@69: * A pointer to a UFormattedRelativeDateTime to populate. jpayne@69: * @param status jpayne@69: * A pointer to a UErrorCode to receive any errors. In jpayne@69: * case of error status, the contents of result are jpayne@69: * undefined. jpayne@69: * @stable ICU 64 jpayne@69: */ jpayne@69: U_STABLE void U_EXPORT2 jpayne@69: ureldatefmt_formatToResult( jpayne@69: const URelativeDateTimeFormatter* reldatefmt, jpayne@69: double offset, jpayne@69: URelativeDateTimeUnit unit, jpayne@69: UFormattedRelativeDateTime* result, jpayne@69: UErrorCode* status); jpayne@69: jpayne@69: /** jpayne@69: * Combines a relative date string and a time string in this object's jpayne@69: * locale. This is done with the same date-time separator used for the jpayne@69: * default calendar in this locale to produce a result such as jpayne@69: * "yesterday at 3:45 PM". jpayne@69: * jpayne@69: * @param reldatefmt jpayne@69: * The URelativeDateTimeFormatter object specifying the format conventions. jpayne@69: * @param relativeDateString jpayne@69: * The relative date string. jpayne@69: * @param relativeDateStringLen jpayne@69: * The length of relativeDateString; may be -1 if relativeDateString jpayne@69: * is zero-terminated. jpayne@69: * @param timeString jpayne@69: * The time string. jpayne@69: * @param timeStringLen jpayne@69: * The length of timeString; may be -1 if timeString is zero-terminated. jpayne@69: * @param result jpayne@69: * A pointer to a buffer to receive the formatted result. jpayne@69: * @param resultCapacity jpayne@69: * The maximum size of result. jpayne@69: * @param status jpayne@69: * A pointer to a UErrorCode to receive any errors. In case of error status, jpayne@69: * the contents of result are undefined. jpayne@69: * @return jpayne@69: * The length of the formatted result; may be greater than resultCapacity, jpayne@69: * in which case an error is returned. jpayne@69: * @stable ICU 57 jpayne@69: */ jpayne@69: U_STABLE int32_t U_EXPORT2 jpayne@69: ureldatefmt_combineDateAndTime( const URelativeDateTimeFormatter* reldatefmt, jpayne@69: const UChar * relativeDateString, jpayne@69: int32_t relativeDateStringLen, jpayne@69: const UChar * timeString, jpayne@69: int32_t timeStringLen, jpayne@69: UChar* result, jpayne@69: int32_t resultCapacity, jpayne@69: UErrorCode* status ); jpayne@69: jpayne@69: #endif /* !UCONFIG_NO_FORMATTING && !UCONFIG_NO_BREAK_ITERATION */ jpayne@69: jpayne@69: #endif