Input object

Either column objects created by ⁠col_*()⁠, or their abbreviated character names (as described in the col_types argument of vroom()). If you're only overriding a few columns, it's best to refer to columns by name. If not named, the column types must match the column names exactly. In ⁠col_*()⁠ functions these are stored in the object.

Any named columns not explicitly overridden in ... will be read with this column type.

The delimiter to use when parsing. If the delim argument used in the call to vroom() it takes precedence over the one specified in col_types.

Character vector of the allowed levels. When levels = NULL (the default), levels are discovered from the unique values of x, in the order in which they appear in x.

Is it an ordered factor?

If TRUE and x contains at least one NA, then NA is included in the levels of the constructed factor.

A format specification, as described below. If set to "", date times are parsed as ISO8601, dates and times used the date and time formats specified in the locale().

Unlike strptime(), the format specification must match the complete string.

The data frame object to extract from

Full and abbreviated month names.

Full and abbreviated week day names. Starts with Sunday.

Names used for AM and PM.

A BCP 47 locale, made up of a language and a region, e.g. "en_US" for American English. See date_names_langs() for a complete list of available locales.

Number of rows to generate

Number of columns to generate, if NULL this is derived from col_types.

One of NULL, a cols() specification, or a string.

If NULL, all column types will be imputed from guess_max rows on the input interspersed throughout the file. This is convenient (and fast), but not robust. If the imputation fails, you'll need to increase the guess_max or supply the correct types yourself.

Column specifications created by list() or cols() must contain one column specification for each column. If you only want to read a subset of the columns, use cols_only().

Alternatively, you can use a compact string representation where each character represents one column:

• c = character

• i = integer

• n = number

• d = double

• l = logical

• f = factor

• D = date

• T = date time

• t = time

• ? = guess

• _ or - = skip

  By default, reading a file without a column specification will print a message showing what readr guessed they were. To remove this message, set show_col_types = FALSE or set options(readr.show_col_types = FALSE).

The locale controls defaults that vary from place to place. The default locale is US-centric (like R), but you can use locale() to create your own locale that controls things like the default time zone, encoding, decimal mark, big mark, and day/month names.

The percentage (from 0 to 1) of missing data to use

The size of the vector to generate

The minimum range for the vector

The maximum range for the vector

The explicit values to use.

Additional arguments passed to internal generation functions

The random function to use.

a vector of probability weights for obtaining the elements of the vector being sampled.

The explicit levels to use, if NULL random levels are generated using gen_name().

Should the factors be ordered factors?

The number of factor levels to generate

Whether to generate times with fractional seconds

The timezone to use for dates

Character vector of values to parse.

Character vector of strings to interpret as missing values. Set this option to character() to indicate no missing values.

The locale controls defaults that vary from place to place. The default locale is US-centric (like R), but you can use locale() to create your own locale that controls things like the default time zone, encoding, decimal mark, big mark, and day/month names.

If TRUE, guess integer types for whole numbers, if FALSE guess numeric type for all numbers.

Character representations of day and month names. Either the language code as string (passed on to date_names_lang()) or an object created by date_names().

Default date and time formats.

Symbols used to indicate the decimal place, and to chunk larger numbers. Decimal mark can only be ⁠,⁠ or ..

Default tz. This is used both for input (if the time zone isn't present in individual strings), and for output (to control the default display). The default is to use "UTC", a time zone that does not use daylight savings time (DST) and hence is typically most useful for data. The absence of time zones makes it approximately 50x faster to generate UTC times than any other time zone.

Use "" to use the system default time zone, but beware that this will not be reproducible across systems.

For a complete list of possible time zones, see OlsonNames(). Americans, note that "EST" is a Canadian time zone that does not have DST. It is not Eastern Standard Time. It's better to use "US/Eastern", "US/Central" etc.

Default encoding.

A vector

A data frame from vroom::vroom().

If TRUE, just the problems found so far are returned. If FALSE (the default) the lazy data is first read completely and all problems are returned.

Either a path to a file, a connection, or literal data (either a single string or a raw vector). file can also be a character vector containing multiple filepaths or a list containing multiple connections.

Files ending in .gz, .bz2, .xz, or .zip will be automatically uncompressed. Files starting with ⁠http://⁠, ⁠https://⁠, ⁠ftp://⁠, or ⁠ftps://⁠ will be automatically downloaded. Remote gz files can also be automatically downloaded and decompressed.

Literal data is most useful for examples and tests. To be recognised as literal data, wrap the input with I().

One or more characters used to delimit fields within a file. If NULL the delimiter is guessed from the set of c(",", "\t", " ", "|", ":", ";").

Either TRUE, FALSE or a character vector of column names.

If TRUE, the first row of the input will be used as the column names, and will not be included in the data frame. If FALSE, column names will be generated automatically: X1, X2, X3 etc.

If col_names is a character vector, the values will be used as the names of the columns, and the first row of the input will be read into the first row of the output data frame.

Missing (NA) column names will generate a warning, and be filled in with dummy names ...1, ...2 etc. Duplicate column names will generate a warning and be made unique, see name_repair to control how this is done.

One of NULL, a cols() specification, or a string.

If NULL, all column types will be imputed from guess_max rows on the input interspersed throughout the file. This is convenient (and fast), but not robust. If the imputation fails, you'll need to increase the guess_max or supply the correct types yourself.

Column specifications created by list() or cols() must contain one column specification for each column. If you only want to read a subset of the columns, use cols_only().

Alternatively, you can use a compact string representation where each character represents one column:

• c = character

• i = integer

• n = number

• d = double

• l = logical

• f = factor

• D = date

• T = date time

• t = time

• ? = guess

• _ or - = skip

  By default, reading a file without a column specification will print a message showing what readr guessed they were. To remove this message, set show_col_types = FALSE or set options(readr.show_col_types = FALSE).

Columns to include in the results. You can use the same mini-language as dplyr::select() to refer to the columns by name. Use c() to use more than one selection expression. Although this usage is less common, col_select also accepts a numeric column index. See ?tidyselect::language for full details on the selection language.

Either a string or 'NULL'. If a string, the output will contain a variable with that name with the filename(s) as the value. If 'NULL', the default, no variable will be created.

Number of lines to skip before reading data. If comment is supplied any commented lines are ignored after skipping.

Maximum number of lines to read.

Character vector of strings to interpret as missing values. Set this option to character() to indicate no missing values.

Single character used to quote strings.

A string used to identify comments. Any text after the comment characters will be silently ignored.

Should blank rows be ignored altogether? i.e. If this option is TRUE then blank rows will not be represented at all. If it is FALSE then they will be represented by NA values in all the columns.

Should leading and trailing whitespace (ASCII spaces and tabs) be trimmed from each field before parsing it?

Does the file escape quotes by doubling them? i.e. If this option is TRUE, the value '""' represents a single quote, '"'.

Does the file use backslashes to escape special characters? This is more general than escape_double as backslashes can be used to escape the delimiter character, the quote character, or to add special characters like ⁠\\n⁠.

The locale controls defaults that vary from place to place. The default locale is US-centric (like R), but you can use locale() to create your own locale that controls things like the default time zone, encoding, decimal mark, big mark, and day/month names.

Maximum number of lines to use for guessing column types. See vignette("column-types", package = "readr") for more details.

Control which column types use Altrep representations, either a character vector of types, TRUE or FALSE. See vroom_altrep() for for full details.

Number of threads to use when reading and materializing vectors. If your data contains newlines within fields the parser will automatically be forced to use a single thread only.

Display a progress bar? By default it will only display in an interactive session and not while knitting a document. The automatic progress bar can be disabled by setting option readr.show_progress to FALSE.

Control showing the column specifications. If TRUE column specifications are always show, if FALSE they are never shown. If NULL (the default) they are shown only if an explicit specification is not given to col_types.

Handling of column names. The default behaviour is to ensure column names are "unique". Various repair strategies are supported:

• "minimal": No name repair or checks, beyond basic existence of names.

• "unique" (default value): Make sure names are unique and not empty.

• "check_unique": no name repair, but check they are unique.

• "universal": Make the names unique and syntactic.

• A function: apply custom name repair (e.g., name_repair = make.names for names in the style of base R).

• A purrr-style anonymous function, see rlang::as_function().

This argument is passed on as repair to vctrs::vec_as_names(). See there for more details on these terms and the strategies used to enforce them.

A character vector of column types to use Altrep for. Can also take TRUE or FALSE to use Altrep for all possible or none of the types

A character vector of column types to use Altrep for. Can also take TRUE or FALSE to use Altrep for all possible or none of the types

Name of file.

A regular expression of filenames to match. If NULL, all available files are returned.

A data frame or tibble to write to disk.

Delimiter used to separate values. Defaults to ⁠\t⁠ to write tab separated value (TSV) files.

The end of line character to use. Most commonly either "\n" for Unix style newlines, or "\r\n" for Windows style newlines.

String used for missing values. Defaults to 'NA'.

If FALSE, column names will not be included at the top of the file. If TRUE, column names will be included. If not specified, col_names will take the opposite value given to append.

The type of escape to use when quotes are in the data.

• double - quotes are escaped by doubling them.

• backslash - quotes are escaped by a preceding backslash.

• none - quotes are not escaped.

How to handle fields which contain characters that need to be quoted.

• needed - Values are only quoted if needed: if they contain a delimiter, quote, or newline.

• all - Quote all fields.

• none - Never quote fields.

If TRUE add a UTF-8 BOM at the beginning of the file. This is recommended when saving data for consumption by excel, as it will force excel to read the data with the correct encoding (UTF-8)

Number of threads to use when reading and materializing vectors. If your data contains newlines within fields the parser will automatically be forced to use a single thread only.

Either a path to a file, a connection, or literal data (either a single string or a raw vector).

Files ending in .gz, .bz2, .xz, or .zip will be automatically uncompressed. Files starting with ⁠http://⁠, ⁠https://⁠, ⁠ftp://⁠, or ⁠ftps://⁠ will be automatically downloaded. Remote gz files can also be automatically downloaded and decompressed.

Literal data is most useful for examples and tests. To be recognised as literal data, the input must be either wrapped with I(), be a string containing at least one new line, or be a vector containing at least one string with a new line.

Using a value of clipboard() will read from the system clipboard.

Column positions, as created by fwf_empty(), fwf_widths() or fwf_positions(). To read in only selected fields, use fwf_positions(). If the width of the last column is variable (a ragged fwf file), supply the last end position as NA.

One of NULL, a cols() specification, or a string. See vignette("readr") for more details.

If NULL, all column types will be inferred from guess_max rows of the input, interspersed throughout the file. This is convenient (and fast), but not robust. If the guessed types are wrong, you'll need to increase guess_max or supply the correct types yourself.

Column specifications created by list() or cols() must contain one column specification for each column. If you only want to read a subset of the columns, use cols_only().

Alternatively, you can use a compact string representation where each character represents one column:

• c = character

• i = integer

• n = number

• d = double

• l = logical

• f = factor

• D = date

• T = date time

• t = time

• ? = guess

• _ or - = skip

By default, reading a file without a column specification will print a message showing what readr guessed they were. To remove this message, set show_col_types = FALSE or set 'options(readr.show_col_types = FALSE).

Columns to include in the results. You can use the same mini-language as dplyr::select() to refer to the columns by name. Use c() to use more than one selection expression. Although this usage is less common, col_select also accepts a numeric column index. See ?tidyselect::language for full details on the selection language.

The name of a column in which to store the file path. This is useful when reading multiple input files and there is data in the file paths, such as the data collection date. If NULL (the default) no extra column is created.

The locale controls defaults that vary from place to place. The default locale is US-centric (like R), but you can use locale() to create your own locale that controls things like the default time zone, encoding, decimal mark, big mark, and day/month names.

Character vector of strings to interpret as missing values. Set this option to character() to indicate no missing values.

A string used to identify comments. Any text after the comment characters will be silently ignored.

Should blank rows be ignored altogether? i.e. If this option is TRUE then blank rows will not be represented at all. If it is FALSE then they will be represented by NA values in all the columns.

Should leading and trailing whitespace (ASCII spaces and tabs) be trimmed from each field before parsing it?

Number of lines to skip before reading data.

Maximum number of lines to read.

Maximum number of lines to use for guessing column types. Will never use more than the number of lines read. See vignette("column-types", package = "readr") for more details.

Control which column types use Altrep representations, either a character vector of types, TRUE or FALSE. See vroom_altrep() for for full details.

The number of processing threads to use for initial parsing and lazy reading of data. If your data contains newlines within fields the parser should automatically detect this and fall back to using one thread only. However if you know your file has newlines within quoted fields it is safest to set num_threads = 1 explicitly.

Display a progress bar? By default it will only display in an interactive session and not while knitting a document. The automatic progress bar can be disabled by setting option readr.show_progress to FALSE.

If FALSE, do not show the guessed column types. If TRUE always show the column types, even if they are supplied. If NULL (the default) only show the column types if they are not explicitly supplied by the col_types argument.

Handling of column names. The default behaviour is to ensure column names are "unique". Various repair strategies are supported:

• "minimal": No name repair or checks, beyond basic existence of names.

• "unique" (default value): Make sure names are unique and not empty.

• "check_unique": no name repair, but check they are unique.

• "universal": Make the names unique and syntactic.

• A function: apply custom name repair (e.g., name_repair = make.names for names in the style of base R).

• A purrr-style anonymous function, see rlang::as_function().

This argument is passed on as repair to vctrs::vec_as_names(). See there for more details on these terms and the strategies used to enforce them.

Either NULL, or a character vector column names.

Number of lines the tokenizer will read to determine file structure. By default it is set to 100.

Width of each field. Use NA as width of last field when reading a ragged fwf file.

Starting and ending (inclusive) positions of each field. Use NA as last end field when reading a ragged fwf file.

If the first element is a data frame, then it must have all numeric columns and either one or two rows. The column names are the variable names. The column values are the variable widths if a length one vector, and if length two, variable start and end positions. The elements of ... are used to construct a data frame with or or two rows as above.

Either a path to a file, a connection, or literal data (either a single string or a raw vector). file can also be a character vector containing multiple filepaths or a list containing multiple connections.

Files ending in .gz, .bz2, .xz, or .zip will be automatically uncompressed. Files starting with ⁠http://⁠, ⁠https://⁠, ⁠ftp://⁠, or ⁠ftps://⁠ will be automatically downloaded. Remote gz files can also be automatically downloaded and decompressed.

Literal data is most useful for examples and tests. To be recognised as literal data, wrap the input with I().

Maximum number of lines to read.

Number of lines to skip before reading data. If comment is supplied any commented lines are ignored after skipping.

Character vector of strings to interpret as missing values. Set this option to character() to indicate no missing values.

Should blank rows be ignored altogether? i.e. If this option is TRUE then blank rows will not be represented at all. If it is FALSE then they will be represented by NA values in all the columns.

The locale controls defaults that vary from place to place. The default locale is US-centric (like R), but you can use locale() to create your own locale that controls things like the default time zone, encoding, decimal mark, big mark, and day/month names.

Control which column types use Altrep representations, either a character vector of types, TRUE or FALSE. See vroom_altrep() for for full details.

Number of threads to use when reading and materializing vectors. If your data contains newlines within fields the parser will automatically be forced to use a single thread only.

Display a progress bar? By default it will only display in an interactive session and not while knitting a document. The automatic progress bar can be disabled by setting option readr.show_progress to FALSE.

a vector

A data frame or tibble to write to disk.

File or connection to write to.

Delimiter used to separate values. Defaults to ⁠\t⁠ to write tab separated value (TSV) files.

The end of line character to use. Most commonly either "\n" for Unix style newlines, or "\r\n" for Windows style newlines.

String used for missing values. Defaults to 'NA'.

If FALSE, column names will not be included at the top of the file. If TRUE, column names will be included. If not specified, col_names will take the opposite value given to append.

If FALSE, will overwrite existing file. If TRUE, will append to existing file. In both cases, if the file does not exist a new file is created.

How to handle fields which contain characters that need to be quoted.

• needed - Values are only quoted if needed: if they contain a delimiter, quote, or newline.

• all - Quote all fields.

• none - Never quote fields.

The type of escape to use when quotes are in the data.

• double - quotes are escaped by doubling them.

• backslash - quotes are escaped by a preceding backslash.

• none - quotes are not escaped.

If TRUE add a UTF-8 BOM at the beginning of the file. This is recommended when saving data for consumption by excel, as it will force excel to read the data with the correct encoding (UTF-8)

Number of threads to use when reading and materializing vectors. If your data contains newlines within fields the parser will automatically be forced to use a single thread only.

Display a progress bar? By default it will only display in an interactive session and not while knitting a document. The display is updated every 50,000 values and will only display if estimated reading time is 5 seconds or more. The automatic progress bar can be disabled by setting option readr.show_progress to FALSE.

is no longer supported, use file instead.

A character vector.

File or connection to write to.

The end of line character to use. Most commonly either "\n" for Unix style newlines, or "\r\n" for Windows style newlines.

String used for missing values. Defaults to 'NA'.

If FALSE, will overwrite existing file. If TRUE, will append to existing file. In both cases, if the file does not exist a new file is created.

Number of threads to use when reading and materializing vectors. If your data contains newlines within fields the parser will automatically be forced to use a single thread only.