Add `format` argument to `format.hms()`

[retodomax]

There seems to be a format() S3 method for class 'hms'. However, it just returns the input as character. I would have expected that it takes the argument format and formats the output like an object of class POSIXct

library(hms)
t <- Sys.time()
format(t, "%H")
#> [1] "17"

t2 <- as_hms(t)
format(t2, "%H")
#> [1] "17:12:38.169816"

^{Created on 2024-11-05 with reprex v2.1.1}

[krlmlr]

Thanks. The hms type inherits from difftime, that type doesn't seem to support the format() syntax you're suggesting either:

d <- Sys.time() - Sys.time()
d
#> Time difference of -9.536743e-07 secs
format(d, "%H")
#> Error in prettyNum(.Internal(format(x, trim, digits, nsmall, width, 3L, : invalid 'trim' argument

^{Created on 2024-11-10 with reprex v2.1.1}

Here's what I think happens: format() is forwarded to format.default(), and the "%H" is matched to the trim argument.

format.difftime
#> function (x, ...) 
#> {
#>     if (length(x)) 
#>         paste(format(unclass(x), ...), units(x))
#>     else character()
#> }
#> <bytecode: 0x10527d070>
#> <environment: namespace:base>
formals(format.default)
#> $x
#> 
#> 
#> $trim
#> [1] FALSE
#> 
#> $digits
#> NULL
#> 
#> $nsmall
#> [1] 0
#> 
#> $justify
#> c("left", "right", "centre", "none")
#> 
#> $width
#> NULL
#> 
#> $na.encode
#> [1] TRUE
#> 
#> $scientific
#> [1] NA
#> 
#> $big.mark
#> [1] ""
#> 
#> $big.interval
#> [1] 3
#> 
#> $small.mark
#> [1] ""
#> 
#> $small.interval
#> [1] 5
#> 
#> $decimal.mark
#> getOption("OutDec")
#> 
#> $zero.print
#> NULL
#> 
#> $drop0trailing
#> [1] FALSE
#> 
#> $...

^{Created on 2024-11-10 with reprex v2.1.1}

[retodomax]

Thanks for the reply!
I guess, ideal would be, if this feature would be implemented in base R but hard to say if they want it there...
If you're interested, I could try to write a method implementing the feature for package hms where in my opinion it would make sense to be able to extract/format specific time components (hours, minutes, ...) as string.

[krlmlr]

Maybe:

x <- hms::hms(hours = 1)
t <- base::.POSIXct(x, tz = "UTC")
format(t, "%H")
#> [1] "01"

^{Created on 2025-03-19 with reprex v2.1.1}

[retodomax]

Yes, so far, I also transformed the hms object to a POSIXct object to apply format.POSIXct(). This is useful for example to remove the seconds in a ggplot time axis:

library(tidyverse)
set.seed(1)
tibble(hour = seq(0,24,0.02),
       time = hms::hms(hours = hour),
       y = sin(hour/24*(2*pi)) + rnorm(length(hour), sd = 0.2)) %>% 
  ggplot(aes(x = time, y = y)) +
  geom_point() +
  geom_smooth() +
  scale_x_time(breaks = hms::hms(hours = c(0, 6, 12, 18, 24)),
               labels = \(x) format(x = as.POSIXct(x), "%H:%M"))

If there would be a format.hms() method with argument format, then this would be even easier : )

[moodymudskipper]

format.hms() formats object in a consistant "HH:MM:SS.ssssss" format with up to 6 decimals:

hms::hms(12345)
#> 03:25:45
hms::hms(12345.12345678)
#> 03:25:45.123457

This format prints similarly to the POSIXct format, but doesn't offer the same flexibility, the digits arg is also ignored for hms, though it works with difftime.

t <- Sys.time()
format(t)
#> [1] "2025-03-21 13:22:19"
format(t, format = "%H:%M:%S")
#> [1] "13:22:19"

A way to support this, suggested in the thread, is to convert the hms object to a POSIXct object and then use the format method, however the hours would be limited to 24, which will confuse users, and formats for years, weeks, months will be available and make little sense.

Providing a glue specification like would be more flexible. The default format could be "{.Hours}:{.minutes}:{.seconds_dec}" where .Hours (capitalised) is total hours, .minutes (not capitalised) means minutes within hour, and .seconds_dec means decimal seconds within the minute, on which the digits arg applies. We could also have .days, .weeks and their variants.

[krlmlr]

I missed that "%H" would mess up the hours. We could work around that by only formatting hms values with less than 24 hours.

"%OS" supports fractional seconds, AFAIR.

There is decompose(). I think the reason that it exists is that I wanted to print hours > 24. But that might be less important for format().

hms:::decompose
#> function (x) 
#> {
#>     x <- vec_data(x) * TICS_PER_SECOND
#>     xr <- round(x)
#>     out <- list(sign = xr < 0 & !is.na(xr), hours = abs(hours(xr)), 
#>         minute_of_hour = minute_of_hour(xr), second_of_minute = second_of_minute(xr), 
#>         tics = tic_of_second(xr))
#>     fake_zero <- (out$tics == 0) & (xr != x)
#>     out$tics[fake_zero] <- 0.25
#>     out
#> }
#> <bytecode: 0x11819e570>
#> <environment: namespace:hms>

^{Created on 2025-03-26 with reprex v2.1.1}

Days and weeks have been out of scope so far, elegantly avoiding issues with leap seconds and whatnot: https://xkcd.com/2867/.

At this stage, it's much easier to enhance the existing format_hms() to support custom delimiters, instead of a format string that must be parsed. Would that serve the same purpose?

[moodymudskipper]

My understanding was that hms returns durations, not intervals, so those leap seconds considerations wouldn't apply.
We can also make digits work, incl negative digits, that's less flexible but that would handle OP's case and hours > 24.

%OS prints fractional seconds but only if options(digits.secs =) is set.

[schochastics]

Specific to R is %OSn, which for output gives the seconds truncated to exactly 0 <= n <= 6 
decimal places. If %OS is not followed by a digit, it uses up to digits decimals (only as many 
as necessary, i.e., not producing extra trailing zeros. The default digits = NULL corresponds 
to digits = 0. 

Would you support %OSn and digits? I think if formats are added to format_hms() it should probably quite simple. Something like %H, %M and %S and a separate digits argument?

[krlmlr]

@retodomax: What are the typical format strings you would use? Can we get away with supporting delimiters instead?

[retodomax]

Thanks for the interesting suggestions! I would mainly use "%H:%M", "%H", "%M" and "%S". The same syntax as used by format.POSIXct() would be easy to remember, but also a glue like sytax would be great. I guess custom delimiters would not allow to remove one component (e.g. seconds) of the string?

[krlmlr]

How about we implement a simple state machine that iterates over strsplit(format, "")[[1]] and creates arguments that are later passed on to paste0() ? The arguments would be characters or calls to format_two_digits() and such.

strsplit("%H:%M", "")[[1]]
#> [1] "%" "H" ":" "%" "M"

^{Created on 2025-03-28 with reprex v2.1.1}

[moodymudskipper]

I had a quick look and none of 'hms', 'lubridate', or 'clock' seem to have a way of formatting a duration to say for instance "There are 90 minutes left". IMHO this is a missed opportunity.
I'm afraid that in the name of simplicity we're building a not only limited but also surprising solution:

• Supporting only a subset of the POSIX standard specifications
• Not supporting things like format = "---%H:%M:%S---"
• Either not supporting hours > 24, or mapping "%H" to hours more than 24 : both surprising