Package com.ibm.icu.text

Class 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"

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

    • Method Detail

      • getInstance

        public static RelativeDateTimeFormatter getInstance()
        Returns a RelativeDateTimeFormatter for the default locale.

      • getInstance

        public static RelativeDateTimeFormatter getInstance​(ULocale locale)
        Returns a RelativeDateTimeFormatter for a particular locale.
        Parameters:
        locale - the locale.
        Returns:
        An instance of RelativeDateTimeFormatter.

      • getInstance

        public static RelativeDateTimeFormatter getInstance​(Locale locale)
        Returns a RelativeDateTimeFormatter for a particular JDK locale.
        Parameters:
        locale - the JDK locale.
        Returns:
        An instance of RelativeDateTimeFormatter.

      • getInstance

        public static RelativeDateTimeFormatter getInstance​(ULocale locale,
                                                    NumberFormat nf)
        Returns a RelativeDateTimeFormatter for a particular locale that uses a particular NumberFormat object.
        Parameters:
        locale - the locale
        nf - the number format object. It is defensively copied to ensure thread-safety and immutability of this class.
        Returns:
        An instance of RelativeDateTimeFormatter.

      • getInstance

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

      • getInstance

        public static RelativeDateTimeFormatter getInstance​(Locale locale,
                                                    NumberFormat nf)
        Returns a RelativeDateTimeFormatter for a particular JDK locale that uses a particular NumberFormat object.
        Parameters:
        locale - the JDK locale
        nf - the number format object. It is defensively copied to ensure thread-safety and immutability of this class.
        Returns:
        An instance of RelativeDateTimeFormatter.

      • format

        public String format​(double quantity,
                     RelativeDateTimeFormatter.Direction direction,
                     RelativeDateTimeFormatter.RelativeUnit unit)
        Formats a relative date with a quantity such as "in 5 days" or "3 months ago"
        Parameters:
        quantity - The numerical amount e.g 5. This value is formatted according to this object's NumberFormat object.
        direction - NEXT means a future relative date; LAST means a past relative date.
        unit - the unit e.g day? month? year?
        Returns:
        the formatted string
        Throws:
        IllegalArgumentException - if direction is something other than NEXT or LAST.

      • format

        public String format​(RelativeDateTimeFormatter.Direction direction,
                     RelativeDateTimeFormatter.AbsoluteUnit unit)
        Formats a relative date without a quantity.
        Parameters:
        direction - NEXT, LAST, THIS, etc.
        unit - e.g SATURDAY, DAY, MONTH
        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.
        Throws:
        IllegalArgumentException - if the direction is incompatible with unit this can occur with NOW which can only take PLAIN.

      • combineDateAndTime

        public String combineDateAndTime​(String relativeDateString,
                                 String timeString)
        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.
        Parameters:
        relativeDateString - the relative date e.g 'yesterday'
        timeString - the time e.g '3:45'
        Returns:
        the date and time concatenated according to the default calendar in this locale e.g 'yesterday, 3:45'

      • getNumberFormat

        public NumberFormat getNumberFormat()
        Returns a copy of the NumberFormat this object is using.
        Returns:
        A copy of the NumberFormat.

      • getCapitalizationContext

        public DisplayContext getCapitalizationContext()
        Return capitalization context.