.TH timespan 1 2024-07-25 util

.SH NAME
timespan \- compute the duration between clock times

.SH SYNOPSIS
.SY timespan
.IB <time> - <time>
.YS

.SH DESCRIPTION
.B timespan
computes the time span between two clock times.
For example, the time between midday and noon would be
.B timespan 12:00-12:00
\(em which is no time at all.

.SH OPTIONS
.B timespan
has no options.
It accepts only times, separated by a hyphen.

.SH EXIT STATUS
.B timespan
always exits with 0.
.SH NOTES
.B timespan
is implemented using
.BR sed (1)
as a parser and
.BR bc (1)
as an interpreter.
.SH BUGS
Lines that fail to parse are passed to
.B bc (1),
which allows arbitrary code execution.
.P
The error messages are not helpful.
.SH EXAMPLES
.HP
.BR timespan\  10:00-12:30
will output 2h30m.
.HP
.BR timespan\  8:00- $(date\ +%R)
will print the duration since 8:00 o'clock,
which may be a negative amount if it is very early.

.SH SEE ALSO
.BR sed (1),\  bc (1),\  date (1)