/* ******************************************************************************* * Copyright (C) 2013-2015, 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: *
* 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.
*
* @stable ICU 53
*/
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"
* @stable ICU 53
*/
public static enum RelativeUnit {
/**
* Seconds
* @stable ICU 53
*/
SECONDS,
/**
* Minutes
* @stable ICU 53
*/
MINUTES,
/**
* Hours
* @stable ICU 53
*/
HOURS,
/**
* Days
* @stable ICU 53
*/
DAYS,
/**
* Weeks
* @stable ICU 53
*/
WEEKS,
/**
* Months
* @stable ICU 53
*/
MONTHS,
/**
* Years
* @stable ICU 53
*/
YEARS,
}
/**
* Represents an absolute unit.
* @stable ICU 53
*/
public static enum AbsoluteUnit {
/**
* Sunday
* @stable ICU 53
*/
SUNDAY,
/**
* Monday
* @stable ICU 53
*/
MONDAY,
/**
* Tuesday
* @stable ICU 53
*/
TUESDAY,
/**
* Wednesday
* @stable ICU 53
*/
WEDNESDAY,
/**
* Thursday
* @stable ICU 53
*/
THURSDAY,
/**
* Friday
* @stable ICU 53
*/
FRIDAY,
/**
* Saturday
* @stable ICU 53
*/
SATURDAY,
/**
* Day
* @stable ICU 53
*/
DAY,
/**
* Week
* @stable ICU 53
*/
WEEK,
/**
* Month
* @stable ICU 53
*/
MONTH,
/**
* Year
* @stable ICU 53
*/
YEAR,
/**
* Now
* @stable ICU 53
*/
NOW,
}
/**
* Represents a direction for an absolute unit e.g "Next Tuesday"
* or "Last Tuesday"
* @stable ICU 53
*/
public static enum Direction {
/**
* Two before. Not fully supported in every locale
* @stable ICU 53
*/
LAST_2,
/**
* Last
* @stable ICU 53
*/
LAST,
/**
* This
* @stable ICU 53
*/
THIS,
/**
* Next
* @stable ICU 53
*/
NEXT,
/**
* Two after. Not fully supported in every locale
* @stable ICU 53
*/
NEXT_2,
/**
* Plain, which means the absence of a qualifier
* @stable ICU 53
*/
PLAIN;
}
/**
* Returns a RelativeDateTimeFormatter for the default locale.
* @stable ICU 53
*/
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.
* @stable ICU 53
*/
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.
* @stable ICU 53
*/
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.
* @stable ICU 53
*/
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.
* @stable ICU 53
*/
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'
* @stable ICU 53
*/
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.
* @stable ICU 53
*/
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