Functions to create and format durations — the difference between two dates, times, or datetimes expressed in calendar units.
A duration is represented as years, months, days, hours, minutes, seconds, and microseconds. This is useful for producing human-readable strings like "11 months and 30 days" or numeric patterns like "37:48:12".
Creating durations
new/2— calculates the duration between two dates, times, or datetimes.new_from_seconds/1— creates a duration from a number of seconds.
Formatting durations
to_string/2— formats a duration as a localized string using unit names (e.g., "11 months and 30 days") viaLocalize.UnitandLocalize.List.to_time_string/2— formats the time portion of a duration using a pattern like"hh:mm:ss". Hours are unbounded (e.g., "37:48:12" for 37 hours).
Summary
Functions
Calculates the calendar duration between two dates, times, or datetimes.
Same as new/2 but raises on error.
Creates a duration from a number of seconds.
Formats a duration as a localized string using unit names.
Same as to_string/2 but raises on error.
Formats the time portion of a duration using a numeric
pattern like "hh:mm:ss".
Same as to_time_string/2 but raises on error.
Types
@type date_or_time_or_datetime() :: Calendar.date() | Calendar.time() | Calendar.datetime() | Calendar.naive_datetime()
A date, time, naive datetime, or datetime.
@type t() :: %Localize.Duration{ day: non_neg_integer(), hour: non_neg_integer(), microsecond: {integer(), 1..6}, minute: non_neg_integer(), month: non_neg_integer(), second: non_neg_integer(), year: non_neg_integer() }
Duration in calendar units.
Functions
@spec new(from :: date_or_time_or_datetime(), to :: date_or_time_or_datetime()) :: {:ok, t()} | {:error, Exception.t() | atom()}
Calculates the calendar duration between two dates, times, or datetimes.
Arguments
fromis a date, time, or datetime representing the start.tois a date, time, or datetime representing the end.
Returns
{:ok, duration}wheredurationis at/0struct.{:error, exception}if the arguments are incompatible.
Examples
iex> {:ok, d} = Localize.Duration.new(~D[2019-01-01], ~D[2019-12-31])
iex> d.month
11
iex> {:ok, d} = Localize.Duration.new(~T[10:00:00], ~T[12:30:45])
iex> {d.hour, d.minute, d.second}
{2, 30, 45}@spec new!(from :: date_or_time_or_datetime(), to :: date_or_time_or_datetime()) :: t() | no_return()
Same as new/2 but raises on error.
Examples
iex> d = Localize.Duration.new!(~D[2019-01-01], ~D[2019-12-31])
iex> d.month
11Creates a duration from a number of seconds.
The duration will contain only hours, minutes, seconds, and microseconds (year/month/day will be zero).
Arguments
secondsis a number of seconds (integer or float).
Returns
- A
t/0struct.
Examples
iex> d = Localize.Duration.new_from_seconds(136_092)
iex> {d.hour, d.minute, d.second}
{37, 48, 12}
iex> d = Localize.Duration.new_from_seconds(90.5)
iex> {d.minute, d.second}
{1, 30}@spec to_string(t(), Keyword.t()) :: {:ok, String.t()} | {:error, Exception.t()}
Formats a duration as a localized string using unit names.
Non-zero duration parts are formatted as units and joined with the locale's list conjunction (e.g., "11 months and 30 days").
Arguments
durationis at/0struct.optionsis a keyword list of options.
Options
:exceptis a list of time unit atoms to omit from the output (e.g.,[:microsecond]). The default is[:microsecond].:localeis a locale identifier. The default isLocalize.get_locale().:styleis one of:long,:short, or:narrow. The default is:long.
Returns
{:ok, formatted_string}on success.{:error, exception}if formatting fails.
Examples
iex> {:ok, d} = Localize.Duration.new(~D[2019-01-01], ~D[2019-12-31])
iex> Localize.Duration.to_string(d, locale: :en)
{:ok, "11 months and 30 days"}Same as to_string/2 but raises on error.
Formats the time portion of a duration using a numeric
pattern like "hh:mm:ss".
Hours are unbounded — a duration of 37 hours, 48 minutes,
and 12 seconds formats as "37:48:12".
Arguments
durationis at/0struct.optionsis a keyword list of options.
Options
:formatis a format pattern string. The default is"hh:mm:ss". Use"h:mm:ss"for no zero-padding on hours, or"mm:ss"for minutes and seconds only.
Returns
{:ok, formatted_string}on success.
Examples
iex> d = Localize.Duration.new_from_seconds(136_092)
iex> Localize.Duration.to_time_string(d)
{:ok, "37:48:12"}
iex> d = Localize.Duration.new_from_seconds(65)
iex> Localize.Duration.to_time_string(d, format: "m:ss")
{:ok, "1:05"}Same as to_time_string/2 but raises on error.