Pretty Time of Day

Implements an S3 class for storing and formatting time-of-day values, based on the 'difftime' class.


Travis-CI Build Status AppVeyor Build Status codecov CRAN_Status_Badge

Overview

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

Installation

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")

Usage

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(1)
#> 00:00:01
as.hms("12:34:56")
#> 12:34:56
as.hms(Sys.time())
#> 16:45:12.828186
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

News

hms 0.4.2 (2018-03-10)

  • Adapted tests to pillar 1.2.1.

hms 0.4.1 (2018-01-23)

  • Preserve NA when converting to character (#51, @jeroen).
  • Adapted tests to pillar 1.1.0.

hms 0.4.0 (2017-11-16)

Breaking changes

  • as.hms.POSIXt() now defaults to the current time zone, the previous default was "UTC" and can be restored by calling pkgconfig::set_config("hms::default_tz", "UTC").

New features

  • Pillar support, will display hms columns in tibbles in color on terminals that support it (#43).
  • New round_hms() and trunc_hms() for rounding or truncating to a given multiple of seconds (#31).
  • New parse_hms() and parse_hm() to parse strings in "HH:MM:SS" and "HH:MM" formats (#30).
  • as.hms.POSIXt() gains tz argument, default "UTC" (#28).
  • as.hms.character() and parse_hms() accept fractional seconds (#33).

Bug fixes

  • hms() now works correctly if all four components (days, hours, minutes, seconds) are passed (#49).
  • hms() creates a zero-length object of class hms that prints as "hms()".
  • hms(integer()) and as.hms(integer()) both work and are identical to hms().
  • Values with durations of over 10000 hours are now printed correctly (#48).
  • c() now returns a hms (#41, @qgeissmann).

Documentation and error messages

  • Fix and enhance examples in ?hms.
  • Documentation is in Markdown format now.
  • Improved error message if calling hms() with a character argument (#29).

hms 0.3 (2016-11-22)

  • Fix lubridate test for compatibility with 1.6.0 (#23, @vspinu).
  • NA values are formatted as NA (#22).

hms 0.2 (2016-06-17)

Minor fixes and improvements.

  • Subsetting keeps hms class (#16).
  • format.hms() right-justifies the output by padding with spaces from the left, as.character.hms() remains unchanged.
  • Times larger than 24 hours or with split seconds are now formatted correctly (#12, #13).
  • Sub-second part is printed with up to six digits, for even smaller values trailing zeros are shown (#17).

hms 0.1 (2016-04-30)

First CRAN release.

  • Values are stored as a numeric vector that contains the number of seconds since midnight.
    • Inherits from difftime class.
    • Updating units is a no-op, anything different from "secs" issues a warning.
  • Supports construction from time values, coercion to and from various data types, and formatting.
    • Conversion from numeric treats input as seconds.
    • Negative times are formatted with a leading -.
  • Can be used as a regular column in a data frame.
  • Full test coverage.
    • Test for arithmetic with Date, POSIXt and hms classes.
    • Test basic compatibility with lubridate package (#5).
  • Interface:
    • hms() (with rigorous argument checks)
    • as.hms() for character, numeric, POSIXct and POSIXlt
    • as.xxx.hms() for character, numeric (implicitly), POSIXct and POSIXlt
    • is.hms()
    • as.data.frame.hms() (forwards to as.data.frame.difftime())
    • format.hms()
    • print.hms() (returns unchanged input invisibly)

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.