duration_cast: Cast a duration between precisions

In clock: Date-Time Types and Tools

Cast a duration between precisions

Description

Casting is one way to change a duration's precision.

Casting to a less precise precision will completely drop information that is more precise than the precision that you are casting to. It does so in a way that makes it round towards zero.

Casting to a more precise precision is done through a multiplication by a conversion factor between the current precision and the new precision.

Usage

duration_cast(x, precision)

Arguments

x	⁠[clock_duration]⁠ A duration.
precision	⁠[character(1)]⁠ A precision. One of: "year" "quarter" "month" "week" "day" "hour" "minute" "second" "millisecond" "microsecond" "nanosecond"

Details

When you want to change to a less precise precision, you often want duration_floor() instead of duration_cast(), as that rounds towards negative infinity, which is generally the desired behavior when working with time points (especially ones pre-1970, which are stored as negative durations).

Value

x cast to the new precision.

Examples

x <- duration_seconds(c(86401, -86401))

# Casting rounds towards 0
cast <- duration_cast(x, "day")
cast

# Flooring rounds towards negative infinity
floor <- duration_floor(x, "day")
floor

# Flooring is generally more useful when working with time points,
# note that the cast ends up rounding the pre-1970 date up to the next
# day, while the post-1970 date is rounded down.
as_sys_time(x)
as_sys_time(cast)
as_sys_time(floor)

# Casting to a more precise precision
duration_cast(x, "millisecond")

clock documentation built on Sept. 11, 2024, 8:39 p.m.