README.md
In hms: Pretty Time of Day

hms

The hms package provides a simple class for storing durations or time-of-day values and displaying them in the hh:mm:ss format. This class is intended to simplify data exchange with databases, spreadsheets, and other data sources:

Stores values as a numeric vector that contains the number of seconds since midnight
Supports construction from explicit hour, minute, or second values
Supports coercion to and from various data types, including POSIXt
Can be used as column in a data frame
Based on the difftime class
Values can exceed the 24-hour boundary or be negative
By default, fractional seconds up to a microsecond are displayed, regardless of the value of the "digits.secs" option

# The easiest way to get hms is to install the whole tidyverse:
install.packages("tidyverse")

# Alternatively, install just hms:
install.packages("hms")

# Or the the development version from GitHub:
# install.packages("devtools")
devtools::install_github("tidyverse/hms")

The following example showcases ways of using the hms class standalone or as a data frame column.

library(hms)

hms(56, 34, 12)
#> 12:34:56
as_hms(Sys.time())
#> 11:55:02.553476
parse_hms("12:34:56")
#> 12:34:56
as.POSIXct(hms(1))
#> [1] "1970-01-01 00:00:01 UTC"

data.frame(hours = 1:3, hms = hms(hours = 1:3))
#>   hours      hms
#> 1     1 01:00:00
#> 2     2 02:00:00
#> 3     3 03:00:00

Objects of the hms and its underlying difftime classes are stored as number of seconds since 00:00:00. Use as.numeric() and as_hms() to convert to and from numbers.

times <- parse_hms(c("00:00:00.25", "00:00:01", "00:01:30", "01:00:00"))
times
#> 00:00:00.25
#> 00:00:01.00
#> 00:01:30.00
#> 01:00:00.00
times_num <- as.numeric(times)
times_num
#> [1]    0.25    1.00   90.00 3600.00
as_hms(times_num)
#> 00:00:00.25
#> 00:00:01.00
#> 00:01:30.00
#> 01:00:00.00