RelativeDateTimeFormatter (moe.ios.core API)

java.lang.Object
- com.ibm.icu.text.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.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`RelativeDateTimeFormatter.AbsoluteUnit` Represents an absolute unit.
`static class`	`RelativeDateTimeFormatter.Direction` Represents a direction for an absolute unit e.g "Next Tuesday" or "Last Tuesday"
`static class`	`RelativeDateTimeFormatter.RelativeUnit` Represents the unit for formatting a relative date.
`static class`	`RelativeDateTimeFormatter.Style` The formatting style

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`String`	`combineDateAndTime(String relativeDateString, String timeString)` Combines a relative date string and a time string in this object's locale.
`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"
`String`	`format(RelativeDateTimeFormatter.Direction direction, RelativeDateTimeFormatter.AbsoluteUnit unit)` Formats a relative date without a quantity.
`DisplayContext`	`getCapitalizationContext()` Return capitalization context.
`RelativeDateTimeFormatter.Style`	`getFormatStyle()` Return style
`static RelativeDateTimeFormatter`	`getInstance()` Returns a RelativeDateTimeFormatter for the default locale.
`static RelativeDateTimeFormatter`	`getInstance(Locale locale)` Returns a RelativeDateTimeFormatter for a particular JDK locale.
`static RelativeDateTimeFormatter`	`getInstance(Locale locale, NumberFormat nf)` Returns a RelativeDateTimeFormatter for a particular JDK locale that uses a particular NumberFormat object.
`static RelativeDateTimeFormatter`	`getInstance(ULocale locale)` Returns a RelativeDateTimeFormatter for a particular locale.
`static RelativeDateTimeFormatter`	`getInstance(ULocale locale, NumberFormat nf)` Returns a RelativeDateTimeFormatter for a particular locale that uses a particular NumberFormat object.
`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
`NumberFormat`	`getNumberFormat()` Returns a copy of the NumberFormat this object is using.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- 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.
  - getFormatStyle
```
public RelativeDateTimeFormatter.Style getFormatStyle()
```
    Return style

Class RelativeDateTimeFormatter

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getInstance

getInstance

getInstance

getInstance

getInstance

getInstance

format

format

combineDateAndTime

getNumberFormat

getCapitalizationContext

getFormatStyle