Cldr v0.3.0 Cldr.DateTime.Relative
Functions to support the string formatting of relative time/datetime numbers. This allows for the 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
Calculates the time span in the given unit
from the time given in seconds
Returns a list of the valid unit keys for to_string/2
Returns a string representing a relative time (ago, in) for a given number, Date or Datetime
Returns an estimate of the appropriate time unit for an integer of a given magnitude of seconds
Functions
Calculates the time span in the given unit
from the time given in seconds.
Examples
iex> Cldr.DateTime.Relative.calculate_unit(1234, :second)
1234
iex> Cldr.DateTime.Relative.calculate_unit(1234, :minute)
21
iex> Cldr.DateTime.Relative.calculate_unit(1234, :hour )
0
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]
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 fromnow
or from options[:relative_to]options
is aKeyword
list of options which are::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 baseline Date or Datetime from which the difference fromrelative
is calculated whenrelative
is a Date or a DateTime. The default for a Date isDate.utc_today
, for a DateTime it isDateTime.utc_now
Examples
iex> Cldr.DateTime.Relative.to_string(-1)
"1 second ago"
iex> Cldr.DateTime.Relative.to_string(1)
"in 1 second"
iex> Cldr.DateTime.Relative.to_string(1, unit: :day)
"tomorrow"
iex> Cldr.DateTime.Relative.to_string(1, unit: :day, locale: "fr")
"demain"
iex> Cldr.DateTime.Relative.to_string(1, unit: :day, format: :narrow)
"tomorrow"
iex> Cldr.DateTime.Relative.to_string(1234, unit: :year)
"in 1,234 years"
iex> Cldr.DateTime.Relative.to_string(1234, unit: :year, locale: "fr")
"dans 1 234 ans"
iex> Cldr.DateTime.Relative.to_string(31)
"in 31 seconds"
iex> Cldr.DateTime.Relative.to_string(~D[2017-04-29], relative_to: ~D[2017-04-26])
"in 3 days"
iex> Cldr.DateTime.Relative.to_string(310, format: :short, locale: "fr")
"dans 5 min"
iex> Cldr.DateTime.Relative.to_string(310, format: :narrow, locale: "fr")
"+5 min"
iex> Cldr.DateTime.Relative.to_string 2, unit: :wed, format: :short
"in 2 Wed."
iex> Cldr.DateTime.Relative.to_string 1, unit: :wed, format: :short
"next Wed."
iex> Cldr.DateTime.Relative.to_string -1, unit: :wed, format: :short
"last Wed."
iex> Cldr.DateTime.Relative.to_string -1, unit: :wed
"last Wednesday"
iex> Cldr.DateTime.Relative.to_string -1, unit: :quarter
"last quarter"
iex> Cldr.DateTime.Relative.to_string -1, unit: :mon, locale: "fr"
"lundi dernier"
iex> Cldr.DateTime.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.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.
Returns an estimate of the appropriate time unit for an integer of a given magnitude of seconds.
Examples
iex> Cldr.DateTime.Relative.unit_from_seconds(1234)
:minute
iex> Cldr.DateTime.Relative.unit_from_seconds(12345)
:hour
iex> Cldr.DateTime.Relative.unit_from_seconds(123456)
:day
iex> Cldr.DateTime.Relative.unit_from_seconds(1234567)
:week
iex> Cldr.DateTime.Relative.unit_from_seconds(12345678)
:month
iex> Cldr.DateTime.Relative.unit_from_seconds(123456789)
:year