ICU 65.1  65.1
Public Member Functions
icu::RelativeDateTimeFormatter Class Reference

Formats simple relative dates. More...

#include <reldatefmt.h>

Inheritance diagram for icu::RelativeDateTimeFormatter:
icu::UObject icu::UMemory

Public Member Functions

 RelativeDateTimeFormatter (UErrorCode &status)
 Create RelativeDateTimeFormatter with default locale. More...
 
 RelativeDateTimeFormatter (const Locale &locale, UErrorCode &status)
 Create RelativeDateTimeFormatter with given locale. More...
 
 RelativeDateTimeFormatter (const Locale &locale, NumberFormat *nfToAdopt, UErrorCode &status)
 Create RelativeDateTimeFormatter with given locale and NumberFormat. More...
 
 RelativeDateTimeFormatter (const Locale &locale, NumberFormat *nfToAdopt, UDateRelativeDateTimeFormatterStyle style, UDisplayContext capitalizationContext, UErrorCode &status)
 Create RelativeDateTimeFormatter with given locale, NumberFormat, and capitalization context. More...
 
 RelativeDateTimeFormatter (const RelativeDateTimeFormatter &other)
 Copy constructor. More...
 
RelativeDateTimeFormatter & operator= (const RelativeDateTimeFormatter &other)
 Assignment operator. More...
 
virtual ~RelativeDateTimeFormatter ()
 Destructor. More...
 
UnicodeString & format (double quantity, UDateDirection direction, UDateRelativeUnit unit, UnicodeString &appendTo, UErrorCode &status) const
 Formats a relative date with a quantity such as "in 5 days" or "3 months ago". More...
 
FormattedRelativeDateTime formatToValue (double quantity, UDateDirection direction, UDateRelativeUnit unit, UErrorCode &status) const
 Formats a relative date with a quantity such as "in 5 days" or "3 months ago". More...
 
UnicodeString & format (UDateDirection direction, UDateAbsoluteUnit unit, UnicodeString &appendTo, UErrorCode &status) const
 Formats a relative date without a quantity. More...
 
FormattedRelativeDateTime formatToValue (UDateDirection direction, UDateAbsoluteUnit unit, UErrorCode &status) const
 Formats a relative date without a quantity. More...
 
UnicodeString & formatNumeric (double offset, URelativeDateTimeUnit unit, UnicodeString &appendTo, UErrorCode &status) const
 Format a combination of URelativeDateTimeUnit and numeric offset using a numeric style, e.g. More...
 
FormattedRelativeDateTime formatNumericToValue (double offset, URelativeDateTimeUnit unit, UErrorCode &status) const
 Format a combination of URelativeDateTimeUnit and numeric offset using a numeric style, e.g. More...
 
UnicodeString & format (double offset, URelativeDateTimeUnit unit, UnicodeString &appendTo, UErrorCode &status) const
 Format a combination of URelativeDateTimeUnit and numeric offset using a text style if possible, e.g. More...
 
FormattedRelativeDateTime formatToValue (double offset, URelativeDateTimeUnit unit, UErrorCode &status) const
 Format a combination of URelativeDateTimeUnit and numeric offset using a text style if possible, e.g. More...
 
UnicodeString & combineDateAndTime (const UnicodeString &relativeDateString, const UnicodeString &timeString, UnicodeString &appendTo, UErrorCode &status) const
 Combines a relative date string and a time string in this object's locale. More...
 
const NumberFormat & getNumberFormat () const
 Returns the NumberFormat this object is using. More...
 
UDisplayContext getCapitalizationContext () const
 Returns the capitalization context. More...
 
UDateRelativeDateTimeFormatterStyle getFormatStyle () const
 Returns the format style. More...
 
- Public Member Functions inherited from icu::UObject
virtual ~UObject ()
 Destructor. More...
 
virtual UClassID getDynamicClassID () const
 ICU4C "poor man's RTTI", returns a UClassID for the actual ICU class. More...
 

Detailed Description

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 mostly thread safe and immutable with the following caveats:

  1. The assignment operator violates Immutability. It must not be used concurrently with other operations.
  2. Caller must not hold onto adopted pointers.

This class is not intended for public subclassing.

Here are some examples of use: 

UErrorCode status = U_ZERO_ERROR;
UnicodeString appendTo;
RelativeDateTimeFormatter fmt(status);
// Appends "in 1 day"
fmt.format(
    1, UDAT_DIRECTION_NEXT, UDAT_RELATIVE_DAYS, appendTo, status);
// Appends "in 3 days"
fmt.format(
    3, UDAT_DIRECTION_NEXT, UDAT_RELATIVE_DAYS, appendTo, status);
// Appends "3.2 years ago"
fmt.format(
    3.2, UDAT_DIRECTION_LAST, UDAT_RELATIVE_YEARS, appendTo, status);
// Appends "last Sunday"
fmt.format(UDAT_DIRECTION_LAST, UDAT_ABSOLUTE_SUNDAY, appendTo, status);
// Appends "this Sunday"
fmt.format(UDAT_DIRECTION_THIS, UDAT_ABSOLUTE_SUNDAY, appendTo, status);
// Appends "next Sunday"
fmt.format(UDAT_DIRECTION_NEXT, UDAT_ABSOLUTE_SUNDAY, appendTo, status);
// Appends "Sunday"
fmt.format(UDAT_DIRECTION_PLAIN, UDAT_ABSOLUTE_SUNDAY, appendTo, status);
// Appends "yesterday"
fmt.format(UDAT_DIRECTION_LAST, UDAT_ABSOLUTE_DAY, appendTo, status);
// Appends "today"
fmt.format(UDAT_DIRECTION_THIS, UDAT_ABSOLUTE_DAY, appendTo, status);
// Appends "tomorrow"
fmt.format(UDAT_DIRECTION_NEXT, UDAT_ABSOLUTE_DAY, appendTo, status);
// Appends "now"
fmt.format(UDAT_DIRECTION_PLAIN, UDAT_ABSOLUTE_NOW, appendTo, status);
 


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


The RelativeDateTimeFormatter class is not intended for public subclassing.


Stable:
ICU 53 



Definition at line 400 of file reldatefmt.h.


Constructor & Destructor Documentation



◆ RelativeDateTimeFormatter() [1/5]






      

        

          icu::RelativeDateTimeFormatter::RelativeDateTimeFormatter 
          (
          UErrorCode & 
          status)
          
        

      





Create RelativeDateTimeFormatter with default locale. 


Stable:
ICU 53 








◆ RelativeDateTimeFormatter() [2/5]






      

        

          icu::RelativeDateTimeFormatter::RelativeDateTimeFormatter 
          (
          const Locale & 
          locale, 
        

        

          
          
          UErrorCode & 
          status 
        

        

          
          )
          
        

      





Create RelativeDateTimeFormatter with given locale. 


Stable:
ICU 53 








◆ RelativeDateTimeFormatter() [3/5]






      

        

          icu::RelativeDateTimeFormatter::RelativeDateTimeFormatter 
          (
          const Locale & 
          locale, 
        

        

          
          
          NumberFormat * 
          nfToAdopt, 
        

        

          
          
          UErrorCode & 
          status 
        

        

          
          )
          
        

      





Create RelativeDateTimeFormatter with given locale and NumberFormat. 


Parameters

  

    
localethe locale 

    
nfToAdoptConstructed object takes ownership of this pointer. It is an error for caller to delete this pointer or change its contents after calling this constructor. 

    
statusAny error is returned here. 

  

  




Stable:
ICU 53 








◆ RelativeDateTimeFormatter() [4/5]






      

        

          icu::RelativeDateTimeFormatter::RelativeDateTimeFormatter 
          (
          const Locale & 
          locale, 
        

        

          
          
          NumberFormat * 
          nfToAdopt, 
        

        

          
          
          UDateRelativeDateTimeFormatterStyle 
          style, 
        

        

          
          
          UDisplayContext 
          capitalizationContext, 
        

        

          
          
          UErrorCode & 
          status 
        

        

          
          )
          
        

      





Create RelativeDateTimeFormatter with given locale, NumberFormat, and capitalization context. 


Parameters

  

    
localethe locale 

    
nfToAdoptConstructed object takes ownership of this pointer. It is an error for caller to delete this pointer or change its contents after calling this constructor. Caller may pass NULL for this argument if they want default number format behavior. 

    
stylethe format style. The UDAT_RELATIVE bit field has no effect. 

    
capitalizationContextA value from UDisplayContext that pertains to capitalization. 

    
statusAny error is returned here. 

  

  




Stable:
ICU 54 








◆ RelativeDateTimeFormatter() [5/5]






      

        

          icu::RelativeDateTimeFormatter::RelativeDateTimeFormatter 
          (
          const RelativeDateTimeFormatter & 
          other)
          
        

      





Copy constructor. 


Stable:
ICU 53 








◆ ~RelativeDateTimeFormatter()








  

  
      

        

          virtual icu::RelativeDateTimeFormatter::~RelativeDateTimeFormatter 
          (
          )
          
        

      

  		
  
virtual  
  







Destructor. 


Stable:
ICU 53 







Member Function Documentation



◆ combineDateAndTime()






      

        

          UnicodeString& icu::RelativeDateTimeFormatter::combineDateAndTime 
          (
          const UnicodeString & 
          relativeDateString, 
        

        

          
          
          const UnicodeString & 
          timeString, 
        

        

          
          
          UnicodeString & 
          appendTo, 
        

        

          
          
          UErrorCode & 
          status 
        

        

          
          )
           const
        

      





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

  

    
relativeDateStringthe relative date, e.g 'yesterday' 

    
timeStringthe time e.g '3:45' 

    
appendToconcatenated date and time appended here 

    
statusICU error code returned here. 

  

  




Returns
appendTo 


Stable:
ICU 53 








◆ format() [1/3]






      

        

          UnicodeString& icu::RelativeDateTimeFormatter::format 
          (
          double 
          quantity, 
        

        

          
          
          UDateDirection 
          direction, 
        

        

          
          
          UDateRelativeUnit 
          unit, 
        

        

          
          
          UnicodeString & 
          appendTo, 
        

        

          
          
          UErrorCode & 
          status 
        

        

          
          )
           const
        

      





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


This method returns a String. To get more information about the formatting result, use formatToValue().


Parameters

  

    
quantityThe numerical amount e.g 5. This value is formatted according to this object's NumberFormat object. 

    
directionNEXT means a future relative date; LAST means a past relative date. If direction is anything else, this method sets status to U_ILLEGAL_ARGUMENT_ERROR. 

    
unitthe unit e.g day? month? year? 

    
appendToThe string to which the formatted result will be appended 

    
statusICU error code returned here. 

  

  




Returns
appendTo 


Stable:
ICU 53 








◆ format() [2/3]






      

        

          UnicodeString& icu::RelativeDateTimeFormatter::format 
          (
          UDateDirection 
          direction, 
        

        

          
          
          UDateAbsoluteUnit 
          unit, 
        

        

          
          
          UnicodeString & 
          appendTo, 
        

        

          
          
          UErrorCode & 
          status 
        

        

          
          )
           const
        

      





Formats a relative date without a quantity. 


This method returns a String. To get more information about the formatting result, use formatToValue().


Parameters

  

    
directionNEXT, LAST, THIS, etc. 

    
unite.g SATURDAY, DAY, MONTH 

    
appendToThe string to which the formatted result will be appended. If the value of direction is documented as not being fully supported in all locales then this method leaves appendTo unchanged if no format string is available. 

    
statusICU error code returned here. 

  

  




Returns
appendTo 


Stable:
ICU 53 








◆ format() [3/3]






      

        

          UnicodeString& icu::RelativeDateTimeFormatter::format 
          (
          double 
          offset, 
        

        

          
          
          URelativeDateTimeUnit 
          unit, 
        

        

          
          
          UnicodeString & 
          appendTo, 
        

        

          
          
          UErrorCode & 
          status 
        

        

          
          )
           const
        

      





Format a combination of URelativeDateTimeUnit and numeric offset using a text style if possible, e.g. 


"last week", "this week", "next week", "yesterday", "tomorrow". Falls back to numeric style if no appropriate text term is available for the specified offset in the object's locale.


This method returns a String. To get more information about the formatting result, use formatToValue().


Parameters

  

    
offsetThe signed offset for the specified unit. 

    
unitThe unit to use when formatting the relative date, e.g. UDAT_REL_UNIT_WEEK, UDAT_REL_UNIT_FRIDAY. 

    
appendToThe string to which the formatted result will be appended. 

    
statusICU error code returned here. 

  

  




Returns
appendTo 


Stable:
ICU 57 








◆ formatNumeric()






      

        

          UnicodeString& icu::RelativeDateTimeFormatter::formatNumeric 
          (
          double 
          offset, 
        

        

          
          
          URelativeDateTimeUnit 
          unit, 
        

        

          
          
          UnicodeString & 
          appendTo, 
        

        

          
          
          UErrorCode & 
          status 
        

        

          
          )
           const
        

      





Format a combination of URelativeDateTimeUnit and numeric offset using a numeric style, e.g. 


"1 week ago", "in 1 week", "5 weeks ago", "in 5 weeks".


This method returns a String. To get more information about the formatting result, use formatNumericToValue().


Parameters

  

    
offsetThe signed offset for the specified unit. This will be formatted according to this object's NumberFormat object. 

    
unitThe unit to use when formatting the relative date, e.g. UDAT_REL_UNIT_WEEK, UDAT_REL_UNIT_FRIDAY. 

    
appendToThe string to which the formatted result will be appended. 

    
statusICU error code returned here. 

  

  




Returns
appendTo 


Stable:
ICU 57 








◆ formatNumericToValue()






      

        

          FormattedRelativeDateTime icu::RelativeDateTimeFormatter::formatNumericToValue 
          (
          double 
          offset, 
        

        

          
          
          URelativeDateTimeUnit 
          unit, 
        

        

          
          
          UErrorCode & 
          status 
        

        

          
          )
           const
        

      





Format a combination of URelativeDateTimeUnit and numeric offset using a numeric style, e.g. 


"1 week ago", "in 1 week", "5 weeks ago", "in 5 weeks".


This method returns a FormattedRelativeDateTime, which exposes more information than the String returned by formatNumeric().


Parameters

  

    
offsetThe signed offset for the specified unit. This will be formatted according to this object's NumberFormat object. 

    
unitThe unit to use when formatting the relative date, e.g. UDAT_REL_UNIT_WEEK, UDAT_REL_UNIT_FRIDAY. 

    
statusICU error code returned here. 

  

  




Returns
The formatted relative datetime 


Draft:
This API may be changed in the future versions and was introduced in ICU 64 








◆ formatToValue() [1/3]






      

        

          FormattedRelativeDateTime icu::RelativeDateTimeFormatter::formatToValue 
          (
          double 
          quantity, 
        

        

          
          
          UDateDirection 
          direction, 
        

        

          
          
          UDateRelativeUnit 
          unit, 
        

        

          
          
          UErrorCode & 
          status 
        

        

          
          )
           const
        

      





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


This method returns a FormattedRelativeDateTime, which exposes more information than the String returned by format().


Parameters

  

    
quantityThe numerical amount e.g 5. This value is formatted according to this object's NumberFormat object. 

    
directionNEXT means a future relative date; LAST means a past relative date. If direction is anything else, this method sets status to U_ILLEGAL_ARGUMENT_ERROR. 

    
unitthe unit e.g day? month? year? 

    
statusICU error code returned here. 

  

  




Returns
The formatted relative datetime 


Draft:
This API may be changed in the future versions and was introduced in ICU 64 








◆ formatToValue() [2/3]






      

        

          FormattedRelativeDateTime icu::RelativeDateTimeFormatter::formatToValue 
          (
          UDateDirection 
          direction, 
        

        

          
          
          UDateAbsoluteUnit 
          unit, 
        

        

          
          
          UErrorCode & 
          status 
        

        

          
          )
           const
        

      





Formats a relative date without a quantity. 


This method returns a FormattedRelativeDateTime, which exposes more information than the String returned by format().


If the string is not available in the requested locale, the return value will be empty (calling toString will give an empty string).


Parameters

  

    
directionNEXT, LAST, THIS, etc. 

    
unite.g SATURDAY, DAY, MONTH 

    
statusICU error code returned here. 

  

  




Returns
The formatted relative datetime 


Draft:
This API may be changed in the future versions and was introduced in ICU 64 








◆ formatToValue() [3/3]






      

        

          FormattedRelativeDateTime icu::RelativeDateTimeFormatter::formatToValue 
          (
          double 
          offset, 
        

        

          
          
          URelativeDateTimeUnit 
          unit, 
        

        

          
          
          UErrorCode & 
          status 
        

        

          
          )
           const
        

      





Format a combination of URelativeDateTimeUnit and numeric offset using a text style if possible, e.g. 


"last week", "this week", "next week", "yesterday", "tomorrow". Falls back to numeric style if no appropriate text term is available for the specified offset in the object's locale.


This method returns a FormattedRelativeDateTime, which exposes more information than the String returned by format().


Parameters

  

    
offsetThe signed offset for the specified unit. 

    
unitThe unit to use when formatting the relative date, e.g. UDAT_REL_UNIT_WEEK, UDAT_REL_UNIT_FRIDAY. 

    
statusICU error code returned here. 

  

  




Returns
The formatted relative datetime 


Draft:
This API may be changed in the future versions and was introduced in ICU 64 








◆ getCapitalizationContext()






      

        

          UDisplayContext icu::RelativeDateTimeFormatter::getCapitalizationContext 
          (
          )
           const
        

      





Returns the capitalization context. 


Stable:
ICU 54 








◆ getFormatStyle()






      

        

          UDateRelativeDateTimeFormatterStyle icu::RelativeDateTimeFormatter::getFormatStyle 
          (
          )
           const
        

      





Returns the format style. 


Stable:
ICU 54 








◆ getNumberFormat()






      

        

          const NumberFormat& icu::RelativeDateTimeFormatter::getNumberFormat 
          (
          )
           const
        

      





Returns the NumberFormat this object is using. 


Stable:
ICU 53 








◆ operator=()






      

        

          RelativeDateTimeFormatter& icu::RelativeDateTimeFormatter::operator= 
          (
          const RelativeDateTimeFormatter & 
          other)
          
        

      





Assignment operator. 


Stable:
ICU 53 







The documentation for this class was generated from the following file:





Generated by  
doxygen
 1.8.13