Introduction to datetimeoffset

Table of Contents

• Overview

• Examples

  • Importing/exporting datetime string formats
  • Heteregeneous time zones
  • Augmenting pdf datetime metadata

• Features

• Comparison with {clock}

  • Things {clock} can do that {datetimeoffset} can’t do
  • Things {datetimeoffset} can do that {clock} can’t do

• Comparison with {parttime}

• Serializing

• External links

  • Datetime standards with UTC offsets
  • Related Software

Overview

{datetimeoffset} provides support for datetimes with optional UTC offsets and/or (possibly heteregeneous) time zones. Strengths compared to other R datetime objects:

1. Import/export for a number of datetime string standards often including lossless re-export of any original reduced precision
2. Datetimes can be augmented with optional UTC offsets and/or (possibly heteregeneous) time zones.
3. Can support up to nanosecond precision.

The motivating use case for this package was the need for a datetime aware class that can losslessy import/export pdf metadata datetimes for {xmpdf}. pdf metadata datetimes are local times with a wide range of legal precisions but with unknown time zones but a possibly known UTC offset. Generally pre-existing R datetime classes either assume knowledge of a (usually single) time zone or alternatively assumed it was acceptable to fully convert to UTC time.

Examples

library("datetimeoffset")

as_datetimeoffset("2020-05") |> format_iso8601()

## [1] "2020-05"

as_datetimeoffset("2020-05-10T20:10") |> format_iso8601()

## [1] "2020-05-10T20:10"

as_datetimeoffset("2020-05-10T20:10:15.003-07") |> format_iso8601()

## [1] "2020-05-10T20:10:15.003-07"

as_datetimeoffset("2020-05-10 20:10:15Z") |> format_iso8601()

## [1] "2020-05-10T20:10:15Z"

as_datetimeoffset("D:202005") |> format_pdfmark()

## [1] "D:202005"

as_datetimeoffset("D:20200510201015+00'00'") |> format_pdfmark()

## [1] "D:20200510201015+00'00'"

as_datetimeoffset("2020-05-10T20:10:15.003[America/Los_Angeles]") |>
    format()

## [1] "2020-05-10T20:10:15.003-07:00[America/Los_Angeles]"

as_datetimeoffset("2020-05-10T20:10-07:00[America/Los_Angeles]") |>
    format()

## [1] "2020-05-10T20:10-07:00[America/Los_Angeles]"

# SQL Server Date / ODBC SQL_TYPE_DATE / SQL_DATE
as_datetimeoffset("2020-05-10") |>
    format_nanotime("%F")

## [1] "2020-05-10"

# SQL Server Smalldatetime / ODBC SQL_TYPE_TIMESTAMP / SQL_TIMESTAMP
as_datetimeoffset("2020-05-10 20:10:15") |>
    format_nanotime("%F %T")

## [1] "2020-05-10 20:10:15"

# SQL Server Datetime / ODBC SQL_TYPE_TIMESTAMP / SQL_TIMESTAMP
as_datetimeoffset("2020-05-10 20:10:15.123") |>
    format_nanotime("%F %H:%M:%E3S")

## [1] "2020-05-10 20:10:15.123"

# SQL Server Datetime2 / ODBC SQL_TYPE_TIMESTAMP / SQL_TIMESTAMP
as_datetimeoffset("2020-05-10 20:10:15.1234567") |>
    format_nanotime("%F %H:%M:%E7S")

## [1] "2020-05-10 20:10:15.1234567"

# SQL Server DatetimeOFFSET / ODBC SQL_SS_TIMESTAMPOFFSET
as_datetimeoffset("2020-05-10 20:10:15.1234567 -07:00") |>
    format_nanotime("%F %H:%M:%E7S %Ez")

## [1] "2020-05-10 20:10:15.1234567 -07:00"

as_datetimeoffset("2020-10-05T10:10:10") |> format_edtf()

## [1] "2020-10-05T10:10:10"

as_datetimeoffset("2020-XX-05") |> format_edtf()

## [1] "2020-XX-05"

# Lossy EDTF import situations
as_datetimeoffset("20XX-10-10") |> format_edtf()

## [1] "XXXX-10-10"

as_datetimeoffset("2020-10-XX") == as_datetimeoffset("2020-10")

## [1] TRUE

# Extensions to EDTF format
as_datetimeoffset("2020-XX-19T10:XX:10") |>
    format_edtf(precision = "nanosecond", usetz = TRUE)

## [1] "2020-XX-19T10:XX:10.XXXXXXXXX+XX:XX[X]"

as_datetimeoffset("1918/11/11 11:11") |>
    format_strftime(usetz = TRUE)

## [1] "1918-11-11 11:11:00 PST"

# Current time in a number of time zones
datetimeoffset_now(c("America/Los_Angeles", "America/New_York",
                     "Europe/London", "Asia/Shanghai"))

## <datetimeoffset[4]>
## [1] 2022-12-21T18:09:02.748841822-08:00[America/Los_Angeles]
## [2] 2022-12-21T21:09:02.748841822-05:00[America/New_York]   
## [3] 2022-12-22T02:09:02.748841822+00:00[Europe/London]      
## [4] 2022-12-22T10:09:02.748841822+08:00[Asia/Shanghai]

library("grid")
library("xmpdf") # remotes::install_github("trevorld/r-xmpdf")

creation_date <- datetimeoffset_now()
print(creation_date)

## <datetimeoffset[1]>
## [1] 2022-12-21T18:09:02.855085140-08:00[America/Los_Angeles]

# Create a two page pdf using `pdf()`
f <- tempfile(fileext = ".pdf")
pdf(f, onefile = TRUE)
grid.text("Page 1")
grid.newpage()
grid.text("Page 2")
Sys.sleep(5L) # sleep to confirm time matches start of `pdf()` call
invisible(dev.off())

di <- xmpdf::get_docinfo(f)[[1]]
print(di)

## Author: NULL
## CreationDate: 2022-12-21T18:09:02
## Creator: R
## Producer: R 4.2.2
## Title: R Graphics Output
## Subject: NULL
## Keywords: NULL
## ModDate: 2022-12-21T18:09:02

di$creation_date <- di$creation_date |>
    set_hour_offset(get_hour_offset(creation_date)) |>
    set_minute_offset(get_minute_offset(creation_date))
di$mod_date <- datetimeoffset_now() # Last modified metadata now
di$subject <- "Augmenting pdf metadata with UTC offsets"

xmpdf::set_docinfo(di, f)
di <- xmpdf::get_docinfo(f)[[1]]
print(di)

## Author: NULL
## CreationDate: 2022-12-21T18:09:02-08:00
## Creator: R
## Producer: GPL Ghostscript 9.55.0
## Title: R Graphics Output
## Subject: Augmenting pdf metadata with UTC offsets
## Keywords: NULL
## ModDate: 2022-12-21T18:09:08-08:00

Features

• datetimeoffset() objects

  • A {vctrs} “record” object that supports datetimes with optional UTC offsets and/or (possibly heteregeneous) time zones

    • Suitable for use as a column in data frames and tibbles
    • Separate {vctrs} accessible record “fields” for year, month, day, hour, minute, second, nanosecond, subsecond_digits, hour_offset, minute_offset, and time zone all of which can all be accessed by {clock} (style) accessor functions (and the {vctrs} accessor functions).
      
    • Non-missing time zones need not all be the same value

  • Supports lossless import/export of pdfmark datetime strings and a decent subset of ISO 8601 datetime strings even when datetime elements are unknown

• as_datetimeoffset() converts from standard datetime strings and other R datetime objects:

  • All pdfmark datetime strings

  • Decent subset of ISO 8601 datetime strings

    • Also supports the de facto RFC 3339 extension of specifying a named time zone at the end surrounded in brackets.

  • The datetime strings understood by the default tryFormats of as.POSIXlt()

  • The datetime strings output by the command-line tool exiftool

  • Date() objects

  • POSIXct() objects

  • POSIXlt() objects

  • nanotime::nanotime() objects

  • parttime::parttime() objects

  • five {clock} calendars and three {clock} times

  • Any other R datetime objects with an as.POSIXct() method

• Support for formatting output datetime strings:

  • format() returns RFC 3339 with de facto time zone extension strings

  • format_edtf() returns Extended Date Time Format (EDTF) strings

    • Supports unofficial extensions of “Unspecified Digit” feature to time components and time zones
    • format_edtf(x, precision = "nanosecond", usetz = TRUE) prints out all information

  • format_exiftool() formats datetime strings as expected by the command-line tool exiftool

  • format_iso8601() and lubridate::format_ISO8601() returns ISO 8601 strings

  • format_pdfmark() returns pdfmark datetime strings

  • format_nanotime() allows CCTZ style formatting

    • Can output SQL Server / ODBC datetime literals

  • format_strftime() allows base::strftime() style formatting

• Support for converting to other R datetime objects:

  • as.Date() and as_date() converts the local date to a base::Date() object

  • as.POSIXct() and as_date_time() converts the datetime to a base::POSIXct() object

  • as.POSIXlt() converts the datetime to a base::POSIXlt() object

  • as.nanotime() converts the datetime to a nanotime::nanotime() object

  • as.parttime() converts the datetime to a parttime::parttime() object

  • {clock} calendars, times, and weekdays:

    • as_iso_year_week_day(), as_year_day(), as_year_month_day(), as_year_month_weekday(), as_year_quarter_day()
    • as_naive_time(), as_sys_time(), as_zoned_time()
    • as_weekday()

• Support for several accessor S3 methods from {clock}

  • get_year() and set_year()
  • get_month() and set_month()
  • get_day() and set_day()
  • get_hour() and set_hour()
  • get_minute() and set_minute()
  • get_second() and set_second()
  • get_nanosecond() and set_nanosecond()

• Support for several accessor methods from {lubridate}

  • year() and year()<-
  • month() and month()<-
  • day() and day()<-
  • hour() and hour()<-
  • minute() and minute()<-
  • second() and second()<-
  • tz() and tz()<-

• New accessor S3 methods:

  • get_subsecond_digits() and set_subsecond_digits()
  • get_hour_offset() and set_hour_offset()
  • get_minute_offset() and set_minute_offset()
  • get_tz() and set_tz() (changes system time, not clock time)

• Get/set datetime “precision” S3 methods

  • datetime_cast()
  • datetime_narrow()
  • datetime_precision()
  • datetime_widen()

• Additional subsecond accessors

  • get_millisecond() and set_millisecond()
  • get_microsecond() and set_microsecond()
  • get_subsecond() and set_subsecond()

• Other utilities:

  • datetimeoffset_now() returns the current time in the corresponding time zone(s).
  • is_datetimeoffset() and NA_datetimeoffset_
  • fill_tz() and fill_utc_offsets() fill in missing time zones and missing UTC offsets respectively.
  • mode_tz() is an S3 method that gets most common time zone for a datetime object
  • datetime_at_tz() can be used to change the timezone (changes clock time, not system time). As an alternative can also use lubridate::with_tz().
  • get_utc_offsets() and set_utc_offsets() gets/sets UTC offset strings
  • Support for {clock} invalid datetime methods invalid_detect(), invalid_any(), invalid_count(), invalid_remove(), and invalid_resolve().
  • precision_to_int() converts datetime precisions to an integer
  • Support for {base} datetime extractors weekdays(), months(), quarters(), and julian()
  • Support for {lubridate} datetime extractors date(), date()<-, isoyear(), epiyear(), quarter(), semester(), week(), isoweek(), epiweek(), qday(), qday<-(), wday(), wday<-(), yday(), yday<-(), am(), pm(), days_in_month(), dst(), and leap_year().
  • Support for {lubridate} force_tz() and with_tz().

Comparison with {clock}

Note: Please feel free to open a pull request to fix any {clock} mis-understandings or statements that are now out-of-date.

{datetimeoffset} is most similar to the excellent {clock} (which {datetimeoffset} uses internally):

• Both use {vctrs} “record” objects
• Both support variable precision datetimes
• Both support up to nanosecond precision
• Both have support for local times (with perhaps unknown time zone or UTC offset), UTC times, and times with time zones

Comparison with {parttime}

Note: Please feel free to open a pull request to fix any {parttime} mis-understandings or statements that are now out-of-date.

A {datetimeoffset} is also similar to the excellent {parttime}:

• Both are {vctrs} datetime objects that allow mixed precision datetimes including support for UTC offsets

• {parttime} supports more advanced mixed precision comparisons

• {parttime} uses 64-bit floating point numbers instead of 32-bit integers to store various fields so can theoretically support years greater than 2,147,483,647 as well as subseconds at greater than nanosecond precision (although there are known issues with using floating point numbers such as representation error avoided by representing subseconds as an integer)

• {datetimeoffset} uses more fields to store UTC offsets and fractional seconds so there are cases where {datetimeoffset} will be more lossless importing/exporting certain datetime strings compared to {parttime}:

  as_datetimeoffset("2020-01-02T03:04:05.10000+05")

  ## <datetimeoffset[1]>
  ## [1] 2020-01-02T03:04:05.10000+05

  parttime::as.parttime("2020-01-02T03:04:05.10000+05")

  ## Initializing default timezone offset, which is assumed when timezone
  ## parts are missing.
  ## 
  ##     options("parttime.assume_tz_offset" = 0L)

  ## <partial_time<YMDhms+tz>[1]> 
  ## [1] "2020-01-02 03:04:05.100+05:00"

Serializing

dts <- datetimeoffset(year = c(2020, 1980), month = c(NA, 10), day = c(15, NA))
format_edtf(dts)

## [1] "2020-XX-15" "1980-10"

# serialize via data frame
df <- vctrs::vec_data(dts)
print(df)

##   year month day hour minute second nanosecond subsecond_digits hour_offset
## 1 2020    NA  15   NA     NA     NA         NA               NA          NA
## 2 1980    10  NA   NA     NA     NA         NA               NA          NA
##   minute_offset   tz
## 1            NA <NA>
## 2            NA <NA>

dts_df <- do.call(datetimeoffset, as.list(df))
all.equal(dts, dts_df)

## [1] TRUE

# serialize via base::serialize() or base::saveRDS()
x <- serialize(dts, NULL) # raw binary vector
dts_x <- unserialize(x)
all.equal(dts, dts_x)

## [1] TRUE

External links

Please feel free to open a pull request to add any missing relevant links.