ICU 58.2 58.2

- Main Page
- Related Pages
- Modules
- Namespaces
- Data Structures
- Files

- Data Structures
- Data Structure Index
- Class Hierarchy
- Data Fields

Public Member Functions
icu::RelativeDateTimeFormatter Class Reference

Formats simple relative dates. More...

`#include <reldatefmt.h>`

Inheritance diagram for icu::RelativeDateTimeFormatter:

## Public Member Functions
| RelativeDateTimeFormatter (UErrorCode &status)
| Create RelativeDateTimeFormatter with default locale. More...
| RelativeDateTimeFormatter (const Locale &locale, UErrorCode &status)
| Create RelativeDateTimeFormatter with given locale. More...
| RelativeDateTimeFormatter (const Locale &locale, NumberFormat *nfToAdopt, UErrorCode &status)
| Create RelativeDateTimeFormatter with given locale and NumberFormat. More...
| RelativeDateTimeFormatter (const Locale &locale, NumberFormat *nfToAdopt, UDateRelativeDateTimeFormatterStyle style, UDisplayContext capitalizationContext, UErrorCode &status)
| Create RelativeDateTimeFormatter with given locale, NumberFormat, and capitalization context. More...
| RelativeDateTimeFormatter (const RelativeDateTimeFormatter &other)
| Copy constructor. More...
RelativeDateTimeFormatter & | operator= (const RelativeDateTimeFormatter &other)
| Assignment operator. More...
virtual | ~RelativeDateTimeFormatter ()
| Destructor. More...
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". More...
UnicodeString & | format (UDateDirection direction, UDateAbsoluteUnit unit, UnicodeString &appendTo, UErrorCode &status) const
| Formats a relative date without a quantity. More...
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. More...
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. More...
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. More...
const NumberFormat & | getNumberFormat () const
| Returns the NumberFormat this object is using. More...
UDisplayContext | getCapitalizationContext () const
| Returns the capitalization context. More...
UDateRelativeDateTimeFormatterStyle | getFormatStyle () const
| Returns the format style. More...
Public Member Functions inherited from icu::UObject
virtual | ~UObject ()
| Destructor. More...
virtual UClassID | getDynamicClassID () const
| ICU4C "poor man's RTTI", returns a UClassID for the actual ICU class. More...

## 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:

1. The assignment operator violates Immutability. It must not be used concurrently with other operations.
2. 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);

In the future, we may add more forms, such as abbreviated/short forms (3 secs ago), and relative day periods ("yesterday afternoon"), etc.

The RelativeDateTimeFormatter class is not intended for public subclassing.

Stable:
  ICU 53

Definition at line 308 of file reldatefmt.h.

## Constructor & Destructor Documentation

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

Create RelativeDateTimeFormatter with default locale.

Stable:
  ICU 53

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

Create RelativeDateTimeFormatter with given locale.

Stable:
  ICU 53

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. Any error is returned here.

Stable:
  ICU 53

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 NULL 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. Any error is returned here.

Stable:
  ICU 54

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

Copy constructor.

Stable:
  ICU 53

virtual icu::RelativeDateTimeFormatter::~RelativeDateTimeFormatter | ( |  | ) |
| virtual

Destructor.

Stable:
  ICU 53

## Member Function Documentation

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

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

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

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

Formats a relative date without a quantity.

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

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.

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

Draft:
  This API may be changed in the future versions and was introduced in ICU 57

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

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

Draft:
  This API may be changed in the future versions and was introduced in ICU 57

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

Returns the capitalization context.

Stable:
  ICU 54

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

Returns the format style.

Stable:
  ICU 54

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

Returns the NumberFormat this object is using.

Stable:
  ICU 53

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

Assignment operator.

Stable:
  ICU 53

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

- reldatefmt.h