Cldr.DateTime.Relative.to_string
to_string
, go back to Cldr.DateTime.Relative module for more information.
to_string(relative, backend \\ Cldr.Date.default_backend(), options \\ [])
View SourceSpecs
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 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
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, :hour, :minute, :month, :second, :week, :year, :mon, :tue, :wed, :thu, :fri, :sat, :sun, :quarter]"}}