View Source TimeQueue.TimeInterval (time_queue v1.1.1)

Utility to parse and format time intervals represented as strings.

A time interval is formatted as pairs of numbers and units. For instance 1d2h is two pairs and means 1 day and 2 hours.

The unit is always lowercase and one of:

  • d for day
  • h for hour
  • m for minute
  • s for second

Note that the ms unit is not supported on parsing, but will be returned when formatting an interval (integer or struct) that is smaller than 1 second.

There are a couple of rules regarding the format:

  • The order of the pairs is not significant. 1d2h is the same as 2h1d.
  • The addition is supported, i.e. the units are cumulative. 1d1d is the same as 2d.
  • The subtraction is not supported, each pair is absolute and just represent a quantity of milliseconds. But it is possible to prefix the expression with a -, which will make the parser return a negative value. So -1d1h will return a negative number, but 1d-1h or 1d-1d are invalid.

Link to this section Summary

Functions

Returns the number of milliseconds in n days.

Returns the number of milliseconds in n hours. Alias for :timer.hours/1.

Returns the number of milliseconds in n minutes. Alias for :timer.minutes/1.

Returns a %TimeQueue.TimeInterval{} struct from a time interval string.

Same as parse/1 but returns the struct directly or raises an ArgumentError.

Returns the number of milliseconds in n seconds. Alias for :timer.seconds/1.

Returns the number of milliseconds in the given interval, wrapped in an :ok tuple, or an :error tuple. The interval can be a string or a %TimeQueue.TimeInterval{} struct.

Same as to_ms/1 but returns the number of milliseconds directly or raises an ArgumentError.

Returns the string representation of the given time interval. Note that as this module is intended to work with long durations, the number of remaining milliseconds after having computed the days, hours, minutes and seconds, is discarded.

Returns the string representation with the same rules as in to_string/1 but in long form.

Link to this section Types

@type t() :: %TimeQueue.TimeInterval{ms: integer()}

Link to this section Functions

Returns the number of milliseconds in n days.

Returns the number of milliseconds in n hours. Alias for :timer.hours/1.

Returns the number of milliseconds in n minutes. Alias for :timer.minutes/1.

@spec parse(binary()) :: {:ok, t()} | {:error, {:cannot_parse_interval, binary()}}
@spec parse(binary()) :: t()

Returns a %TimeQueue.TimeInterval{} struct from a time interval string.

examples

Examples

iex> TimeInterval.parse("1d1h")
{:ok, %TimeQueue.TimeInterval{ms: 90000000}}

iex> TimeInterval.parse("some gibberish")
{:error, {:cannot_parse_interval, "some gibberish"}}

Same as parse/1 but returns the struct directly or raises an ArgumentError.

example

Example

iex> TimeInterval.parse!("1d1h")
%TimeQueue.TimeInterval{ms: 90000000}

Returns the number of milliseconds in n seconds. Alias for :timer.seconds/1.

@spec to_ms(binary() | integer() | t()) ::
  {:ok, integer()} | {:error, {:cannot_parse_interval, binary()}}
@spec to_ms(binary() | integer() | t()) :: integer()

Returns the number of milliseconds in the given interval, wrapped in an :ok tuple, or an :error tuple. The interval can be a string or a %TimeQueue.TimeInterval{} struct.

For convenience reasons, this function also accepts integers, which are returned as is.

examples

Examples

iex> TimeInterval.to_ms("1d1h")
{:ok, 90000000}

iex> "1d1h" |> TimeInterval.parse!() |> TimeInterval.to_ms()
{:ok, 90000000}

iex> TimeInterval.to_ms("some gibberish")
{:error, {:cannot_parse_interval, "some gibberish"}}

iex> TimeInterval.to_ms(1234)
{:ok, 1234}

Same as to_ms/1 but returns the number of milliseconds directly or raises an ArgumentError.

Link to this function

to_string(time_interval)

View Source
@spec to_string(t() | integer()) :: binary()

Returns the string representation of the given time interval. Note that as this module is intended to work with long durations, the number of remaining milliseconds after having computed the days, hours, minutes and seconds, is discarded.

examples

Examples

iex> "1d1h" |> TimeInterval.parse!() |> TimeInterval.to_string()
"1d1h"

iex> "1d1d1d" |> TimeInterval.parse!() |> TimeInterval.to_string()
"3d"

iex> TimeInterval.to_string(90000000)
"1d1h"

iex> TimeInterval.to_string(90000123) # Discared remaining milliseconds
"1d1h"

iex> TimeInterval.to_string(123) # Smaller than 1 second
"123ms"
@spec to_string(t() | integer(), :verbose) :: binary()

Returns the string representation with the same rules as in to_string/1 but in long form.

example

Example

iex> "1d1h" |> TimeInterval.parse!() |> TimeInterval.to_string(:verbose)
"1 day 1 hour"