TimeQueue.TimeInterval (time_queue v1.2.1)
View SourceUtility 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 dayh
for hourm
for minutes
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 as2h1d
. - The addition is supported, i.e. the units are cumulative.
1d1d
is the same as2d
. - 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, but1d-1h
or1d-1d
are invalid.
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.
Types
@type t() :: %TimeQueue.TimeInterval{ms: integer()}
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
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
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
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
.
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
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"
Returns the string representation with the same rules as in to_string/1
but
in long form.
Example
iex> "1d1h" |> TimeInterval.parse!() |> TimeInterval.to_string(:verbose)
"1 day 1 hour"