View Source Cldr.DateTime.Relative (Cldr Dates & Times v2.20.3)

Functions to support the string formatting of relative time/datetime numbers.

This module provides formatting of numbers (as integers, floats, Dates or DateTimes) as "ago" or "in" with an appropriate time unit. For example, "2 days ago" or "in 10 seconds"

Summary

Functions

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

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

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

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

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

Functions

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]
Link to this function

scale_relative(time, unit)

View Source

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
Link to this function

to_string(relative, backend \\ Cldr.Date.default_backend(), options \\ [])

View Source
@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 t:Date/0 or t:Datetime.t/0 from which the difference from relative is calculated when relative is a Date or a DateTime. The default for a Date.t/0 is Date.utc_today/0, for a DateTime.t/0 it is DateTime.utc_now/0.

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.DateTime.UnknownTimeUnit,
 "Unknown time unit :ziggeraut.  Valid time units are [:day, :fri, :hour, :minute, :mon, :month, :quarter, :sat, :second, :sun, :thu, :tue, :wed, :week, :year]"}}
Link to this function

to_string!(relative, backend \\ Cldr.Date.default_backend(), options \\ [])

View Source
@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 t:Date/0 or t:Datetime.t/0 from which the difference from relative is calculated when relative is a Date or a DateTime. The default for a Date.t/0 is Date.utc_today/0, for a DateTime.t/0 it is DateTime.utc_now/0.

See to_string/3

Link to this function

unit_from_relative_time(time)

View Source

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