ICU 59.1  59.1
Namespaces | Typedefs | Enumerations | Functions
ureldatefmt.h File Reference

C API: URelativeDateTimeFormatter, relative date formatting of unit + numeric offset. More...

#include "unicode/utypes.h"
#include "unicode/unum.h"
#include "unicode/udisplaycontext.h"
#include "unicode/localpointer.h"

Go to the source code of this file.

Namespaces

 icu
 File coll.h.
 

Typedefs

typedef enum UDateRelativeDateTimeFormatterStyle UDateRelativeDateTimeFormatterStyle
 The formatting style. More...
 
typedef enum URelativeDateTimeUnit URelativeDateTimeUnit
 Represents the unit for formatting a relative date. More...
 
typedef struct URelativeDateTimeFormatter URelativeDateTimeFormatter
 C typedef for struct URelativeDateTimeFormatter. More...
 

Enumerations

enum  UDateRelativeDateTimeFormatterStyle { UDAT_STYLE_LONG, UDAT_STYLE_SHORT, UDAT_STYLE_NARROW, UDAT_STYLE_COUNT }
 The formatting style. More...
 
enum  URelativeDateTimeUnit {
  UDAT_REL_UNIT_YEAR, UDAT_REL_UNIT_QUARTER, UDAT_REL_UNIT_MONTH, UDAT_REL_UNIT_WEEK,
  UDAT_REL_UNIT_DAY, UDAT_REL_UNIT_HOUR, UDAT_REL_UNIT_MINUTE, UDAT_REL_UNIT_SECOND,
  UDAT_REL_UNIT_SUNDAY, UDAT_REL_UNIT_MONDAY, UDAT_REL_UNIT_TUESDAY, UDAT_REL_UNIT_WEDNESDAY,
  UDAT_REL_UNIT_THURSDAY, UDAT_REL_UNIT_FRIDAY, UDAT_REL_UNIT_SATURDAY, UDAT_REL_UNIT_COUNT
}
 Represents the unit for formatting a relative date. More...
 

Functions

URelativeDateTimeFormatterureldatefmt_open (const char *locale, UNumberFormat *nfToAdopt, UDateRelativeDateTimeFormatterStyle width, UDisplayContext capitalizationContext, UErrorCode *status)
 Open a new URelativeDateTimeFormatter object for a given locale using the specified width and capitalizationContext, along with a number formatter (if desired) to override the default formatter that would be used for display of numeric field offsets. More...
 
void ureldatefmt_close (URelativeDateTimeFormatter *reldatefmt)
 Close a URelativeDateTimeFormatter object. More...
 
int32_t ureldatefmt_formatNumeric (const URelativeDateTimeFormatter *reldatefmt, double offset, URelativeDateTimeUnit unit, UChar *result, int32_t resultCapacity, UErrorCode *status)
 Format a combination of URelativeDateTimeUnit and numeric offset using a numeric style, e.g. More...
 
int32_t ureldatefmt_format (const URelativeDateTimeFormatter *reldatefmt, double offset, URelativeDateTimeUnit unit, UChar *result, int32_t resultCapacity, UErrorCode *status)
 Format a combination of URelativeDateTimeUnit and numeric offset using a text style if possible, e.g. More...
 
int32_t ureldatefmt_combineDateAndTime (const URelativeDateTimeFormatter *reldatefmt, const UChar *relativeDateString, int32_t relativeDateStringLen, const UChar *timeString, int32_t timeStringLen, UChar *result, int32_t resultCapacity, UErrorCode *status)
 Combines a relative date string and a time string in this object's locale. More...
 

Detailed Description

C API: URelativeDateTimeFormatter, relative date formatting of unit + numeric offset.

Provides simple formatting of relative dates, in two ways

This does not provide compound formatting for multiple units, other than the ability to combine a time string with a relative date, as in "next Tuesday at 3:45 PM". It also does not provide support for determining which unit to use, such as deciding between "in 7 days" and "in 1 week".

Stable:
ICU 57

Definition in file ureldatefmt.h.

Typedef Documentation

§ UDateRelativeDateTimeFormatterStyle

The formatting style.

Stable:
ICU 54

§ URelativeDateTimeFormatter

C typedef for struct URelativeDateTimeFormatter.

Stable:
ICU 57

Definition at line 182 of file ureldatefmt.h.

§ URelativeDateTimeUnit

Represents the unit for formatting a relative date.

e.g "in 5 days" or "next year"

Stable:
ICU 57

Enumeration Type Documentation

§ UDateRelativeDateTimeFormatterStyle

The formatting style.

Stable:
ICU 54
Enumerator
UDAT_STYLE_LONG 

Everything spelled out.

Stable:
ICU 54
UDAT_STYLE_SHORT 

Abbreviations used when possible.

Stable:
ICU 54
UDAT_STYLE_NARROW 

Use the shortest possible form.

Stable:
ICU 54
UDAT_STYLE_COUNT 

One more than the highest normal UDateRelativeDateTimeFormatterStyle value.

Deprecated:
ICU 58 The numeric value may change over time, see ICU ticket #12420.

Definition at line 44 of file ureldatefmt.h.

§ URelativeDateTimeUnit

Represents the unit for formatting a relative date.

e.g "in 5 days" or "next year"

Stable:
ICU 57
Enumerator
UDAT_REL_UNIT_YEAR 

Specifies that relative unit is year, e.g.

"last year", "in 5 years".

Stable:
ICU 57
UDAT_REL_UNIT_QUARTER 

Specifies that relative unit is quarter, e.g.

"last quarter", "in 5 quarters".

Stable:
ICU 57
UDAT_REL_UNIT_MONTH 

Specifies that relative unit is month, e.g.

"last month", "in 5 months".

Stable:
ICU 57
UDAT_REL_UNIT_WEEK 

Specifies that relative unit is week, e.g.

"last week", "in 5 weeks".

Stable:
ICU 57
UDAT_REL_UNIT_DAY 

Specifies that relative unit is day, e.g.

"yesterday", "in 5 days".

Stable:
ICU 57
UDAT_REL_UNIT_HOUR 

Specifies that relative unit is hour, e.g.

"1 hour ago", "in 5 hours".

Stable:
ICU 57
UDAT_REL_UNIT_MINUTE 

Specifies that relative unit is minute, e.g.

"1 minute ago", "in 5 minutes".

Stable:
ICU 57
UDAT_REL_UNIT_SECOND 

Specifies that relative unit is second, e.g.

"1 second ago", "in 5 seconds".

Stable:
ICU 57
UDAT_REL_UNIT_SUNDAY 

Specifies that relative unit is Sunday, e.g.

"last Sunday", "this Sunday", "next Sunday", "in 5 Sundays".

Stable:
ICU 57
UDAT_REL_UNIT_MONDAY 

Specifies that relative unit is Monday, e.g.

"last Monday", "this Monday", "next Monday", "in 5 Mondays".

Stable:
ICU 57
UDAT_REL_UNIT_TUESDAY 

Specifies that relative unit is Tuesday, e.g.

"last Tuesday", "this Tuesday", "next Tuesday", "in 5 Tuesdays".

Stable:
ICU 57
UDAT_REL_UNIT_WEDNESDAY 

Specifies that relative unit is Wednesday, e.g.

"last Wednesday", "this Wednesday", "next Wednesday", "in 5 Wednesdays".

Stable:
ICU 57
UDAT_REL_UNIT_THURSDAY 

Specifies that relative unit is Thursday, e.g.

"last Thursday", "this Thursday", "next Thursday", "in 5 Thursdays".

Stable:
ICU 57
UDAT_REL_UNIT_FRIDAY 

Specifies that relative unit is Friday, e.g.

"last Friday", "this Friday", "next Friday", "in 5 Fridays".

Stable:
ICU 57
UDAT_REL_UNIT_SATURDAY 

Specifies that relative unit is Saturday, e.g.

"last Saturday", "this Saturday", "next Saturday", "in 5 Saturdays".

Stable:
ICU 57
UDAT_REL_UNIT_COUNT 

One more than the highest normal URelativeDateTimeUnit value.

Deprecated:
ICU 58 The numeric value may change over time, see ICU ticket #12420.

Definition at line 77 of file ureldatefmt.h.

Function Documentation

§ ureldatefmt_close()

void ureldatefmt_close ( URelativeDateTimeFormatter reldatefmt)

Close a URelativeDateTimeFormatter object.

Once closed it may no longer be used.

Parameters
reldatefmtThe URelativeDateTimeFormatter object to close.
Stable:
ICU 57

§ ureldatefmt_combineDateAndTime()

int32_t ureldatefmt_combineDateAndTime ( const URelativeDateTimeFormatter reldatefmt,
const UChar relativeDateString,
int32_t  relativeDateStringLen,
const UChar timeString,
int32_t  timeStringLen,
UChar result,
int32_t  resultCapacity,
UErrorCode status 
)

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 to produce a result such as "yesterday at 3:45 PM".

Parameters
reldatefmtThe URelativeDateTimeFormatter object specifying the format conventions.
relativeDateStringThe relative date string.
relativeDateStringLenThe length of relativeDateString; may be -1 if relativeDateString is zero-terminated.
timeStringThe time string.
timeStringLenThe length of timeString; may be -1 if timeString is zero-terminated.
resultA pointer to a buffer to receive the formatted result.
resultCapacityThe maximum size of result.
statusA pointer to a UErrorCode to receive any errors. In case of error status, the contents of result are undefined.
Returns
The length of the formatted result; may be greater than resultCapacity, in which case an error is returned.
Stable:
ICU 57

§ ureldatefmt_format()

int32_t ureldatefmt_format ( const URelativeDateTimeFormatter reldatefmt,
double  offset,
URelativeDateTimeUnit  unit,
UChar result,
int32_t  resultCapacity,
UErrorCode status 
)

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.

Parameters
reldatefmtThe URelativeDateTimeFormatter object specifying the format conventions.
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.
resultA pointer to a buffer to receive the formatted result.
resultCapacityThe maximum size of result.
statusA pointer to a UErrorCode to receive any errors. In case of error status, the contents of result are undefined.
Returns
The length of the formatted result; may be greater than resultCapacity, in which case an error is returned.
Stable:
ICU 57

§ ureldatefmt_formatNumeric()

int32_t ureldatefmt_formatNumeric ( const URelativeDateTimeFormatter reldatefmt,
double  offset,
URelativeDateTimeUnit  unit,
UChar result,
int32_t  resultCapacity,
UErrorCode status 
)

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

Parameters
reldatefmtThe URelativeDateTimeFormatter object specifying the format conventions.
offsetThe signed offset for the specified unit. This will be formatted according to this object's UNumberFormat object.
unitThe unit to use when formatting the relative date, e.g. UDAT_REL_UNIT_WEEK, UDAT_REL_UNIT_FRIDAY.
resultA pointer to a buffer to receive the formatted result.
resultCapacityThe maximum size of result.
statusA pointer to a UErrorCode to receive any errors. In case of error status, the contents of result are undefined.
Returns
The length of the formatted result; may be greater than resultCapacity, in which case an error is returned.
Stable:
ICU 57

§ ureldatefmt_open()

URelativeDateTimeFormatter* ureldatefmt_open ( const char *  locale,
UNumberFormat nfToAdopt,
UDateRelativeDateTimeFormatterStyle  width,
UDisplayContext  capitalizationContext,
UErrorCode status 
)

Open a new URelativeDateTimeFormatter object for a given locale using the specified width and capitalizationContext, along with a number formatter (if desired) to override the default formatter that would be used for display of numeric field offsets.

The default formatter typically rounds toward 0 and has a minimum of 0 fraction digits and a maximum of 3 fraction digits (i.e. it will show as many decimal places as necessary up to 3, without showing trailing 0s).

Parameters
localeThe locale
nfToAdoptA number formatter to set for this URelativeDateTimeFormatter object (instead of the default decimal formatter). Ownership of this UNumberFormat object will pass to the URelativeDateTimeFormatter object (the URelativeDateTimeFormatter adopts the UNumberFormat), which becomes responsible for closing it. If the caller wishes to retain ownership of the UNumberFormat object, the caller must clone it (with unum_clone) and pass the clone to ureldatefmt_open. May be NULL to use the default decimal formatter.
widthThe width - wide, short, narrow, etc.
capitalizationContextA value from UDisplayContext that pertains to capitalization, e.g. UDISPCTX_CAPITALIZATION_FOR_BEGINNING_OF_SENTENCE.
statusA pointer to a UErrorCode to receive any errors.
Returns
A pointer to a URelativeDateTimeFormatter object for the specified locale, or NULL if an error occurred.
Stable:
ICU 57