Returns a string representing a relative time (ago, in) for a given number, Date or Datetime.

• relative is a number or Date/Datetime representing the time distance from now or from options[:relative_to]

• options is a Keyword list of options which are:

  • :locale is the locale in which the binary is formatted. The default is Cldr.get_locale/0
  • :format is the format of the binary. Format may be :default, :narrow or :short
  • :unit is the time unit for the formatting. The allowable units are :second, :minute, :hour, :day, :week, :month, :year, :mon, :tue, :wed, :thu, :fri, :sat, :sun, :quarter
  • :relative_to is the baseline Date or Datetime from which the difference from relative is calculated when relative is a Date or a DateTime. The default for a Date is Date.utc_today, for a DateTime it is DateTime.utc_now

Examples

iex> Cldr.Date.Relative.to_string(-1)
"1 second ago"

iex> Cldr.Date.Relative.to_string(1)
"in 1 second"

iex> Cldr.Date.Relative.to_string(1, unit: :day)
"tomorrow"

iex> Cldr.Date.Relative.to_string(1, unit: :day, locale: "fr")
"demain"

iex> Cldr.Date.Relative.to_string(1, unit: :day, format: :narrow)
"tomorrow"

iex> Cldr.Date.Relative.to_string(1234, unit: :year)
"in 1,234 years"

iex> Cldr.Date.Relative.to_string(1234, unit: :year, locale: "fr")
"dans 1 234 ans"

iex> Cldr.Date.Relative.to_string(31)
"in 31 seconds"

iex> Cldr.Date.Relative.to_string(~D[2017-04-29], relative_to: ~D[2017-04-26])
"in 3 days"

iex> Cldr.Date.Relative.to_string(310, format: :short, locale: "fr")
"dans 5 min"

iex> Cldr.Date.Relative.to_string(310, format: :narrow, locale: "fr")
"+5 min"

iex> Cldr.Date.Relative.to_string 2, unit: :wed, format: :short
"in 2 Wed."

iex> Cldr.Date.Relative.to_string 1, unit: :wed, format: :short
"next Wed."

iex> Cldr.Date.Relative.to_string -1, unit: :wed, format: :short
"last Wed."

iex> Cldr.Date.Relative.to_string -1, unit: :wed
"last Wednesday"

iex> Cldr.Date.Relative.to_string -1, unit: :quarter
"last quarter"

iex> Cldr.Date.Relative.to_string -1, unit: :mon, locale: "fr"
"lundi dernier"

iex> Cldr.Date.Relative.to_string(~D[2017-04-29], unit: :ziggeraut)
{:error,
 "Unknown time unit :ziggeraut.  Valid time units are [:day, :hour, :minute, :month, :second, :week, :year, :mon, :tue, :wed, :thu, :fri, :sat, :sun, :quarter]"}

Notes

When options[:unit] is not specified, Cldr.Date.Relative.to_string/2 attempts to identify the appropriate unit based upon the magnitude of relative. For example, given a parameter of less than 60, then to_string/2 will assume :seconds as the unit.