,
Gábor Csárdi [aut, cre],
Posit Software, PBC [cph, fnd]| Title: | Basic R Input Output |
|---|---|
| Description: | Functions to handle basic input output, these functions always read and write UTF-8 (8-bit Unicode Transformation Format) files and provide more explicit control over line endings. |
| Authors: | Jim Hester [aut] ,
Gábor Csárdi [aut, cre],
Posit Software, PBC [cph, fnd] |
| Maintainer: | Gábor Csárdi <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 1.1.5.9000 |
| Built: | 2024-06-25 05:31:47 UTC |
| Source: | https://github.com/r-lib/brio |
Retrieve the type of line endings used by a file
file_line_endings(path)file_line_endings(path)
path |
A character string of the path to the file to read. |
The line endings used, one of
'\n' - if the file uses Unix line endings
'\r\n' - if the file uses Windows line endings
NA - if it cannot be determined
tf1 <- tempfile() tf2 <- tempfile() write_lines("foo", tf1, eol = "\n") write_lines("bar", tf2, eol = "\r\n") file_line_endings(tf1) file_line_endings(tf2) unlink(c(tf1, tf2))tf1 <- tempfile() tf2 <- tempfile() write_lines("foo", tf1, eol = "\n") write_lines("bar", tf2, eol = "\r\n") file_line_endings(tf1) file_line_endings(tf2) unlink(c(tf1, tf2))
read_file() reads an entire file into a single character vector.
read_file_raw() reads an entire file into a raw vector.
read_file(path) read_file_raw(path)read_file(path) read_file_raw(path)
path |
A character string of the path to the file to read. |
read_file() assumes the file has a UTF-8 encoding.
read_file(): A length 1 character vector.
read_file_raw(): A raw vector.
authors_file <- file.path(R.home("doc"), "AUTHORS") data <- read_file(authors_file) data_raw <- read_file_raw(authors_file) identical(data, rawToChar(data_raw))authors_file <- file.path(R.home("doc"), "AUTHORS") data <- read_file(authors_file) data_raw <- read_file_raw(authors_file) identical(data, rawToChar(data_raw))
The file is assumed to be UTF-8 and the resulting text has its encoding set as such.
read_lines(path, n = -1)read_lines(path, n = -1)
path |
A character string of the path to the file to read. |
n |
integer. The number of lines to read. A negative number means read all the lines in the file. |
Both '\r\n' and '\n' are treated as a newline.
A UTF-8 encoded character vector of the lines in the file.
authors_file <- file.path(R.home("doc"), "AUTHORS") data <- read_lines(authors_file)authors_file <- file.path(R.home("doc"), "AUTHORS") data <- read_lines(authors_file)
This is a drop in replacement for base::readLines() with restricted
functionality. Compared to base::readLines() it:
Only works with file paths, not connections.
Assumes the files are always UTF-8 encoded.
Does not warn or skip embedded nulls, they will likely crash R.
Does not warn if the file is missing the end of line character.
The arguments ok, warn, encoding and skipNul are ignored, with a warning.
readLines(con, n = -1, ok, warn, encoding, skipNul)readLines(con, n = -1, ok, warn, encoding, skipNul)
con |
A character string of the path to a file. Throws an error if a connection object is passed. |
n |
integer. The number of lines to read. A negative number means read all the lines in the file. |
ok |
Ignored, with a warning. |
warn |
Ignored, with a warning. |
encoding |
Ignored, with a warning. |
skipNul |
Ignored, with a warning. |
A UTF-8 encoded character vector of the lines in the file.
authors_file <- file.path(R.home("doc"), "AUTHORS") data <- readLines(authors_file) # Trying to use connections throws an error con <- file(authors_file) try(readLines(con)) close(con) # Trying to use unsupported args throws a warning data <- readLines(authors_file, encoding = "UTF-16")authors_file <- file.path(R.home("doc"), "AUTHORS") data <- readLines(authors_file) # Trying to use connections throws an error con <- file(authors_file) try(readLines(con)) close(con) # Trying to use unsupported args throws a warning data <- readLines(authors_file, encoding = "UTF-16")
This function differs from write_lines() in that it writes the data in
text directly, without any checking or adding any newlines.
write_file(text, path)write_file(text, path)
text |
A character vector of length 1 with data to write. |
path |
A character string giving the file path to write to. |
The UTF-8 encoded input text (invisibly).
tf <- tempfile() write_file("some data\n", tf) unlink(tf)tf <- tempfile() write_file("some data\n", tf) unlink(tf)
This function differs from write_lines() in that it writes the data in
text directly, without any checking or adding any newlines.
write_file_raw(raw, path)write_file_raw(raw, path)
raw |
A raw vector with data to write. |
path |
A character string giving the file path to write to. |
tf <- tempfile() write_file_raw(as.raw(c(0x66, 0x6f, 0x6f, 0x0, 0x62, 0x61, 0x72)), tf) unlink(tf)tf <- tempfile() write_file_raw(as.raw(c(0x66, 0x6f, 0x6f, 0x0, 0x62, 0x61, 0x72)), tf) unlink(tf)
The text is converted to UTF-8 encoding before writing.
write_lines(text, path, eol = "\n")write_lines(text, path, eol = "\n")
text |
A character vector to write |
path |
A character string giving the file path to write to. |
eol |
The end of line characters to use between lines. |
The files are opened in binary mode, so they always use exactly the string
given in eol as the line separator.
To write a file with windows line endings use write_lines(eol = "\r\n")
The UTF-8 encoded input text (invisibly).
tf <- tempfile() write_lines(rownames(mtcars), tf) # Write with Windows style line endings write_lines(rownames(mtcars), tf, eol = "\r\n") unlink(tf)tf <- tempfile() write_lines(rownames(mtcars), tf) # Write with Windows style line endings write_lines(rownames(mtcars), tf, eol = "\r\n") unlink(tf)
This is a drop in replacement for base::writeLines() with restricted
functionality. Compared to base::writeLines() it:
Only works with file paths, not connections.
Uses enc2utf8() to convert text() to UTF-8 before writing.
Uses sep unconditionally as the line ending, regardless of platform.
The useBytes argument is ignored, with a warning.
writeLines(text, con, sep = "\n", useBytes)writeLines(text, con, sep = "\n", useBytes)
text |
A character vector to write |
con |
A character string of the path to a file. Throws an error if a connection object is passed. |
sep |
The end of line characters to use between lines. |
useBytes |
Ignored, with a warning. |
The UTF-8 encoded input text (invisibly).
tf <- tempfile() writeLines(rownames(mtcars), tf) # Trying to use connections throws an error con <- file(tf) try(writeLines(con)) close(con) # Trying to use unsupported args throws a warning writeLines(rownames(mtcars), tf, useBytes = TRUE) unlink(tf)tf <- tempfile() writeLines(rownames(mtcars), tf) # Trying to use connections throws an error con <- file(tf) try(writeLines(con)) close(con) # Trying to use unsupported args throws a warning writeLines(rownames(mtcars), tf, useBytes = TRUE) unlink(tf)