Formats simple relative dates. More...
#include <reldatefmt.h>
Public Member Functions inherited from 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);
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 394 of file reldatefmt.h.
Constructor & Destructor Documentation
◆ RelativeDateTimeFormatter() [1/5]
| icu::RelativeDateTimeFormatter::RelativeDateTimeFormatter | ( | UErrorCode & | status | ) |
Create RelativeDateTimeFormatter with default locale.
- Stable:
- ICU 53
◆ RelativeDateTimeFormatter() [2/5]
| icu::RelativeDateTimeFormatter::RelativeDateTimeFormatter | ( | const Locale & | locale, |
| UErrorCode & | status | ||
| ) |
Create RelativeDateTimeFormatter with given locale.
- Stable:
- ICU 53
◆ RelativeDateTimeFormatter() [3/5]
| 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
◆ RelativeDateTimeFormatter() [4/5]
| 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
◆ RelativeDateTimeFormatter() [5/5]
| icu::RelativeDateTimeFormatter::RelativeDateTimeFormatter | ( | const RelativeDateTimeFormatter & | other | ) |
Copy constructor.
- Stable:
- ICU 53
◆ ~RelativeDateTimeFormatter()
|
virtual |
Destructor.
- Stable:
- ICU 53
Member Function Documentation
◆ combineDateAndTime()
| 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
◆ format() [1/3]
| 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
◆ format() [2/3]
| 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
◆ format() [3/3]
| 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
◆ formatNumeric()
| 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
◆ formatNumericToValue()
| 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
◆ formatToValue() [1/3]
| 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
◆ formatToValue() [2/3]
| 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
◆ formatToValue() [3/3]
| 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
◆ getCapitalizationContext()
| UDisplayContext icu::RelativeDateTimeFormatter::getCapitalizationContext | ( | ) | const |
Returns the capitalization context.
- Stable:
- ICU 54
◆ getFormatStyle()
| UDateRelativeDateTimeFormatterStyle icu::RelativeDateTimeFormatter::getFormatStyle | ( | ) | const |
Returns the format style.
- Stable:
- ICU 54
◆ getNumberFormat()
| const NumberFormat & icu::RelativeDateTimeFormatter::getNumberFormat | ( | ) | const |
Returns the NumberFormat this object is using.
- Stable:
- ICU 53
◆ operator=()
| RelativeDateTimeFormatter & icu::RelativeDateTimeFormatter::operator= | ( | const RelativeDateTimeFormatter & | other | ) |
Assignment operator.
- Stable:
- ICU 53
The documentation for this class was generated from the following file:
- i18n/unicode/reldatefmt.h
