C API: URelativeDateTimeFormatter, relative date formatting of unit + numeric offset. More...

#include "unicode/utypes.h"
#include "unicode/unum.h"
#include "unicode/udisplaycontext.h"
#include "unicode/uformattedvalue.h"
#include "unicode/localpointer.h"

Namespaces
namespace	icu
	File coll.h.

Typedefs
typedef enum UDateRelativeDateTimeFormatterStyle	UDateRelativeDateTimeFormatterStyle
	The formatting style.

typedef enum URelativeDateTimeUnit	URelativeDateTimeUnit
	Represents the unit for formatting a relative date.

typedef enum URelativeDateTimeFormatterField	URelativeDateTimeFormatterField
	FieldPosition and UFieldPosition selectors for format fields defined by RelativeDateTimeFormatter.

typedef struct URelativeDateTimeFormatter	URelativeDateTimeFormatter
	C typedef for struct URelativeDateTimeFormatter.

typedef struct UFormattedRelativeDateTime	UFormattedRelativeDateTime
	Opaque struct to contain the results of a URelativeDateTimeFormatter operation.

Enumerations
enum	UDateRelativeDateTimeFormatterStyle { UDAT_STYLE_LONG , UDAT_STYLE_SHORT , UDAT_STYLE_NARROW , UDAT_STYLE_COUNT }
	The formatting style. More...

enum	URelativeDateTimeUnit { UDAT_REL_UNIT_YEAR , UDAT_REL_UNIT_QUARTER , UDAT_REL_UNIT_MONTH , UDAT_REL_UNIT_WEEK , UDAT_REL_UNIT_DAY , UDAT_REL_UNIT_HOUR , UDAT_REL_UNIT_MINUTE , UDAT_REL_UNIT_SECOND , UDAT_REL_UNIT_SUNDAY , UDAT_REL_UNIT_MONDAY , UDAT_REL_UNIT_TUESDAY , UDAT_REL_UNIT_WEDNESDAY , UDAT_REL_UNIT_THURSDAY , UDAT_REL_UNIT_FRIDAY , UDAT_REL_UNIT_SATURDAY , UDAT_REL_UNIT_COUNT }
	Represents the unit for formatting a relative date. More...

enum	URelativeDateTimeFormatterField { UDAT_REL_LITERAL_FIELD , UDAT_REL_NUMERIC_FIELD }
	FieldPosition and UFieldPosition selectors for format fields defined by RelativeDateTimeFormatter. More...

Functions
U_CAPI URelativeDateTimeFormatter *	ureldatefmt_open (const char locale, UNumberFormat nfToAdopt, UDateRelativeDateTimeFormatterStyle width, UDisplayContext capitalizationContext, UErrorCode *status)
	Open a new URelativeDateTimeFormatter object for a given locale using the specified width and capitalizationContext, along with a number formatter (if desired) to override the default formatter that would be used for display of numeric field offsets.

U_CAPI void	ureldatefmt_close (URelativeDateTimeFormatter *reldatefmt)
	Close a URelativeDateTimeFormatter object.

U_CAPI UFormattedRelativeDateTime *	ureldatefmt_openResult (UErrorCode *ec)
	Creates an object to hold the result of a URelativeDateTimeFormatter operation.

U_CAPI const UFormattedValue *	ureldatefmt_resultAsValue (const UFormattedRelativeDateTime ufrdt, UErrorCode ec)
	Returns a representation of a UFormattedRelativeDateTime as a UFormattedValue, which can be subsequently passed to any API requiring that type.

U_CAPI void	ureldatefmt_closeResult (UFormattedRelativeDateTime *ufrdt)
	Releases the UFormattedRelativeDateTime created by ureldatefmt_openResult.

U_CAPI int32_t	ureldatefmt_formatNumeric (const URelativeDateTimeFormatter reldatefmt, double offset, URelativeDateTimeUnit unit, UChar result, int32_t resultCapacity, UErrorCode *status)
	Format a combination of URelativeDateTimeUnit and numeric offset using a numeric style, e.g.

U_CAPI void	ureldatefmt_formatNumericToResult (const URelativeDateTimeFormatter reldatefmt, double offset, URelativeDateTimeUnit unit, UFormattedRelativeDateTime result, UErrorCode *status)
	Format a combination of URelativeDateTimeUnit and numeric offset using a numeric style, e.g.

U_CAPI int32_t	ureldatefmt_format (const URelativeDateTimeFormatter reldatefmt, double offset, URelativeDateTimeUnit unit, UChar result, int32_t resultCapacity, UErrorCode *status)
	Format a combination of URelativeDateTimeUnit and numeric offset using a text style if possible, e.g.

U_CAPI void	ureldatefmt_formatToResult (const URelativeDateTimeFormatter reldatefmt, double offset, URelativeDateTimeUnit unit, UFormattedRelativeDateTime result, UErrorCode *status)
	Format a combination of URelativeDateTimeUnit and numeric offset using a text style if possible, e.g.

U_CAPI int32_t	ureldatefmt_combineDateAndTime (const URelativeDateTimeFormatter reldatefmt, const UChar relativeDateString, int32_t relativeDateStringLen, const UChar timeString, int32_t timeStringLen, UChar result, int32_t resultCapacity, UErrorCode *status)
	Combines a relative date string and a time string in this object's locale.

Detailed Description

C API: URelativeDateTimeFormatter, relative date formatting of unit + numeric offset.

Provides simple formatting of relative dates, in two ways

relative dates with a quantity e.g "in 5 days"
relative dates without a quantity e.g "next Tuesday"

This does not provide compound formatting for multiple units, other than the ability to combine a time string with a relative date, as in "next Tuesday at 3:45 PM". It also does not provide support for determining which unit to use, such as deciding between "in 7 days" and "in 1 week".

Stable:: ICU 57

Definition in file ureldatefmt.h.

Typedef Documentation

◆ UDateRelativeDateTimeFormatterStyle

typedef enum UDateRelativeDateTimeFormatterStyle UDateRelativeDateTimeFormatterStyle

The formatting style.

Stable:: ICU 54

◆ UFormattedRelativeDateTime

typedef struct UFormattedRelativeDateTime UFormattedRelativeDateTime

Opaque struct to contain the results of a URelativeDateTimeFormatter operation.

Stable:: ICU 64

Definition at line 261 of file ureldatefmt.h.

◆ URelativeDateTimeFormatter

typedef struct URelativeDateTimeFormatter URelativeDateTimeFormatter

C typedef for struct URelativeDateTimeFormatter.

Stable:: ICU 57

Definition at line 205 of file ureldatefmt.h.

◆ URelativeDateTimeFormatterField

typedef enum URelativeDateTimeFormatterField URelativeDateTimeFormatterField

FieldPosition and UFieldPosition selectors for format fields defined by RelativeDateTimeFormatter.

Stable:: ICU 64

◆ URelativeDateTimeUnit

typedef enum URelativeDateTimeUnit URelativeDateTimeUnit

Represents the unit for formatting a relative date.

e.g "in 5 days" or "next year"

Stable:: ICU 57

Enumeration Type Documentation

◆ UDateRelativeDateTimeFormatterStyle

enum UDateRelativeDateTimeFormatterStyle

The formatting style.

Stable:: ICU 54

Enumerator
UDAT_STYLE_LONG	Everything spelled out. Stable: ICU 54
UDAT_STYLE_SHORT	Abbreviations used when possible. Stable: ICU 54
UDAT_STYLE_NARROW	Use the shortest possible form. Stable: ICU 54
UDAT_STYLE_COUNT	One more than the highest normal UDateRelativeDateTimeFormatterStyle value. Deprecated: ICU 58 The numeric value may change over time, see ICU ticket #12420.

Definition at line 48 of file ureldatefmt.h.

◆ URelativeDateTimeFormatterField

enum URelativeDateTimeFormatterField

FieldPosition and UFieldPosition selectors for format fields defined by RelativeDateTimeFormatter.

Stable:: ICU 64

Enumerator

UDAT_REL_LITERAL_FIELD

Represents a literal text string, like "tomorrow" or "days ago".

Stable:: ICU 64

UDAT_REL_NUMERIC_FIELD

Represents a number quantity, like "3" in "3 days ago".

Stable:: ICU 64

Definition at line 186 of file ureldatefmt.h.

◆ URelativeDateTimeUnit

enum URelativeDateTimeUnit

Represents the unit for formatting a relative date.

e.g "in 5 days" or "next year"

Stable:: ICU 57

Enumerator
UDAT_REL_UNIT_YEAR	Specifies that relative unit is year, e.g. "last year", "in 5 years". Stable: ICU 57
UDAT_REL_UNIT_QUARTER	Specifies that relative unit is quarter, e.g. "last quarter", "in 5 quarters". Stable: ICU 57
UDAT_REL_UNIT_MONTH	Specifies that relative unit is month, e.g. "last month", "in 5 months". Stable: ICU 57
UDAT_REL_UNIT_WEEK	Specifies that relative unit is week, e.g. "last week", "in 5 weeks". Stable: ICU 57
UDAT_REL_UNIT_DAY	Specifies that relative unit is day, e.g. "yesterday", "in 5 days". Stable: ICU 57
UDAT_REL_UNIT_HOUR	Specifies that relative unit is hour, e.g. "1 hour ago", "in 5 hours". Stable: ICU 57
UDAT_REL_UNIT_MINUTE	Specifies that relative unit is minute, e.g. "1 minute ago", "in 5 minutes". Stable: ICU 57
UDAT_REL_UNIT_SECOND	Specifies that relative unit is second, e.g. "1 second ago", "in 5 seconds". Stable: ICU 57
UDAT_REL_UNIT_SUNDAY	Specifies that relative unit is Sunday, e.g. "last Sunday", "this Sunday", "next Sunday", "in 5 Sundays". Stable: ICU 57
UDAT_REL_UNIT_MONDAY	Specifies that relative unit is Monday, e.g. "last Monday", "this Monday", "next Monday", "in 5 Mondays". Stable: ICU 57
UDAT_REL_UNIT_TUESDAY	Specifies that relative unit is Tuesday, e.g. "last Tuesday", "this Tuesday", "next Tuesday", "in 5 Tuesdays". Stable: ICU 57
UDAT_REL_UNIT_WEDNESDAY	Specifies that relative unit is Wednesday, e.g. "last Wednesday", "this Wednesday", "next Wednesday", "in 5 Wednesdays". Stable: ICU 57
UDAT_REL_UNIT_THURSDAY	Specifies that relative unit is Thursday, e.g. "last Thursday", "this Thursday", "next Thursday", "in 5 Thursdays". Stable: ICU 57
UDAT_REL_UNIT_FRIDAY	Specifies that relative unit is Friday, e.g. "last Friday", "this Friday", "next Friday", "in 5 Fridays". Stable: ICU 57
UDAT_REL_UNIT_SATURDAY	Specifies that relative unit is Saturday, e.g. "last Saturday", "this Saturday", "next Saturday", "in 5 Saturdays". Stable: ICU 57
UDAT_REL_UNIT_COUNT	One more than the highest normal URelativeDateTimeUnit value. Deprecated: ICU 58 The numeric value may change over time, see ICU ticket #12420.

Definition at line 81 of file ureldatefmt.h.

Function Documentation

◆ ureldatefmt_close()

U_CAPI void ureldatefmt_close ( URelativeDateTimeFormatter * reldatefmt )

Close a URelativeDateTimeFormatter object.

Once closed it may no longer be used.

Parameters

reldatefmt The URelativeDateTimeFormatter object to close.

Stable:: ICU 57

◆ ureldatefmt_closeResult()

U_CAPI void ureldatefmt_closeResult ( UFormattedRelativeDateTime * ufrdt )

Releases the UFormattedRelativeDateTime created by ureldatefmt_openResult.

Parameters

ufrdt The object to release.

Stable:: ICU 64

◆ ureldatefmt_combineDateAndTime()

U_CAPI int32_t ureldatefmt_combineDateAndTime	(	const URelativeDateTimeFormatter *	reldatefmt,
		const UChar *	relativeDateString,
		int32_t	relativeDateStringLen,
		const UChar *	timeString,
		int32_t	timeStringLen,
		UChar *	result,
		int32_t	resultCapacity,
		UErrorCode *	status
	)

Combines a relative date string and a time string in this object's locale.

This is done with the same date-time separator used for the default calendar in this locale to produce a result such as "yesterday at 3:45 PM".

Parameters

reldatefmt	The URelativeDateTimeFormatter object specifying the format conventions.
relativeDateString	The relative date string.
relativeDateStringLen	The length of relativeDateString; may be -1 if relativeDateString is zero-terminated.
timeString	The time string.
timeStringLen	The length of timeString; may be -1 if timeString is zero-terminated.
result	A pointer to a buffer to receive the formatted result.
resultCapacity	The maximum size of result.
status	A pointer to a UErrorCode to receive any errors. In case of error status, the contents of result are undefined.

Returns: The length of the formatted result; may be greater than resultCapacity, in which case an error is returned.

Stable:: ICU 57

◆ ureldatefmt_format()

U_CAPI int32_t ureldatefmt_format	(	const URelativeDateTimeFormatter *	reldatefmt,
		double	offset,
		URelativeDateTimeUnit	unit,
		UChar *	result,
		int32_t	resultCapacity,
		UErrorCode *	status
	)

Format a combination of URelativeDateTimeUnit and numeric offset using a text style if possible, e.g.

"last week", "this week", "next week", "yesterday", "tomorrow". Falls back to numeric style if no appropriate text term is available for the specified offset in the object's locale.

Parameters

reldatefmt	The URelativeDateTimeFormatter object specifying the format conventions.
offset	The signed offset for the specified unit.
unit	The unit to use when formatting the relative date, e.g. UDAT_REL_UNIT_WEEK, UDAT_REL_UNIT_FRIDAY.
result	A pointer to a buffer to receive the formatted result.
resultCapacity	The maximum size of result.
status	A pointer to a UErrorCode to receive any errors. In case of error status, the contents of result are undefined.

Returns: The length of the formatted result; may be greater than resultCapacity, in which case an error is returned.

Stable:: ICU 57

◆ ureldatefmt_formatNumeric()

U_CAPI int32_t ureldatefmt_formatNumeric	(	const URelativeDateTimeFormatter *	reldatefmt,
		double	offset,
		URelativeDateTimeUnit	unit,
		UChar *	result,
		int32_t	resultCapacity,
		UErrorCode *	status
	)

Format a combination of URelativeDateTimeUnit and numeric offset using a numeric style, e.g.

"1 week ago", "in 1 week", "5 weeks ago", "in 5 weeks".

Parameters

reldatefmt	The URelativeDateTimeFormatter object specifying the format conventions.
offset	The signed offset for the specified unit. This will be formatted according to this object's UNumberFormat object.
unit	The unit to use when formatting the relative date, e.g. UDAT_REL_UNIT_WEEK, UDAT_REL_UNIT_FRIDAY.
result	A pointer to a buffer to receive the formatted result.
resultCapacity	The maximum size of result.
status	A pointer to a UErrorCode to receive any errors. In case of error status, the contents of result are undefined.

Returns: The length of the formatted result; may be greater than resultCapacity, in which case an error is returned.

Stable:: ICU 57

◆ ureldatefmt_formatNumericToResult()

U_CAPI void ureldatefmt_formatNumericToResult	(	const URelativeDateTimeFormatter *	reldatefmt,
		double	offset,
		URelativeDateTimeUnit	unit,
		UFormattedRelativeDateTime *	result,
		UErrorCode *	status
	)

Format a combination of URelativeDateTimeUnit and numeric offset using a numeric style, e.g.

"1 week ago", "in 1 week", "5 weeks ago", "in 5 weeks".

Parameters

reldatefmt	The URelativeDateTimeFormatter object specifying the format conventions.
offset	The signed offset for the specified unit. This will be formatted according to this object's UNumberFormat object.
unit	The unit to use when formatting the relative date, e.g. UDAT_REL_UNIT_WEEK, UDAT_REL_UNIT_FRIDAY.
result	A pointer to a UFormattedRelativeDateTime to populate.
status	A pointer to a UErrorCode to receive any errors. In case of error status, the contents of result are undefined.

Stable:: ICU 64

◆ ureldatefmt_formatToResult()

U_CAPI void ureldatefmt_formatToResult	(	const URelativeDateTimeFormatter *	reldatefmt,
		double	offset,
		URelativeDateTimeUnit	unit,
		UFormattedRelativeDateTime *	result,
		UErrorCode *	status
	)

Format a combination of URelativeDateTimeUnit and numeric offset using a text style if possible, e.g.

"last week", "this week", "next week", "yesterday", "tomorrow". Falls back to numeric style if no appropriate text term is available for the specified offset in the object's locale.

This method populates a UFormattedRelativeDateTime, which exposes more information than the string populated by format().

Parameters

reldatefmt	The URelativeDateTimeFormatter object specifying the format conventions.
offset	The signed offset for the specified unit.
unit	The unit to use when formatting the relative date, e.g. UDAT_REL_UNIT_WEEK, UDAT_REL_UNIT_FRIDAY.
result	A pointer to a UFormattedRelativeDateTime to populate.
status	A pointer to a UErrorCode to receive any errors. In case of error status, the contents of result are undefined.

Stable:: ICU 64

◆ ureldatefmt_open()

U_CAPI URelativeDateTimeFormatter * ureldatefmt_open	(	const char *	locale,
		UNumberFormat *	nfToAdopt,
		UDateRelativeDateTimeFormatterStyle	width,
		UDisplayContext	capitalizationContext,
		UErrorCode *	status
	)

Open a new URelativeDateTimeFormatter object for a given locale using the specified width and capitalizationContext, along with a number formatter (if desired) to override the default formatter that would be used for display of numeric field offsets.

The default formatter typically rounds toward 0 and has a minimum of 0 fraction digits and a maximum of 3 fraction digits (i.e. it will show as many decimal places as necessary up to 3, without showing trailing 0s).

Parameters

locale	The locale
nfToAdopt	A number formatter to set for this URelativeDateTimeFormatter object (instead of the default decimal formatter). Ownership of this UNumberFormat object will pass to the URelativeDateTimeFormatter object (the URelativeDateTimeFormatter adopts the UNumberFormat), which becomes responsible for closing it. If the caller wishes to retain ownership of the UNumberFormat object, the caller must clone it (with unum_clone) and pass the clone to ureldatefmt_open. May be NULL to use the default decimal formatter.
width	The width - wide, short, narrow, etc.
capitalizationContext	A value from UDisplayContext that pertains to capitalization, e.g. UDISPCTX_CAPITALIZATION_FOR_BEGINNING_OF_SENTENCE.
status	A pointer to a UErrorCode to receive any errors.

Returns: A pointer to a URelativeDateTimeFormatter object for the specified locale, or NULL if an error occurred.

Stable:: ICU 57

◆ ureldatefmt_openResult()

U_CAPI UFormattedRelativeDateTime * ureldatefmt_openResult ( UErrorCode * ec )

Creates an object to hold the result of a URelativeDateTimeFormatter operation.

The object can be used repeatedly; it is cleared whenever passed to a format function.

Parameters

ec	Set if an error occurs.

Returns: A pointer needing ownership.

Stable:: ICU 64

◆ ureldatefmt_resultAsValue()

U_CAPI const UFormattedValue * ureldatefmt_resultAsValue	(	const UFormattedRelativeDateTime *	ufrdt,
		UErrorCode *	ec
	)

Returns a representation of a UFormattedRelativeDateTime as a UFormattedValue, which can be subsequently passed to any API requiring that type.

The returned object is owned by the UFormattedRelativeDateTime and is valid only as long as the UFormattedRelativeDateTime is present and unchanged in memory.

You can think of this method as a cast between types.

Parameters

ufrdt	The object containing the formatted string.
ec	Set if an error occurs.

Returns: A UFormattedValue owned by the input object.

Stable:: ICU 64

Namespaces

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ UDateRelativeDateTimeFormatterStyle

◆ UFormattedRelativeDateTime

◆ URelativeDateTimeFormatter

◆ URelativeDateTimeFormatterField

◆ URelativeDateTimeUnit

Enumeration Type Documentation

◆ UDateRelativeDateTimeFormatterStyle

◆ URelativeDateTimeFormatterField

◆ URelativeDateTimeUnit

Function Documentation

◆ ureldatefmt_close()

◆ ureldatefmt_closeResult()

◆ ureldatefmt_combineDateAndTime()

◆ ureldatefmt_format()

◆ ureldatefmt_formatNumeric()

◆ ureldatefmt_formatNumericToResult()

◆ ureldatefmt_formatToResult()

◆ ureldatefmt_open()

◆ ureldatefmt_openResult()

◆ ureldatefmt_resultAsValue()