btread: Read a delimited text file

In basetable: Fast and Memory-Efficient Base R Table Manipulation

Read a delimited text file

Description

A from-scratch delimited-file reader written in C++: the file is memory mapped, scanned once for row boundaries (RFC 4180 quoting), type-guessed from a bounded sample, and materialised into typed vectors. Numeric columns are filled by a thread pool; character columns are built on the R thread.

Usage

btread(
  file,
  delim = NULL,
  header = TRUE,
  col_names = NULL,
  col_types = NULL,
  col_select = NULL,
  na = c("NA", ""),
  quote = "\"",
  comment = "",
  trim_ws = FALSE,
  skip = 0,
  n_max = Inf,
  guess_max = 10000,
  lazy = FALSE,
  n_threads = bt_default_threads(),
  as = c("data.frame", "basetable")
)

Arguments

file	Path to a delimited text file. .gz inputs are decompressed to a temporary file first.
delim	Field delimiter. NULL (default) sniffs the first line for one of ⁠,⁠ ⁠\t⁠ ⁠;⁠ | and a space.
header	Logical; does the first row hold column names?
col_names	Optional character vector of names, used only when header = FALSE. Defaults to V1, V2, ...
col_types	NULL to guess, or a character vector of "logical", "integer", "double", "character", "skip", "guess". Length 1 is recycled; otherwise it must have one entry per column.
col_select	Optional integer positions or character names of the columns to keep. Other columns are not parsed.
na	Character vector of strings to read as NA.
quote	Quoting character.
comment	Lines beginning with this one-character string are skipped ("" disables).
trim_ws	Logical; strip leading/trailing spaces and tabs from unquoted fields.
skip	Number of raw lines to discard before reading.
n_max	Maximum number of data rows to read (Inf for all).
guess_max	Number of rows sampled for type guessing.
lazy	Logical; return numeric columns as lazily-parsed ALTREP vectors.
n_threads	Number of worker threads for the eager numeric fill.
as	Return "data.frame" (default) or "basetable".

Details

With lazy = TRUE the integer and double columns are returned as ALTREP vectors that parse their column only the first time it is touched, which makes "read a few columns from a wide file" close to free.

Value

A data.frame.

Examples

p <- tempfile(fileext = ".csv")
write.csv(head(iris), p, row.names = FALSE)
btread(p)

basetable documentation built on Sept. 18, 2026, 9:13 a.m.