RelativeDateTimeFormatter

class RelativeDateTimeFormatter

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"
  

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

Summary

Public methods

fun combineDateAndTime(
    relativeDateString: String!, 
    timeString: String!
): String!

fun format(
    quantity: Double, 
    direction: RelativeDateTimeFormatter.Direction!, 
    unit: RelativeDateTimeFormatter.RelativeUnit!
): String!

fun format(
    direction: RelativeDateTimeFormatter.Direction!, 
    unit: RelativeDateTimeFormatter.AbsoluteUnit!
): String!

fun format(
    offset: Double, 
    unit: RelativeDateTimeFormatter.RelativeDateTimeUnit!
): String!

fun formatNumeric(
    offset: Double, 
    unit: RelativeDateTimeFormatter.RelativeDateTimeUnit!
): String!

fun formatNumericToValue(
    offset: Double, 
    unit: RelativeDateTimeFormatter.RelativeDateTimeUnit!
): RelativeDateTimeFormatter.FormattedRelativeDateTime!

fun formatToValue(
    quantity: Double, 
    direction: RelativeDateTimeFormatter.Direction!, 
    unit: RelativeDateTimeFormatter.RelativeUnit!
): RelativeDateTimeFormatter.FormattedRelativeDateTime!

fun formatToValue(
    direction: RelativeDateTimeFormatter.Direction!, 
    unit: RelativeDateTimeFormatter.AbsoluteUnit!
): RelativeDateTimeFormatter.FormattedRelativeDateTime!

fun formatToValue(
    offset: Double, 
    unit: RelativeDateTimeFormatter.RelativeDateTimeUnit!
): RelativeDateTimeFormatter.FormattedRelativeDateTime!

fun getCapitalizationContext(): DisplayContext!

fun getFormatStyle(): RelativeDateTimeFormatter.Style!

static fun getInstance(): RelativeDateTimeFormatter!

static fun getInstance(locale: ULocale!): RelativeDateTimeFormatter!

static fun getInstance(locale: Locale!): RelativeDateTimeFormatter!

static fun getInstance(
    locale: ULocale!, 
    nf: NumberFormat!
): RelativeDateTimeFormatter!

static fun getInstance(
    locale: ULocale!, 
    nf: NumberFormat!, 
    style: RelativeDateTimeFormatter.Style!, 
    capitalizationContext: DisplayContext!
): RelativeDateTimeFormatter!

static fun getInstance(
    locale: Locale!, 
    nf: NumberFormat!
): RelativeDateTimeFormatter!

fun getNumberFormat(): NumberFormat!