Class RelativeDateTimeFormatter

java.lang.Object
com.ibm.icu.text.RelativeDateTimeFormatter
public final class RelativeDateTimeFormatter extends Object
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 both immutable and thread-safe.

Here are some examples of use: 

RelativeDateTimeFormatter fmt = RelativeDateTimeFormatter.getInstance();
fmt.format(1, Direction.NEXT, RelativeUnit.DAYS); // "in 1 day"
fmt.format(3, Direction.NEXT, RelativeUnit.DAYS); // "in 3 days"
fmt.format(3.2, Direction.LAST, RelativeUnit.YEARS); // "3.2 years ago"

fmt.format(Direction.LAST, AbsoluteUnit.SUNDAY); // "last Sunday"
fmt.format(Direction.THIS, AbsoluteUnit.SUNDAY); // "this Sunday"
fmt.format(Direction.NEXT, AbsoluteUnit.SUNDAY); // "next Sunday"
fmt.format(Direction.PLAIN, AbsoluteUnit.SUNDAY); // "Sunday"

fmt.format(Direction.LAST, AbsoluteUnit.DAY); // "yesterday"
fmt.format(Direction.THIS, AbsoluteUnit.DAY); // "today"
fmt.format(Direction.NEXT, AbsoluteUnit.DAY); // "tomorrow"

fmt.format(Direction.PLAIN, AbsoluteUnit.NOW); // "now"

The Style 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.