Top Description Inners Fields Constructors Methods
com.ibm.icu.text

public final Class RelativeDateTimeFormatter

extends Object
Class Inheritance
Imports
java.io.InvalidObjectException, java.text.AttributedCharacterIterator, .Format, java.util.EnumMap, .Locale, com.ibm.icu.impl.CacheBase, .FormattedStringBuilder, .FormattedValueStringBuilderImpl, .ICUData, .ICUResourceBundle, .SimpleFormatterImpl, .SoftCache, .StandardPlural, .UResource, .Utility, com.ibm.icu.impl.number.DecimalQuantity, .DecimalQuantity_DualStorageBCD, com.ibm.icu.lang.UCharacter, com.ibm.icu.util.Calendar, .ICUException, .ULocale, .UResourceBundle
Formats simple relative dates. There are two types of relative dates that it handles:

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.

ICU Status
Stable since ICU 53.

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static enum
RelativeDateTimeFormatter.AbsoluteUnit

Represents an absolute unit.

private static class
RelativeDateTimeFormatter.Cache

public static enum
RelativeDateTimeFormatter.Direction

Represents a direction for an absolute unit e.g "Next Tuesday" or "Last Tuesday"

public static class
RelativeDateTimeFormatter.Field

Field constants used when accessing field information for relative datetime strings in FormattedValue.

public static class
RelativeDateTimeFormatter.FormattedRelativeDateTime

Represents the result of a formatting operation of a relative datetime.

private static class
RelativeDateTimeFormatter.Loader

private static class
RelativeDateTimeFormatter.RelativeDateTimeFormatterData

public static enum
RelativeDateTimeFormatter.RelativeDateTimeUnit

Represents the unit for formatting a relative date.

public static enum
RelativeDateTimeFormatter.RelativeUnit

Represents the unit for formatting a relative date.

private static class
RelativeDateTimeFormatter.RelDateTimeDataSink

Sink for enumerating all of the relative data time formatter names.

public static enum
RelativeDateTimeFormatter.Style

The formatting style

Field Summary

Modifier and TypeField and Description
private final BreakIterator
breakIterator

private static final RelativeDateTimeFormatter.Cache
cache

private final DisplayContext
capitalizationContext

private final String
combinedDateAndTime

private final DateFormatSymbols
dateFormatSymbols

private static final RelativeDateTimeFormatter.Style[]
fallbackCache

private final ULocale
locale

private final NumberFormat
numberFormat

private final EnumMap<RelativeDateTimeFormatter.Style, EnumMap<RelativeDateTimeFormatter.RelativeUnit, String[][]>>
patternMap

private final PluralRules
pluralRules

private final EnumMap<RelativeDateTimeFormatter.Style, EnumMap<RelativeDateTimeFormatter.AbsoluteUnit, EnumMap<RelativeDateTimeFormatter.Direction, String>>>
qualitativeUnitMap

private final RelativeDateTimeFormatter.Style
style

private int[]
styleToDateFormatSymbolsWidth

Constructor Summary

AccessConstructor and Description
private
RelativeDateTimeFormatter(EnumMap<RelativeDateTimeFormatter.Style, EnumMap<RelativeDateTimeFormatter.AbsoluteUnit, EnumMap<RelativeDateTimeFormatter.Direction, String>>> qualitativeUnitMap, EnumMap<RelativeDateTimeFormatter.Style, EnumMap<RelativeDateTimeFormatter.RelativeUnit, String[][]>> patternMap, String combinedDateAndTime, PluralRules pluralRules, NumberFormat numberFormat, RelativeDateTimeFormatter.Style style, DisplayContext capitalizationContext, BreakIterator breakIterator, ULocale locale)

Method Summary

Modifier and TypeMethod and Description
private String
adjustForContext(String originalFormattedString)

private void
checkNoAdjustForContext()

public String

Returns:

the date and time concatenated according to the default calendar in this locale e.g 'yesterday, 3:45'
combineDateAndTime(String
the relative date e.g 'yesterday'
relativeDateString, String
the time e.g '3:45'
timeString)

Combines a relative date string and a time string in this object's locale.

public String

Returns:

the formatted string
format(double
The numerical amount e.g 5. This value is formatted according to this object's NumberFormat object.
quantity, RelativeDateTimeFormatter.Direction
NEXT means a future relative date; LAST means a past relative date.
direction, RelativeDateTimeFormatter.RelativeUnit
the unit e.g day? month? year?
unit)

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

public String

Returns:

the formatted string. If direction has a value that is documented as not being fully supported in every locale (for example NEXT_2 or LAST_2) then this function may return null to signal that no formatted string is available.
format(RelativeDateTimeFormatter.Direction
NEXT, LAST, THIS, etc.
direction, RelativeDateTimeFormatter.AbsoluteUnit
e.g SATURDAY, DAY, MONTH
unit)

Formats a relative date without a quantity.

public String

Returns:

The formatted string (may be empty in case of error)
format(double
The signed offset for the specified field.
offset, RelativeDateTimeFormatter.RelativeDateTimeUnit
The unit to use when formatting the relative date, e.g. RelativeDateTimeUnit.WEEK, RelativeDateTimeUnit.FRIDAY.
unit)

Format a combination of RelativeDateTimeUnit and numeric offset using a text style if possible, e.g. "last week", "this week", "next week", "yesterday", "tomorrow".

private String
formatAbsoluteImpl(RelativeDateTimeFormatter.Direction direction, RelativeDateTimeFormatter.AbsoluteUnit unit)

Implementation method for format and formatToValue with AbsoluteUnit

private FormattedStringBuilder
formatImpl(double quantity, RelativeDateTimeFormatter.Direction direction, RelativeDateTimeFormatter.RelativeUnit unit)

Implementation method for format and formatToValue with RelativeUnit

public String

Returns:

The formatted string (may be empty in case of error)
formatNumeric(double
The signed offset for the specified unit. This will be formatted according to this object's NumberFormat object.
offset, RelativeDateTimeFormatter.RelativeDateTimeUnit
The unit to use when formatting the relative date, e.g. RelativeDateTimeUnit.WEEK, RelativeDateTimeUnit.FRIDAY.
unit)

Format a combination of RelativeDateTimeUnit and numeric offset using a numeric style, e.g. "1 week ago", "in 1 week", "5 weeks ago", "in 5 weeks".

private FormattedStringBuilder
formatNumericImpl(double offset, RelativeDateTimeFormatter.RelativeDateTimeUnit unit)

Implementation method for formatNumeric and formatNumericToValue

public RelativeDateTimeFormatter.FormattedRelativeDateTime

Returns:

The formatted string (may be empty in case of error)
formatNumericToValue(double
The signed offset for the specified unit. This will be formatted according to this object's NumberFormat object.
offset, RelativeDateTimeFormatter.RelativeDateTimeUnit
The unit to use when formatting the relative date, e.g. RelativeDateTimeUnit.WEEK, RelativeDateTimeUnit.FRIDAY.
unit)

Format a combination of RelativeDateTimeUnit and numeric offset using a numeric style, e.g. "1 week ago", "in 1 week", "5 weeks ago", "in 5 weeks".

private CharSequence
formatRelativeImpl(double offset, RelativeDateTimeFormatter.RelativeDateTimeUnit unit)

Implementation method for format and formatToValue with RelativeDateTimeUnit.

public RelativeDateTimeFormatter.FormattedRelativeDateTime

Returns:

the formatted relative datetime
formatToValue(double
The numerical amount e.g 5. This value is formatted according to this object's NumberFormat object.
quantity, RelativeDateTimeFormatter.Direction
NEXT means a future relative date; LAST means a past relative date.
direction, RelativeDateTimeFormatter.RelativeUnit
the unit e.g day? month? year?
unit)

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

public RelativeDateTimeFormatter.FormattedRelativeDateTime

Returns:

the formatted string. If direction has a value that is documented as not being fully supported in every locale (for example NEXT_2 or LAST_2) then this function may return null to signal that no formatted string is available.
formatToValue(RelativeDateTimeFormatter.Direction
NEXT, LAST, THIS, etc.
direction, RelativeDateTimeFormatter.AbsoluteUnit
e.g SATURDAY, DAY, MONTH
unit)

Formats a relative date without a quantity.

public RelativeDateTimeFormatter.FormattedRelativeDateTime

Returns:

The formatted string (may be empty in case of error)
formatToValue(double
The signed offset for the specified field.
offset, RelativeDateTimeFormatter.RelativeDateTimeUnit
The unit to use when formatting the relative date, e.g. RelativeDateTimeUnit.WEEK, RelativeDateTimeUnit.FRIDAY.
unit)

Format a combination of RelativeDateTimeUnit and numeric offset using a text style if possible, e.g. "last week", "this week", "next week", "yesterday", "tomorrow".

private String
getAbsoluteUnitString(RelativeDateTimeFormatter.Style style, RelativeDateTimeFormatter.AbsoluteUnit unit, RelativeDateTimeFormatter.Direction direction)

Gets the string value from qualitativeUnitMap with fallback based on style.

public DisplayContext

Returns:

The capitalization context.
getCapitalizationContext()

Return capitalization context.

public RelativeDateTimeFormatter.Style

Returns:

The formatting style.
getFormatStyle()

Return style

public static RelativeDateTimeFormatter
getInstance()

Returns a RelativeDateTimeFormatter for the default locale.

public static RelativeDateTimeFormatter

Returns:

An instance of RelativeDateTimeFormatter.
getInstance(ULocale
the locale.
locale)

Returns a RelativeDateTimeFormatter for a particular locale.

public static RelativeDateTimeFormatter

Returns:

An instance of RelativeDateTimeFormatter.
getInstance(Locale
the java.util.Locale.
locale)

Returns a RelativeDateTimeFormatter for a particular java.util.Locale.

public static RelativeDateTimeFormatter

Returns:

An instance of RelativeDateTimeFormatter.
getInstance(ULocale
the locale
locale, NumberFormat
the number format object. It is defensively copied to ensure thread-safety and immutability of this class.
nf)

Returns a RelativeDateTimeFormatter for a particular locale that uses a particular NumberFormat object.

public static RelativeDateTimeFormatter
getInstance(ULocale
the locale
locale, NumberFormat
the number format object. It is defensively copied to ensure thread-safety and immutability of this class. May be null.
nf, RelativeDateTimeFormatter.Style
the style.
style, DisplayContext
the capitalization context.
capitalizationContext)

Returns a RelativeDateTimeFormatter for a particular locale that uses a particular NumberFormat object, style, and capitalization context

public static RelativeDateTimeFormatter

Returns:

An instance of RelativeDateTimeFormatter.
getInstance(Locale
the java.util.Locale
locale, NumberFormat
the number format object. It is defensively copied to ensure thread-safety and immutability of this class.
nf)

Returns a RelativeDateTimeFormatter for a particular java.util.Locale that uses a particular NumberFormat object.

public NumberFormat

Returns:

A copy of the NumberFormat.
getNumberFormat()

Returns a copy of the NumberFormat this object is using.

private String
getRelativeUnitPattern(RelativeDateTimeFormatter.Style style, RelativeDateTimeFormatter.RelativeUnit unit, int pastFutureIndex, StandardPlural pluralForm)

private String
getRelativeUnitPluralPattern(RelativeDateTimeFormatter.Style style, RelativeDateTimeFormatter.RelativeUnit unit, int pastFutureIndex, StandardPlural pluralForm)

private static RelativeDateTimeFormatter.Direction
keyToDirection(UResource.Key key)

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait