Formats simple relative dates. More...

#include <reldatefmt.h>

Inheritance diagram for icu::RelativeDateTimeFormatter:

Public Member Functions
U_I18N_API	RelativeDateTimeFormatter (UErrorCode &status)
	Create RelativeDateTimeFormatter with default locale.
U_I18N_API	RelativeDateTimeFormatter (const Locale &locale, UErrorCode &status)
	Create RelativeDateTimeFormatter with given locale.
U_I18N_API	RelativeDateTimeFormatter (const Locale &locale, NumberFormat *nfToAdopt, UErrorCode &status)
	Create RelativeDateTimeFormatter with given locale and NumberFormat.
U_I18N_API	RelativeDateTimeFormatter (const Locale &locale, NumberFormat *nfToAdopt, UDateRelativeDateTimeFormatterStyle style, UDisplayContext capitalizationContext, UErrorCode &status)
	Create RelativeDateTimeFormatter with given locale, NumberFormat, and capitalization context.
U_I18N_API	RelativeDateTimeFormatter (const RelativeDateTimeFormatter &other)
	Copy constructor.
U_I18N_API RelativeDateTimeFormatter &	operator= (const RelativeDateTimeFormatter &other)
	Assignment operator.
virtual U_I18N_API	~RelativeDateTimeFormatter ()
	Destructor.
U_I18N_API UnicodeString &	format (double quantity, UDateDirection direction, UDateRelativeUnit unit, UnicodeString &appendTo, UErrorCode &status) const
	Formats a relative date with a quantity such as "in 5 days" or "3 months ago".
U_I18N_API FormattedRelativeDateTime	formatToValue (double quantity, UDateDirection direction, UDateRelativeUnit unit, UErrorCode &status) const
	Formats a relative date with a quantity such as "in 5 days" or "3 months ago".
U_I18N_API UnicodeString &	format (UDateDirection direction, UDateAbsoluteUnit unit, UnicodeString &appendTo, UErrorCode &status) const
	Formats a relative date without a quantity.
U_I18N_API FormattedRelativeDateTime	formatToValue (UDateDirection direction, UDateAbsoluteUnit unit, UErrorCode &status) const
	Formats a relative date without a quantity.
U_I18N_API UnicodeString &	formatNumeric (double offset, URelativeDateTimeUnit unit, UnicodeString &appendTo, UErrorCode &status) const
	Format a combination of URelativeDateTimeUnit and numeric offset using a numeric style, e.g.
U_I18N_API FormattedRelativeDateTime	formatNumericToValue (double offset, URelativeDateTimeUnit unit, UErrorCode &status) const
	Format a combination of URelativeDateTimeUnit and numeric offset using a numeric style, e.g.
U_I18N_API UnicodeString &	format (double offset, URelativeDateTimeUnit unit, UnicodeString &appendTo, UErrorCode &status) const
	Format a combination of URelativeDateTimeUnit and numeric offset using a text style if possible, e.g.
U_I18N_API FormattedRelativeDateTime	formatToValue (double offset, URelativeDateTimeUnit unit, UErrorCode &status) const
	Format a combination of URelativeDateTimeUnit and numeric offset using a text style if possible, e.g.
U_I18N_API UnicodeString &	combineDateAndTime (const UnicodeString &relativeDateString, const UnicodeString &timeString, UnicodeString &appendTo, UErrorCode &status) const
	Combines a relative date string and a time string in this object's locale.
U_I18N_API const NumberFormat &	getNumberFormat () const
	Returns the NumberFormat this object is using.
U_I18N_API UDisplayContext	getCapitalizationContext () const
	Returns the capitalization context.
U_I18N_API UDateRelativeDateTimeFormatterStyle	getFormatStyle () const
	Returns the format style.
Public Member Functions inherited from icu::UObject
virtual	~UObject ()
	Destructor.
virtual UClassID	getDynamicClassID () const
	ICU4C "poor man's RTTI", returns a UClassID for the actual ICU class.

Detailed Description

Formats simple relative dates.

There are two types of relative dates that it handles:

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

This API is very basic and is intended to be a building block for more fancy APIs. The caller tells it exactly what to display in a locale independent way. While this class automatically provides the correct plural forms, the grammatical form is otherwise as neutral as possible. It is the caller's responsibility to handle cut-off logic such as deciding between displaying "in 7 days" or "in 1 week." This API supports relative dates involving one single unit. This API does not support relative dates involving compound units, e.g "in 5 days and 4 hours" nor does it support parsing.

This class is mostly thread safe and immutable with the following caveats:

The assignment operator violates Immutability. It must not be used concurrently with other operations.
Caller must not hold onto adopted pointers.

This class is not intended for public subclassing.

Here are some examples of use:

UErrorCode status = U_ZERO_ERROR;
UnicodeString appendTo;
RelativeDateTimeFormatter fmt(status);
// Appends "in 1 day"
fmt.format(
    1, UDAT_DIRECTION_NEXT, UDAT_RELATIVE_DAYS, appendTo, status);
// Appends "in 3 days"
fmt.format(
    3, UDAT_DIRECTION_NEXT, UDAT_RELATIVE_DAYS, appendTo, status);
// Appends "3.2 years ago"
fmt.format(
    3.2, UDAT_DIRECTION_LAST, UDAT_RELATIVE_YEARS, appendTo, status);
// Appends "last Sunday"
fmt.format(UDAT_DIRECTION_LAST, UDAT_ABSOLUTE_SUNDAY, appendTo, status);
// Appends "this Sunday"
fmt.format(UDAT_DIRECTION_THIS, UDAT_ABSOLUTE_SUNDAY, appendTo, status);
// Appends "next Sunday"
fmt.format(UDAT_DIRECTION_NEXT, UDAT_ABSOLUTE_SUNDAY, appendTo, status);
// Appends "Sunday"
fmt.format(UDAT_DIRECTION_PLAIN, UDAT_ABSOLUTE_SUNDAY, appendTo, status);

// Appends "yesterday"
fmt.format(UDAT_DIRECTION_LAST, UDAT_ABSOLUTE_DAY, appendTo, status);
// Appends "today"
fmt.format(UDAT_DIRECTION_THIS, UDAT_ABSOLUTE_DAY, appendTo, status);
// Appends "tomorrow"
fmt.format(UDAT_DIRECTION_NEXT, UDAT_ABSOLUTE_DAY, appendTo, status);
// Appends "now"
fmt.format(UDAT_DIRECTION_PLAIN, UDAT_ABSOLUTE_NOW, appendTo, status);

The UDateRelativeDateTimeFormatterStyle parameter allows selection of different length styles: LONG ("3 seconds ago"), SHORT ("3 sec. ago"), NARROW ("3s ago"). In the future, we may add more forms, such as relative day periods ("yesterday afternoon"), etc.

The RelativeDateTimeFormatter class is not intended for public subclassing.

Stable: ICU 53

Definition at line 396 of file reldatefmt.h.

Constructor & Destructor Documentation

◆ RelativeDateTimeFormatter() [1/5]

U_I18N_API icu::RelativeDateTimeFormatter::RelativeDateTimeFormatter ( UErrorCode & status )

Create RelativeDateTimeFormatter with default locale.

Stable: ICU 53

References U_I18N_API.

Referenced by operator=(), and RelativeDateTimeFormatter().

◆ RelativeDateTimeFormatter() [2/5]

U_I18N_API icu::RelativeDateTimeFormatter::RelativeDateTimeFormatter	(	const Locale &	locale,
		UErrorCode &	status )

Create RelativeDateTimeFormatter with given locale.

Stable: ICU 53

References U_I18N_API.

◆ RelativeDateTimeFormatter() [3/5]

U_I18N_API icu::RelativeDateTimeFormatter::RelativeDateTimeFormatter	(	const Locale &	locale,
		NumberFormat *	nfToAdopt,
		UErrorCode &	status )

Create RelativeDateTimeFormatter with given locale and NumberFormat.

Parameters

locale	the locale
nfToAdopt	Constructed object takes ownership of this pointer. It is an error for caller to delete this pointer or change its contents after calling this constructor.
status	Any error is returned here.

Stable: ICU 53

References U_I18N_API.

◆ RelativeDateTimeFormatter() [4/5]

U_I18N_API icu::RelativeDateTimeFormatter::RelativeDateTimeFormatter	(	const Locale &	locale,
		NumberFormat *	nfToAdopt,
		UDateRelativeDateTimeFormatterStyle	style,
		UDisplayContext	capitalizationContext,
		UErrorCode &	status )

Create RelativeDateTimeFormatter with given locale, NumberFormat, and capitalization context.

Parameters

locale	the locale
nfToAdopt	Constructed object takes ownership of this pointer. It is an error for caller to delete this pointer or change its contents after calling this constructor. Caller may pass nullptr for this argument if they want default number format behavior.
style	the format style. The UDAT_RELATIVE bit field has no effect.
capitalizationContext	A value from UDisplayContext that pertains to capitalization.
status	Any error is returned here.

Stable: ICU 54

References U_I18N_API.

◆ RelativeDateTimeFormatter() [5/5]

U_I18N_API icu::RelativeDateTimeFormatter::RelativeDateTimeFormatter ( const RelativeDateTimeFormatter & other )

Copy constructor.

Stable: ICU 53

References RelativeDateTimeFormatter(), and U_I18N_API.

◆ ~RelativeDateTimeFormatter()

virtual U_I18N_API icu::RelativeDateTimeFormatter::~RelativeDateTimeFormatter ( )

virtual

Destructor.

Stable: ICU 53

References U_I18N_API.

Member Function Documentation

◆ combineDateAndTime()

U_I18N_API UnicodeString & icu::RelativeDateTimeFormatter::combineDateAndTime	(	const UnicodeString &	relativeDateString,
		const UnicodeString &	timeString,
		UnicodeString &	appendTo,
		UErrorCode &	status ) const

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.

Parameters

relativeDateString	the relative date, e.g 'yesterday'
timeString	the time e.g '3:45'
appendTo	concatenated date and time appended here
status	ICU error code returned here.

Returns: appendTo

Stable: ICU 53

References U_I18N_API.

◆ format() [1/3]

U_I18N_API UnicodeString & icu::RelativeDateTimeFormatter::format	(	double	offset,
		URelativeDateTimeUnit	unit,
		UnicodeString &	appendTo,
		UErrorCode &	status ) const

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 returns a String. To get more information about the formatting result, use formatToValue().

Parameters

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.
appendTo	The string to which the formatted result will be appended.
status	ICU error code returned here.

Returns: appendTo

Stable: ICU 57

References U_I18N_API.

◆ format() [2/3]

U_I18N_API UnicodeString & icu::RelativeDateTimeFormatter::format	(	double	quantity,
		UDateDirection	direction,
		UDateRelativeUnit	unit,
		UnicodeString &	appendTo,
		UErrorCode &	status ) const

Formats a relative date with a quantity such as "in 5 days" or "3 months ago".

This method returns a String. To get more information about the formatting result, use formatToValue().

Parameters

quantity	The numerical amount e.g 5. This value is formatted according to this object's NumberFormat object.
direction	NEXT means a future relative date; LAST means a past relative date. If direction is anything else, this method sets status to U_ILLEGAL_ARGUMENT_ERROR.
unit	the unit e.g day? month? year?
appendTo	The string to which the formatted result will be appended
status	ICU error code returned here.

Returns: appendTo

Stable: ICU 53

References U_I18N_API.

◆ format() [3/3]

U_I18N_API UnicodeString & icu::RelativeDateTimeFormatter::format	(	UDateDirection	direction,
		UDateAbsoluteUnit	unit,
		UnicodeString &	appendTo,
		UErrorCode &	status ) const

Formats a relative date without a quantity.

This method returns a String. To get more information about the formatting result, use formatToValue().

Parameters

direction	NEXT, LAST, THIS, etc.
unit	e.g SATURDAY, DAY, MONTH
appendTo	The string to which the formatted result will be appended. If the value of direction is documented as not being fully supported in all locales then this method leaves appendTo unchanged if no format string is available.
status	ICU error code returned here.

Returns: appendTo

Stable: ICU 53

References U_I18N_API.

◆ formatNumeric()

U_I18N_API UnicodeString & icu::RelativeDateTimeFormatter::formatNumeric	(	double	offset,
		URelativeDateTimeUnit	unit,
		UnicodeString &	appendTo,
		UErrorCode &	status ) const

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".

This method returns a String. To get more information about the formatting result, use formatNumericToValue().

Parameters

offset	The signed offset for the specified unit. This will be formatted according to this object's NumberFormat object.
unit	The unit to use when formatting the relative date, e.g. UDAT_REL_UNIT_WEEK, UDAT_REL_UNIT_FRIDAY.
appendTo	The string to which the formatted result will be appended.
status	ICU error code returned here.

Returns: appendTo

Stable: ICU 57

References U_I18N_API.

◆ formatNumericToValue()

U_I18N_API FormattedRelativeDateTime icu::RelativeDateTimeFormatter::formatNumericToValue	(	double	offset,
		URelativeDateTimeUnit	unit,
		UErrorCode &	status ) const

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".

This method returns a FormattedRelativeDateTime, which exposes more information than the String returned by formatNumeric().

Parameters

offset	The signed offset for the specified unit. This will be formatted according to this object's NumberFormat object.
unit	The unit to use when formatting the relative date, e.g. UDAT_REL_UNIT_WEEK, UDAT_REL_UNIT_FRIDAY.
status	ICU error code returned here.

Returns: The formatted relative datetime

Stable: ICU 64

References U_I18N_API.

◆ formatToValue() [1/3]

U_I18N_API FormattedRelativeDateTime icu::RelativeDateTimeFormatter::formatToValue	(	double	offset,
		URelativeDateTimeUnit	unit,
		UErrorCode &	status ) const

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 returns a FormattedRelativeDateTime, which exposes more information than the String returned by format().

Parameters

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.
status	ICU error code returned here.

Returns: The formatted relative datetime

Stable: ICU 64

References U_I18N_API.

◆ formatToValue() [2/3]

U_I18N_API FormattedRelativeDateTime icu::RelativeDateTimeFormatter::formatToValue	(	double	quantity,
		UDateDirection	direction,
		UDateRelativeUnit	unit,
		UErrorCode &	status ) const

Formats a relative date with a quantity such as "in 5 days" or "3 months ago".

This method returns a FormattedRelativeDateTime, which exposes more information than the String returned by format().

Parameters

quantity	The numerical amount e.g 5. This value is formatted according to this object's NumberFormat object.
direction	NEXT means a future relative date; LAST means a past relative date. If direction is anything else, this method sets status to U_ILLEGAL_ARGUMENT_ERROR.
unit	the unit e.g day? month? year?
status	ICU error code returned here.

Returns: The formatted relative datetime

Stable: ICU 64

References U_I18N_API.

◆ formatToValue() [3/3]

U_I18N_API FormattedRelativeDateTime icu::RelativeDateTimeFormatter::formatToValue	(	UDateDirection	direction,
		UDateAbsoluteUnit	unit,
		UErrorCode &	status ) const

Formats a relative date without a quantity.

This method returns a FormattedRelativeDateTime, which exposes more information than the String returned by format().

If the string is not available in the requested locale, the return value will be empty (calling toString will give an empty string).

Parameters

direction	NEXT, LAST, THIS, etc.
unit	e.g SATURDAY, DAY, MONTH
status	ICU error code returned here.

Returns: The formatted relative datetime

Stable: ICU 64

References U_I18N_API.

◆ getCapitalizationContext()

U_I18N_API UDisplayContext icu::RelativeDateTimeFormatter::getCapitalizationContext ( ) const

Returns the capitalization context.

Stable: ICU 54

References U_I18N_API.

◆ getFormatStyle()

U_I18N_API UDateRelativeDateTimeFormatterStyle icu::RelativeDateTimeFormatter::getFormatStyle ( ) const

Returns the format style.

Stable: ICU 54

References U_I18N_API, and UCONFIG_NO_BREAK_ITERATION.

◆ getNumberFormat()

U_I18N_API const NumberFormat & icu::RelativeDateTimeFormatter::getNumberFormat ( ) const

Returns the NumberFormat this object is using.

Stable: ICU 53

References U_I18N_API.

◆ operator=()

U_I18N_API RelativeDateTimeFormatter & icu::RelativeDateTimeFormatter::operator= ( const RelativeDateTimeFormatter & other )

Assignment operator.

Stable: ICU 53

References RelativeDateTimeFormatter(), and U_I18N_API.

The documentation for this class was generated from the following file:

i18n/unicode/reldatefmt.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ RelativeDateTimeFormatter() [1/5]

◆ RelativeDateTimeFormatter() [2/5]

◆ RelativeDateTimeFormatter() [3/5]

◆ RelativeDateTimeFormatter() [4/5]

◆ RelativeDateTimeFormatter() [5/5]

◆ ~RelativeDateTimeFormatter()

Member Function Documentation

◆ combineDateAndTime()

◆ format() [1/3]

◆ format() [2/3]

◆ format() [3/3]

◆ formatNumeric()

◆ formatNumericToValue()

◆ formatToValue() [1/3]

◆ formatToValue() [2/3]

◆ formatToValue() [3/3]

◆ getCapitalizationContext()

◆ getFormatStyle()

◆ getNumberFormat()

◆ operator=()