R: Counting: time point

time_point_count_between {clock} | R Documentation

## Counting: time point

### Description

`time_point_count_between()` counts the number of `precision` units between `start` and `end` (i.e., the number of days or hours). This count corresponds to the whole number of units, and will never return a fractional value.

This is suitable for, say, computing the whole number of days between two time points, accounting for the time of day.

### Usage

    time_point_count_between(start, end, precision, ..., n = 1L)

### Arguments

`start, end` | `[clock_time_point]` A pair of time points. These will be recycled to their common size.
`precision` | `[character(1)]` One of: `"week"` `"day"` `"hour"` `"minute"` `"second"` `"millisecond"` `"microsecond"` `"nanosecond"`
`...` | These dots are for future extensions and must be empty.
`n` | `[positive integer(1)]` A single positive integer specifying a multiple of `precision` to use.

### Details

Remember that `time_point_count_between()` returns an integer vector. With extremely fine precisions, such as nanoseconds, the count can quickly exceed the maximum value that is allowed in an integer. In this case, an `NA` will be returned with a warning.

### Value

An integer representing the number of `precision` units between `start` and `end`.

### Comparison Direction

The computed count has the property that if `start <= end`, then `start + <count> <= end`. Similarly, if `start >= end`, then `start + <count> >= end`. In other words, the comparison direction between `start` and `end` will never change after adding the count to `start`. This makes this function useful for repeated count computations at increasingly fine precisions.

### Examples

    x <- as_naive_time(year_month_day(2019, 2, 3))
    y <- as_naive_time(year_month_day(2019, 2, 10))

    # Whole number of days or hours between two time points
    time_point_count_between(x, y, "day")
    time_point_count_between(x, y, "hour")

    # Whole number of 2-day units
    time_point_count_between(x, y, "day", n = 2)

    # Leap years are taken into account
    x <- as_naive_time(year_month_day(c(2020, 2021), 2, 28))
    y <- as_naive_time(year_month_day(c(2020, 2021), 3, 01))
    time_point_count_between(x, y, "day")

    # Time of day is taken into account.
    # `2020-02-02T04 -> 2020-02-03T03` is not a whole day (because of the hour)
    # `2020-02-02T04 -> 2020-02-03T05` is a whole day
    x <- as_naive_time(year_month_day(2020, 2, 2, 4))
    y <- as_naive_time(year_month_day(2020, 2, 3, c(3, 5)))
    time_point_count_between(x, y, "day")
    time_point_count_between(x, y, "hour")

    # Can compute negative counts (using the same example from above)
    time_point_count_between(y, x, "day")
    time_point_count_between(y, x, "hour")

    # Repeated computation at increasingly fine precisions
    x <- as_naive_time(year_month_day(
      2020, 2, 2, 4, 5, 6, 200,
      subsecond_precision = "microsecond"
    ))
    y <- as_naive_time(year_month_day(
      2020, 3, 1, 8, 9, 10, 100,
      subsecond_precision = "microsecond"
    ))

    days <- time_point_count_between(x, y, "day")
    x <- x + duration_days(days)

    hours <- time_point_count_between(x, y, "hour")
    x <- x + duration_hours(hours)

    minutes <- time_point_count_between(x, y, "minute")
    x <- x + duration_minutes(minutes)

    seconds <- time_point_count_between(x, y, "second")
    x <- x + duration_seconds(seconds)

    microseconds <- time_point_count_between(x, y, "microsecond")
    x <- x + duration_microseconds(microseconds)

    data.frame(
      days = days,
      hours = hours,
      minutes = minutes,
      seconds = seconds,
      microseconds = microseconds
    )

[Package clock version 0.6.0 Index]