com.ibm.icu.text.RelativeDateTimeFormatter Maven / Gradle / Ivy
Show all versions of icu4j Show documentation
/*
*******************************************************************************
* Copyright (C) 2013-2014, International Business Machines Corporation and
* others. All Rights Reserved.
*******************************************************************************
*/
package com.ibm.icu.text;
import java.util.EnumMap;
import java.util.Locale;
import com.ibm.icu.impl.CalendarData;
import com.ibm.icu.impl.ICUCache;
import com.ibm.icu.impl.ICUResourceBundle;
import com.ibm.icu.impl.SimpleCache;
import com.ibm.icu.lang.UCharacter;
import com.ibm.icu.util.ULocale;
import com.ibm.icu.util.UResourceBundle;
/**
* 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.
*
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
public final class RelativeDateTimeFormatter {
/**
* The formatting style
* @draft ICU 54
* @provisional This API might change or be removed in a future release.
*
*/
public static enum Style {
/**
* Everything spelled out.
* @draft ICU 54
* @provisional This API might change or be removed in a future release.
*/
LONG,
/**
* Abbreviations used when possible.
* @draft ICU 54
* @provisional This API might change or be removed in a future release.
*/
SHORT,
/**
* Use single letters when possible.
* @draft ICU 54
* @provisional This API might change or be removed in a future release.
*/
NARROW,
}
/**
* Represents the unit for formatting a relative date. e.g "in 5 days"
* or "in 3 months"
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
public static enum RelativeUnit {
/**
* Seconds
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
SECONDS,
/**
* Minutes
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
MINUTES,
/**
* Hours
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
HOURS,
/**
* Days
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
DAYS,
/**
* Weeks
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
WEEKS,
/**
* Months
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
MONTHS,
/**
* Years
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
YEARS,
}
/**
* Represents an absolute unit.
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
public static enum AbsoluteUnit {
/**
* Sunday
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
SUNDAY,
/**
* Monday
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
MONDAY,
/**
* Tuesday
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
TUESDAY,
/**
* Wednesday
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
WEDNESDAY,
/**
* Thursday
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
THURSDAY,
/**
* Friday
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
FRIDAY,
/**
* Saturday
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
SATURDAY,
/**
* Day
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
DAY,
/**
* Week
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
WEEK,
/**
* Month
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
MONTH,
/**
* Year
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
YEAR,
/**
* Now
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
NOW,
}
/**
* Represents a direction for an absolute unit e.g "Next Tuesday"
* or "Last Tuesday"
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
public static enum Direction {
/**
* Two before. Not fully supported in every locale
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
LAST_2,
/**
* Last
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
LAST,
/**
* This
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
THIS,
/**
* Next
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
NEXT,
/**
* Two after. Not fully supported in every locale
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
NEXT_2,
/**
* Plain, which means the absence of a qualifier
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
PLAIN;
}
/**
* Returns a RelativeDateTimeFormatter for the default locale.
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
public static RelativeDateTimeFormatter getInstance() {
return getInstance(ULocale.getDefault(), null, Style.LONG, DisplayContext.CAPITALIZATION_NONE);
}
/**
* Returns a RelativeDateTimeFormatter for a particular locale.
*
* @param locale the locale.
* @return An instance of RelativeDateTimeFormatter.
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
public static RelativeDateTimeFormatter getInstance(ULocale locale) {
return getInstance(locale, null, Style.LONG, DisplayContext.CAPITALIZATION_NONE);
}
/**
* Returns a RelativeDateTimeFormatter for a particular JDK locale.
*
* @param locale the JDK locale.
* @return An instance of RelativeDateTimeFormatter.
* @draft ICU 54
* @provisional This API might change or be removed in a future release.
*/
public static RelativeDateTimeFormatter getInstance(Locale locale) {
return getInstance(ULocale.forLocale(locale));
}
/**
* Returns a RelativeDateTimeFormatter for a particular locale that uses a particular
* NumberFormat object.
*
* @param locale the locale
* @param nf the number format object. It is defensively copied to ensure thread-safety
* and immutability of this class.
* @return An instance of RelativeDateTimeFormatter.
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
public static RelativeDateTimeFormatter getInstance(ULocale locale, NumberFormat nf) {
return getInstance(locale, nf, Style.LONG, DisplayContext.CAPITALIZATION_NONE);
}
/**
* Returns a RelativeDateTimeFormatter for a particular locale that uses a particular
* NumberFormat object, style, and capitalization context
*
* @param locale the locale
* @param nf the number format object. It is defensively copied to ensure thread-safety
* and immutability of this class. May be null.
* @param style the style.
* @param capitalizationContext the capitalization context.
* @draft ICU 54
* @provisional This API might change or be removed in a future release.
*/
public static RelativeDateTimeFormatter getInstance(
ULocale locale,
NumberFormat nf,
Style style,
DisplayContext capitalizationContext) {
RelativeDateTimeFormatterData data = cache.get(locale);
if (nf == null) {
nf = NumberFormat.getInstance(locale);
} else {
nf = (NumberFormat) nf.clone();
}
return new RelativeDateTimeFormatter(
data.qualitativeUnitMap,
data.quantitativeUnitMap,
new MessageFormat(data.dateTimePattern),
PluralRules.forLocale(locale),
nf,
style,
capitalizationContext,
capitalizationContext == DisplayContext.CAPITALIZATION_FOR_BEGINNING_OF_SENTENCE ?
BreakIterator.getSentenceInstance(locale) : null,
locale);
}
/**
* Returns a RelativeDateTimeFormatter for a particular JDK locale that uses a particular
* NumberFormat object.
*
* @param locale the JDK locale
* @param nf the number format object. It is defensively copied to ensure thread-safety
* and immutability of this class.
* @return An instance of RelativeDateTimeFormatter.
* @draft ICU 54
* @provisional This API might change or be removed in a future release.
*/
public static RelativeDateTimeFormatter getInstance(Locale locale, NumberFormat nf) {
return getInstance(ULocale.forLocale(locale), nf);
}
/**
* Formats a relative date with a quantity such as "in 5 days" or
* "3 months ago"
* @param quantity The numerical amount e.g 5. This value is formatted
* according to this object's {@link NumberFormat} object.
* @param direction NEXT means a future relative date; LAST means a past
* relative date.
* @param unit the unit e.g day? month? year?
* @return the formatted string
* @throws IllegalArgumentException if direction is something other than
* NEXT or LAST.
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
public String format(double quantity, Direction direction, RelativeUnit unit) {
if (direction != Direction.LAST && direction != Direction.NEXT) {
throw new IllegalArgumentException("direction must be NEXT or LAST");
}
String result;
// This class is thread-safe, yet numberFormat is not. To ensure thread-safety of this
// class we must guarantee that only one thread at a time uses our numberFormat.
synchronized (numberFormat) {
result = getQuantity(
unit, direction == Direction.NEXT).format(
quantity, numberFormat, pluralRules);
}
return adjustForContext(result);
}
/**
* Formats a relative date without a quantity.
* @param direction NEXT, LAST, THIS, etc.
* @param unit e.g SATURDAY, DAY, MONTH
* @return 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.
* @throws IllegalArgumentException if the direction is incompatible with
* unit this can occur with NOW which can only take PLAIN.
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
public String format(Direction direction, AbsoluteUnit unit) {
if (unit == AbsoluteUnit.NOW && direction != Direction.PLAIN) {
throw new IllegalArgumentException("NOW can only accept direction PLAIN.");
}
String result = this.qualitativeUnitMap.get(style).get(unit).get(direction);
return result != null ? adjustForContext(result) : null;
}
/**
* 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.
* @param relativeDateString the relative date e.g 'yesterday'
* @param timeString the time e.g '3:45'
* @return the date and time concatenated according to the default
* calendar in this locale e.g 'yesterday, 3:45'
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
public String combineDateAndTime(String relativeDateString, String timeString) {
return this.combinedDateAndTime.format(
new Object[]{timeString, relativeDateString}, new StringBuffer(), null).toString();
}
/**
* Returns a copy of the NumberFormat this object is using.
* @return A copy of the NumberFormat.
* @draft ICU 53
* @provisional This API might change or be removed in a future release.
*/
public NumberFormat getNumberFormat() {
// This class is thread-safe, yet numberFormat is not. To ensure thread-safety of this
// class we must guarantee that only one thread at a time uses our numberFormat.
synchronized (numberFormat) {
return (NumberFormat) numberFormat.clone();
}
}
/**
* Return capitalization context.
*
* @draft ICU 54
* @provisional This API might change or be removed in a future release.
*/
public DisplayContext getCapitalizationContext() {
return capitalizationContext;
}
/**
* Return style
*
* @draft ICU 54
* @provisional This API might change or be removed in a future release.
*/
public Style getFormatStyle() {
return style;
}
private String adjustForContext(String originalFormattedString) {
if (breakIterator == null || originalFormattedString.length() == 0
|| !UCharacter.isLowerCase(UCharacter.codePointAt(originalFormattedString, 0))) {
return originalFormattedString;
}
synchronized (breakIterator) {
return UCharacter.toTitleCase(
locale,
originalFormattedString,
breakIterator,
UCharacter.TITLECASE_NO_LOWERCASE | UCharacter.TITLECASE_NO_BREAK_ADJUSTMENT);
}
}
private static void addQualitativeUnit(
EnumMap> qualitativeUnits,
AbsoluteUnit unit,
String current) {
EnumMap unitStrings =
new EnumMap(Direction.class);
unitStrings.put(Direction.PLAIN, current);
qualitativeUnits.put(unit, unitStrings);
}
private static void addQualitativeUnit(
EnumMap> qualitativeUnits,
AbsoluteUnit unit, ICUResourceBundle bundle, String plain) {
EnumMap unitStrings =
new EnumMap(Direction.class);
unitStrings.put(Direction.LAST, bundle.getStringWithFallback("-1"));
unitStrings.put(Direction.THIS, bundle.getStringWithFallback("0"));
unitStrings.put(Direction.NEXT, bundle.getStringWithFallback("1"));
addOptionalDirection(unitStrings, Direction.LAST_2, bundle, "-2");
addOptionalDirection(unitStrings, Direction.NEXT_2, bundle, "2");
unitStrings.put(Direction.PLAIN, plain);
qualitativeUnits.put(unit, unitStrings);
}
private static void addOptionalDirection(
EnumMap unitStrings,
Direction direction,
ICUResourceBundle bundle,
String key) {
String s = bundle.findStringWithFallback(key);
if (s != null) {
unitStrings.put(direction, s);
}
}
private RelativeDateTimeFormatter(
EnumMap