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]
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, 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 fromnow
or fromoptions[:relative_to]
backend
is any module that includesuse Cldr
and therefore is aCldr
backend module. The default isCldr.default_backend/0
.options
is aKeyword
list of options which are:
Options
:locale
is the locale in which the binary is formatted. The default isCldr.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 baselinet:Date/0
ort:Datetime.t/0
from which the difference fromrelative
is calculated whenrelative
is a Date or a DateTime. The default for aDate.t/0
isDate.utc_today/0
, for aDateTime.t/0
it isDateTime.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]"}}
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 fromnow
or from options[:relative_to].backend
is any module that includesuse Cldr
and therefore is aCldr
backend module. The default isCldr.default_backend/0
.options
is aKeyword
list of options.
Options
:locale
is the locale in which the binary is formatted. The default isCldr.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 baselinet:Date/0
ort:Datetime.t/0
from which the difference fromrelative
is calculated whenrelative
is a Date or a DateTime. The default for aDate.t/0
isDate.utc_today/0
, for aDateTime.t/0
it isDateTime.utc_now/0
.
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