Convert datetime objects to character

format() returns a datetime string with as much known information possible (RFC 3339 with de facto standard time zone extension). format_iso8601() returns an ISO 8601 datetime string. format_pdfmark() returns a pdfmark datetime string with as much known information possible. format_strftime() allows base::strftime() style formatting. format_nanotime() allows CCTZ style formatting. format_edtf() returns an Extended Date Time Format (EDTF) string. format_exiftool() returns the date/time string expected by exiftool.

Usage

# S3 method for class 'datetimeoffset'
format(x, ...)

format_iso8601(
  x,
  offsets = TRUE,
  precision = NULL,
  sep = ":",
  mode = c("normal", "toml", "xmp"),
  ...
)

format_pdfmark(x, prefix = "D:")

format_edtf(x, offsets = TRUE, precision = NULL, usetz = FALSE, ...)

format_exiftool(x, mode = c("normal", "xmp", "pdf"), ...)

format_strftime(
  x,
  format = "%Y-%m-%d %H:%M:%S",
  tz = get_tz(x),
  usetz = FALSE,
  fill = mode_tz(x)
)

format_nanotime(
  x,
  format = "%Y-%m-%dT%H:%M:%E9S%Ez",
  tz = get_tz(x),
  fill = ""
)

Arguments

x

A datetimeoffset() object.

...

Ignored

offsets

Include the UTC offsets in the formatting

precision

The amount of precision: either "year", "month", "day", "hour", "minute", "second", "decisecond", "centisecond", "millisecond", "hundred microseconds", "ten microseconds", "microsecond", "hundred nanoseconds", "ten nanoseconds", or "nanosecond". If NULL then full precision for the object is shown.

sep

UTC offset separator. Either ":" or "".

mode

If mode = "pdf" only output supported PDF docinfo datetime values. If mode = "toml" only output supported TOML datetime values. If mode = "xmp" only output valid XMP metadata datetime values.

prefix

Prefix to use. Either "D:" (default) or "".

usetz

Include the time zone in the formatting

format

For format_strftime() see base::strftime(). For format_nanotime() see https://github.com/google/cctz/blob/6e09ceb/include/time_zone.h#L197.

tz

A character string specifying the time zone to be used for the conversion. Can be a length greater than one.

fill

If timezone and UTC offset info is missing what timezone to assume. See fill_tz().

Value

A character vector

Examples

  # ISO 8601 datetimes
  format_iso8601(as_datetimeoffset("2020-05"))
#> [1] "2020-05"
  format_iso8601(as_datetimeoffset("2020-05-10 20:15"))
#> [1] "2020-05-10T20:15"
  format_iso8601(as_datetimeoffset("2020-05-10 20:15:05-07"))
#> [1] "2020-05-10T20:15:05-07"
  if (requireNamespace("lubridate"))
    lubridate::format_ISO8601(as_datetimeoffset("2020-05-10 20:15:05-07"))
#> [1] "2020-05-10T20:15:05"

  # pdfmark datetimes
  format_pdfmark(as_datetimeoffset("2020-05"))
#> [1] "D:202005"
  format_pdfmark(as_datetimeoffset("2020-05-10 20:15"))
#> [1] "D:202005102015"
  format_pdfmark(as_datetimeoffset("2020-05-10 20:15:05-07"))
#> [1] "D:20200510201505-07'"

  # strftime style formatting
  dt <- as_datetimeoffset("2020-05-10 20:15")
  format_strftime(dt)
#> [1] "2020-05-10 20:15:00"
  format_strftime(dt, format = "%c")
#> [1] "Sun 10 May 2020 08:15:00 PM PDT"

  # CCTZ style formatting
  if (requireNamespace("nanotime")) {
    dt <- as_datetimeoffset(Sys.time())
    format_nanotime(dt, format = "%F %H:%M:%E7S %Ez") # SQL Server datetimeoffset
  }
#> [1] "2025-03-24 09:52:31.8412620 -07:00"

  # EDTF style formatting
  format_edtf(as_datetimeoffset("2020-05"))
#> [1] "2020-05"
  format_edtf(as_datetimeoffset("2020-05-10T20:15:05-07"))
#> [1] "2020-05-10T20:15:05-07"
  dt <- datetimeoffset(2020, NA_integer_, 10)
  format_edtf(dt)
#> [1] "2020-XX-10"

  # `exiftool` formatting
  format_exiftool(as_datetimeoffset("2020:05:10"))
#> [1] "2020:05:10 00:00:00"
  format_exiftool(as_datetimeoffset("2020:05:10 20:15"))
#> [1] "2020:05:10 20:15:00"
  format_exiftool(as_datetimeoffset("2020:05:10 20:15:05-07:00"))
#> [1] "2020:05:10 20:15:05-07:00"