Returns a list of the valid unit keys for to_string/2

Example

iex> Cldr.DateTime.Relative.known_units()
[:day, :fri, :hour, :minute, :mon, :month, :quarter, :sat, :second, :sun, :thu, :tue, :wed, :week, :year]

Calculates the time span in the given unit from the time given in seconds.

Examples

iex> Cldr.DateTime.Relative.scale_relative(1234, :second)
1234

iex> Cldr.DateTime.Relative.scale_relative(1234, :minute)
21

iex> Cldr.DateTime.Relative.scale_relative(1234, :hour)
0

@spec to_string(
  integer() | float() | Date.t() | DateTime.t(),
  Cldr.backend(),
  Keyword.t()
) ::
  {:ok, String.t()} | {:error, {module(), String.t()}}

Returns a {:ok, string} representing a relative time (ago, in) for a given number, Date or Datetime. Returns {:error, reason} when errors are detected.

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

• backend is any module that includes use Cldr and therefore is a Cldr backend module. The default is Cldr.default_backend/0.

• options is a Keyword list of options which are:

Options

• :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

Notes

When options[:unit] is not specified, Cldr.DateTime.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. See unit_from_relative_time/1.

Examples

iex> Cldr.DateTime.Relative.to_string(-1, MyApp.Cldr)
{:ok, "1 second ago"}

iex> Cldr.DateTime.Relative.to_string(1, MyApp.Cldr)
{:ok, "in 1 second"}

iex> Cldr.DateTime.Relative.to_string(1, MyApp.Cldr, unit: :day)
{:ok, "tomorrow"}

iex> Cldr.DateTime.Relative.to_string(1, MyApp.Cldr, unit: :day, locale: "fr")
{:ok, "demain"}

iex> Cldr.DateTime.Relative.to_string(1, MyApp.Cldr, unit: :day, format: :narrow)
{:ok, "tomorrow"}

iex> Cldr.DateTime.Relative.to_string(1234, MyApp.Cldr, unit: :year)
{:ok, "in 1,234 years"}

iex> Cldr.DateTime.Relative.to_string(1234, MyApp.Cldr, unit: :year, locale: "fr")
{:ok, "dans 1 234 ans"}

iex> Cldr.DateTime.Relative.to_string(31, MyApp.Cldr)
{:ok, "in 31 seconds"}

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

iex> Cldr.DateTime.Relative.to_string(310, MyApp.Cldr, format: :short, locale: "fr")
{:ok, "dans 5 min"}

iex> Cldr.DateTime.Relative.to_string(310, MyApp.Cldr, format: :narrow, locale: "fr")
{:ok, "+5 min"}

iex> Cldr.DateTime.Relative.to_string 2, MyApp.Cldr, unit: :wed, format: :short, locale: "en"
{:ok, "in 2 Wed."}

iex> Cldr.DateTime.Relative.to_string 1, MyApp.Cldr, unit: :wed, format: :short
{:ok, "next Wed."}

iex> Cldr.DateTime.Relative.to_string -1, MyApp.Cldr, unit: :wed, format: :short
{:ok, "last Wed."}

iex> Cldr.DateTime.Relative.to_string -1, MyApp.Cldr, unit: :wed
{:ok, "last Wednesday"}

iex> Cldr.DateTime.Relative.to_string -1, MyApp.Cldr, unit: :quarter
{:ok, "last quarter"}

iex> Cldr.DateTime.Relative.to_string -1, MyApp.Cldr, unit: :mon, locale: "fr"
{:ok, "lundi dernier"}

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

@spec to_string!(
  integer() | float() | Date.t() | DateTime.t(),
  Cldr.backend(),
  Keyword.t()
) ::
  String.t()

Returns a string representing a relative time (ago, in) for a given number, Date or Datetime or raises an exception on error.

Arguments

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

• backend is any module that includes use Cldr and therefore is a Cldr backend module. The default is Cldr.default_backend/0.

• options is a Keyword list of options.

Options

• :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. The default is :default

• :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

See to_string/3

Returns an estimate of the appropriate time unit for an integer of a given magnitude of seconds.

Examples

iex> Cldr.DateTime.Relative.unit_from_relative_time(1234)
:minute

iex> Cldr.DateTime.Relative.unit_from_relative_time(12345)
:hour

iex> Cldr.DateTime.Relative.unit_from_relative_time(123456)
:day

iex> Cldr.DateTime.Relative.unit_from_relative_time(1234567)
:week

iex> Cldr.DateTime.Relative.unit_from_relative_time(12345678)
:month

iex> Cldr.DateTime.Relative.unit_from_relative_time(123456789)
:year