# hms

## 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

``` r
# 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("pak")
pak::pak("tidyverse/hms")
```

## Usage

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

``` r
library(hms)

hms(56, 34, 12)
#> 12:34:56
as_hms(Sys.time())
#> 10:27:38.905625
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
```

## Internal representation

Objects of the `hms` and its underlying `difftime` classes are stored as
number of seconds since `00:00:00`. Use
[`as.numeric()`](https://rdrr.io/r/base/numeric.html) and
[`as_hms()`](https://hms.tidyverse.org/reference/hms.md) to convert to
and from numbers.

``` r
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
```

# Package index

## Construction

- [`hms()`](https://hms.tidyverse.org/reference/hms.md)
  [`new_hms()`](https://hms.tidyverse.org/reference/hms.md)
  [`is_hms()`](https://hms.tidyverse.org/reference/hms.md)
  [`as_hms()`](https://hms.tidyverse.org/reference/hms.md)
  [`as.POSIXct(`*`<hms>`*`)`](https://hms.tidyverse.org/reference/hms.md)
  [`as.POSIXlt(`*`<hms>`*`)`](https://hms.tidyverse.org/reference/hms.md)
  [`as.character(`*`<hms>`*`)`](https://hms.tidyverse.org/reference/hms.md)
  [`format(`*`<hms>`*`)`](https://hms.tidyverse.org/reference/hms.md)
  [`print(`*`<hms>`*`)`](https://hms.tidyverse.org/reference/hms.md)
  [`seq(`*`<hms>`*`)`](https://hms.tidyverse.org/reference/hms.md) : A
  simple class for storing time-of-day values

## Conversion

- [`vec_cast(`*`<hms>`*`)`](https://hms.tidyverse.org/reference/vec_cast.hms.md)
  : Casting
- [`vec_ptype2(`*`<hms>`*`)`](https://hms.tidyverse.org/reference/vec_ptype2.hms.md)
  : Coercion
- [`parse_hms()`](https://hms.tidyverse.org/reference/parse_hms.md)
  [`parse_hm()`](https://hms.tidyverse.org/reference/parse_hms.md) :
  Parsing hms values

## Utilities

- [`round_hms()`](https://hms.tidyverse.org/reference/round_hms.md)
  [`trunc_hms()`](https://hms.tidyverse.org/reference/round_hms.md)
  [`ceiling_hms()`](https://hms.tidyverse.org/reference/round_hms.md)
  [`floor_hms()`](https://hms.tidyverse.org/reference/round_hms.md) :
  Round an hms object

## Package documentation

- [`hms-package`](https://hms.tidyverse.org/reference/hms-package.md) :
  hms: Pretty Time of Day