Cldr Dates & Times v1.2.0 Cldr.DateTime.Relative View Source

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”

Link to this section Summary

Functions

known_units()

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

scale_relative(time, unit)

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

to_string(relative, options \\ [])

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

to_string!(relative, options \\ [])

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

unit_from_relative_time(time)

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

validate_unit(unit)

Link to this section Functions

known_units()

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

Example

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

scale_relative(time, unit)

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

to_string(relative, options \\ [])

to_string(integer() | float() | Date.t() | DateTime.t(), []) :: binary()

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]
options is a Keyword list of options which are:
- :locale is the locale in which the binary is formatted. The default is Cldr.get_current_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)
{:ok, "1 second ago"}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

to_string!(relative, options \\ [])

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

Options

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_current_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

See to_string/2

unit_from_relative_time(time)

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

validate_unit(unit)