pointblank (version 0.7.0)

affix_datetime: Put the current date-time into a file name

Description

This function helps to affix the current date-time to a filename. This is useful when writing agent and/or informant objects to disk as part of a continuous process. The date-time string can be based on the current UTC time or the local system time. The date-time can be affixed either to the end of the filename (before the file extension) or at the beginning with a customizable delimiter. Optionally, the time zone information can be included. If the date-time is based on the local system time, the user system time zone is shown with the format <time>(+/-)hhmm. If using UTC time, then the <time>Z format is adopted.

The x_write_disk(), yaml_write() functions allow for the writing of pointblank objects to disk. The modification of the filename string takes effect immediately but not at the time of writing a file to disk. In most cases, especially when using affix_datetime() with the aforementioned file-writing functions, the file timestamps should approximate the time components affixed to the filenames.

Usage

affix_datetime(
  filename,
  position = c("end", "start"),
  format = "%Y-%m-%d_%H-%M-%S",
  delimiter = "_",
  utc_time = TRUE,
  add_tz = FALSE
)

Arguments

filename

The filename to modify.

position

Where to place the formatted date-time. This could either be at the "end" of the filename (the default) or at the "start".

format

A base::strptime() format string for formatting the date-time. By default, this is "%Y-%m-%dT%H:%M:%S" which expresses the date according to the ISO 8601 standard. For example, if the current date-time is 2020-12-04 13:11:23, the formatted string would become "2020-12-04T13:11:23". Refer to the documentation on base::strptime() for conversion specifications if planning to use a different format string.

delimiter

The delimiter characters to use for separating the date-time string from the original file name.

utc_time

An option for whether to use the current UTC time to establish the date-time (the default, with TRUE), or, use the system's local time (FALSE).

add_tz

Should the time zone (as an offset from UTC) be provided? If TRUE then the UTC offset will be either provided as <time>Z (if utc_time = TRUE) or <time>(+/-)hhmm. By default, this is FALSE.

Value

A character vector.

Function ID

12-4

See Also

The affix_date() function provides the same features except it produces a date string by default.

Other Utility and Helper Functions: affix_date(), col_schema(), from_github(), has_columns(), stop_if_not()

Examples

# NOT RUN {
# Taking the generic `pb_file` name for
# a file, we add the current date-time to it
# as a suffix
affix_datetime(filename = "pb_file")

# File extensions won't get in the way:
affix_datetime(filename = "pb_file.rds")

# The date-time can be used as a prefix
affix_datetime(
  filename = "pb_file",
  position = "start"
)

# The date-time pattern can be changed and so
# can the delimiter
affix_datetime(
  filename = "pb_file.yml",
  format = "%Y%m%d_%H%M%S",
  delimiter = "-"
)

# Time zone information can be included
affix_datetime(
  filename = "pb_file.yml",
  add_tz = TRUE
)

if (interactive()) {

# We can use a file-naming convention
# involving date-times when writing output
# files immediately after interrogating;
# useful when interrogating directly
# from YAML in a scheduled process
yaml_agent_interrogate(
  filename = system.file(
    "yaml", "agent-small_table.yml",
    package = "pointblank"
  )
) %>% 
  x_write_disk(
    filename = affix_datetime(
      filename = "small_table_agent.rds",
      delimiter = "-"
    ),
    keep_tbl = TRUE,
    keep_extracts = TRUE
  )

}

# }