Skip to contents

Create a File Path

Source: R/create_file_path.R
create_file_path.Rd

Create a file path, creating the indicated directory if it does not yet exist.

Usage

create_file_path(
  filename,
  format_stamp = "%Y_%m_%d_%H_%M_%S",
  dir = fs::path(".", "output"),
  add_date = TRUE
)

Arguments

filename

character string with the file name, including the file extension like .csv or .txt. Should adhere to the restrictions described in checkinput::is_path().

format_stamp

character string indicating the format of the stamp to be added in front of the file name. No stamp is added if format_stamp is an empty string (""). The formatted stamp is treated as part of the filename, such that the same restrictions apply to format_stamp as to filename, see 'Details'.

dir

character string containing a valid path, see 'Details' and the section 'Notes on Paths' below.

add_date

TRUE or FALSE: create a subdirectory in dir with the current date in the format YYYY_mm_dd?

Value

A character string with the created absolute normalized path, returned invisibly, see the section 'Notes on Paths' below.

An error is thrown if the attempt to create a file path fails. A warning is issued if the file already exists, see 'Details'.

Details

filename should contain a file extension (i.e., a dot followed by any character until the end of the file name) and should not contain slashes or backslashes: use dir to indicate subdirectories.

The path in dir is interpreted as a relative path to the directory that should be created, starting from the working directory, see the section 'Notes on Paths' below.

A warning is issued if the file indicated by the returned path already exists. To prevent this when creating files in quick succession, use "%OSn" as part of format_stamp to create precise stamps by truncating seconds to 0 <= n <= 6 decimal places, see strftime() for details.

create_file_path() creates the directory but does not create the file: wrap the call to create_file_path() in fs::file_create() or in file.create() to create the file.

Calls where date nor time stamps are added (i.e, using format_stamp = "" and add_date = FALSE) can be replaced by fs::path(fs::dir_create(path = "<dir>"), "<filename>") to not get a warning if the file already exists.

Side Effects

The directory indicated by the returned path is created if it does not yet exist.

Notes on Paths

The file separator is a backslash (\) on Windows but a forward slash (/) on other operating systems: use file.path() or fs::path() to construct paths in a platform-independent way and .Platform$file.sep to get the file separator used on the current platform.

Furthermore, the backslash is also used as an escape character in R, such that backslashes need to be escaped in R code by doubling them. Use cat(x) to omit the escape characters to see how x would be printed.

The working directory can be indicated by a single dot (".") and the parent directory can be indicated by two dots ("..").

relative paths start from the working directory. In contrast, absolute paths start from the root directory and thus give the complete path, such that the path still points to the same directory if the working directory changes.

Paths can be normalised, e.g., through normalizePath() or fs::path_norm() (which is also called by fs::path_abs()). On case-insensitive file systems, this also adjusts the case to match names of directories that are already present.

See also

checkinput::is_path() to check if a path is valid, with extensive references about file paths and directories; get_file_path() to check if a file exists and is a unique match to a pattern; create_dir() (used by this function) to create a directory if it does not yet exist

Other functions to handle paths and directories: create_dir(), create_tempdir(), get_file_path()

Examples

# Use a temporary directory to not write in the user's directory
my_tempdir <- create_tempdir(prefix = "examplecreatefilepath")

(create_file_path(
  filename = "abc.txt", format_stamp = "",
  dir = my_tempdir, add_date = TRUE))
#> /tmp/RtmpmaAUni/examplecreatefilepath1aa922c9aed/2026_10_22/abc.txt
(create_file_path(
  filename = "abc.txt", format_stamp = "%d_%m_%Y",
  dir = my_tempdir, add_date = TRUE))
#> /tmp/RtmpmaAUni/examplecreatefilepath1aa922c9aed/2026_10_22/22_10_2026_abc.txt
(create_file_path(
  filename = "def.html", format_stamp = "",
  dir = my_tempdir, add_date = FALSE))
#> /tmp/RtmpmaAUni/examplecreatefilepath1aa922c9aed/def.html
(create_file_path(
  filename = "def.html", format_stamp = "%d_%m_%Y",
  dir = my_tempdir, add_date = FALSE))
#> /tmp/RtmpmaAUni/examplecreatefilepath1aa922c9aed/22_10_2026_def.html
(create_file_path(
  filename = "abc.txt", format_stamp = "",
  dir = fs::path(my_tempdir, "subdir"), add_date = TRUE))
#> /tmp/RtmpmaAUni/examplecreatefilepath1aa922c9aed/subdir/2026_10_22/abc.txt
(create_file_path(
  filename = "abc.txt", format_stamp = "%d_%m_%Y",
  dir = fs::path(my_tempdir, "subdir"), add_date = TRUE))
#> /tmp/RtmpmaAUni/examplecreatefilepath1aa922c9aed/subdir/2026_10_22/22_10_2026_abc.txt
(create_file_path(
  filename = "def.html", format_stamp = "",
  dir = fs::path(my_tempdir, "subdir"), add_date = FALSE))
#> /tmp/RtmpmaAUni/examplecreatefilepath1aa922c9aed/subdir/def.html
(create_file_path(
  filename = "def.html", format_stamp = "%d_%m_%Y",
  dir = fs::path(my_tempdir, "subdir"), add_date = FALSE))
#> /tmp/RtmpmaAUni/examplecreatefilepath1aa922c9aed/subdir/22_10_2026_def.html

# Cleaning up
unlink(x = my_tempdir, recursive = TRUE)
rm(my_tempdir)