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


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


# Alternatively, install just hms:
# Or the the development version from GitHub:
# install.packages("devtools")


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

hms(56, 34, 12)
#> 12:34:56
#> 00:00:01
#> 12:34:56
#> 16:45:12.828186
#> [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


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
    • for character, numeric (implicitly), POSIXct and POSIXlt
    • is.hms()
    • (forwards to
    • 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.


0.4.2 by Kirill Müller, 10 days ago

Report a bug at

Browse source code at

Authors: Kirill Müller [aut, cre], The R Consortium [fnd]

Documentation:   PDF Manual  

GPL-3 license

Imports methods, pkgconfig, rlang

Suggests crayon, lubridate, pillar, testthat

Imported by DBItest, RMariaDB, RPostgres, feather, haven, mudata2, odbc, processmapR, rclimateca, readr, tibbletime, tidyverse.

Suggested by DBI, bigrquery, dplyr, scales, tsibble.

See at CRAN